parityos-serialization 0.1.0__tar.gz

parityos_serialization-0.1.0/.gitignore

@@ -0,0 +1,96 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+coverage.xml
+report.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Sphinx documentation
+**/docs/_build/
+**/docs/**/generated/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery
+celerybeat-schedule
+celerybeat.pid
+
+# Environments
+*.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+uv.lock
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# IDE stuff
+*.iws
+*.iml
+**/.idea/
+**/.idea/**
+**/.vscode
+
+# Apple stuff
+.DS_Store
+
+# artifacts
+.png
+.tar
+
+# uv
+uv.toml
+

parityos_serialization-0.1.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+
+## [0.1.0] - 2026-06-10
+
+### Added
+
+ - More flexible tag creation and de-/reregistration (#139)
+ - Allow extra keywords during deserialization (#147)
+ - Remove registered cls from pass through containers (#151)
+ - Hooks take serializer (#159) 
+ - Deserialization from data missing default values fails (#160)
+ - Convenience classes for different serialization tasks (#162)
+ - More flexible mapping serialization (#163)
+ - Allow editing of pass through classes (#165)
+ - Allow flexible fall back strategies (#166)

parityos_serialization-0.1.0/LICENSE.txt

@@ -0,0 +1,37 @@
+ParityOS Client Software License Terms (BSD-3-Clause)
+=====================================================
+
+Copyright 2023 Parity Quantum Computing GmbH (ParityQC)
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS”
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+===============================================================================
+
+Parity Quantum Computing GmbH
+Rennweg 1 / Top 314 / 6020 Innsbruck, Austria
+info@parityqc.com / www.parityqc.com
+
+===============================================================================

parityos_serialization-0.1.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: parityos-serialization
+Version: 0.1.0
+Summary: Simple automatic (de)serialization of custom classes
+Project-URL: Documentation, https://docs.parityqc.com/parityos-serialization/latest
+Project-URL: Homepage, https://parityqc.com/
+Author-email: ParityQC <parityos@parityqc.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE.txt
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: attrs<26.0
+Requires-Dist: typing-extensions
+Description-Content-Type: text/markdown
+
+# ParityOS Serialization
+
+A simple automatic serialization library that is largely inspired by [cattrs](https://github.com/python-attrs/cattrs). It shares *cattrs*'s philosophy of being non-intrusive and not requiring subclassing or abstract method implementation. Instead it relies on automatic object structure deduction for [attrs](https://github.com/python-attrs/attrs) classes or dataclasses and custom (de)serialization hooks which can be registered for custom classes. This is similar to [json](https://docs.python.org/3/library/json.html#module-json)'s `default` parameter to [`dump`](https://docs.python.org/3/library/json.html#json.dump) and `object_hook` parameter to [`load`](https://docs.python.org/3/library/json.html#json.load).
+
+However with respect to *cattrs* it comes with some significant differences:
+ 
+ - All objects are serialized together with a unique class tag and the serializer relies on this information for deserialization, rather than type annotations of target fields. This alleviates many troubles *cattrs* has with deserializing subclasses of types used as type annotations.
+ - It inspects the object to serialize, not just its type, which allows e.g. serialization of classes themselves.
+ - It doesn't care about generics and typevars as all concrete type information is recorded in the serialized data. This especially allows for greater flexibility with using subclasses of generics.
+
+For more information see the [documentation](https://docs.parityqc.com/parityos-serialization/latest)
+
+## Installation
+
+It is recommended to install this package in a separate Python virtual environment. For example:
+
+```shell
+# To create a standard Python virtual environment:
+python -m venv my_new_venv && source my_new_venv/bin/activate
+# Alternatively, to create a Anaconda/Miniconda environment:
+conda create --name my_new_conda_env python=<version> && conda activate my_new_conda_env
+# or a pyenv environment
+pyenv virtualenv <version> my_new_venv && pyenv activate my_new_venv
+# or a uv managed environment
+uv venv -p <version>
+```
+where `<version>` is a python version and one of `[3.11, 3.12, 3.13]`.
+
+After activating the virtual environment, install via your favorite package manager, e.g.:
+
+```shell
+# using pip
+pip install parityos-serialization
+# using uv
+uv pip install parityos-serialization
+```
+
+## License
+
+This software package is made available under the 3-Clause BSD License. See `License.txt` for details.

parityos_serialization-0.1.0/README.md

@@ -0,0 +1,40 @@
+# ParityOS Serialization
+
+A simple automatic serialization library that is largely inspired by [cattrs](https://github.com/python-attrs/cattrs). It shares *cattrs*'s philosophy of being non-intrusive and not requiring subclassing or abstract method implementation. Instead it relies on automatic object structure deduction for [attrs](https://github.com/python-attrs/attrs) classes or dataclasses and custom (de)serialization hooks which can be registered for custom classes. This is similar to [json](https://docs.python.org/3/library/json.html#module-json)'s `default` parameter to [`dump`](https://docs.python.org/3/library/json.html#json.dump) and `object_hook` parameter to [`load`](https://docs.python.org/3/library/json.html#json.load).
+
+However with respect to *cattrs* it comes with some significant differences:
+ 
+ - All objects are serialized together with a unique class tag and the serializer relies on this information for deserialization, rather than type annotations of target fields. This alleviates many troubles *cattrs* has with deserializing subclasses of types used as type annotations.
+ - It inspects the object to serialize, not just its type, which allows e.g. serialization of classes themselves.
+ - It doesn't care about generics and typevars as all concrete type information is recorded in the serialized data. This especially allows for greater flexibility with using subclasses of generics.
+
+For more information see the [documentation](https://docs.parityqc.com/parityos-serialization/latest)
+
+## Installation
+
+It is recommended to install this package in a separate Python virtual environment. For example:
+
+```shell
+# To create a standard Python virtual environment:
+python -m venv my_new_venv && source my_new_venv/bin/activate
+# Alternatively, to create a Anaconda/Miniconda environment:
+conda create --name my_new_conda_env python=<version> && conda activate my_new_conda_env
+# or a pyenv environment
+pyenv virtualenv <version> my_new_venv && pyenv activate my_new_venv
+# or a uv managed environment
+uv venv -p <version>
+```
+where `<version>` is a python version and one of `[3.11, 3.12, 3.13]`.
+
+After activating the virtual environment, install via your favorite package manager, e.g.:
+
+```shell
+# using pip
+pip install parityos-serialization
+# using uv
+uv pip install parityos-serialization
+```
+
+## License
+
+This software package is made available under the 3-Clause BSD License. See `License.txt` for details.

parityos_serialization-0.1.0/docs/api/index.rst

@@ -0,0 +1,12 @@
+.. 
+    comment: This file only exists to trigger the recursive autosummary generation, it is not linked
+    in any TOC or referenced in any other markdown file.
+
+:orphan:
+
+.. autosummary::
+   :toctree: generated
+   :recursive:
+   :nosignatures:
+
+   parityos_serialization

parityos_serialization-0.1.0/docs/index.md

@@ -0,0 +1,26 @@
+# ParityOS Serialization
+
+A simple automatic serialization library that is largely inspired by [cattrs](https://github.com/python-attrs/cattrs). It shares *cattrs*'s philosophy of being non-intrusive and not requiring subclassing or abstract method implementation. Instead it relies on automatic object structure deduction for [attrs](https://github.com/python-attrs/attrs) classes or dataclasses and custom (de)serialization hooks which can be registered for custom classes. This is similar to [json](https://docs.python.org/3/library/json.html#module-json)'s `default` parameter to [`dump`](https://docs.python.org/3/library/json.html#json.dump) and `object_hook` parameter to [`load`](https://docs.python.org/3/library/json.html#json.load).
+
+However with respect to *cattrs* it comes with some significant differences:
+ 
+ - All objects are serialized together with a unique class tag and the serializer relies on this information for deserialization, rather than type annotations of target fields. This alleviates many troubles *cattrs* has with deserializing subclasses of types used as type annotations.
+ - It inspects the object to serialize, not just its type, which allows e.g. serialization of classes themselves.
+ - It doesn't care about generics and typevars as all concrete type information is recorded in the serialized data. This especially allows for greater flexibility with using subclasses of generics.
+
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+:caption: Documentation
+
+user_guide/index
+```
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+:caption: API Reference
+
+api/generated/parityos_serialization
+```

parityos_serialization-0.1.0/docs/user_guide/class_tagging/import_path_class_tagger.md

@@ -0,0 +1,48 @@
+# ImportPathClassTagger
+
+To remove the necessity for class registration and a mapping between class tags and classes, the {any}`ImportPathClassTagger` uses absolute import paths as class tags. This enables bootstrapping at deserialization by gradually importing all needed classes without having to know and import all involved classes beforehand. This convenience comes at the price of brittleness of serialized data against code base refactoring, especially against moving and renaming of classes. This is similar to {any}`pickle` which suffers from the same brittleness. However while pickle files are binary and import paths of involved objects cannot be retrieved or changed, the output of the Serializer is human readable and lends itself to easy refactoring if import paths that have changed between code base versions.
+
+```python
+# Example 6:
+from attrs import frozen
+from parityos_serialization.serializer import DeterministicJsonSerializer
+from parityos_serialization.utils.class_tagger import ImportPathClassTagger
+
+serializer = DeterministicJsonSerializer(class_tagger=ImportPathClassTagger())
+
+
+@frozen
+class Foo:
+    bar: int
+    baz: str
+
+
+@frozen
+class Bar(Foo):
+    fox: dict[str, int]
+
+
+obj = Bar(42, "qux", {"a": 22})
+dct = serializer.serialize(obj)
+obj2 = serializer.deserialize(dct)
+assert obj == obj2
+print(dct)
+# {
+#     "_data": {
+#         "bar": 42,
+#         "baz": "qux",
+#         "fox": {
+#             "_data": [["a", 22]],
+#             "_cls": "builtins.dict",
+#         },
+#     },
+#     "_cls": "__main__.Bar",
+# }
+```
+Here, no registration of any custom classes is necessary. In turn, the class tags contain the full import path of the serialized class objects.
+
+Notably, this strategy also works in cases where the target classes have not been imported before deserialization. 
+
+:::{caution}
+Be sure you know and trust the content of the data to be deserialized using an {any}`ImportPathClassTagger`, as it can import arbitrary modules which might contain and execute unwanted code. 
+:::

parityos_serialization-0.1.0/docs/user_guide/class_tagging/index.md

@@ -0,0 +1,19 @@
+# Class Tagging Strategies
+```{toctree}
+:hidden:
+
+name_class_tagger
+import_path_class_tagger
+```
+
+The `class_tagger` in a {any}`Serializer` is responsible for
+ - generating class tags from objects for serialization 
+ - determining the target class from a class tag in the serialized data for deserialization. 
+
+The {any}`DeterministicJsonSerializer` uses a {any}`NameClassTagger` as default, which generates tags based on class names and keeps an internal mapping between tags and imported classes. Other strategies can be used by passing other class objects that implement the {any}`ClassTagger` interface for the `class_tagger` parameter.
+
+This library supplies two built-in class taggers
+ - {any}`NameClassTagger`
+ - {any}`ImportPathClassTagger`
+
+In the {ref}`Example 2 <example-nested>` we needed to register custom classes `AFoo`, `DFoo`, `Bar`, `Parity` with the serializer's {any}`NameClassTagger`. See {doc}`NameClassTagger <name_class_tagger>` for details and {doc}`ImportPathClassTagger <import_path_class_tagger>` for a strategy where this step is not necessary. {any}`DeterministicJsonSerializer` however uses {any}`NameClassTagger` as default as it is more robust against moving classes during refactoring.

parityos_serialization-0.1.0/docs/user_guide/class_tagging/name_class_tagger.md

@@ -0,0 +1,84 @@
+# NameClassTagger
+
+It uses the *class name* of the object as a class tag and keeps an internal mapping between classes and class tags. Classes have to be explicitly registered with the class tagger by either passing a sequence of classes to the constructor or by using the {any}`register_classes <NameClassTagger.register_classes>` method. Pre-registered classes can be unregistered from an existing tagger with the {any}`deregister_classes  <NameClassTagger.deregister_classes>` method. 
+
+The following built-in python classes are pre-registered:
+- {any}`object`
+- {any}`type`
+- {any}`GenericAlias <types.GenericAlias>`
+- {any}`set`
+- {any}`frozenset`
+- {any}`list`
+- {any}`tuple`
+- {any}`dict`
+- {any}`MappingProxyType <types.MappingProxyType>`
+
+Non-built-in classes must be registered first with the class tagger before they can be deserialized.
+
+```python
+# Example 4:
+from attrs import frozen
+from parityos_serialization.serializer import DeterministicJsonSerializer
+
+
+@frozen
+class Foo:
+    bar: int
+    baz: str
+
+
+serializer = DeterministicJsonSerializer()
+serializer.class_tagger.register_classes(Foo)
+obj = Foo(42, "qux")
+dct = serializer.serialize(obj)
+obj2 = serializer.deserialize(dct)
+assert obj == obj2
+print(dct)
+# {'_data': {'bar': 42, 'baz': 'qux'}, '_cls': 'Foo'}
+```
+
+As it can be daunting and unpractical to register all classes explicitly, there is a class decorator that enables automatic registration of the decorated class together with all its subclasses down its inheritance tree:
+
+```python
+# Example 5:
+from attrs import frozen
+from parityos_serialization.serializer import DeterministicJsonSerializer
+from parityos_serialization.utils.class_tagger import NameClassTagger, register
+
+class_tagger = NameClassTagger()
+serializer = DeterministicJsonSerializer(class_tagger=class_tagger)
+
+
+@register(class_tagger)
+@frozen
+class Foo:
+    bar: int
+    baz: str
+
+
+@frozen
+class Bar(Foo):
+    fox: dict[str, int]
+
+
+obj = Bar(42, "qux", {"a": 22})
+dct = serializer.serialize(obj)
+obj2 = serializer.deserialize(dct)
+assert obj == obj2
+print(dct)
+# {
+#     "_data": {
+#         "bar": 42,
+#         "baz": "qux",
+#         "fox": {
+#             "_data": [["a", 22]],
+#             "_cls": "dict",
+#         },
+#     },
+#     "_cls": "Bar",
+# }
+```
+
+You can see that no explicit call to {any}`serializer.class_tagger.register_classes <NameClassTagger.register_classes>` was necessary. However, the class tagger object needs to be available at definition time of the classes to register for passing it as argument to the {any}`register <parityos_serialization.utils.class_tagger.register>` decorator. It is therefore often advisable to use a module constant class tagger and serializer for such purposes.
+
+At deserialization time all classes present in the serialized data must be registered with the class tagger. Consequently, all modules that contain code for registering involved classes must be imported before deserialization, even if these classes do not explicitly appear in the file that calls the deserialization.

parityos_serialization-0.1.0/docs/user_guide/custom_classes/class_hooks.md

@@ -0,0 +1,53 @@
+# Class Hooks
+To add support for e.g. {any}`complex` we register class hooks using {any}`register_class_serialization_hook <Serializer.register_class_serialization_hook>` and {any}`register_class_deserialization_hook <Serializer.register_class_deserialization_hook>`.
+
+```python
+# Example 7:
+from parityos_serialization.serializer import (
+    DeterministicJsonSerializer,
+    Serializer,
+)
+from parityos_serialization.utils.class_tagger import NameClassTagger
+from parityos_serialization.utils.typedefs import (
+    TypedDataDict,
+)
+
+
+# serialization hook
+def serialize_complex(
+    x: complex, _serializer: Serializer[TypedDataDict, NameClassTagger]
+) -> dict[str, float]:
+    return {"real": x.real, "imag": x.imag}
+
+
+# deserialization hook
+def deserialize_complex(
+    data: dict[str, float],
+    _: type[complex],
+    _serializer: Serializer[TypedDataDict, NameClassTagger],
+) -> complex:
+    return complex(data["real"], data["imag"])
+
+
+serializer = DeterministicJsonSerializer()
+serializer.register_class_serialization_hook(complex, serialize_complex)
+serializer.register_class_deserialization_hook(complex, deserialize_complex)
+serializer.class_tagger.register_classes(complex)
+
+obj = complex(4, 2)
+dct = serializer.serialize(obj)
+obj2 = serializer.deserialize(dct)
+assert obj == obj2
+print(dct)
+# {'_data': {'real': 4.0, 'imag': 2.0}, '_cls': 'complex'}
+```
+Here we have registered hooks that are used for all objects of type {any}`complex`.
+
+A *class serialization hook* is a function that takes an object of the registered class `T` and a serializer of class `S` and returns the serialized **data**. 
+This structure is formalized in the {any}`SerializeHook` type alias. The class tag will be injected by the serializer automatically, so the hook does not need to do this.
+
+A *class deserialization hook* is a function that takes the serialized data, the target class `type[T]` and a serializer of type `S` and returns an **object of type `T`** constructed from the serialized data. This structure is formalized in the {any}`DeserializeHook` type alias. The unpacking of the class tag is done by the serializer automatically and the deserialization hook will receive already unpacked serialized data and the target class `type[T]`.
+
+Registering a class hook for a class that already has a hook registered overwrites the old hook.
+
+Class hook resolution uses {any}`singledispatch <functools.singledispatch>`'s resolution method based on the object's {any}`mro <type.__mro__>`. For a mechanism to register hooks more broadly across many classes, see {doc}`Predicate Hooks <predicate_hooks>`.

parityos_serialization-0.1.0/docs/user_guide/custom_classes/index.md

@@ -0,0 +1,25 @@
+# Custom classes
+```{toctree}
+:hidden:
+
+class_hooks
+predicate_hooks
+resolution_order
+```
+
+Any classes that are not {doc}`pass-through classes <../pass_through_classes>` must be handled by registering hooks for them. {any}`DeterministicJsonSerializer` has some predefined hooks registered and thus supports (de)serialization of the following built-in types out of the box:
+
+| class                                           | output | 
+| ---                                             | ---    | 
+|{any}`tuple`                                     |{any}`list`| 
+|{any}`set`                                       |sorted {any}`list`| 
+|{any}`frozenset`                                 |sorted {any}`list`| 
+|{any}`dict`                                      |sorted {any}`list` of (key, value) pair {any}`list`s|
+|{any}`MappingProxyType  <types.MappingProxyType>`|sorted {any}`list` of (key, value) pair {any}`list`s|
+|{any}`Enum <enum.Enum>`                          |element name as {any}`str`|
+|{any}`type`                                      |class name as {any}`str`|
+|{any}`GenericAlias <types.GenericAlias>`         |{any}`dict` with fields "origin" and "args" containing the class names of origin and args classes|
+|{any}`dataclass <dataclasses.dataclass>`         |{any}`dict` with serialized fields from {any}`dataclasses.fields`|
+|{any}`attrs` classes                             |`dict` with serialized fields from {any}`attrs.fields`|
+
+For any custom classes not belonging to the built-in supported classes, {doc}`class hooks <class_hooks>` or {doc}`predicate hooks <predicate_hooks>` facilitating their (de)serialization can be registered with the serializer.

parityos_serialization-0.1.0/docs/user_guide/custom_classes/predicate_hooks.md

@@ -0,0 +1,78 @@
+# Predicate Hooks
+In contrast to {doc}`Class Hooks <class_hooks>`, predicate hooks enable registering hooks more broadly based on class or object properties, rather than just the class and its inheritance tree itself. This is done through registering boolean predicate functions together with (de)serialization hooks. They receive the object, inspect it and return `True` if the corresponding hook should be used for the object. A prime usecase example for this mechanism are {any}`DeterministicJsonSerializer`'s default hooks registered for {any}`dataclasses <dataclasses.dataclass>` and {any}`attrs` classes, which immediately catches all such class objects by inspecting whether they are dataclasses or attrs classes. Otherwise, an individual class hook would be needed for every single dataclass or attrs class, while a predicate hook can catch all such classes in one go.
+
+(example-predicate-hook)=
+```python
+# Example 8:
+from typing import Any, Protocol, Self
+
+from parityos_serialization.serializer import DeterministicJsonSerializer, Serializer
+from parityos_serialization.utils.class_tagger import NameClassTagger
+from parityos_serialization.utils.typedefs import TypedDataDict
+from typing_extensions import override
+
+
+class PointLike2D(Protocol):
+    x: int
+    y: int
+
+    @classmethod
+    def from_2d_coordinates(cls, x: int, y: int) -> Self: ...
+
+
+class Point2D:
+    x: int
+    y: int
+
+    def __init__(self, x: int, y: int) -> None:
+        self.x = x
+        self.y = y
+
+    @classmethod
+    def from_2d_coordinates(cls, x: int, y: int):
+        return cls(x, y)
+
+    @override
+    def __eq__(self, other: object) -> bool:
+        return vars(self) == vars(other)
+
+
+# serialization predicate
+def is_pointlike_obj(obj: object) -> bool:
+    return hasattr(obj, "x") and hasattr(obj, "y")
+
+
+# serialization hook
+def serialize_pointlike(
+    obj: PointLike2D, _serializer: Serializer[TypedDataDict, NameClassTagger]
+) -> dict[str, int]:
+    return {"x": obj.x, "y": obj.y}
+
+
+# deserialization predicate
+def is_pointlike_data(data: Any, _: type):
+    return isinstance(data, dict) and data.keys() == {"x", "y"}
+
+
+# deserialization hook
+def deserialize_pointlike(
+    data: dict[str, int],
+    cls: type[PointLike2D],
+    _serializer: Serializer[TypedDataDict, NameClassTagger],
+) -> PointLike2D:
+    return cls.from_2d_coordinates(data["x"], data["y"])
+
+
+serializer = DeterministicJsonSerializer()
+serializer.register_predicate_serialization_hook(is_pointlike_obj, serialize_pointlike)
+serializer.register_predicate_deserialization_hook(is_pointlike_data, deserialize_pointlike)
+serializer.class_tagger.register_classes(Point2D)
+
+obj = Point2D(4, 2)
+dct = serializer.serialize(obj)
+obj2 = serializer.deserialize(dct)
+assert obj == obj2
+print(dct)
+# {'_data': {'x': 4, 'y': 2}, '_cls': 'Point2D'}
+```
+You can imagine e.g. implementing a `Point3D` (whose `from_2d_coordinates` classmethod would just set the `z` coordinate to zero) which would also be supported by these hooks.

parityos_serialization-0.1.0/docs/user_guide/custom_classes/resolution_order.md

@@ -0,0 +1,20 @@
+# Hook Resolution Order
+Class hooks are evaluated before Predicate Hooks. Class hooks work by dictionary lookup using {any}`functools.singledispatch`'s resolution algorithm. Predicate-hook pairs are registered and stored in an ordered sequence and are evaluated in reverse order of registration, i.e. most recently registered predicates are evaluated first. This enables a hierarchical organization of predicate hook pairs from fine grained to increasing coarseness.
+
+## Serialization
+Objects are serialized in the following order of preference:
+
+1. If the *object* is an instance of one of the registered {any}`pass_through_classes <Serializer.pass_through_classes>`, the object is returned unaltered.
+2. If the *object's class* or any of its base classes has a *class serialization hook* registered for it, the corresponding hook is used.
+3. If any of the registered *serialization predicates* evaluate to `True` on the object, its corresponding serialization hook is used. 
+4. If none of the above apply, the *fallback strategy* is applied
+
+
+## Deserialization
+Likewise, objects are deserialized in the following order of preference, where `cls` is the target class corresponding to the class tag contained in the serialized data:
+
+1. If the *serialized data* is an instance of one of the registered {any}`pass_through_classes <Serializer.pass_through_classes>`, the data is returned unaltered.
+2. If `cls` or any of its base classes has a *class deserialization hook* registered for it, the corresponding hook is used.
+3. If any of the registered *deserialization predicates* evaluate to `True` on `cls` or the serialized data, the corresponding deserialization hook is used.
+4. If none of the above apply, the *fallback strategy* is applied
+

parityos_serialization-0.1.0/docs/user_guide/fallback/index.md

@@ -0,0 +1,12 @@
+# Fallback Strategies
+```{toctree}
+:hidden:
+
+pickle
+```
+The `fallback_strategy` parameter of the {any}`Serializer` defines the strategy for dealing with objects that are not pass-through classes or aren't caught by any hooks. This library offers a few preconfigured strategies as variants of the {any}`FallBackStrategy` enum:
+- `FallBackStrategy.RAISE`: raise an error for objects that are not covered otherwise.
+- `FallBackStrategy.PASS_THROUGH`: treat uncaught objects as pass-through classes.
+- `FallBackStrategy.PICKLE_INTERFACE`: use catch-all hooks utilizing the pickle interface (see {doc}`Pickle Fallback Strategy <pickle>`).
+
+Alternatively, serializers can be initialized with a custom pair of fallback catch-all serialization and deserialization hooks, packaged in a {any}`HookPair` object.

parityos_serialization-0.1.0/docs/user_guide/fallback/pickle.md

@@ -0,0 +1,9 @@
+# Pickle Fallback Strategy
+
+The pickle fallback strategy uses predefined hooks that utilize {any}`__getstate__ <object.__getstate__>` for serialization and a custom implemented {any}`__setstate__ <object.__setstate__>` if available or otherwise pickle's default strategy for restoring an object's state. Both slotted and non-slotted classes are supported.
+
+For more information about stateful objects and the pickle serialization interface, see also how to [handle stateful objects](https://docs.python.org/3/library/pickle.html#handling-stateful-objects).
+
+:::{caution}
+Pickle's default restoration strategy for dict classes just updates an object's `__dict__` attribute. There is no stable way to check which attributes a dict class expects like in slotted classes, as a newly created object has an empty `__dict__`. A dict class can therefore be restored with any `dict[str, Any]` without errors, but the resulting class object might be broken with missing or extra `__dict__` fields. The serializer thus has no way to ensure a healthy object when restoring dict classes using the pickle fallback strategy. We recommend using attrs classes, dataclasses or pure slotted classes instead.
+:::