daniil-berg/marshmallow-generic
1
0
Fork 0
generated from daniil-berg/boilerplate-py
Code Issues Pull Requests Packages Projects Releases Wiki Activity

📝 Write and configure documentation

Browse Source
This commit is contained in:
Daniil Fajnberg
2023-03-11 16:17:12 +01:00
parent 72218fd2cb
commit 21c201b681
8 changed files with 234 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
src/marshmallow_generic/decorators.py
View File

@ -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)

136
src/marshmallow_generic/schema.py
View File

@ -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`
"""
...