Refine pyserde guide (#700)

Author: yukinarit

docs/en/class-attributes.md

@@ -2,6 +2,8 @@
 
 Class attributes can be specified as arguments in the `serialize`/`deserialize` decorators in order to customize the (de)serialization behaviour of the class entirely. If you want to customize a field, please consider using [Field Attributes](field-attributes.md).
 
+Class attributes affect how every field is treated, so they are ideal for naming conventions, tagging, or behavior that must be consistent across the whole class.
+
 ## Attributes offered by dataclasses
 
 ### **`frozen`**
@@ -141,7 +143,7 @@ New in v0.13.0.
 
 > **NOTE:** Deprecated since v0.13.0. Consider using `class_serializer` and `class_deserializer`.
 
-If you want to use a custom (de)serializer at class level, you can pass your (de)serializer methods n `serializer` and `deserializer` class attributes.
+If you want to use a custom (de)serializer at class level, you can pass your (de)serializer methods in `serializer` and `deserializer` class attributes.
 
 ```python
 def serializer(cls, o):

docs/en/data-formats.md

@@ -2,14 +2,17 @@
 
 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`
+Use the format-specific modules (e.g. `serde.json`, `serde.yaml`) when you want to control serialization options. For example, if you want to preserve the field order in YAML, you can pass `sort_key=True` in `serde.yaml.to_yaml`.
+
 
 ```python
 serde.yaml.to_yaml(foo, sort_key=True)
 ```
 
 `sort_key=True` will be passed in the [yaml.safedump](https://github.com/yukinarit/pyserde/blob/a9f44d52d109144a4c3bb93965f831e91d13960b/serde/yaml.py#L18)
 
+> **NOTE:** JSON, YAML, TOML, and MsgPack formats require their matching extras. `dict`, `tuple`, and Pickle work without optional dependencies.
+
 ## dict
 
 ```python
@@ -50,6 +53,8 @@ See [serde.to_tuple](https://yukinarit.github.io/pyserde/api/serde/se.html#to_tu
 Foo(i=10, s='foo', f=100.0, b=True)
 ```
 
+If you enable the `orjson` extra, pyserde can use it under the hood for faster JSON encoding/decoding.
+
 See [serde.json.to_json](https://yukinarit.github.io/pyserde/api/serde/json.html#to_json) / [serde.json.from_json](https://yukinarit.github.io/pyserde/api/serde/json.html#from_json) for more information.
 
 ## Yaml
@@ -119,4 +124,4 @@ See [serde.pickle.to_pickle](https://yukinarit.github.io/pyserde/api/serde/pickl
 
 ## Needs a new data format support?
 
-We don't plan to supprot a data format such as XML to keep pyserde as simple as possible. If you need a new data format support, we recommend to create a separate python package. If the data format is interchangable to dict or tuple, implementing the serialize/desrialize API is not that difficult. See [YAML's implementation](https://github.com/yukinarit/pyserde/blob/main/serde/yaml.py) to know how to implement.
+We don't plan to support a data format such as XML to keep pyserde as simple as possible. If you need a new data format support, we recommend to create a separate python package. If the data format is interchangable to dict or tuple, implementing the serialize/deserialize API is not that difficult. See [YAML's implementation](https://github.com/yukinarit/pyserde/blob/main/serde/yaml.py) to know how to implement.

docs/en/decorators.md

@@ -27,6 +27,8 @@ class Foo:
 * You can pass both (de)serialize attributes to the decorator
     * `serializer` attribute is ignored in `@deserialize` and `deserializer` attribute is ignored in `@serialize`
 
+Use `@serde` for most classes unless you need separate serialization/deserialization configs.
+
 ```python
 @serde(serializer=serializer, deserializer=deserializer)
 @dataclass

docs/en/extension.md

@@ -2,6 +2,8 @@
 
 pyserde offers three ways to extend pyserde to support non builtin types.
 
+Choose field-level serializers for one-off fields, class serializers for reusable types, and global serializers to apply extensions project-wide.
+
 ## Custom field (de)serializer
 
 See [custom field serializer](./field-attributes.md#serializerdeserializer).

docs/en/faq.md

@@ -7,6 +7,8 @@ pyserde provides `inspect` submodule that works as commandline:
 python -m serde.inspect <PATH_TO_FILE> <CLASS>
 ```
 
+This is useful when you want to understand generated code, debug custom serializers, or confirm how pyserde handles a specific type.
+
 e.g. in pyserde project
 
 ```

docs/en/field-attributes.md

@@ -1,6 +1,6 @@
 # Field Attributes
 
-Field attributes are options to customize (de)serialization behaviour for a field of a dataclass.
+Field attributes are options to customize (de)serialization behaviour for a field of a dataclass. Use them when you want different wire formats, optional behavior, or custom logic for specific fields.
 
 ## Attributes offered by dataclasses
 
@@ -34,7 +34,7 @@ Here is an example specifying `rename` attribute in both `serde.field` and `data
 @serde.serde
 class Foo:
     a: str = serde.field(rename="A")
-    b: str = dataclasses.field(metadata={"serde_rename"="B"})
+    b: str = dataclasses.field(metadata={"serde_rename": "B"})
 ```
 
 ### **`rename`**
@@ -65,7 +65,7 @@ See [examples/skip.py](https://github.com/yukinarit/pyserde/blob/main/examples/s
 
 ### **`skip_if`**
 
-`skip` is used to skip (de)serialization of the field if the predicate function returns `True`.
+`skip_if` is used to skip (de)serialization of the field if the predicate function returns `True`.
 
 ```python
 @serde
@@ -75,6 +75,8 @@ class World:
 
 See [examples/skip.py](https://github.com/yukinarit/pyserde/blob/main/examples/skip.py) for the complete example.
 
+> **NOTE:** `skip`, `skip_if`, `skip_if_false`, and `skip_if_default` apply to both serialization and deserialization. Use them to keep wire formats compact or to ignore fields you only use locally.
+
 ### **`skip_if_false`**
 
 `skip` is used to skip (de)serialization of the field if the field evaluates to `False`. For example, this code skip (de)serializing if `enemies` is empty.

docs/en/getting-started.md

@@ -4,6 +4,8 @@
 
 Install pyserde from PyPI. pyserde requires Python>=3.10.
 
+If you want faster JSON handling, you can also install `orjson` and use the `orjson` extra for optional acceleration.
+
 ```
 pip install pyserde
 ```
@@ -45,6 +47,8 @@ Here are the available extras
 * `orjson`: Install [orjson](https://github.com/ijl/orjson)
 * `sqlalchemy`: Install [sqlalchemy](https://github.com/sqlalchemy/sqlalchemy)
 
+> **NOTE:** Extras enable additional formats and types, but you can mix them as needed. For example, install only `toml` and `yaml` if you do not need MsgPack or numpy.
+
 ## Define your first pyserde class
 
 Define your class with pyserde's `@serde` decorators. Be careful that module name is `serde`, not `pyserde`. `pyserde` heavily depends on the standard library's `dataclasses` module. If you are new to dataclass, I would recommend to read [dataclasses documentation](https://docs.python.org/3/library/dataclasses.html) first.
@@ -98,7 +102,7 @@ from serde.json import from_json, to_json
 ```
 
 Use `to_json` to serialize the object into JSON.
-```
+```python
 f = Foo(i=10, s='foo', f=100.0, b=True)
 print(to_json(f))
 ```
@@ -109,7 +113,20 @@ s = '{"i": 10, "s": "foo", "f": 100.0, "b": true}'
 print(from_json(Foo, s))
 ```
 
+You can also serialize to a Python `dict` when you need to manipulate data before writing it to a file or sending it over the network.
+
+```python
+from serde import to_dict, from_dict
+
+payload = to_dict(f)
+# e.g. add a field before sending
+payload["source"] = "cli"
+print(from_dict(Foo, payload))
+```
+
 That's it! pyserde offers many more features. If you're interested, please read the rest of the documentation.
 
+> **NOTE:** If you plan to use YAML, TOML, or MsgPack, remember to install the matching extras listed above.
+
 > 💡 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).

docs/en/introduction.md

@@ -2,6 +2,13 @@
 
 `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.
 
+pyserde focuses on dataclass-first workflows and keeps runtime overhead low by generating serializers when classes are loaded.
+
+Highlights:
+- Multiple formats (`dict`, `tuple`, JSON, YAML, TOML, MsgPack, Pickle)
+- Rich type support (Optional, Union, Literals, enums, datetime, numpy, etc.)
+- Runtime type checking and extensibility hooks
+
 Declare your class with `@serde` decorator and annotate fields using [PEP484](https://peps.python.org/pep-0484/) as below.
 
 ```python
@@ -30,6 +37,16 @@ You can deserialize JSON into `Foo` object.
 Foo(i=10, s='foo', f=100.0, b=True)
 ```
 
+pyserde also provides in-memory formats like `dict` and `tuple`, plus YAML, TOML, MsgPack, and Pickle when their extras are installed.
+
+```python
+>>> from serde import to_dict, from_dict
+>>> to_dict(Foo(i=10, s='foo', f=100.0, b=True))
+{"i": 10, "s": "foo", "f": 100.0, "b": True}
+>>> from_dict(Foo, {"i": 10, "s": "foo", "f": 100.0, "b": True})
+Foo(i=10, s='foo', f=100.0, b=True)
+```
+
 ## Next Steps
 
 * [Getting started](getting-started.md)

docs/en/type-check.md

@@ -2,6 +2,8 @@
 
 pyserde offers runtime type checking since v0.9. It was completely reworked at v0.14 using [beartype](https://github.com/beartype/beartype) and it became more sophisticated and reliable. It is highly recommended to enable type checking always as it helps writing type-safe and robust programs.
 
+If you need to accept untrusted input, prefer `strict` or `coerce` so invalid data fails early.
+
 ## `strict`
 
 Strict type checking is to check every field value against the declared type during (de)serialization and object construction. This is the default type check mode since v0.14. What will happen with this mode is if you declare a class with `@serde` decorator without any class attributes, `@serde(type_check=strict)` is assumed and strict type checking is enabled.
@@ -43,23 +45,22 @@ serde.compat.SerdeError: Method __main__.Foo.__init__() parameter s=10 violates
 > The following code mutates the property "s" at the bottom. beartype can not detect this case.
 > ```python
 > @serde
-> class Foo
+> class Foo:
 >     s: str
 >
 > f = Foo("foo")
 > f.s = 100
 > ```
 >
-> 2. beartype can not validate every one of elements in containers. This is not a bug. This is desgin principle of beartype. See [Does beartype actually do anything?](https://beartype.readthedocs.io/en/latest/faq/#faq-o1].
-> ```
+> 2. beartype can not validate every one of elements in containers. This is not a bug. This is desgin principle of beartype. See [Does beartype actually do anything?](https://beartype.readthedocs.io/en/latest/faq/#faq-o1).
 
 ## `coerce`
 
 Type coercing automatically converts a value into the declared type during (de)serialization. If the value is incompatible e.g. value is "foo" and type is int, pyserde raises an `SerdeError`.
 
 ```python
 @serde(type_check=coerce)
-class Foo
+class Foo:
     s: str
 
 foo = Foo(10)
@@ -74,7 +75,7 @@ This is the default behavior until pyserde v0.8.3 and v0.9.x. No type coercion o
 
 ```python
 @serde
-class Foo
+class Foo:
     s: str
 
 foo = Foo(10)

docs/en/types.md

@@ -1,6 +1,8 @@
 # Types
 
-Here is the list of the supported types. See the simple example for each type in the footnotes
+Here is the list of the supported types. See the simple example for each type in the footnotes.
+
+Tip: Most standard-library containers and datetime types just work, but you can always add custom serializers for third-party types.
 
 * Primitives (int, float, str, bool) [^1]
 * Containers
@@ -34,7 +36,7 @@ Here is the list of the supported types. See the simple example for each type in
 You can write pretty complex class like this:
 ```python
 @serde
-class bar:
+class Bar:
     i: int
 
 @serde
@@ -101,7 +103,7 @@ It's recommended to exercise caution when relying on experimental features in pr
 
 ## Needs a new type support?
 
-If you need to use a type which is currently not supported in the standard library, please creat a Github issue to request. For types in third party python packages, unless it's polular like numpy, we don't plan to support it to keep pyserde as simple as possible. We recommend to use custom class or field serializer.
+If you need to use a type which is currently not supported in the standard library, please create a Github issue to request. For types in third party python packages, unless it's popular like numpy, we don't plan to support it to keep pyserde as simple as possible. We recommend to use custom class or field serializer.
 
 [^1]: See [examples/simple.py](https://github.com/yukinarit/pyserde/blob/main/examples/simple.py)