serialite 0.3.8__tar.gz

serialite-0.3.8/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2022-2025 David R Hagen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

serialite-0.3.8/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: serialite
+Version: 0.3.8
+Summary: A serialization library for Python
+Keywords: serialization,deserialization,serde,pydantic,fastapi
+Author: David Hagen
+Author-email: David Hagen <david@drhagen.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: typing-extensions~=4.3
+Requires-Dist: fastapi>=0.100,<0.111 ; extra == 'fastapi'
+Requires-Dist: pydantic~=1.10 ; extra == 'fastapi'
+Requires-Dist: numpy>=1.25,<2 ; extra == 'numpy'
+Requires-Dist: ordered-set~=4.1 ; extra == 'ordered-set'
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/drhagen/serialite
+Provides-Extra: fastapi
+Provides-Extra: numpy
+Provides-Extra: ordered-set
+Description-Content-Type: text/markdown
+
+# Serialite
+
+Serialite is a library serializing and deserializing arbitrarily complex objects in Python. You
+apply the `@serializable` decorator to a dataclass to automatically create `to_data` and `from_data`
+methods using the type annotations. Or for more control, inherit from the `SerializableMixin` and
+implement the class attribute `__fields_serializer__`. For even more control, inherit from the 
+abstract base class `Serializer` and implement the `to_data` and `from_data` methods directly. 
+
+## Basics
+
+The abstract base class is `Serializer`:
+
+```python
+class Serializer(Generic[Output]):
+    def from_data(self, data: Json) -> DeserializationSuccess[Output]: ...
+    def to_data(self, value: Output) -> Json: ...
+```
+
+The class is generic in the type of the object that it serializes. The two abstract methods
+`from_data` and `to_data` are the key to the whole design, which revolves around getting objects to
+and from JSON-serializable data, which are objects constructed entirely of `bool`s, `int`s, 
+`float`s, `list`s, and `dict`s. Such structures can be consumed by `json.dumps` to produce a string
+and produced by `json.loads` after consuming a string. By basing the serialization around JSON
+serializable data, complex structures can be built up or torn down piece by piece while
+alternatively building up complex error messages during deserialization which pinpoint the location
+in the structure where the bad data exist.
+
+For new classes, it is recommended that the `Serializer` be implemented on the class itself. There is
+an abstract base class `Serializable` that classes can inherit from to indicate this. There is a mixin
+`SerializableMixin` that provides an implementation of `from_data` and `to_data` for any class that
+implements the `__fields_serializer` class attribute.
+
+For `dataclass`es, it is even easier. There is a decorator `serializable` that inserts
+`SerializableMixin` into the list of base classes after the `dataclass` decorator has run and also
+generates `__fields_serializer__` from the data class attributes.
+
+Finding the correct serializer for each type can be a pain, so
+`serializer(cls: type) -> Serializer` is provided as a convenience function. This is a single
+dispatch function, which looks up the serializer registered for a particular type. For example,
+`serializer(list[float])` will return `ListSerializer(FloatSerializer)`.

serialite-0.3.8/README.md

