serde.yaml

 1"""
 2Serialize and Deserialize in YAML format. This module depends on
 3[pyyaml](https://pypi.org/project/PyYAML/) package.
 4"""
 5
 6from typing import overload, Optional, Any
 7
 8import yaml
 9
10from .compat import T
11from .de import Deserializer, from_dict
12from .se import Serializer, to_dict
13
14__all__ = ["from_yaml", "to_yaml"]
15
16
17class YamlSerializer(Serializer[str]):
18    @classmethod
19    def serialize(cls, obj: Any, **opts: Any) -> str:
20        return yaml.safe_dump(obj, **opts)  # type: ignore
21
22
23class YamlDeserializer(Deserializer[str]):
24    @classmethod
25    def deserialize(cls, data: str, **opts: Any) -> Any:
26        return yaml.safe_load(data, **opts)
27
28
29def to_yaml(
30    obj: Any,
31    cls: Optional[Any] = None,
32    se: type[Serializer[str]] = YamlSerializer,
33    reuse_instances: bool = False,
34    convert_sets: bool = True,
35    skip_none: bool = False,
36    **opts: Any,
37) -> str:
38    """
39    Serialize the object into YAML.
40
41    You can pass any serializable `obj`. If you supply keyword arguments other than `se`,
42    they will be passed in `yaml.safe_dump` function.
43
44    * `skip_none`: When set to True, any field in the class with a None value is excluded from the
45    serialized output. Defaults to False.
46
47    If you want to use the other yaml package, you can subclass `YamlSerializer` and implement
48    your own logic.
49    """
50    return se.serialize(
51        to_dict(
52            obj,
53            c=cls,
54            reuse_instances=reuse_instances,
55            convert_sets=convert_sets,
56            skip_none=skip_none,
57        ),
58        **opts,
59    )
60
61
62@overload
63def from_yaml(
64    c: type[T], s: str, de: type[Deserializer[str]] = YamlDeserializer, **opts: Any
65) -> T: ...
66
67
68# For Union, Optional etc.
69@overload
70def from_yaml(
71    c: Any, s: str, de: type[Deserializer[str]] = YamlDeserializer, **opts: Any
72) -> Any: ...
73
74
75def from_yaml(c: Any, s: str, de: type[Deserializer[str]] = YamlDeserializer, **opts: Any) -> Any:
76    """
77    `c` is a class object and `s` is YAML string. If you supply keyword arguments other than `de`,
78    they will be passed in `yaml.safe_load` function.
79
80    If you want to use the other yaml package, you can subclass `YamlDeserializer` and implement
81    your own logic.
82    """
83    return from_dict(c, de.deserialize(s, **opts), reuse_instances=False)