serializable 1.3.2__tar.gz → 1.3.4__tar.gz

{serializable-1.3.2/serializable.egg-info → serializable-1.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: serializable
-Version: 1.3.2
+Version: 1.3.4
 Summary: Base class with serialization helpers for user-defined Python objects
 Author-email: Alex Rubinsteyn <alex.rubinsteyn@unc.edu>
 License:                                  Apache License
@@ -231,15 +231,22 @@ Requires-Dist: build; extra == "dev"
 Requires-Dist: twine; extra == "dev"
 Dynamic: license-file
 
-[![Tests](https://github.com/openvax/serializable/actions/workflows/tests.yml/badge.svg)](https://github.com/openvax/serializable/actions/workflows/tests.yml)
-<a href="https://pypi.python.org/pypi/serializable/">
-<img src="https://img.shields.io/pypi/v/serializable.svg?maxAge=1000" alt="PyPI" />
-</a>
+[![Tests](https://github.com/openvax/serializable/actions/workflows/tests.yml/badge.svg?branch=master)](https://github.com/openvax/serializable/actions/workflows/tests.yml)
+[![Documentation](https://github.com/openvax/serializable/actions/workflows/documentation.yml/badge.svg?branch=master)](https://openvax.github.io/serializable/)
+[![PyPI](https://img.shields.io/pypi/v/serializable.svg)](https://pypi.org/project/serializable/)
 [![PyPI downloads](https://img.shields.io/pypi/dm/serializable.svg)](https://pypistats.org/packages/serializable)
 
 # serializable
 
-Base class with serialization methods for user-defined Python objects
+serializable saves Python objects as JSON or pickles and reconstructs the same
+classes, including nested objects. Subclass `DataclassSerializable` for a
+dataclass, or `Serializable` for a class whose constructor arguments describe
+its state. It is the serialization layer of the OpenVax libraries:
+[varcode](https://github.com/openvax/varcode) and
+[vaxrank](https://github.com/openvax/vaxrank) results,
+[pyensembl](https://github.com/openvax/pyensembl) genomes and
+[sercol](https://github.com/openvax/sercol) collections all save and reload
+through it.
 
 ## Install
 
@@ -247,9 +254,9 @@ Base class with serialization methods for user-defined Python objects
 python -m pip install serializable
 ```
 
-## `DataclassSerializable` for `@dataclass` subclasses
+Python 3.11 or later is required.
 
-If you're using `@dataclass` (e.g. in `vaxrank`, `pyensembl`, or `varcode`), inherit from `DataclassSerializable` instead of `Serializable`. It provides the same serialization surface — `to_dict` / `from_dict` / `to_json` / `from_json` — but leaves `__init__`, `__eq__`, `__repr__`, and `__hash__` to `@dataclass`, so you get dataclass-native equality and repr without conflicts.
+## Quick start
 
 ```python
 from dataclasses import dataclass
@@ -260,44 +267,53 @@ class Point(DataclassSerializable):
     x: float
     y: float
 
-p = Point(1.0, 2.0)
-assert Point.from_json(p.to_json()) == p
+point = Point(1.0, 2.0)
+restored = Point.from_json(point.to_json())
+print(point.to_dict())
+print(restored)
+print(restored == point)
 ```
 
-The on-wire JSON format is identical to `Serializable`, so mixed codebases interoperate: a `DataclassSerializable` instance can reference a legacy `Serializable` object (and vice versa) and still round-trip cleanly. The `_SERIALIZABLE_KEYWORD_ALIASES` hook works the same way for migrating field names across releases.
-
-## Usage
-
-Classes which inherit from `Serializable` are enabled with default implementations of
-`to_json`, `from_json`, `__reduce__` (for pickling), and other serialization
-helpers.
-
-A derived class must either:
+```text
+{'x': 1.0, 'y': 2.0}
+Point(x=1.0, y=2.0)
+True
+```
 
-- have a member data matching the name of each positional argument to `__init__`
-- provide a user-defined `to_dict()` method which returns a dictionary whose keys match the arguments to `__init__`
+`to_dict()` gives the constructor fields; `to_json()` also records the class
+and its module so `from_json()` can rebuild it. The dataclass keeps its own
+generated constructor, equality, representation and hashing. The recorded module and
+class must be importable when loading, so load data only from sources you
+trust.
 
-Keyword-only arguments to `__init__` (those after `*`) are left out of the default `to_dict()`, so they can be used for constructor options which aren't part of an object's serialized state.
+## Documentation
 
-Pickling goes through the same `to_dict()` / `from_dict()` pair, so pickles also survive renamed keywords (see below). Pickles written by versions before 1.2.0 can still be loaded.
+The [documentation](https://openvax.github.io/serializable/) covers, in
+reading order:
 
-If you change the keyword arguments to a class which derives from `Serializable` but would like to be able to deserialize older JSON representations then you can define a class-level dictionary called `_SERIALIZABLE_KEYWORD_ALIASES` which maps old keywords to new names (or `None` if a keyword was removed).
+1. [Getting started](https://openvax.github.io/serializable/): the example
+   above, choosing a base class, and the format's limits.
+2. [Save classes and files](https://openvax.github.io/serializable/guides/objects/):
+   constructor-based classes, JSON files, pickles and nested containers.
+3. [Change field names](https://openvax.github.io/serializable/guides/migration/):
+   read data written before a constructor argument was renamed.
+4. [API reference](https://openvax.github.io/serializable/reference/).
 
-## Limitations
+## Development
 
-The format records Python classes and modules, which must remain importable when
-loading data. Keys starting with two underscores are reserved. Nested Python
-values require the serialization helpers rather than ordinary JSON encoding.
-`to_json` raises `ValueError` for NaN or infinite floats, which standard JSON
-can't represent; `from_json` still reads the `NaN` / `Infinity` literals which
-older versions wrote.
+```sh
+python -m pip install -e ".[dev]"   # or ./develop.sh, which uses .venv
+./format.sh   # ruff format
+./lint.sh     # ruff check, ruff format --check and mypy
+./test.sh     # pytest with coverage
+python -m pip install -r requirements-docs.txt
+./docs.sh     # mkdocs build --strict, then a rendered-link check
+python scripts/check_docs_examples.py   # run docs examples, compare output
+```
 
-## Documentation
+Every PR bumps `serializable/version.py`. Maintainers release with
+`./deploy.sh` from a clean `master`.
 
-- [Save classes, files and nested objects](docs/guides/objects.md)
-- [Migrate field names](docs/guides/migration.md)
-- [API reference](docs/reference.md)
-- [Writing and checking docs](docs/dev/documentation-style.md)
+## License
 
-The site builds with `python -m pip install -r requirements-docs.txt` followed
-by `./docs.sh`. Run `python scripts/check_docs_examples.py` to check the examples.
+Apache 2.0; see [LICENSE](https://github.com/openvax/serializable/blob/master/LICENSE).

serializable-1.3.4/README.md

@@ -0,0 +1,86 @@
+[![Tests](https://github.com/openvax/serializable/actions/workflows/tests.yml/badge.svg?branch=master)](https://github.com/openvax/serializable/actions/workflows/tests.yml)
+[![Documentation](https://github.com/openvax/serializable/actions/workflows/documentation.yml/badge.svg?branch=master)](https://openvax.github.io/serializable/)
+[![PyPI](https://img.shields.io/pypi/v/serializable.svg)](https://pypi.org/project/serializable/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/serializable.svg)](https://pypistats.org/packages/serializable)
+
+# serializable
+
+serializable saves Python objects as JSON or pickles and reconstructs the same
+classes, including nested objects. Subclass `DataclassSerializable` for a
+dataclass, or `Serializable` for a class whose constructor arguments describe
+its state. It is the serialization layer of the OpenVax libraries:
+[varcode](https://github.com/openvax/varcode) and
+[vaxrank](https://github.com/openvax/vaxrank) results,
+[pyensembl](https://github.com/openvax/pyensembl) genomes and
+[sercol](https://github.com/openvax/sercol) collections all save and reload
+through it.
+
+## Install
+
+```sh
+python -m pip install serializable
+```
+
+Python 3.11 or later is required.
+
+## Quick start
+
+```python
+from dataclasses import dataclass
+from serializable import DataclassSerializable
+
+@dataclass
+class Point(DataclassSerializable):
+    x: float
+    y: float
+
+point = Point(1.0, 2.0)
+restored = Point.from_json(point.to_json())
+print(point.to_dict())
+print(restored)
+print(restored == point)
+```
+
+```text
+{'x': 1.0, 'y': 2.0}
+Point(x=1.0, y=2.0)
+True
+```
+
+`to_dict()` gives the constructor fields; `to_json()` also records the class
+and its module so `from_json()` can rebuild it. The dataclass keeps its own
+generated constructor, equality, representation and hashing. The recorded module and
+class must be importable when loading, so load data only from sources you
+trust.
+
+## Documentation
+
+The [documentation](https://openvax.github.io/serializable/) covers, in
+reading order:
+
+1. [Getting started](https://openvax.github.io/serializable/): the example
+   above, choosing a base class, and the format's limits.
+2. [Save classes and files](https://openvax.github.io/serializable/guides/objects/):
+   constructor-based classes, JSON files, pickles and nested containers.
+3. [Change field names](https://openvax.github.io/serializable/guides/migration/):
+   read data written before a constructor argument was renamed.
+4. [API reference](https://openvax.github.io/serializable/reference/).
+
+## Development
+
+```sh
+python -m pip install -e ".[dev]"   # or ./develop.sh, which uses .venv
+./format.sh   # ruff format
+./lint.sh     # ruff check, ruff format --check and mypy
+./test.sh     # pytest with coverage
+python -m pip install -r requirements-docs.txt
+./docs.sh     # mkdocs build --strict, then a rendered-link check
+python scripts/check_docs_examples.py   # run docs examples, compare output
+```
+
+Every PR bumps `serializable/version.py`. Maintainers release with
+`./deploy.sh` from a clean `master`.
+
+## License
+
+Apache 2.0; see [LICENSE](https://github.com/openvax/serializable/blob/master/LICENSE).

{serializable-1.3.2 → serializable-1.3.4}/serializable/dataclass_serializable.py

@@ -45,6 +45,7 @@ from dataclasses import fields
 from typing import Any, ClassVar, Optional, TypeVar
 
 from .helpers import from_json, to_json
+from .keyword_aliases import apply_keyword_aliases
 
 _T = TypeVar("_T", bound="DataclassSerializable")
 
@@ -73,21 +74,15 @@ class DataclassSerializable:
     def from_dict(cls: type[_T], state_dict: Mapping[str, Any]) -> _T:
         """Reconstruct an instance from a ``to_dict``-shaped dictionary,
         applying ``_SERIALIZABLE_KEYWORD_ALIASES`` for backwards compat."""
-        kwargs = dict(state_dict)
-        for klass in cls.__mro__:
-            aliases = getattr(klass, "_SERIALIZABLE_KEYWORD_ALIASES", {})
-            for old_name, new_name in aliases.items():
-                if old_name in kwargs:
-                    value = kwargs.pop(old_name)
-                    if new_name is not None and new_name not in kwargs:
-                        kwargs[new_name] = value
-        return cls(**kwargs)
+        return cls(**apply_keyword_aliases(cls, dict(state_dict)))
 
     def to_json(self) -> str:
+        """Return a JSON string from which ``from_json`` rebuilds this object."""
         return to_json(self)
 
     @classmethod
     def from_json(cls: type[_T], json_string: str) -> _T:
+        """Reconstruct an object from a string produced by ``to_json``."""
         return from_json(json_string)
 
     def __reduce__(self) -> tuple[Any, ...]:

{serializable-1.3.2 → serializable-1.3.4}/serializable/helpers.py

@@ -57,6 +57,13 @@ def _class_init_arg_names(cls):
 
 
 def simple_object_to_dict(self: object) -> dict[str, Any]:
+    """
+    Map each positional __init__ argument name of an object's class to the
+    attribute of the same name. This is Serializable's default to_dict.
+
+    Raises AttributeError if the object has no attribute for an argument, and
+    ValueError if its class's __init__ arguments can't be determined.
+    """
     return {name: getattr(self, name) for name in init_arg_names(self)}
 
 
@@ -100,6 +107,9 @@ def class_from_serializable_representation(class_repr):
 
 
 def get_module_name(obj):
+    """
+    Name of the module where a class or function is defined (its __module__).
+    """
     module_name = obj.__module__
     return module_name
 
@@ -143,6 +153,11 @@ SERIALIZED_DICTIONARY_KEYS_ELEMENT_PREFIX = SERIALIZED_DICTIONARY_KEYS_FIELD + "
 
 
 def index_to_serialized_key_name(index):
+    """
+    Placeholder key, such as __serialized_keys__element_3, that stands for the
+    non-string dictionary key at this index of the serialized key list.
+    Inverse of parse_serialized_keys_index.
+    """
     return f"{SERIALIZED_DICTIONARY_KEYS_ELEMENT_PREFIX}{index:d}"
 
 
@@ -246,6 +261,10 @@ def from_serializable_dict(x):
 
 
 def list_to_serializable_repr(x):
+    """
+    Convert each element of a list (or other iterable) with to_serializable_repr,
+    returning a new list.
+    """
     return [to_serializable_repr(element) for element in x]
 
 

serializable-1.3.4/serializable/keyword_aliases.py

@@ -0,0 +1,57 @@
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Migrate renamed or removed constructor keywords when loading old data.
+
+Both ``Serializable`` and ``DataclassSerializable`` let a class declare
+``_SERIALIZABLE_KEYWORD_ALIASES``, a dict mapping an old keyword to its new
+name, or to ``None`` if the keyword was removed.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def apply_keyword_aliases(cls: type, kwargs: dict[str, Any]) -> dict[str, Any]:
+    """
+    Rename or drop old keyword arguments using a class's declared aliases.
+
+    Every class in ``cls``'s method resolution order contributes its
+    ``_SERIALIZABLE_KEYWORD_ALIASES``. For each ``old_name -> new_name`` pair
+    whose ``old_name`` is in ``kwargs``, the old entry is removed. Its value is
+    stored under ``new_name`` unless ``new_name`` is ``None`` or empty (the
+    keyword was removed) or ``kwargs`` already has a value for ``new_name``
+    (the current name wins).
+
+    Parameters
+    ----------
+    cls : type
+        Class whose aliases apply, typically the class being reconstructed.
+
+    kwargs : dict
+        Keyword arguments for ``cls``'s constructor. Modified in place.
+
+    Returns
+    -------
+    dict
+        The same ``kwargs`` object, updated.
+    """
+    for klass in cls.__mro__:
+        aliases = getattr(klass, "_SERIALIZABLE_KEYWORD_ALIASES", {})
+        for old_name, new_name in aliases.items():
+            if old_name in kwargs:
+                value = kwargs.pop(old_name)
+                if new_name and new_name not in kwargs:
+                    kwargs[new_name] = value
+    return kwargs

{serializable-1.3.2 → serializable-1.3.4}/serializable/serializable.py

@@ -18,6 +18,7 @@ from collections.abc import Mapping
 from typing import Any, ClassVar, Optional, TypeVar, Union
 
 from .helpers import from_json, simple_object_to_dict, to_json
+from .keyword_aliases import apply_keyword_aliases
 
 _T = TypeVar("_T", bound="Serializable")
 
@@ -75,18 +76,11 @@ class Serializable:
     @classmethod
     def _update_kwargs(cls, kwargs: dict[str, Any]) -> dict[str, Any]:
         """
-        Rename any old keyword arguments to preserve backwards compatibility
-        """
-        # check every class in the inheritance chain for its own
-        # definition of _SERIALIZABLE_KEYWORD_ALIASES
-        for klass in cls.mro():
-            keyword_rename_dict = getattr(klass, "_SERIALIZABLE_KEYWORD_ALIASES", {})
-            for old_name, new_name in keyword_rename_dict.items():
-                if old_name in kwargs:
-                    old_value = kwargs.pop(old_name)
-                    if new_name and new_name not in kwargs:
-                        kwargs[new_name] = old_value
-        return kwargs
+        Rename any old keyword arguments to preserve backwards compatibility.
+
+        Kept as an overridable hook for from_dict; see apply_keyword_aliases.
+        """
+        return apply_keyword_aliases(cls, kwargs)
 
     @classmethod
     def from_dict(cls: type[_T], state_dict: Mapping[str, Any]) -> _T:

{serializable-1.3.2 → serializable-1.3.4}/serializable/version.py

@@ -1,4 +1,4 @@
-__version__ = "1.3.2"
+__version__ = "1.3.4"
 
 
 def print_version():

{serializable-1.3.2 → serializable-1.3.4/serializable.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: serializable
-Version: 1.3.2
+Version: 1.3.4
 Summary: Base class with serialization helpers for user-defined Python objects
 Author-email: Alex Rubinsteyn <alex.rubinsteyn@unc.edu>
 License:                                  Apache License
@@ -231,15 +231,22 @@ Requires-Dist: build; extra == "dev"
 Requires-Dist: twine; extra == "dev"
 Dynamic: license-file
 
-[![Tests](https://github.com/openvax/serializable/actions/workflows/tests.yml/badge.svg)](https://github.com/openvax/serializable/actions/workflows/tests.yml)
-<a href="https://pypi.python.org/pypi/serializable/">
-<img src="https://img.shields.io/pypi/v/serializable.svg?maxAge=1000" alt="PyPI" />
-</a>
+[![Tests](https://github.com/openvax/serializable/actions/workflows/tests.yml/badge.svg?branch=master)](https://github.com/openvax/serializable/actions/workflows/tests.yml)
+[![Documentation](https://github.com/openvax/serializable/actions/workflows/documentation.yml/badge.svg?branch=master)](https://openvax.github.io/serializable/)
+[![PyPI](https://img.shields.io/pypi/v/serializable.svg)](https://pypi.org/project/serializable/)
 [![PyPI downloads](https://img.shields.io/pypi/dm/serializable.svg)](https://pypistats.org/packages/serializable)
 
 # serializable
 
-Base class with serialization methods for user-defined Python objects
+serializable saves Python objects as JSON or pickles and reconstructs the same
+classes, including nested objects. Subclass `DataclassSerializable` for a
+dataclass, or `Serializable` for a class whose constructor arguments describe
+its state. It is the serialization layer of the OpenVax libraries:
+[varcode](https://github.com/openvax/varcode) and
+[vaxrank](https://github.com/openvax/vaxrank) results,
+[pyensembl](https://github.com/openvax/pyensembl) genomes and
+[sercol](https://github.com/openvax/sercol) collections all save and reload
+through it.
 
 ## Install
 
@@ -247,9 +254,9 @@ Base class with serialization methods for user-defined Python objects
 python -m pip install serializable
 ```
 
-## `DataclassSerializable` for `@dataclass` subclasses
+Python 3.11 or later is required.
 
-If you're using `@dataclass` (e.g. in `vaxrank`, `pyensembl`, or `varcode`), inherit from `DataclassSerializable` instead of `Serializable`. It provides the same serialization surface — `to_dict` / `from_dict` / `to_json` / `from_json` — but leaves `__init__`, `__eq__`, `__repr__`, and `__hash__` to `@dataclass`, so you get dataclass-native equality and repr without conflicts.
+## Quick start
 
 ```python
 from dataclasses import dataclass
@@ -260,44 +267,53 @@ class Point(DataclassSerializable):
     x: float
     y: float
 
-p = Point(1.0, 2.0)
-assert Point.from_json(p.to_json()) == p
+point = Point(1.0, 2.0)
+restored = Point.from_json(point.to_json())
+print(point.to_dict())
+print(restored)
+print(restored == point)
 ```
 
-The on-wire JSON format is identical to `Serializable`, so mixed codebases interoperate: a `DataclassSerializable` instance can reference a legacy `Serializable` object (and vice versa) and still round-trip cleanly. The `_SERIALIZABLE_KEYWORD_ALIASES` hook works the same way for migrating field names across releases.
-
-## Usage
-
-Classes which inherit from `Serializable` are enabled with default implementations of
-`to_json`, `from_json`, `__reduce__` (for pickling), and other serialization
-helpers.
-
-A derived class must either:
+```text
+{'x': 1.0, 'y': 2.0}
+Point(x=1.0, y=2.0)
+True
+```
 
-- have a member data matching the name of each positional argument to `__init__`
-- provide a user-defined `to_dict()` method which returns a dictionary whose keys match the arguments to `__init__`
+`to_dict()` gives the constructor fields; `to_json()` also records the class
+and its module so `from_json()` can rebuild it. The dataclass keeps its own
+generated constructor, equality, representation and hashing. The recorded module and
+class must be importable when loading, so load data only from sources you
+trust.
 
-Keyword-only arguments to `__init__` (those after `*`) are left out of the default `to_dict()`, so they can be used for constructor options which aren't part of an object's serialized state.
+## Documentation
 
-Pickling goes through the same `to_dict()` / `from_dict()` pair, so pickles also survive renamed keywords (see below). Pickles written by versions before 1.2.0 can still be loaded.
+The [documentation](https://openvax.github.io/serializable/) covers, in
+reading order:
 
-If you change the keyword arguments to a class which derives from `Serializable` but would like to be able to deserialize older JSON representations then you can define a class-level dictionary called `_SERIALIZABLE_KEYWORD_ALIASES` which maps old keywords to new names (or `None` if a keyword was removed).
+1. [Getting started](https://openvax.github.io/serializable/): the example
+   above, choosing a base class, and the format's limits.
+2. [Save classes and files](https://openvax.github.io/serializable/guides/objects/):
+   constructor-based classes, JSON files, pickles and nested containers.
+3. [Change field names](https://openvax.github.io/serializable/guides/migration/):
+   read data written before a constructor argument was renamed.
+4. [API reference](https://openvax.github.io/serializable/reference/).
 
-## Limitations
+## Development
 
-The format records Python classes and modules, which must remain importable when
-loading data. Keys starting with two underscores are reserved. Nested Python
-values require the serialization helpers rather than ordinary JSON encoding.
-`to_json` raises `ValueError` for NaN or infinite floats, which standard JSON
-can't represent; `from_json` still reads the `NaN` / `Infinity` literals which
-older versions wrote.
+```sh
+python -m pip install -e ".[dev]"   # or ./develop.sh, which uses .venv
+./format.sh   # ruff format
+./lint.sh     # ruff check, ruff format --check and mypy
+./test.sh     # pytest with coverage
+python -m pip install -r requirements-docs.txt
+./docs.sh     # mkdocs build --strict, then a rendered-link check
+python scripts/check_docs_examples.py   # run docs examples, compare output
+```
 
-## Documentation
+Every PR bumps `serializable/version.py`. Maintainers release with
+`./deploy.sh` from a clean `master`.
 
-- [Save classes, files and nested objects](docs/guides/objects.md)
-- [Migrate field names](docs/guides/migration.md)
-- [API reference](docs/reference.md)
-- [Writing and checking docs](docs/dev/documentation-style.md)
+## License
 
-The site builds with `python -m pip install -r requirements-docs.txt` followed
-by `./docs.sh`. Run `python scripts/check_docs_examples.py` to check the examples.
+Apache 2.0; see [LICENSE](https://github.com/openvax/serializable/blob/master/LICENSE).

{serializable-1.3.2 → serializable-1.3.4}/serializable.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ pyproject.toml
 serializable/__init__.py
 serializable/dataclass_serializable.py
 serializable/helpers.py
+serializable/keyword_aliases.py
 serializable/primitive_types.py
 serializable/py.typed
 serializable/serializable.py

{serializable-1.3.2 → serializable-1.3.4}/tests/test_keyword_aliases.py

@@ -11,7 +11,11 @@
 # limitations under the License.
 
 
-from serializable import Serializable
+from dataclasses import dataclass
+from typing import ClassVar
+
+from serializable import DataclassSerializable, Serializable
+from serializable.keyword_aliases import apply_keyword_aliases
 
 from .common import eq_
 
@@ -103,3 +107,66 @@ def test_from_dict_does_not_modify_input():
     obj = TestClassWithKeywordAliases.from_dict(d)
     eq_(obj.x, 1)
     eq_(d, {"old_x": 1, "old_gone": 2})
+
+
+def test_apply_keyword_aliases_renames_drops_and_returns_same_dict():
+    kwargs = {"old_x": 1, "old_gone": 2}
+    result = apply_keyword_aliases(TestClassWithKeywordAliases, kwargs)
+    assert result is kwargs
+    eq_(result, {"x": 1})
+
+
+def test_apply_keyword_aliases_prefers_current_name():
+    kwargs = {"old_x": "old", "x": "new"}
+    eq_(apply_keyword_aliases(TestClassWithKeywordAliases, kwargs), {"x": "new"})
+
+
+def test_apply_keyword_aliases_uses_every_class_in_the_mro():
+    kwargs = {"old_x": 1, "old_y": 2, "old_gone": 3}
+    eq_(apply_keyword_aliases(DerivedClassWithMoreKeywordAliases, kwargs), {"x": 1, "y": 2})
+
+
+def test_apply_keyword_aliases_without_aliases_is_a_no_op():
+    eq_(apply_keyword_aliases(object, {"a": 1}), {"a": 1})
+
+
+@dataclass
+class DataclassWithEmptyAlias(DataclassSerializable):
+    _SERIALIZABLE_KEYWORD_ALIASES: ClassVar[dict[str, str | None]] = {"legacy": ""}
+    x: int
+
+
+class SerializableWithEmptyAlias(Serializable):
+    _SERIALIZABLE_KEYWORD_ALIASES = {"legacy": ""}
+
+    def __init__(self, x):
+        self.x = x
+
+
+def test_both_base_classes_treat_an_empty_alias_as_removed():
+    # Serializable always dropped these; DataclassSerializable used to pass
+    # them to the constructor under the keyword "", which raised TypeError.
+    assert SerializableWithEmptyAlias.from_dict(
+        {"x": 1, "legacy": 2}
+    ) == SerializableWithEmptyAlias(x=1)
+    assert DataclassWithEmptyAlias.from_dict({"x": 1, "legacy": 2}) == DataclassWithEmptyAlias(x=1)
+
+
+class ClassOverridingUpdateKwargs(TestClassWithKeywordAliases):
+    def __init__(self, x, y):
+        self.x = x
+        self.y = y
+
+    @classmethod
+    def _update_kwargs(cls, kwargs):
+        kwargs = super()._update_kwargs(kwargs)
+        kwargs.setdefault("y", "filled in by override")
+        return kwargs
+
+
+def test_from_dict_still_calls_an_overridden_update_kwargs():
+    # _update_kwargs is kept as a hook: an override runs in from_dict and can
+    # still apply the inherited aliases through super().
+    obj = ClassOverridingUpdateKwargs.from_dict({"old_x": 1})
+    eq_(obj.x, 1)
+    eq_(obj.y, "filled in by override")

serializable-1.3.2/README.md

@@ -1,70 +0,0 @@
-[![Tests](https://github.com/openvax/serializable/actions/workflows/tests.yml/badge.svg)](https://github.com/openvax/serializable/actions/workflows/tests.yml)
-<a href="https://pypi.python.org/pypi/serializable/">
-<img src="https://img.shields.io/pypi/v/serializable.svg?maxAge=1000" alt="PyPI" />
-</a>
-[![PyPI downloads](https://img.shields.io/pypi/dm/serializable.svg)](https://pypistats.org/packages/serializable)
-
-# serializable
-
-Base class with serialization methods for user-defined Python objects
-
-## Install
-
-```sh
-python -m pip install serializable
-```
-
-## `DataclassSerializable` for `@dataclass` subclasses
-
-If you're using `@dataclass` (e.g. in `vaxrank`, `pyensembl`, or `varcode`), inherit from `DataclassSerializable` instead of `Serializable`. It provides the same serialization surface — `to_dict` / `from_dict` / `to_json` / `from_json` — but leaves `__init__`, `__eq__`, `__repr__`, and `__hash__` to `@dataclass`, so you get dataclass-native equality and repr without conflicts.
-
-```python
-from dataclasses import dataclass
-from serializable import DataclassSerializable
-
-@dataclass
-class Point(DataclassSerializable):
-    x: float
-    y: float
-
-p = Point(1.0, 2.0)
-assert Point.from_json(p.to_json()) == p
-```
-
-The on-wire JSON format is identical to `Serializable`, so mixed codebases interoperate: a `DataclassSerializable` instance can reference a legacy `Serializable` object (and vice versa) and still round-trip cleanly. The `_SERIALIZABLE_KEYWORD_ALIASES` hook works the same way for migrating field names across releases.
-
-## Usage
-
-Classes which inherit from `Serializable` are enabled with default implementations of
-`to_json`, `from_json`, `__reduce__` (for pickling), and other serialization
-helpers.
-
-A derived class must either:
-
-- have a member data matching the name of each positional argument to `__init__`
-- provide a user-defined `to_dict()` method which returns a dictionary whose keys match the arguments to `__init__`
-
-Keyword-only arguments to `__init__` (those after `*`) are left out of the default `to_dict()`, so they can be used for constructor options which aren't part of an object's serialized state.
-
-Pickling goes through the same `to_dict()` / `from_dict()` pair, so pickles also survive renamed keywords (see below). Pickles written by versions before 1.2.0 can still be loaded.
-
-If you change the keyword arguments to a class which derives from `Serializable` but would like to be able to deserialize older JSON representations then you can define a class-level dictionary called `_SERIALIZABLE_KEYWORD_ALIASES` which maps old keywords to new names (or `None` if a keyword was removed).
-
-## Limitations
-
-The format records Python classes and modules, which must remain importable when
-loading data. Keys starting with two underscores are reserved. Nested Python
-values require the serialization helpers rather than ordinary JSON encoding.
-`to_json` raises `ValueError` for NaN or infinite floats, which standard JSON
-can't represent; `from_json` still reads the `NaN` / `Infinity` literals which
-older versions wrote.
-
-## Documentation
-
-- [Save classes, files and nested objects](docs/guides/objects.md)
-- [Migrate field names](docs/guides/migration.md)
-- [API reference](docs/reference.md)
-- [Writing and checking docs](docs/dev/documentation-style.md)
-
-The site builds with `python -m pip install -r requirements-docs.txt` followed
-by `./docs.sh`. Run `python scripts/check_docs_examples.py` to check the examples.