@@ -0,0 +1,40 @@
+# Serialite
+
+Serialite is a library serializing and deserializing arbitrarily complex objects in Python. You
+apply the `@serializable` decorator to a dataclass to automatically create `to_data` and `from_data`
+methods using the type annotations. Or for more control, inherit from the `SerializableMixin` and
+implement the class attribute `__fields_serializer__`. For even more control, inherit from the 
+abstract base class `Serializer` and implement the `to_data` and `from_data` methods directly. 
+
+## Basics
+
+The abstract base class is `Serializer`:
+
+```python
+class Serializer(Generic[Output]):
+    def from_data(self, data: Json) -> DeserializationSuccess[Output]: ...
+    def to_data(self, value: Output) -> Json: ...
+```
+
+The class is generic in the type of the object that it serializes. The two abstract methods
+`from_data` and `to_data` are the key to the whole design, which revolves around getting objects to
+and from JSON-serializable data, which are objects constructed entirely of `bool`s, `int`s, 
+`float`s, `list`s, and `dict`s. Such structures can be consumed by `json.dumps` to produce a string
+and produced by `json.loads` after consuming a string. By basing the serialization around JSON
+serializable data, complex structures can be built up or torn down piece by piece while
+alternatively building up complex error messages during deserialization which pinpoint the location
+in the structure where the bad data exist.
+
+For new classes, it is recommended that the `Serializer` be implemented on the class itself. There is
+an abstract base class `Serializable` that classes can inherit from to indicate this. There is a mixin
+`SerializableMixin` that provides an implementation of `from_data` and `to_data` for any class that
+implements the `__fields_serializer` class attribute.
+
+For `dataclass`es, it is even easier. There is a decorator `serializable` that inserts
+`SerializableMixin` into the list of base classes after the `dataclass` decorator has run and also
+generates `__fields_serializer__` from the data class attributes.
+
+Finding the correct serializer for each type can be a pain, so
+`serializer(cls: type) -> Serializer` is provided as a convenience function. This is a single
+dispatch function, which looks up the serializer registered for a particular type. For example,
+`serializer(list[float])` will return `ListSerializer(FloatSerializer)`.

serialite-0.3.8/pyproject.toml

@@ -0,0 +1,114 @@
+[build-system]
+requires = ["uv_build == 0.8.*"]
+build-backend = "uv_build"
+
+[project]
+name = "serialite"
+version = "0.3.8"
+description = "A serialization library for Python"
+authors = [ { name = "David Hagen", email = "david@drhagen.com" } ]
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+keywords = ["serialization", "deserialization", "serde", "pydantic", "fastapi"]
+requires-python = ">=3.12"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+dependencies = [
+    "typing_extensions ~= 4.3",
+]
+
+[project.optional-dependencies]
+fastapi = [
+    "fastapi >=0.100,<0.111",
+    "pydantic ~= 1.10",
+]
+
+numpy = [
+    "numpy >=1.25,<2",
+]
+
+ordered-set = [
+    "ordered-set ~= 4.1",
+]
+
+[project.urls]
+Repository = "https://github.com/drhagen/serialite"
+
+[dependency-groups]
+nox = [
+    "nox-uv == 0.6.*",
+]
+test = [
+    "pytest == 8.*",
+    "coverage == 7.*",
+    "httpx", # Needed by starlette testclient
+]
+lint = [
+    "ruff == 0.14.*"
+]
+
+[tool.uv]
+default-groups = "all"
+python-preference = "only-managed"
+
+[tool.coverage.run]
+branch = true
+source_pkgs = ["serialite"]
+relative_files = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:",
+]
+
+[tool.coverage.paths]
+source = [
+    "src/",
+    "**/site-packages/",
+]
+
+[tool.ruff]
+src = ["src"]
+line-length = 99
+
+[tool.ruff.lint]
+extend-select = [
+    "I", # isort
+    "N", # pep8-naming
+    "RUF", # ruff
+    "B", # flake8-bugbear
+    "N", # flake8-broken-line
+    "C4", # flake8-comprehensions
+    "PIE", # flake8-pie
+    "PT", # flake8-pytest-style
+    "PTH", # flake8-use-pathlib
+    "ERA", # flake8-eradicate
+]
+# F402: Variable shadowing is perfectly fine
+# PT011: testing for broad exceptions is fine
+extend-ignore = ["F402", "PT011"]
+
+[tool.ruff.lint.per-file-ignores]
+# F401: unused-import; Allow unused imports in __init__.py files
+"__init__.py" = ["F401"]
+
+[tool.ruff.lint.isort]
+extra-standard-library = ["typing_extensions"]
+
+[tool.ruff.lint.pep8-naming]
+classmethod-decorators = ["serialite._descriptors.classproperty"]
+
+[tool.ruff.lint.flake8-bugbear]
+extend-immutable-calls = ["serialite.field", "fastapi.Body"]

serialite-0.3.8/src/serialite/__init__.py

