Encoder¶

Note

Checkout the getting started guide for more details on encoding.

Implements the JSON5Encoder class and the dumps and dump functions.

JSON5Encoder ¶

JSON5Encoder(
    *,
    default: DefaultInterface | None = None,
    skip_keys: bool = False,
    ensure_ascii: bool = True,
    check_circular: bool = True,
    allow_nan: bool = True,
    indent: int | None = None,
    separators: tuple[str, str] | None = None,
    sort_keys: bool = False,
    key_quotation: KeyQuotation = "double",
    trailing_comma: bool | None = None,
)

JSON5 encoder class. This encoder is used to serialize Python objects to JSON5 strings. This class mirrors the standard library's JSONEncoder class, with the addition of a few extra options and features. This class will transform common data structures according to this table:

Python	JSON
dict	object
list, tuple	array
str	string
int, float	number
True	true
False	false
None	null

To extend the encoder, subclass this class and override the .default() method, which will try to encode the data structures that are not supported by default. The .default() method should return a serializable object. If the .default() method is not overridden, the encoder will raise a JSON5EncodeError when trying to encode an unsupported object. The overridden .default() method should also call the parent class's .default() method to handle the default encoding.

The constructor also takes in a default argument, which can be used to set a default function that will be called when trying to encode an unsupported object. This argument will take precedence over the overridden .default() method.

Warning

Comment extraction is currently only fully supported on Python 3.12+. On older versions, the function will still work but will not extract all comments from the parent TypedDicts.

Example:

import ujson5


class MyEncoder(ujson5.JSON5Encoder):
    def default(self, obj):
        if isinstance(obj, set):  # (1)!
            return list(obj)
        return super().default(obj)  # (2)!


user = {"name": "John", "age": "123", "hobbies": {"tennis", "reading"}}
print(ujson5.dumps(user, cls=MyEncoder))
# {"name": "John", "age": "123", "hobbies": ["reading", "tennis"]}

In this example, the encoder subclass MyEncoder overrides the .default() method to handle the serialization of sets. The method returns a list of the set elements.
It is recommended to call the parent class's .default() method to handle the default encoding.

All arguments are keyword-only arguments.

Parameters:

Name	Type	Description	Default
`default`	`DefaultInterface \| None`	A function that returns a serializable object when trying to encode an unsupported object. If None, the default`.default()` method will be used. Defaults to None.	`None`
`skip_keys`	`bool`	If True, keys with unsupported types (anything other than str, int, float, bool, or None) will be skipped. Otherwise, an exception will be raised. Defaults to False.	`False`
`ensure_ascii`	`bool`	If True, all non-ASCII characters will be escaped. Defaults to True.	`True`
`check_circular`	`bool`	If True, circular references will be checked. This will introduce a small performance hit. Defaults to True.	`True`
`allow_nan`	`bool`	If True, NaN, Infinity, and -Infinity will be allowed. Otherwise, an exception will be raised when trying to encode these values. Defaults to True.	`True`
`indent`	`int \| None`	If not None, the output will be formatted with the given indent level. Otherwise, the output will be compact. Defaults to None.	`None`
`separators`	`tuple[str, str] \| None`	A tuple containing the item separator and the key-value separator. Defaults to None. If None, it will be set to (", ", ": ") if indent is None, and (",", ":") if indent is not None.	`None`
`sort_keys`	`bool`	If True, the keys will be sorted. Defaults to False.	`False`
`key_quotation`	`KeyQuotation`	The quotation style to be used for keys. Can be one of "single", "double", or "none". If "single" or "double", the keys will be enclosed in single or double quotes, respectively. If "none", the keys will not be enclosed in quotes. Defaults to "double".	`'double'`
`trailing_comma`	`bool \| None`	If True, a trailing comma will be added to the last item in a list or dictionary. If None, a trailing comma will be added if indent is not None. Defaults to None.	`None`

Source code in src/ujson5/encoder.py

