From 6f0a3245af438ccdb339a8918333daa485606823 Mon Sep 17 00:00:00 2001 From: yukinarit Date: Wed, 12 Jun 2024 20:59:25 +0900 Subject: [PATCH] Update documentation of from_dict/to_dict --- README.md | 10 +++++++++- docs/en/data-formats.md | 2 +- docs/en/getting-started.md | 4 ++-- serde/se.py | 22 ++++++++++++++++++---- 4 files changed, 30 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 409b11c8..3c4fdb12 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,9 @@ ## Overview -Declare a class with pyserde's `@serde` decorator. +`pyserde` is a simple yet powerful serialization library on top of [dataclasses](https://docs.python.org/3/library/dataclasses.html). It allows you to convert Python objects to and from JSON, YAML, and other formats easily and efficiently. + +Declare your class with `@serde` decorator and annotate fields using [PEP484](https://peps.python.org/pep-0484/) as below. ```python @serde @@ -45,6 +47,12 @@ You can deserialize JSON into `Foo` object. Foo(i=10, s='foo', f=100.0, b=True) ``` +That's it! If you're interested in pyserde, please check our documentation! +Happy coding with pyserde! 🚀 +* [Getting started](https://yukinarit.github.io/pyserde/guide/en/getting-started.html) +* [API Reference](https://yukinarit.github.io/pyserde/api/serde.html) +* [Examples](https://github.com/yukinarit/pyserde/tree/main/examples) + ## Features - Supported data formats diff --git a/docs/en/data-formats.md b/docs/en/data-formats.md index e70c9cf5..b6a53161 100644 --- a/docs/en/data-formats.md +++ b/docs/en/data-formats.md @@ -1,6 +1,6 @@ # Data Formats -Currently `dict`, `tuple`, `JSON`, `Yaml`, `Toml`, `MsgPack` and `Pickle` are supported. Each Serialize/Deserialize API can take additional keyword arguments. Keyword arguements are forwared to the packages which is used by pyserde to encode data internally. +pyserde supports several data formats for serialization and deserialization, including `dict`, `tuple`, `JSON`, `YAML`, `TOML`, `MsgPack`, and `Pickle`. Each API can take additional keyword arguments, which are forwarded to the underlying packages used by pyserde. e.g. If you want to preserve the field order in YAML, you can pass `sort_key=True` in `serde.yaml.to_yaml` diff --git a/docs/en/getting-started.md b/docs/en/getting-started.md index 778437f9..0d995ecc 100644 --- a/docs/en/getting-started.md +++ b/docs/en/getting-started.md @@ -109,5 +109,5 @@ print(from_json(Foo, s)) That's it! pyserde offers many more features. If you're interested, please read the rest of the documentation. -> **NOTE:** which type checker should be used? -> pyserde depends on [PEP681 dataclass_transform](https://peps.python.org/pep-0681/). [mypy](https://github.com/python/mypy) does not fully support dataclass_transform as of Jan. 2024. [pyright](https://github.com/microsoft/pyright) is recommended for codebase using pyserde. +> 💡 Tip: which type checker should I use? +> pyserde depends on [PEP681 dataclass_transform](https://peps.python.org/pep-0681/). [mypy](https://github.com/python/mypy) does not fully support dataclass_transform as of Jan. 2024. My personal recommendation is [pyright](https://github.com/microsoft/pyright). diff --git a/serde/se.py b/serde/se.py index 8bf49382..52e8702f 100644 --- a/serde/se.py +++ b/serde/se.py @@ -436,9 +436,22 @@ def to_dict( convert_sets: Optional[bool] = None, ) -> dict[Any, Any]: """ - Serialize object into dictionary. - - >>> @serialize + Serialize object into python dictionary. This function ensures that the dataclass's fields are + accurately represented as key-value pairs in the resulting dictionary. + + * `o`: Any pyserde object that you want to convert to `dict` + * `c`: Optional class argument + * `reuse_instances`: pyserde will pass instances (e.g. Path, datetime) directly to serializer + instead of converting them to serializable representation e.g. string. This behaviour allows + to delegate serializtation to underlying data format packages e.g. `pyyaml` and potentially + improve performance. + * `convert_sets`: This option controls how sets are handled during serialization and + deserialization. When `convert_sets` is set to True, pyserde will convert sets to lists during + serialization and back to sets during deserialization. This is useful for data formats that + do not natively support sets. + + >>> from serde import serde + >>> @serde ... class Foo: ... i: int ... s: str = 'foo' @@ -448,7 +461,8 @@ def to_dict( >>> to_dict(Foo(i=10)) {'i': 10, 's': 'foo', 'f': 100.0, 'b': True} - You can pass any type supported by pyserde. For example, + You can serialize not only pyserde objects but also objects of any supported types. For example, + the following example serializes list of pyserde objects into dict. >>> lst = [Foo(i=10), Foo(i=20)] >>> to_dict(lst)