@@ -0,0 +1,35 @@
+from ._base import Serializable, Serializer
+from ._dataclass import field
+from ._decorators import abstract_serializable, serializable
+from ._dispatcher import serializer
+from ._fields_serializer import (
+    AccessPermissions,
+    FieldsSerializer,
+    FieldsSerializerField,
+    MultiField,
+    SingleField,
+    empty_default,
+    no_default,
+)
+from ._implementations import *  # noqa: F403
+from ._mixins import AbstractSerializableMixin, SerializableMixin
+from ._monkey_patches import (
+    monkey_patch_fastapi_create_cloned_field,
+    monkey_patch_pydantic_get_flat_models_from_model,
+    monkey_patch_pydantic_instancecheck,
+    monkey_patch_pydantic_model_type_schema,
+    monkey_patch_pydantic_subclasscheck,
+)
+from ._result import (
+    DeserializationError,
+    DeserializationFailure,
+    DeserializationResult,
+    DeserializationSuccess,
+)
+from ._stable_set import StableSet
+
+monkey_patch_pydantic_subclasscheck()
+monkey_patch_pydantic_instancecheck()
+monkey_patch_fastapi_create_cloned_field()
+monkey_patch_pydantic_get_flat_models_from_model()
+monkey_patch_pydantic_model_type_schema()