def __init__(
    self,
    *,
    default: DefaultInterface | None = None,
    skip_keys: bool = False,
    ensure_ascii: bool = True,
    check_circular: bool = True,
    allow_nan: bool = True,
    indent: int | None = None,
    separators: tuple[str, str] | None = None,
    sort_keys: bool = False,
    key_quotation: KeyQuotation = "double",
    trailing_comma: bool | None = None,
) -> None:
    self._skip_keys: bool = skip_keys
    self._ensure_ascii: bool = ensure_ascii
    self._allow_nan: bool = allow_nan
    self._sort_keys: bool = sort_keys
    self._indent_str: str | None = " " * indent if indent is not None else None
    self._item_separator: str = ", "
    self._key_separator: str = ": "
    self._key_quotation: str = key_quotation
    if indent is not None:
        self._item_separator = ","
    self._trailing_comma: bool = indent is not None
    if trailing_comma is not None:
        self._trailing_comma = trailing_comma
    if separators is not None:
        self._item_separator, self._key_separator = separators

    self._default: DefaultInterface | None = default

    if check_circular:
        self._markers: dict[int, Any] | None = {}
    else:
        self._markers = None

    self._comments_cache: CommentsCache = {}

encode ¶

encode(obj: Any, typed_dict_cls: Any | None = None) -> str

Return a JSON5 string representation of a Python object.

Parameters:

Name	Type	Description	Default
`obj`	`Any`	The Python object to be serialized	required
`typed_dict_cls`	`Any \| None`	A TypedDict class that will be used to extract comments from the TypedDict entries. Defaults to None.	`None`

Returns:

Name	Type	Description
`str`	`str`	The JSON5 string representation of the Python object

Raises:

Type	Description
`JSON5EncodeError`	If the TypedDict class is not a TypedDict subclass or if the object cannot be serialized

Source code in src/ujson5/encoder.py

def encode(self, obj: Any, typed_dict_cls: Any | None = None) -> str:
    """Return a JSON5 string representation of a Python object.

    Args:
        obj: The Python object to be serialized
        typed_dict_cls: A TypedDict class that will be used to extract comments from
            the TypedDict entries. Defaults to None.

    Returns:
        str: The JSON5 string representation of the Python object

    Raises:
        JSON5EncodeError: If the TypedDict class is not a TypedDict subclass or if the
            object cannot be serialized
    """
    if typed_dict_cls is not None and not is_typeddict(typed_dict_cls):
        raise JSON5EncodeError(EncoderErrors.invalid_typed_dict(typed_dict_cls))
    if isinstance(obj, str):
        return self._encode_str(obj)
    if isinstance(obj, bool):
        return "true" if obj else "false"
    if isinstance(obj, int):
        return self._encode_int(obj)
    if isinstance(obj, float):
        return self._encode_float(obj)
    if obj is None:
        return "null"

    chunks = self.iterencode(obj, typed_dict_cls)
    if not isinstance(chunks, (list, tuple)):
        chunks = list(chunks)
    return "".join(chunks)

iterencode ¶

iterencode(
    obj: Any, typed_dict_cls: Any | None = None
) -> Iterable[str]

Encode the given object and yield each part of the JSON5 string representation

Parameters:

Name	Type	Description	Default
`obj`	`Any`	The Python object to be serialized	required
`typed_dict_cls`	`Any \| None`	A TypedDict class that will be used to extract comments from the TypedDict entries. Defaults to None.	`None`

Returns:

Type	Description
`Iterable[str]`	Iterable[str]: An iterable of strings representing the JSON5 serialization of the Python object

Raises:

Type	Description
`JSON5EncodeError`	If the TypedDict class is not a TypedDict subclass or if the object cannot be serialized

Source code in src/ujson5/encoder.py

def iterencode(self, obj: Any, typed_dict_cls: Any | None = None) -> Iterable[str]:
    """Encode the given object and yield each part of the JSON5 string representation

    Args:
        obj: The Python object to be serialized
        typed_dict_cls: A TypedDict class that will be used to extract comments from
            the TypedDict entries. Defaults to None.

    Returns:
        Iterable[str]: An iterable of strings representing the JSON5 serialization of the
            Python object

    Raises:
        JSON5EncodeError: If the TypedDict class is not a TypedDict subclass or if the
            object cannot be serialized
    """
    if is_typeddict(typed_dict_cls) and self._indent_str is not None:
        self._comments_cache = get_comments(typed_dict_cls)
    if typed_dict_cls is not None and not is_typeddict(typed_dict_cls):
        raise JSON5EncodeError(EncoderErrors.invalid_typed_dict(typed_dict_cls))
    return self._iterencode(obj, indent_level=0, key_path="")

