From 094e8b93f0e245bb3f2d992495d1a24995ce9367 Mon Sep 17 00:00:00 2001 From: Daniil Fajnberg Date: Sat, 11 Mar 2023 16:17:12 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Write=20and=20configure=20docume?= =?UTF-8?q?ntation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/api_reference/decorators.md | 1 + docs/api_reference/schema.md | 1 + docs/img/ide_suggestion_user.png | Bin 0 -> 73373 bytes docs/index.md | 73 +++++++++++++- mkdocs.yaml | 17 +++- pyproject.toml | 1 + src/marshmallow_generic/decorators.py | 30 +++++- src/marshmallow_generic/schema.py | 136 ++++++++++++++++++++++---- 8 files changed, 234 insertions(+), 25 deletions(-) create mode 100644 docs/api_reference/decorators.md create mode 100644 docs/api_reference/schema.md create mode 100644 docs/img/ide_suggestion_user.png diff --git a/docs/api_reference/decorators.md b/docs/api_reference/decorators.md new file mode 100644 index 0000000..53549cb --- /dev/null +++ b/docs/api_reference/decorators.md @@ -0,0 +1 @@ +::: marshmallow_generic.decorators \ No newline at end of file diff --git a/docs/api_reference/schema.md b/docs/api_reference/schema.md new file mode 100644 index 0000000..8e0a448 --- /dev/null +++ b/docs/api_reference/schema.md @@ -0,0 +1 @@ +::: marshmallow_generic.schema diff --git a/docs/img/ide_suggestion_user.png b/docs/img/ide_suggestion_user.png new file mode 100644 index 0000000000000000000000000000000000000000..4c194363389bfbfe12548114828e1e039397c820 GIT binary patch literal 73373 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 B32FcU literal 0 HcmV?d00001 diff --git a/docs/index.md b/docs/index.md index 8532ea9..0f3b91c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,15 +1,82 @@ # marshmallow-generic -Generic schema with full typing support and minimal boilerplate +**Generic schema with full typing support and minimal boilerplate** -## Usage +--- + +**Documentation**: daniil-berg.github.io/marshmallow-generic + +**Source Code**: github.com/daniil-berg/marshmallow-generic + +--- + +Extension for `marshmallow` to make deserialization to objects easier and improve type safety. + +The main `GenericSchema` class extends `marshmallow.Schema` making it **generic** in terms of the class that data should be deserialized to, when calling `load`/`loads`. + +With `GenericSchema` there is no need to explicitly write `post_load` hooks to initialize the object anymore. 🎉 + +If the "model" class is (for example) `User`, it just needs to be passed as the type argument, when subclassing `GenericSchema`. Depending on whether `many` is `True` or not, the output of the `load`/`loads` method will then be automatically inferred as either `User` or `list[User]` by any competent type checker. ✨ + +## Usage Example + +```python +from marshmallow import fields +from marshmallow_generic import GenericSchema + + +class User: + def __init__(self, name: str, email: str) -> None: + self.name = name + self.email = email + + def __repr__(self) -> str: + return "".format(self=self) ... +class UserSchema(GenericSchema[User]): + name = fields.Str() + email = fields.Email() + + +user_data = {"name": "Monty", "email": "monty@python.org"} +schema = UserSchema() +single_user = schema.load(user_data) +print(single_user) # + +json_data = '''[ + {"name": "Monty", "email": "monty@python.org"}, + {"name": "Ronnie", "email": "ronnie@stones.com"} +]''' +multiple_users = schema.loads(json_data, many=True) +print(multiple_users) # [, ] +``` + +Adding `reveal_type(single_user)` and `reveal_type(multiple_users)` at the bottom and running that code through `mypy` would yield the following output: + +``` +# note: Revealed type is "User" +# note: Revealed type is "builtins.list[User]" +``` + +With the regular `marshmallow.Schema`, the output of `mypy` would instead be this: + +``` +# note: Revealed type is "Any" +# note: Revealed type is "Any" +``` + +This also means your IDE will be able to infer the types and thus provide useful auto-suggestions for the loaded objects. 👨‍💻 + +Here is PyCharm with the example from above: + +![Image title](img/ide_suggestion_user.png){ width="540" } + ## Installation `pip install marshmallow-generic` ## Dependencies -Python Version ..., OS ... +Python Version `3.9+` and `marshmallow` (duh) diff --git a/mkdocs.yaml b/mkdocs.yaml index 5a41e3d..2b927c5 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -26,13 +26,28 @@ extra_css: plugins: - search - - mkdocstrings + - mkdocstrings: + handlers: + python: + options: + show_source: false + show_root_toc_entry: false + import: + - https://marshmallow.readthedocs.io/en/stable/objects.inv markdown_extensions: - admonition - codehilite - extra - pymdownx.superfences + - toc: + permalink: true + +watch: + - src nav: - Home: index.md + - 'API Reference': + - api_reference/schema.md + - api_reference/decorators.md diff --git a/pyproject.toml b/pyproject.toml index 9086c39..5182983 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -120,6 +120,7 @@ ignore = [ "D203", # 1 blank line required before class docstring -> D211 is better "D212", # Multi-line docstring summary should start at the first line -> ugly, D212 is better "D401", # First line of docstring should be in imperative mood -> no, it shouldn't + "D407", # Missing dashed underline after section -> different docstring style ] [tool.ruff.per-file-ignores] diff --git a/src/marshmallow_generic/decorators.py b/src/marshmallow_generic/decorators.py index 9d672a5..93f50b3 100644 --- a/src/marshmallow_generic/decorators.py +++ b/src/marshmallow_generic/decorators.py @@ -1,4 +1,8 @@ -"""Typed overloads for some of the `marshmallow.decorators` module.""" +""" +Typed overloads for the [`marshmallow.decorators`][marshmallow.decorators] module. + +Implements decorators as generic in terms of the decorated method types. +""" from collections.abc import Callable from typing import Any, Optional, TypeVar, overload @@ -34,9 +38,31 @@ def post_load( pass_original: bool = False, ) -> Callable[..., Any]: """ - Typed overload of the original `marshmallow.post_load` decorator function. + Register a method to invoke after deserializing an object. + Typed overload of the original [`marshmallow.post_load`] + [marshmallow.post_load] decorator function. Generic to ensure that the decorated function retains its type. Runtime behavior is unchanged. + + Receives the deserialized data and returns the processed data. + By default it receives a single object at a time, transparently handling + the `many` argument passed to the [`Schema.load`][marshmallow.Schema.load] + call. + + Args: + fn (Optional[Callable[P, R]]): + The function to decorate or `None`; if a function is supplied, + a decorated version of it is returned; if `None` the decorator + is returned with its other arguments already bound. + pass_many: + If `True`, the raw data (which may be a collection) is passed + pass_original: + If `True`, the original data (before deserializing) will be passed + as an additional argument to the method + + Returns: + (Callable[P, R]): if `fn` is passed a function + (Callable[[Callable[P, R]], Callable[P, R]]): if `fn` is `None` """ return _post_load(fn, pass_many=pass_many, pass_original=pass_original) diff --git a/src/marshmallow_generic/schema.py b/src/marshmallow_generic/schema.py index 797faac..8e68ecd 100644 --- a/src/marshmallow_generic/schema.py +++ b/src/marshmallow_generic/schema.py @@ -1,4 +1,9 @@ -"""Definition of the `GenericSchema` base class.""" +""" +Definition of the `GenericSchema` base class. + +For details about the inherited methods and attributes, see the official +documentation of [`marshmallow.Schema`][marshmallow.Schema]. +""" from collections.abc import Iterable, Mapping, Sequence from typing import TYPE_CHECKING, Any, Literal, Optional, TypeVar, Union, overload @@ -8,23 +13,58 @@ from marshmallow import Schema from ._util import GenericInsightMixin from .decorators import post_load -_T = TypeVar("_T") +Model = TypeVar("Model") -class GenericSchema(GenericInsightMixin[_T], Schema): +class GenericSchema(GenericInsightMixin[Model], Schema): """ - Schema parameterized by the class it deserializes data to. + Generic schema parameterized by a **`Model`** class. + + Data will always be deserialized to instances of that **`Model`** class. + + !!! note + The **`Model`** referred to throughout the documentation is a + **type variable**, not any concrete class. For more information about + type variables, see the "Generics" section in + [PEP 484](https://peps.python.org/pep-0484/#generics). Registers a `post_load` hook to pass validated data to the constructor - of the specified class. + of the specified **`Model`**. - Requires a specific (non-generic) class to be passed as the type argument - for deserialization to work properly. + Requires a specific (non-generic) class to be passed as the **`Model`** + type argument for deserialization to work properly: + + ```python + class Foo: # Model + ... + + class FooSchema(GenericSchema[Foo]): + ... + ``` """ @post_load - def instantiate(self, data: dict[str, Any], **_kwargs: Any) -> _T: - """Unpacks `data` into the constructor of the specified type.""" + def instantiate(self, data: dict[str, Any], **_kwargs: Any) -> Model: + """ + Unpacks `data` into the constructor of the specified **`Model`**. + + Registered as a [`@post_load`] + [marshmallow_generic.decorators.post_load] hook for the schema. + + !!! warning + You should probably **not** use this method directly; + no parsing, transformation or validation of any kind is done + in this method. The `data` passed to the **`Model`** constructor + "as is". + + Args: + data: + The validated data after deserialization; will be unpacked + into the constructor of the specified **`Model`** class. + + Returns: + Instance of the schema's **`Model`** initialized with `**data` + """ return self._get_type_arg()(**data) if TYPE_CHECKING: @@ -37,7 +77,7 @@ class GenericSchema(GenericInsightMixin[_T], Schema): many: Literal[True], partial: Union[bool, Sequence[str], set[str], None] = None, unknown: Optional[str] = None, - ) -> list[_T]: + ) -> list[Model]: ... @overload @@ -48,7 +88,7 @@ class GenericSchema(GenericInsightMixin[_T], Schema): many: Optional[Literal[False]] = None, partial: Union[bool, Sequence[str], set[str], None] = None, unknown: Optional[str] = None, - ) -> _T: + ) -> Model: ... def load( @@ -58,12 +98,40 @@ class GenericSchema(GenericInsightMixin[_T], Schema): many: Optional[bool] = None, partial: Union[bool, Sequence[str], set[str], None] = None, unknown: Optional[str] = None, - ) -> Union[list[_T], _T]: + ) -> Union[list[Model], Model]: """ - Same as `marshmallow.Schema.load` at runtime. + Deserializes data to objects of the specified **`Model`** class. + + Same as [`marshmallow.Schema.load`] + [marshmallow.schema.Schema.load] at runtime, but data will always + pass through the [`instantiate`] + [marshmallow_generic.schema.GenericSchema.instantiate] + hook after deserialization. Annotations ensure that type checkers will infer the return type - correctly based on the type argument passed to a specific subclass. + correctly based on the **`Model`** type argument of the class. + + Args: + data: + The data to deserialize + many: + Whether to deserialize `data` as a collection. If `None`, + the value for `self.many` is used. + partial: + Whether to ignore missing fields and not require any + fields declared. Propagates down to [`Nested`] + [marshmallow.fields.Nested] fields as well. If its value + is an iterable, only missing fields listed in that + iterable will be ignored. Use dot delimiters to specify + nested fields. + unknown: + Whether to exclude, include, or raise an error for unknown + fields in the data. Use `EXCLUDE`, `INCLUDE` or `RAISE`. + If `None`, the value for `self.unknown` is used. + + Returns: + (Model): if `many` is set to `False` + (list[Model]): if `many` is set to `True` """ ... @@ -76,7 +144,7 @@ class GenericSchema(GenericInsightMixin[_T], Schema): partial: Union[bool, Sequence[str], set[str], None] = None, unknown: Optional[str] = None, **kwargs: Any, - ) -> list[_T]: + ) -> list[Model]: ... @overload @@ -88,7 +156,7 @@ class GenericSchema(GenericInsightMixin[_T], Schema): partial: Union[bool, Sequence[str], set[str], None] = None, unknown: Optional[str] = None, **kwargs: Any, - ) -> _T: + ) -> Model: ... def loads( @@ -99,11 +167,41 @@ class GenericSchema(GenericInsightMixin[_T], Schema): partial: Union[bool, Sequence[str], set[str], None] = None, unknown: Optional[str] = None, **kwargs: Any, - ) -> Union[list[_T], _T]: + ) -> Union[list[Model], Model]: """ - Same as `marshmallow.Schema.loads` at runtime. + Deserializes data to objects of the specified **`Model`** class. + + Same as [`marshmallow.Schema.loads`] + [marshmallow.schema.Schema.loads] at runtime, but data will always + pass through the [`instantiate`] + [marshmallow_generic.schema.GenericSchema.instantiate] + hook after deserialization. Annotations ensure that type checkers will infer the return type - correctly based on the type argument passed to a specific subclass. + correctly based on the **`Model`** type argument of the class. + + Args: + json_data: + A JSON string of the data to deserialize + many: + Whether to deserialize `data` as a collection. If `None`, + the value for `self.many` is used. + partial: + Whether to ignore missing fields and not require any + fields declared. Propagates down to [`Nested`] + [marshmallow.fields.Nested] fields as well. If its value + is an iterable, only missing fields listed in that + iterable will be ignored. Use dot delimiters to specify + nested fields. + unknown: + Whether to exclude, include, or raise an error for unknown + fields in the data. Use `EXCLUDE`, `INCLUDE` or `RAISE`. + If `None`, the value for `self.unknown` is used. + **kwargs: + Passed to the JSON decoder + + Returns: + (Model): if `many` is set to `False` + (list[Model]): if `many` is set to `True` """ ...