From 7305bb7832238130dc11307b04804ff171511ddc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tin=20Tvrtkovi=C4=87?= Date: Thu, 31 Aug 2023 00:02:28 +0200 Subject: [PATCH] Doc improvements --- docs/index.md | 3 ++- docs/structuring.md | 7 ++++--- docs/unions.md | 12 ++++++++---- src/cattrs/converters.py | 18 ++++++++---------- 4 files changed, 22 insertions(+), 18 deletions(-) diff --git a/docs/index.md b/docs/index.md index 8b6c89f7..e6a06b01 100644 --- a/docs/index.md +++ b/docs/index.md @@ -14,9 +14,10 @@ strategies validation preconf unions +history benchmarking contributing -history +API ``` ```{include} ../README.md diff --git a/docs/structuring.md b/docs/structuring.md index 121deed2..f410567c 100644 --- a/docs/structuring.md +++ b/docs/structuring.md @@ -154,7 +154,7 @@ to deques are: - `Deque[T]` - `deque[T]` -In all cases, a new **unbounded** deque (`maxlen=None`) will be returned, +In all cases, a new **unbounded** deque (`maxlen=None`) will be returned, so this operation can be used to copy an iterable into a deque. If you want to convert into bounded `deque`, registering a custom structuring hook is a good approach. @@ -173,6 +173,7 @@ deque(['1', None, '3']) ``` ```{versionadded} 23.1.0 + ``` ### Sets and Frozensets @@ -384,10 +385,10 @@ Another option is to use a custom tagged union strategy (see [Strategies - Tagge [PEP 593](https://www.python.org/dev/peps/pep-0593/) annotations (`typing.Annotated[type, ...]`) are supported and are matched using the first type present in the annotated type. -### `typing.NewType` +## `typing.NewType` [NewTypes](https://docs.python.org/3/library/typing.html#newtype) are supported and are structured according to the rules for their underlying type. -Their hooks can also be overriden using :py:attr:`cattrs.Converter.register_structure_hook`. +Their hooks can also be overriden using {meth}`Converter.register_structure_hook() `. ```{doctest} diff --git a/docs/unions.md b/docs/unions.md index 7fdbbc9b..4385bc91 100644 --- a/docs/unions.md +++ b/docs/unions.md @@ -1,10 +1,14 @@ -# Tips for handling unions +# Tips for Handling Unions This sections contains information for advanced union handling. -As mentioned in the structuring section, _cattrs_ is able to handle simple -unions of _attrs_ classes automatically. More complex cases require -converter customization (since there are many ways of handling unions). +As mentioned in the structuring section, _cattrs_ is able to handle simple unions of _attrs_ classes automatically. +More complex cases require converter customization (since there are many ways of handling unions). + +_cattrs_ also comes with a number of strategies to help handle unions: + +- [tagged unions strategy](strategies.md#tagged-unions-strategy) mentioned below +- [union passthrough strategy](strategies.md#union-passthrough), which is preapplied to all the [preconfigured](preconf.md) converters ## Unstructuring unions with extra metadata diff --git a/src/cattrs/converters.py b/src/cattrs/converters.py index e0320c28..4d7e8a30 100644 --- a/src/cattrs/converters.py +++ b/src/cattrs/converters.py @@ -279,11 +279,10 @@ def register_unstructure_hook_factory( """ Register a hook factory for a given predicate. - A predicate is a function that, given a type, returns whether the factory - can produce a hook for that type. - - A factory is a callable that, given a type, produces an unstructuring - hook for that type. This unstructuring hook will be cached. + :param predicate: A function that, given a type, returns whether the factory + can produce a hook for that type. + :param factory: A callable that, given a type, produces an unstructuring + hook for that type. This unstructuring hook will be cached. """ self._unstructure_func.register_func_list([(predicate, factory, True)]) @@ -326,11 +325,10 @@ def register_structure_hook_factory( """ Register a hook factory for a given predicate. - A predicate is a function that, given a type, returns whether the factory - can produce a hook for that type. - - A factory is a callable that, given a type, produces a structuring - hook for that type. This structuring hook will be cached. + :param predicate: A function that, given a type, returns whether the factory + can produce a hook for that type. + :param factory: A callable that, given a type, produces a structuring + hook for that type. This structuring hook will be cached. """ self._structure_func.register_func_list([(predicate, factory, True)])