default ¶

default(obj: Any) -> Serializable

Override this method in a subclass to implement custom serialization for objects that are not serializable by default. This method should return a serializable object. If this method is not overridden, the encoder will raise a JSON5EncodeError when trying to encode an unsupported object.

Parameters:

Name	Type	Description	Default
`obj`	`Any`	The object to be serialized that is not supported by default	required

Returns:

Name	Type	Description
`Serializable`	`Serializable`	A serializable object

Raises:

Type	Description
`JSON5EncodeError`	If the object cannot be serialized

Source code in src/ujson5/encoder.py

def default(self, obj: Any) -> Serializable:
    """Override this method in a subclass to implement custom serialization
    for objects that are not serializable by default. This method should return
    a serializable object. If this method is not overridden, the encoder will
    raise a JSON5EncodeError when trying to encode an unsupported object.

    Args:
        obj: The object to be serialized that is not supported by default

    Returns:
        Serializable: A serializable object

    Raises:
        JSON5EncodeError: If the object cannot be serialized
    """
    if self._default is not None:
        return self._default(obj)
    raise JSON5EncodeError(EncoderErrors.unable_to_encode(obj))

dump ¶

dump(
    obj: Any,
    fp: TextIO,
    typed_dict_cls: Any | None = None,
    *,
    skip_keys: bool = False,
    ensure_ascii: bool = True,
    check_circular: bool = True,
    allow_nan: bool = True,
    cls: type[JSON5Encoder] | None = None,
    indent: int | None = None,
    separators: tuple[str, str] | None = None,
    default: DefaultInterface | None = None,
    sort_keys: bool = False,
    key_quotation: KeyQuotation = "double",
    trailing_comma: bool | None = None,
) -> None

Serialize obj as a JSON formatted stream to fp (a .write()-supporting file-like object).

Example:

import ujson5
user = {"name": "John", "age": 123, "hobbies": ["tennis", "reading"]}
with open("user.json", "w") as f:
    ujson5.dump(user, f)

Parameters:

Name	Type	Description	Default
`cls`	`type[JSON5Encoder] \| None`	The encoder class to be used. a custom `JSON5Encoder` subclass (e.g. one that overrides the `.default()` method to serialize additional types) can be provided. If None, the default `JSON5Encoder` class will be used. Defaults to None.	`None`
`default`	`DefaultInterface \| None`	A function that returns a serializable object when trying to encode an unsupported object. If None, the default `.default()` method will be used. Defaults to None.	`None`
`skip_keys`	`bool`	If True, keys with unsupported types (anything other than str, int, float, bool, or None) will be skipped. Otherwise, an exception will be raised. Defaults to False.	`False`
`ensure_ascii`	`bool`	If True, all non-ASCII characters will be escaped. Defaults to True.	`True`
`check_circular`	`bool`	If True, circular references will be checked. This will introduce a small performance hit. Defaults to True.	`True`
`allow_nan`	`bool`	If True, NaN, Infinity, and -Infinity will be allowed. Otherwise, an exception will be raised when trying to encode these values. Defaults to True.	`True`
`indent`	`int \| None`	If not None, the output will be formatted with the given indent level. Otherwise, the output will be compact. Defaults to None.	`None`
`separators`	`tuple[str, str] \| None`	A tuple containing the item separator and the key-value separator. Defaults to None. If None, it will be set to (", ", ": ") if indent is None, and (",", ":") if indent is not None.	`None`
`sort_keys`	`bool`	If True, the keys will be sorted. Defaults to False.	`False`
`key_quotation`	`KeyQuotation`	The quotation style to be used for keys. Can be one of "single", "double", or "none". If "single" or "double", the keys will be enclosed in single or double quotes, respectively. If "none", the keys will not be enclosed in quotes. Defaults to "double".	`'double'`
`trailing_comma`	`bool \| None`	If True, a trailing comma will be added to the last item in a list or dictionary. If None, a trailing comma will be added if indent is not None. Defaults to None.	`None`

