Edit on GitHub

serde.json

Serialize and Deserialize in JSON format.

  1"""
  2Serialize and Deserialize in JSON format.
  3"""
  4
  5from typing import Any, AnyStr, overload, Optional, Union
  6
  7from .compat import T
  8from .de import Deserializer, from_dict
  9from .se import Serializer, to_dict
 10from .numpy import encode_numpy
 11
 12try:  # pragma: no cover
 13    import orjson
 14
 15    def json_dumps(obj: Any, **opts: Any) -> str:
 16        if "option" not in opts:
 17            opts["option"] = orjson.OPT_SERIALIZE_NUMPY
 18        return orjson.dumps(obj, **opts).decode()  # type: ignore
 19
 20    def json_loads(s: Union[str, bytes], **opts: Any) -> Any:
 21        return orjson.loads(s, **opts)
 22
 23except ImportError:
 24    import json
 25
 26    def json_dumps(obj: Any, **opts: Any) -> str:
 27        if "default" not in opts:
 28            opts["default"] = encode_numpy
 29        # compact output
 30        ensure_ascii = opts.pop("ensure_ascii", False)
 31        separators = opts.pop("separators", (",", ":"))
 32        return json.dumps(obj, ensure_ascii=ensure_ascii, separators=separators, **opts)
 33
 34    def json_loads(s: Union[str, bytes], **opts: Any) -> Any:
 35        return json.loads(s, **opts)
 36
 37
 38__all__ = ["from_json", "to_json"]
 39
 40
 41class JsonSerializer(Serializer[str]):
 42    @classmethod
 43    def serialize(cls, obj: Any, **opts: Any) -> str:
 44        return json_dumps(obj, **opts)
 45
 46
 47class JsonDeserializer(Deserializer[AnyStr]):
 48    @classmethod
 49    def deserialize(cls, data: AnyStr, **opts: Any) -> Any:
 50        return json_loads(data, **opts)
 51
 52
 53def to_json(
 54    obj: Any,
 55    cls: Optional[Any] = None,
 56    se: type[Serializer[str]] = JsonSerializer,
 57    reuse_instances: bool = False,
 58    convert_sets: bool = True,
 59    skip_none: bool = False,
 60    **opts: Any,
 61) -> str:
 62    """
 63    Serialize the object into JSON str. [orjson](https://github.com/ijl/orjson)
 64    will be used if installed.
 65
 66    You can pass any serializable `obj`. If you supply other keyword arguments,
 67    they will be passed in `dumps` function.
 68    By default, numpy objects are serialized, this behaviour can be customized with the `option`
 69    argument with [orjson](https://github.com/ijl/orjson#numpy), or the `default` argument with
 70    Python standard json library.
 71
 72    * `skip_none`: When set to True, any field in the class with a None value is excluded from the
 73    serialized output. Defaults to False.
 74
 75    If you want to use another json package, you can subclass `JsonSerializer` and implement
 76    your own logic.
 77    """
 78    return se.serialize(
 79        to_dict(obj, c=cls, reuse_instances=reuse_instances, convert_sets=convert_sets), **opts
 80    )
 81
 82
 83@overload
 84def from_json(
 85    c: type[T], s: AnyStr, de: type[Deserializer[AnyStr]] = JsonDeserializer, **opts: Any
 86) -> T: ...
 87
 88
 89# For Union, Optional etc.
 90@overload
 91def from_json(
 92    c: Any, s: AnyStr, de: type[Deserializer[AnyStr]] = JsonDeserializer, **opts: Any
 93) -> Any: ...
 94
 95
 96def from_json(
 97    c: Any, s: AnyStr, de: type[Deserializer[AnyStr]] = JsonDeserializer, **opts: Any
 98) -> Any:
 99    """
100    Deserialize from JSON into the object. [orjson](https://github.com/ijl/orjson) will be used
101    if installed.
102
103    `c` is a class obejct and `s` is JSON bytes or str. If you supply other keyword arguments,
104    they will be passed in `loads` function.
105
106    If you want to use another json package, you can subclass `JsonDeserializer` and implement
107    your own logic.
108    """
109    return from_dict(c, de.deserialize(s, **opts), reuse_instances=False)
def from_json( c: Any, s: ~AnyStr, de: type[serde.de.Deserializer[~AnyStr]] = <class 'serde.json.JsonDeserializer'>, **opts: Any) -> Any:
 97def from_json(
 98    c: Any, s: AnyStr, de: type[Deserializer[AnyStr]] = JsonDeserializer, **opts: Any
 99) -> Any:
100    """
101    Deserialize from JSON into the object. [orjson](https://github.com/ijl/orjson) will be used
102    if installed.
103
104    `c` is a class obejct and `s` is JSON bytes or str. If you supply other keyword arguments,
105    they will be passed in `loads` function.
106
107    If you want to use another json package, you can subclass `JsonDeserializer` and implement
108    your own logic.
109    """
110    return from_dict(c, de.deserialize(s, **opts), reuse_instances=False)

Deserialize from JSON into the object. orjson will be used if installed.

c is a class obejct and s is JSON bytes or str. If you supply other keyword arguments, they will be passed in loads function.

If you want to use another json package, you can subclass JsonDeserializer and implement your own logic.

def to_json( obj: Any, cls: Optional[Any] = None, se: type[serde.se.Serializer[str]] = <class 'serde.json.JsonSerializer'>, reuse_instances: bool = False, convert_sets: bool = True, skip_none: bool = False, **opts: Any) -> str:
54def to_json(
55    obj: Any,
56    cls: Optional[Any] = None,
57    se: type[Serializer[str]] = JsonSerializer,
58    reuse_instances: bool = False,
59    convert_sets: bool = True,
60    skip_none: bool = False,
61    **opts: Any,
62) -> str:
63    """
64    Serialize the object into JSON str. [orjson](https://github.com/ijl/orjson)
65    will be used if installed.
66
67    You can pass any serializable `obj`. If you supply other keyword arguments,
68    they will be passed in `dumps` function.
69    By default, numpy objects are serialized, this behaviour can be customized with the `option`
70    argument with [orjson](https://github.com/ijl/orjson#numpy), or the `default` argument with
71    Python standard json library.
72
73    * `skip_none`: When set to True, any field in the class with a None value is excluded from the
74    serialized output. Defaults to False.
75
76    If you want to use another json package, you can subclass `JsonSerializer` and implement
77    your own logic.
78    """
79    return se.serialize(
80        to_dict(obj, c=cls, reuse_instances=reuse_instances, convert_sets=convert_sets), **opts
81    )

Serialize the object into JSON str. orjson will be used if installed.

You can pass any serializable obj. If you supply other keyword arguments, they will be passed in dumps function. By default, numpy objects are serialized, this behaviour can be customized with the option argument with orjson, or the default argument with Python standard json library.

  • skip_none: When set to True, any field in the class with a None value is excluded from the serialized output. Defaults to False.

If you want to use another json package, you can subclass JsonSerializer and implement your own logic.