serializable 1.2.0__tar.gz → 1.2.1__tar.gz

{serializable-1.2.0 → serializable-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: serializable
-Version: 1.2.0
+Version: 1.2.1
 Summary: Base class with serialization helpers for user-defined Python objects
 Author-email: Alex Rubinsteyn <alex.rubinsteyn@unc.edu>
 License:                                  Apache License
@@ -217,6 +217,9 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -226,6 +229,7 @@ Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
 Requires-Dist: coveralls; extra == "dev"
 Requires-Dist: build; extra == "dev"
 Requires-Dist: twine; extra == "dev"

{serializable-1.2.0 → serializable-1.2.1}/pyproject.toml

@@ -22,6 +22,9 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
 ]
 requires-python = ">=3.9"
 dependencies = [
@@ -34,6 +37,7 @@ dev = [
     "pytest",
     "pytest-cov",
     "ruff",
+    "mypy",
     "coveralls",
     "build",
     "twine",
@@ -49,6 +53,9 @@ version = {attr = "serializable.version.__version__"}
 [tool.setuptools.packages.find]
 include = ["serializable*"]
 
+[tool.setuptools.package-data]
+serializable = ["py.typed"]
+
 [tool.ruff]
 target-version = "py39"
 line-length = 100
@@ -81,6 +88,7 @@ ignore = [
     "B905",   # zip() without explicit strict
     "SIM108", # use ternary operator instead of if-else
     "UP007",  # use X | Y for type unions (need Python 3.10+)
+    "UP045",  # use X | None for Optional (need Python 3.10+)
 ]
 
 [tool.ruff.lint.per-file-ignores]
@@ -96,6 +104,11 @@ ignore = [
 [tool.ruff.lint.isort]
 known-first-party = ["serializable"]
 
+[tool.mypy]
+# Annotations are never evaluated at runtime (`from __future__ import annotations`),
+# so checking them as 3.10 also covers 3.9, which mypy 2 can no longer target.
+python_version = "3.10"
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 python_files = "test_*.py"

{serializable-1.2.0 → serializable-1.2.1}/serializable/dataclass_serializable.py

@@ -40,11 +40,14 @@ Example::
 
 from __future__ import annotations
 
+from collections.abc import Mapping
 from dataclasses import fields
-from typing import Any, ClassVar
+from typing import Any, ClassVar, Optional, TypeVar
 
 from .helpers import from_json, to_json
 
+_T = TypeVar("_T", bound="DataclassSerializable")
+
 
 class DataclassSerializable:
     """Mixin providing ``to_dict`` / ``from_dict`` / ``to_json`` / ``from_json``
@@ -57,16 +60,17 @@ class DataclassSerializable:
     ``Serializable``.
     """
 
-    _SERIALIZABLE_KEYWORD_ALIASES: ClassVar[dict[str, str | None]] = {}
+    _SERIALIZABLE_KEYWORD_ALIASES: ClassVar[dict[str, Optional[str]]] = {}
 
     def to_dict(self) -> dict[str, Any]:
         """Return a dict mapping each dataclass field name to its current
         value. Keys match the ``__init__`` keyword arguments, so
         ``cls(**obj.to_dict())`` reconstructs an equal instance."""
-        return {f.name: getattr(self, f.name) for f in fields(self)}
+        # subclasses are dataclasses, the mixin itself isn't
+        return {f.name: getattr(self, f.name) for f in fields(self)}  # type: ignore[arg-type]
 
     @classmethod
-    def from_dict(cls, state_dict: dict[str, Any]):
+    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)
@@ -83,10 +87,10 @@ class DataclassSerializable:
         return to_json(self)
 
     @classmethod
-    def from_json(cls, json_string: str):
+    def from_json(cls: type[_T], json_string: str) -> _T:
         return from_json(json_string)
 
-    def __reduce__(self):
+    def __reduce__(self) -> tuple[Any, ...]:
         """Pickle via the same to_dict / from_dict path used for JSON so
         pickled objects round-trip even when field order or internal
         representation changes between releases. Pickles written before

{serializable-1.2.0 → serializable-1.2.1}/serializable/helpers.py

@@ -15,15 +15,18 @@ Helper functions for deconstructing classes, functions, and user-defined
 objects into serializable types.
 """
 
+from __future__ import annotations
+
 from functools import lru_cache
 from types import BuiltinFunctionType, FunctionType
+from typing import Any, Union
 
-import simplejson as json
+import simplejson as json  # type: ignore[import-untyped]
 
 from .primitive_types import PRIMITIVE_TYPES
 
 
-def init_arg_names(obj):
+def init_arg_names(obj: Any) -> tuple[str, ...]:
     """
     Names of the positional arguments to the __init__ method of this
     object's class (excluding self).
@@ -31,7 +34,8 @@ def init_arg_names(obj):
     Keyword-only arguments are deliberately excluded, so a class can accept
     constructor options which aren't part of its serialized state.
     """
-    return _class_init_arg_names(type(obj))
+    # mypy doesn't consider classes Hashable
+    return _class_init_arg_names(type(obj))  # type: ignore[arg-type]
 
 
 # Cached per class since this is called on every to_dict/__eq__/__hash__ of
@@ -53,7 +57,7 @@ def _class_init_arg_names(cls):
     return init_code.co_varnames[1 : init_code.co_argcount]
 
 
-def simple_object_to_dict(self):
+def simple_object_to_dict(self: object) -> dict[str, Any]:
     return {name: getattr(self, name) for name in init_arg_names(self)}
 
 
@@ -246,7 +250,7 @@ def list_to_serializable_repr(x):
     return [to_serializable_repr(element) for element in x]
 
 
-def to_dict(obj):
+def to_dict(obj: Any) -> dict[str, Any]:
     """
     If value isn't a primitive scalar or collection then it needs to
     either implement to_dict (instances of Serializable) or have member
@@ -262,7 +266,7 @@ def to_dict(obj):
         raise ValueError(f"Cannot convert {obj} : {type(obj)} to dictionary") from exc
 
 
-def to_serializable_repr(x):
+def to_serializable_repr(x: Any) -> Any:
     """
     Convert an instance of Serializable or a primitive collection containing
     such instances into serializable types.
@@ -288,7 +292,7 @@ def to_serializable_repr(x):
     return state_dictionary
 
 
-def from_serializable_repr(x):
+def from_serializable_repr(x: Any) -> Any:
     """
     Inverse of to_serializable_repr. Does not modify `x`.
     """
@@ -302,7 +306,7 @@ def from_serializable_repr(x):
     raise TypeError(f"Cannot convert {x} : {type(x)} from serializable representation to object")
 
 
-def to_json(x):
+def to_json(x: Any) -> str:
     """
     Returns JSON representation of a given Serializable instance or
     other primitive object.
@@ -310,7 +314,7 @@ def to_json(x):
     return json.dumps(to_serializable_repr(x))
 
 
-def from_json(json_string):
+def from_json(json_string: Union[str, bytes]) -> Any:
     """
     Inverse of to_json. Objects are reconstructed bottom-up while parsing,
     equivalent to (but faster than) from_serializable_repr(json.loads(...)).

{serializable-1.2.0 → serializable-1.2.1}/serializable/serializable.py

@@ -11,10 +11,16 @@
 # limitations under the License.
 
 
-from typing import ClassVar
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from typing import Any, ClassVar, Optional, TypeVar, Union
 
 from .helpers import from_json, simple_object_to_dict, to_json
 
+_T = TypeVar("_T", bound="Serializable")
+
 
 class Serializable:
     """
@@ -24,17 +30,17 @@ class Serializable:
     Relies on the keys of to_dict() matching the arguments to __init__.
     """
 
-    def __str__(self):
+    def __str__(self) -> str:
         fields = ", ".join(f"{k}={v}" for (k, v) in self.to_dict().items())
         return f"{self.__class__.__name__}({fields})"
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return str(self)
 
-    def __eq__(self, other):
+    def __eq__(self, other) -> bool:
         return self.__class__ is other.__class__ and self.to_dict() == other.to_dict()
 
-    def to_dict(self):
+    def to_dict(self) -> dict[str, Any]:
         """
         Returns a dictionary which can be used to reconstruct an instance
         of a derived class (typically by matching args to __init__). The values
@@ -49,11 +55,11 @@ class Serializable:
         """
         return simple_object_to_dict(self)
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         return hash(tuple(sorted(self.to_dict().items())))
 
     @classmethod
-    def _reconstruct_nested_objects(cls, state_dict):
+    def _reconstruct_nested_objects(cls, state_dict: dict[str, Any]) -> dict[str, Any]:
         """
         Nested serializable objects will be represented as dictionaries so we
         allow manual reconstruction of those objects in this method.
@@ -64,10 +70,10 @@ class Serializable:
 
     # dictionary mapping old keywords to either new names or
     # None if the keyword has been removed from a class
-    _SERIALIZABLE_KEYWORD_ALIASES: ClassVar[dict] = {}
+    _SERIALIZABLE_KEYWORD_ALIASES: ClassVar[dict[str, Optional[str]]] = {}
 
     @classmethod
-    def _update_kwargs(cls, kwargs):
+    def _update_kwargs(cls, kwargs: dict[str, Any]) -> dict[str, Any]:
         """
         Rename any old keyword arguments to preserve backwards compatibility
         """
@@ -83,7 +89,7 @@ class Serializable:
         return kwargs
 
     @classmethod
-    def from_dict(cls, state_dict):
+    def from_dict(cls: type[_T], state_dict: Mapping[str, Any]) -> _T:
         """
         Given a dictionary of flattened fields (result of calling to_dict()),
         returns an instance. Does not modify `state_dict`.
@@ -91,20 +97,20 @@ class Serializable:
         state_dict = cls._reconstruct_nested_objects(dict(state_dict))
         return cls(**cls._update_kwargs(state_dict))
 
-    def to_json(self):
+    def to_json(self) -> str:
         """
         Returns a string containing a JSON representation of this object.
         """
         return to_json(self)
 
     @classmethod
-    def from_json(cls, json_string):
+    def from_json(cls: type[_T], json_string: str) -> _T:
         """
         Reconstruct an instance from a JSON string.
         """
         return from_json(json_string)
 
-    def write_json_file(self, path):
+    def write_json_file(self, path: Union[str, os.PathLike[str]]) -> None:
         """
         Serialize this object to JSON and write it to the text file at `path`.
         """
@@ -112,7 +118,7 @@ class Serializable:
             f.write(self.to_json())
 
     @classmethod
-    def read_json_file(cls, path):
+    def read_json_file(cls: type[_T], path: Union[str, os.PathLike[str]]) -> _T:
         """
         Construct an instance of this class from the JSON file at `path`.
         """
@@ -120,7 +126,7 @@ class Serializable:
             json_string = f.read()
         return cls.from_json(json_string)
 
-    def __reduce__(self):
+    def __reduce__(self) -> tuple[Any, ...]:
         """
         Overriding this method directs the default pickler to reconstruct
         this object using our from_dict method, so pickles survive the same

{serializable-1.2.0 → serializable-1.2.1}/serializable/version.py

@@ -1,4 +1,4 @@
-__version__ = "1.2.0"
+__version__ = "1.2.1"
 
 
 def print_version():

{serializable-1.2.0 → serializable-1.2.1}/serializable.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: serializable
-Version: 1.2.0
+Version: 1.2.1
 Summary: Base class with serialization helpers for user-defined Python objects
 Author-email: Alex Rubinsteyn <alex.rubinsteyn@unc.edu>
 License:                                  Apache License
@@ -217,6 +217,9 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -226,6 +229,7 @@ Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
 Requires-Dist: coveralls; extra == "dev"
 Requires-Dist: build; extra == "dev"
 Requires-Dist: twine; extra == "dev"

{serializable-1.2.0 → serializable-1.2.1}/serializable.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ serializable/__init__.py
 serializable/dataclass_serializable.py
 serializable/helpers.py
 serializable/primitive_types.py
+serializable/py.typed
 serializable/serializable.py
 serializable/version.py
 serializable.egg-info/PKG-INFO
@@ -24,4 +25,5 @@ tests/test_object.py
 tests/test_pickle.py
 tests/test_primitive_values.py
 tests/test_set.py
-tests/test_tuple.py
+tests/test_tuple.py
+tests/test_typing.py

{serializable-1.2.0 → serializable-1.2.1}/serializable.egg-info/requires.txt

@@ -5,6 +5,7 @@ simplejson>=3.0.0
 pytest
 pytest-cov
 ruff
+mypy
 coveralls
 build
 twine

serializable-1.2.1/tests/test_typing.py

@@ -0,0 +1,48 @@
+# 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.
+
+import inspect
+import typing
+from dataclasses import dataclass
+
+import pytest
+
+from serializable import DataclassSerializable, Serializable, helpers
+
+
+class Point(Serializable):
+    def __init__(self, x):
+        self.x = x
+
+
+@dataclass
+class DataclassPoint(DataclassSerializable):
+    x: int
+
+
+def annotated_objects():
+    yield Point
+    yield DataclassPoint
+    for cls in (Serializable, DataclassSerializable):
+        for _, method in inspect.getmembers(cls, callable):
+            if (getattr(method, "__module__", None) or "").startswith("serializable"):
+                yield method
+    for _, function in inspect.getmembers(helpers, inspect.isfunction):
+        if function.__module__ == helpers.__name__:
+            yield function
+
+
+@pytest.mark.parametrize("obj", list(annotated_objects()), ids=lambda obj: obj.__qualname__)
+def test_annotations_evaluate_at_runtime(obj):
+    # annotations must stay evaluable on the oldest supported Python (no
+    # `X | Y` unions before 3.10) for tools which call get_type_hints
+    typing.get_type_hints(obj)