Returns:

Name	Type	Description
`str`	`None`	The JSON5 formatted string representation of the Python object

Raises:

Type	Description
`JSON5EncodeError`	If the object cannot be serialized

Source code in src/ujson5/encoder.py

def dump(
    obj: Any,
    fp: TextIO,
    typed_dict_cls: Any | None = None,
    *,
    skip_keys: bool = False,
    ensure_ascii: bool = True,
    check_circular: bool = True,
    allow_nan: bool = True,
    cls: type[JSON5Encoder] | None = None,
    indent: int | None = None,
    separators: tuple[str, str] | None = None,
    default: DefaultInterface | None = None,
    sort_keys: bool = False,
    key_quotation: KeyQuotation = "double",
    trailing_comma: bool | None = None,
) -> None:
    """Serialize `obj` as a JSON formatted stream to `fp` (a `.write()`-supporting
    file-like object).

    Example:
    ```python
    import ujson5
    user = {"name": "John", "age": 123, "hobbies": ["tennis", "reading"]}
    with open("user.json", "w") as f:
        ujson5.dump(user, f)
    ```

    Args:
        cls: The encoder class to be used. a custom [`JSON5Encoder`][ujson5.JSON5Encoder]
            subclass (e.g. one that overrides the [`.default()`][ujson5.JSON5Encoder.default]
            method to serialize additional types) can be provided. If None, the default
            [`JSON5Encoder`][ujson5.JSON5Encoder] class will be used. Defaults to None.
        default: A function that returns a serializable object when trying to encode an
            unsupported object. If None, the default
            [`.default()`][ujson5.JSON5Encoder.default] method will be used. Defaults to None.
        skip_keys: If True, keys with unsupported types (anything other than str, int, float,
            bool, or None) will be skipped. Otherwise, an exception will be raised.
            Defaults to False.
        ensure_ascii: If True, all non-ASCII characters will be escaped. Defaults to True.
        check_circular: If True, circular references will be checked. This will introduce a
            small performance hit. Defaults to True.
        allow_nan: If True, NaN, Infinity, and -Infinity will be allowed. Otherwise, an
            exception will be raised when trying to encode these values. Defaults to True.
        indent: If not None, the output will be formatted with the given indent level.
            Otherwise, the output will be compact. Defaults to None.
        separators: A tuple containing the item separator and the key-value separator.
            Defaults to None. If None, it will be set to (", ", ": ") if indent is None,
            and (",", ":") if indent is not None.
        sort_keys: If True, the keys will be sorted. Defaults to False.
        key_quotation: The quotation style to be used for keys. Can be one of "single",
            "double", or "none". If "single" or "double", the keys will be enclosed in
            single or double quotes, respectively. If "none", the keys will not be enclosed
            in quotes. Defaults to "double".
        trailing_comma: If True, a trailing comma will be added to the last item in
            a list or dictionary. If None, a trailing comma will be added if indent
            is not None. Defaults to None.

    Returns:
        str: The JSON5 formatted string representation of the Python object

    Raises:
        JSON5EncodeError: If the object cannot be serialized
    """
    if (
        not skip_keys  # pylint: disable=R0916
        and ensure_ascii
        and check_circular
        and allow_nan
        and cls is None
        and indent is None
        and separators is None
        and default is None
        and not sort_keys
        and key_quotation == "double"
        and trailing_comma is None
    ):
        iterable = _default_encoder.iterencode(obj, typed_dict_cls)
    else:
        if cls is None:
            cls = JSON5Encoder
        iterable = cls(
            skip_keys=skip_keys,
            ensure_ascii=ensure_ascii,
            check_circular=check_circular,
            allow_nan=allow_nan,
            indent=indent,
            separators=separators,
            default=default,
            sort_keys=sort_keys,
            key_quotation=key_quotation,
            trailing_comma=trailing_comma,
        ).iterencode(obj, typed_dict_cls)
    for chunk in iterable:
        fp.write(chunk)
    fp.write("\n")