serialite-0.3.8/src/serialite/_base.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+__all__ = ["Serializable", "Serializer"]
+
+from abc import abstractmethod
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
+
+from ._descriptors import classproperty
+from ._result import DeserializationFailure, DeserializationResult
+from ._stable_set import StableSet
+
+if TYPE_CHECKING:
+    from pydantic.typing import AbstractSetIntStr, MappingIntStrAny
+
+Output = TypeVar("Output")
+SerializableOutput = TypeVar("SerializableOutput", bound="Serializable")
+
+
+class Serializer(Generic[Output]):
+    """Serialize and deserialize a particular object."""
+
+    @abstractmethod
+    def from_data(self, data: Any) -> DeserializationResult[Output]:
+        """Deserialize an object from data."""
+        raise NotImplementedError()
+
+    @abstractmethod
+    def to_data(self, value: Output) -> Any:
+        """Serialize an object to data."""
+        raise NotImplementedError()
+
+    def collect_openapi_models(
+        self, parent_models: StableSet[Serializer]
+    ) -> StableSet[Serializer]:
+        """Collect the set of OpenAPI models required for this Serializer.
+
+        `Serializer`s that represent models should return a set containing
+        themselves.
+
+        `Serializer`s with child `Serializer`s that may be models should add
+        themselves to `parent_models` and pass that to all children's
+        `collect_openapi_models` method. The parent `Serializer` and all models
+        received from children should be combined and returned.
+
+        The default is to return no models.
+        """
+        return StableSet()
+
+    def to_openapi_schema(self, refs: dict[Serializer, str], force: bool = False) -> Any:
+        """Generate the OpenAPI schema representation for this class.
+
+        Each serializer should check if its fully qualified name exists in
+        `refs` and return a '$ref', unless `force` is true, in which case it
+        should return its full schema, but not pass `force` to its child
+        serializers.
+
+        The default is no schema.
+        """
+        return {}
+
+
+class Serializable(Serializer[SerializableOutput]):
+    """Classes that serialize instances of themselves."""
+
+    # There is no way to indicate in Python's type system that
+    # type[Serializable] is an instance of Serializer. So these signatures
+    # appear inconsistent with the base class.
+    @classmethod
+    @abstractmethod
+    def from_data(cls, data: Any) -> DeserializationResult[Output]:
+        pass
+
+    @abstractmethod
+    def to_data(self: SerializableOutput) -> Any:
+        pass
+
+    @classmethod
+    def collect_openapi_models(cls, parent_models: StableSet[Serializer]) -> StableSet[Serializer]:
+        return StableSet()
+
+    @classmethod
+    def to_openapi_schema(cls, refs: dict[Serializer, str], force: bool = False) -> Any:
+        return {}
+
+    # All attributes and methods below this point are for Pydantic
+    # compatibility. These methods along with the appropriate monkey patching
+    # allow all Serialite Serializables to be used as Pydantic BaseModels.
+
+    # This flag is used by the issubclass(_, BaseModel) monkey patch to identify
+    # classes that claim to be subclasses of BaseModel.
+    _is_pydantic_base_model = True
+
+    # This flag protects dataclasses from conversion
+    __processed__ = True
+
+    @classmethod
+    def validate(cls, value: Any, values, field, config):
+        # This is the canonical name for the main Pydantic validator. It does
+        # not have to have this name as long as it is returned by
+        # __get_validators__.
+
+        # FastAPI passes in both data to be parsed and instances of the object
+        # itself for some reason. Politely return the object if we get an
+        # instance of this class.
+        if isinstance(value, cls):
+            return value
+
+        result = cls.from_data(value)
+
+        if isinstance(result, DeserializationFailure):
+            # Must raise ValueError, TypeError, or AssertionError for Pydantic
+            # to catch it. Or we could construct a Pydantic ValidationError.
+            # https://pydantic-docs.helpmanual.io/usage/validators/
+            raise ValueError(result.error)
+        else:
+            return result.or_die()
+
+    @classmethod
+    def __get_validators__(cls):
+        # FastAPI uses pydantic.fields.ModelField to convert a type hint into a
+        # Pydantic parser. ModelField relies on this field to get the parser.
+        # The call chain is here: APIRoute > get_dependant > get_param_field >
+        # create_response_field > ModelField > prepare > populate_validators >
+        # __get_validators__
+
+        yield cls.validate
+
+    @classproperty
+    def __config__(cls):
+        # FastAPI accesses this attribute in a few places. It does not matter.
+        try:
+            from pydantic import BaseConfig
+
+            return BaseConfig
+        except ImportError:
+            # Protect against auto-documentation programs trying to get all
+            # properties.
+            return None
+
+    def dict(
+        self,
+        include: AbstractSetIntStr | MappingIntStrAny = None,
+        exclude: AbstractSetIntStr | MappingIntStrAny = None,
+        by_alias: bool = False,
+        skip_defaults: bool = None,  # noqa: RUF013
+        exclude_unset: bool = False,
+        exclude_defaults: bool = False,
+        exclude_none: bool = False,
+    ):
+        # FastAPI and Pydantic can only serialize instances of the validator,
+        # which is why dict is implemented on Serializable instead of plain Serializer.
+        # Serialite Serializers simply cannot be passed directly to FastAPI.
+
+        data = self.to_data()
+        if exclude is not None:
+            data = {key: value for key, value in data.items() if key not in exclude}
+
+        if hasattr(self, "__subclass_serializers__"):
+            # Pydantic has no concept of algebraic data types. It does not use
+            # the field to determine how to serialize an object. It purely asks
+            # the object itself how it should be serialized via the dict
+            # method. This implementation of dict assumes that anytime a
+            # subclass of an abstract serializable is serialized, it was
+            # supposed to be serialized with the abstract serializer, not the
+            # concrete class. This is not a good assumption, but Pydantic is not
+            # expressive enough to have two serializers for the same object.
+            return {"_type": self.__class__.__name__} | data
+        else:
+            return data

serialite-0.3.8/src/serialite/_dataclass.py

@@ -0,0 +1,31 @@
+__all__ = ["field"]
+
+import dataclasses
+from dataclasses import MISSING, Field
+
+from ._base import Serializer
+
+
+def field(
+    *,
+    default=MISSING,
+    default_factory=MISSING,
+    serializer: Serializer | type = MISSING,
+    init: bool = True,
+    repr: bool = True,
+    hash: bool | None = None,
+    compare: bool = True,
+    metadata: dict | None = None,
+    kw_only: bool = MISSING,
+) -> Field:
+    serializer_metadata = (metadata if metadata is not None else {}) | {"serializer": serializer}
+    return dataclasses.field(
+        default=default,
+        default_factory=default_factory,
+        init=init,
+        repr=repr,
+        hash=hash,
+        compare=compare,
+        metadata=serializer_metadata,
+        kw_only=kw_only,
+    )