dumps ¶

dumps(
    obj: Any,
    typed_dict_cls: Any | None = None,
    *,
    cls: type[JSON5Encoder] | None = None,
    default: DefaultInterface | None = None,
    skip_keys: bool = False,
    ensure_ascii: bool = True,
    check_circular: bool = True,
    allow_nan: bool = True,
    indent: int | None = None,
    separators: tuple[str, str] | None = None,
    sort_keys: bool = False,
    key_quotation: KeyQuotation = "double",
    trailing_comma: bool | None = None,
) -> str

Serialize obj to a JSON5 formatted str.

Example:

import ujson5
user = {"name": "John", "age": 123, "hobbies": ["tennis", "reading"]}
print(ujson5.dumps(user))
# Output: '{"name": "John", "age": 123, "hobbies": ["tennis", "reading"]}'

All arguments except obj and typed_dict_cls are keyword-only arguments.

Parameters:

Name	Type	Description	Default
`cls`	`type[JSON5Encoder] \| None`	The encoder class to be used. a custom `JSON5Encoder` subclass (e.g. one that overrides the `.default()` method to serialize additional types) can be provided. If None, the default `JSON5Encoder` class will be used. Defaults to None.	`None`
`default`	`DefaultInterface \| None`	A function that returns a serializable object when trying to encode an unsupported object. If None, the default `.default()` method will be used. Defaults to None.	`None`
`skip_keys`	`bool`	If True, keys with unsupported types (anything other than str, int, float, bool, or None) will be skipped. Otherwise, an exception will be raised. Defaults to False.	`False`
`ensure_ascii`	`bool`	If True, all non-ASCII characters will be escaped. Defaults to True.	`True`
`check_circular`	`bool`	If True, circular references will be checked. This will introduce a small performance hit. Defaults to True.	`True`
`allow_nan`	`bool`	If True, NaN, Infinity, and -Infinity will be allowed. Otherwise, an exception will be raised when trying to encode these values. Defaults to True.	`True`
`indent`	`int \| None`	If not None, the output will be formatted with the given indent level. Otherwise, the output will be compact. Defaults to None.	`None`
`separators`	`tuple[str, str] \| None`	A tuple containing the item separator and the key-value separator. Defaults to None. If None, it will be set to (", ", ": ") if indent is None, and (",", ":") if indent is not None.	`None`
`sort_keys`	`bool`	If True, the keys will be sorted. Defaults to False.	`False`
`key_quotation`	`KeyQuotation`	The quotation style to be used for keys. Can be one of "single", "double", or "none". If "single" or "double", the keys will be enclosed in single or double quotes, respectively. If "none", the keys will not be enclosed in quotes. Defaults to "double".	`'double'`
`trailing_comma`	`bool \| None`	If True, a trailing comma will be added to the last item in a list or dictionary. If None, a trailing comma will be added if indent is not None. Defaults to None.	`None`

Returns:

Name	Type	Description
`str`	`str`	The JSON5 formatted string representation of the Python object

Raises:

Type	Description
`JSON5EncodeError`	If the object cannot be serialized

Source code in src/ujson5/encoder.py

def dumps(
    obj: Any,
    typed_dict_cls: Any | None = None,
    *,
    cls: type[JSON5Encoder] | None = None,
    default: DefaultInterface | None = None,
    skip_keys: bool = False,
    ensure_ascii: bool = True,
    check_circular: bool = True,
    allow_nan: bool = True,
    indent: int | None = None,
    separators: tuple[str, str] | None = None,
    sort_keys: bool = False,
    key_quotation: KeyQuotation = "double",
    trailing_comma: bool | None = None,
) -> str:
    """Serialize `obj` to a JSON5 formatted `str`.

    Example:
    ```python
    import ujson5
    user = {"name": "John", "age": 123, "hobbies": ["tennis", "reading"]}
    print(ujson5.dumps(user))
    # Output: '{"name": "John", "age": 123, "hobbies": ["tennis", "reading"]}'
    ```

    All arguments except `obj` and `typed_dict_cls` are keyword-only arguments.

    Args:
        cls: The encoder class to be used. a custom [`JSON5Encoder`][ujson5.JSON5Encoder]
            subclass (e.g. one that overrides the [`.default()`][ujson5.JSON5Encoder.default]
            method to serialize additional types) can be provided. If None, the default
            [`JSON5Encoder`][ujson5.JSON5Encoder] class will be used. Defaults to None.
        default: A function that returns a serializable object when trying to encode an
            unsupported object. If None, the default
            [`.default()`][ujson5.JSON5Encoder.default] method will be used. Defaults to None.
        skip_keys: If True, keys with unsupported types (anything other than str, int, float,
            bool, or None) will be skipped. Otherwise, an exception will be raised.
            Defaults to False.
        ensure_ascii: If True, all non-ASCII characters will be escaped. Defaults to True.
        check_circular: If True, circular references will be checked. This will introduce a
            small performance hit. Defaults to True.
        allow_nan: If True, NaN, Infinity, and -Infinity will be allowed. Otherwise, an
            exception will be raised when trying to encode these values. Defaults to True.
        indent: If not None, the output will be formatted with the given indent level.
            Otherwise, the output will be compact. Defaults to None.
        separators: A tuple containing the item separator and the key-value separator.
            Defaults to None. If None, it will be set to (", ", ": ") if indent is None,
            and (",", ":") if indent is not None.
        sort_keys: If True, the keys will be sorted. Defaults to False.
        key_quotation: The quotation style to be used for keys. Can be one of "single",
            "double", or "none". If "single" or "double", the keys will be enclosed in
            single or double quotes, respectively. If "none", the keys will not be enclosed
            in quotes. Defaults to "double".
        trailing_comma: If True, a trailing comma will be added to the last item in
            a list or dictionary. If None, a trailing comma will be added if indent
            is not None. Defaults to None.

    Returns:
        str: The JSON5 formatted string representation of the Python object

    Raises:
        JSON5EncodeError: If the object cannot be serialized
    """
    if (
        not skip_keys  # pylint: disable=R0916
        and ensure_ascii
        and check_circular
        and allow_nan
        and cls is None
        and indent is None
        and separators is None
        and default is None
        and not sort_keys
        and key_quotation == "double"
        and trailing_comma is None
    ):
        return _default_encoder.encode(obj, typed_dict_cls)
    if cls is None:
        cls = JSON5Encoder
    return cls(
        skip_keys=skip_keys,
        ensure_ascii=ensure_ascii,
        check_circular=check_circular,
        allow_nan=allow_nan,
        indent=indent,
        separators=separators,
        default=default,
        sort_keys=sort_keys,
        key_quotation=key_quotation,
        trailing_comma=trailing_comma,
    ).encode(obj, typed_dict_cls)

Implements the JSON5Encoder class and the dumps and dump functions.

DefaultInterface `module-attribute` ¶

DefaultInterface = (
    Callable[[Any], dict]
    | Callable[[Any], list]
    | Callable[[Any], tuple]
    | Callable[[Any], int]
    | Callable[[Any], float]
    | Callable[[Any], str]
    | Callable[[Any], None]
    | Callable[[Any], bool]
    | Callable[[Any], Serializable]
)

A callable that takes in an object that is not serializable and returns a serializable object

Serializable `module-attribute` ¶

Serializable = (
    dict | list | tuple | int | float | str | None | bool
)

Python objects that can be serialized to JSON5

KeyQuotation `module-attribute` ¶

KeyQuotation = Literal['single', 'double', 'none']

The quotation style to be used for keys in a json5 object.

    relative_crossrefs: true

Encoder¶

JSON5Encoder ¶

encode ¶

iterencode ¶

default ¶

dump ¶

dumps ¶

DefaultInterface module-attribute ¶

Serializable module-attribute ¶

KeyQuotation module-attribute ¶

DefaultInterface `module-attribute` ¶

Serializable `module-attribute` ¶

KeyQuotation `module-attribute` ¶