localstack-py-avro-schema 3.9.0__tar.gz → 3.9.2__tar.gz

{localstack_py_avro_schema-3.9.0 → localstack_py_avro_schema-3.9.2}/.github/workflows/test-package.yml

@@ -27,11 +27,9 @@ jobs:
       fail-fast: false
       matrix:
         python-version:
-          - '3.9'
-          - '3.10'
           - '3.11'
           - '3.12'
-          - '3.13-dev'
+          - '3.13'
 
     steps:
       - uses: actions/checkout@v4

{localstack_py_avro_schema-3.9.0 → localstack_py_avro_schema-3.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: localstack-py-avro-schema
-Version: 3.9.0
+Version: 3.9.2
 Summary: Generate Apache Avro schemas for Python types including standard library data-classes and Pydantic data models.
 Author-email: LocalStack Contributors <info@localstack.cloud>, "J.P. Morgan Chase & Co." <open_source@jpmorgan.com>
 License:                                  Apache License

{localstack_py_avro_schema-3.9.0 → localstack_py_avro_schema-3.9.2}/src/localstack_py_avro_schema.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: localstack-py-avro-schema
-Version: 3.9.0
+Version: 3.9.2
 Summary: Generate Apache Avro schemas for Python types including standard library data-classes and Pydantic data models.
 Author-email: LocalStack Contributors <info@localstack.cloud>, "J.P. Morgan Chase & Co." <open_source@jpmorgan.com>
 License:                                  Apache License

{localstack_py_avro_schema-3.9.0 → localstack_py_avro_schema-3.9.2}/src/localstack_py_avro_schema.egg-info/SOURCES.txt

@@ -22,6 +22,7 @@ src/localstack_py_avro_schema.egg-info/dependency_links.txt
 src/localstack_py_avro_schema.egg-info/requires.txt
 src/localstack_py_avro_schema.egg-info/top_level.txt
 src/py_avro_schema/__init__.py
+src/py_avro_schema/_alias.py
 src/py_avro_schema/_schemas.py
 src/py_avro_schema/_testing.py
 src/py_avro_schema/_typing.py

localstack_py_avro_schema-3.9.2/src/py_avro_schema/_alias.py

@@ -0,0 +1,116 @@
+"""
+Module to register aliases for Python types
+
+This module maintains global state via the _ALIASES registry.
+Decorators will modify this state when applied to classes.
+"""
+
+import dataclasses
+from collections import defaultdict
+from typing import Annotated, Type, get_args, get_origin
+
+FQN = str
+"""Fully qualified name for a Python type"""
+_ALIASES: dict[FQN, set[FQN]] = defaultdict(set)
+"""Maps the FQN of a Python type to a set of aliases"""
+
+
+@dataclasses.dataclass
+class Alias:
+    """Alias for a record field"""
+
+    alias: str
+
+
+@dataclasses.dataclass
+class Aliases:
+    """Aliases for a record field"""
+
+    aliases: list[str]
+
+
+def get_fully_qualified_name(py_type: type) -> str:
+    """Returns the fully qualified name for a Python type"""
+    module = getattr(py_type, "__module__", None)
+    qualname = getattr(py_type, "__qualname__", py_type.__name__)
+
+    # py-avro-schema does not consider <locals> in the namespace.
+    # we skip it here as well for consistency
+    if module and "<locals>" in qualname:
+        return f"{module}.{py_type.__name__}"
+
+    if module and module not in ("builtins", "__main__"):
+        return f"{module}.{qualname}"
+    return qualname
+
+
+def register_type_aliases(aliases: list[FQN]):
+    """
+    Decorator to register aliases for a given type.
+    It allows for compatible schemas following a change type (e.g., a rename), if the type fields do not
+    change in an incompatible way.
+
+    Example::
+        @register_type_aliases(aliases=["py_avro_schema.OldAddress"])
+        class Address(TypedDict):
+            street: str
+            number: int
+    """
+
+    def _wrapper(cls):
+        """Wrapper function that updates the aliases dictionary"""
+        fqn = get_fully_qualified_name(cls)
+        _ALIASES[fqn].update(aliases)
+        return cls
+
+    return _wrapper
+
+
+def register_type_alias(alias: FQN):
+    """
+    Decorator to register a single alias for a given type.
+    It allows for compatible schemas following a change type (e.g., a rename), if the type fields do not
+    change in an incompatible way.
+
+    Example::
+        @register_type_alias(alias="py_avro_schema.OldAddress")
+        class Address(TypedDict):
+            street: str
+            number: int
+    """
+
+    def _wrapper(cls):
+        """Wrapper function that updates the aliases dictionary"""
+        fqn = get_fully_qualified_name(cls)
+        _ALIASES[fqn].add(alias)
+        return cls
+
+    return _wrapper
+
+
+def get_aliases(fqn: str) -> list[str]:
+    """Returns the list of aliases for a given type"""
+    if aliases := _ALIASES.get(fqn):
+        return sorted(aliases)
+    return []
+
+
+def get_field_aliases_and_actual_type(py_type: Type) -> tuple[list[str] | None, Type]:
+    """
+    Check if a type contains an alias metadata via `Alias` or `Aliases` as metadata.
+    It returns the eventual aliases and the type.
+    """
+    # py_type is not annotated. It can't have aliases
+    if get_origin(py_type) is not Annotated:
+        return [], py_type
+
+    args = get_args(py_type)
+    actual_type, annotation = args[0], args[1]
+
+    # Annotated type but not an alias. We do nothing.
+    if type(annotation) not in (Alias, Aliases):
+        return [], py_type
+
+    # If the annotated type is an alias, we extract the aliases and return the actual type
+    aliases = annotation.aliases if type(annotation) is Aliases else [annotation.alias]
+    return aliases, actual_type

{localstack_py_avro_schema-3.9.0 → localstack_py_avro_schema-3.9.2}/src/py_avro_schema/_schemas.py

@@ -50,6 +50,7 @@ import orjson
 import typeguard
 
 import py_avro_schema._typing
+from py_avro_schema._alias import get_aliases, get_field_aliases_and_actual_type
 
 if TYPE_CHECKING:
     # Pydantic not necessarily required at runtime
@@ -857,6 +858,9 @@ class EnumSchema(NamedSchema):
         }
         if self.namespace is not None:
             enum_schema["namespace"] = self.namespace
+            fqn = f"{self.namespace}.{self.name}"
+            if aliases := get_aliases(fqn):
+                enum_schema["aliases"] = aliases
         if Option.NO_DOC not in self.options:
             doc = _doc_for_class(self.py_type)
             if doc:
@@ -887,6 +891,9 @@ class RecordSchema(NamedSchema):
         }
         if self.namespace is not None:
             record_schema["namespace"] = self.namespace
+            fqn = f"{self.namespace}.{self.name}"
+            if aliases := get_aliases(fqn):
+                record_schema["aliases"] = aliases
         if Option.NO_DOC not in self.options:
             doc = _doc_for_class(self.py_type)
             if doc:
@@ -902,6 +909,7 @@ class RecordField:
         py_type: Type,
         name: str,
         namespace: Optional[str],
+        aliases: list[str] | None = None,
         default: Any = dataclasses.MISSING,
         docs: str = "",
         options: Option = Option(0),
@@ -912,12 +920,16 @@ class RecordField:
         :param py_type:   The Python class or type
         :param name:      Field name
         :param namespace: Avro schema namespace
+        :param aliases:   Aliases for the field
         :param default:   Field default value
         :param docs:      Field documentation or description
         :param options:   Schema generation options
         """
+        if aliases is None:
+            aliases = []
         self.py_type = py_type
         self.name = name
+        self.aliases = aliases
         self._namespace = namespace
         self.default = default
         self.docs = docs
@@ -942,6 +954,8 @@ class RecordField:
             "name": self.name,
             "type": self.schema.data(names=names),
         }
+        if self.aliases:
+            field_data["aliases"] = sorted(self.aliases)
         if self.default != dataclasses.MISSING:
             field_data["default"] = self.schema.make_default(self.default)
         if self.docs and Option.NO_DOC not in self.options:
@@ -977,11 +991,13 @@ class DataclassSchema(RecordSchema):
         default = py_field.default
         if callable(py_field.default_factory):  # type: ignore
             default = py_field.default_factory()  # type: ignore
+        aliases, actual_type = get_field_aliases_and_actual_type(py_field.type)  # type: ignore
         field_obj = RecordField(
-            py_type=py_field.type,  # type: ignore
+            py_type=actual_type,  # type: ignore
             name=py_field.name,
             namespace=self.namespace_override,
             default=default,
+            aliases=aliases,
             options=self.options,
         )
 
@@ -1017,11 +1033,13 @@ class PydanticSchema(RecordSchema):
         default = dataclasses.MISSING if py_field.is_required() else py_field.get_default(call_default_factory=True)
         py_type = self._annotation(name)
         record_name = py_field.alias if Option.USE_FIELD_ALIAS in self.options and py_field.alias else name
+        aliases, actual_type = get_field_aliases_and_actual_type(py_type)
         field_obj = RecordField(
-            py_type=py_type,
+            py_type=actual_type,
             name=record_name,
             namespace=self.namespace_override,
             default=default,
+            aliases=aliases,
             docs=py_field.description or "",
             options=self.options,
         )
@@ -1080,11 +1098,13 @@ class PlainClassSchema(RecordSchema):
     def _record_field(self, py_field: inspect.Parameter) -> RecordField:
         """Return an Avro record field object for a given Python instance attribute"""
         default = py_field.default if py_field.default != inspect.Parameter.empty else dataclasses.MISSING
+        aliases, actual_type = get_field_aliases_and_actual_type(py_field.annotation)
         field_obj = RecordField(
-            py_type=py_field.annotation,
+            py_type=actual_type,
             name=py_field.name,
             namespace=self.namespace_override,
             default=default,
+            aliases=aliases,
             options=self.options,
         )
         return field_obj
@@ -1109,15 +1129,17 @@ class TypedDictSchema(RecordSchema):
         """
         super().__init__(py_type, namespace=namespace, options=options)
         py_type = _type_from_annotated(py_type)
-        self.py_fields: dict[str, Type] = get_type_hints(py_type)
+        self.py_fields: dict[str, Type] = get_type_hints(py_type, include_extras=True)
         self.record_fields = [self._record_field(field) for field in self.py_fields.items()]
 
     def _record_field(self, py_field: tuple[str, Type]) -> RecordField:
         """Return an Avro record field object for a given TypedDict field"""
+        aliases, actual_type = get_field_aliases_and_actual_type(py_field[1])
         field_obj = RecordField(
-            py_type=py_field[1],
+            py_type=actual_type,
             name=py_field[0],
             namespace=self.namespace_override,
+            aliases=aliases,
             options=self.options,
         )
         return field_obj

{localstack_py_avro_schema-3.9.0 → localstack_py_avro_schema-3.9.2}/tests/test_avro_schema.py

@@ -10,11 +10,14 @@
 # specific language governing permissions and limitations under the License.
 
 import dataclasses
+import json
+from typing import TypedDict
 
 import avro.schema
 import orjson
 
 import py_avro_schema as pas
+from py_avro_schema._alias import register_type_alias, register_type_aliases
 
 
 def test_package_has_version():
@@ -43,3 +46,21 @@ def test_dataclass_string_field():
     json_data = pas.generate(PyType)
     assert json_data == orjson.dumps(expected)
     assert avro.schema.parse(json_data)
+
+
+def test_avro_type_aliases():
+    @register_type_aliases(aliases=["test_avro_schema.VeryOldDict", "test_avro_schema.OldDict"])
+    class PyTypedDict(TypedDict):
+        value: str
+
+    json_data = pas.generate(PyTypedDict)
+    assert json.loads(json_data)["aliases"] == ["test_avro_schema.OldDict", "test_avro_schema.VeryOldDict"]
+
+    register_type_alias(alias="test_avro_schema.SuperOldDict")(PyTypedDict)
+    pas.generate.cache_clear()
+    json_data = pas.generate(PyTypedDict)
+    assert json.loads(json_data)["aliases"] == [
+        "test_avro_schema.OldDict",
+        "test_avro_schema.SuperOldDict",
+        "test_avro_schema.VeryOldDict",
+    ]

{localstack_py_avro_schema-3.9.0 → localstack_py_avro_schema-3.9.2}/tests/test_dataclass.py

@@ -19,6 +19,7 @@ from typing import Annotated, Dict, List, Optional, Tuple
 import pytest
 
 import py_avro_schema as pas
+from py_avro_schema._alias import Alias, register_type_aliases
 from py_avro_schema._testing import assert_schema
 
 
@@ -400,6 +401,7 @@ def test_dataclass_repeated_string_field():
 
 
 def test_dataclass_repeated_enum_field():
+    @register_type_aliases(aliases=["test_dataclass.OldEnum"])
     class PyTypeEnum(enum.Enum):
         RED = "RED"
         GREEN = "GREEN"
@@ -412,12 +414,15 @@ def test_dataclass_repeated_enum_field():
     expected = {
         "type": "record",
         "name": "PyType",
+        "namespace": "test_dataclass",
         "fields": [
             {
                 "name": "field_child_1",
                 "type": {
                     "type": "enum",
                     "name": "PyTypeEnum",
+                    "namespace": "test_dataclass",
+                    "aliases": ["test_dataclass.OldEnum"],
                     "symbols": [
                         "RED",
                         "GREEN",
@@ -427,11 +432,11 @@ def test_dataclass_repeated_enum_field():
             },
             {
                 "name": "field_child_2",
-                "type": "PyTypeEnum",
+                "type": "test_dataclass.PyTypeEnum",
             },
         ],
     }
-    assert_schema(PyType, expected)
+    assert_schema(PyType, expected, do_auto_namespace=True)
 
 
 def test_self_ref_field():
@@ -839,3 +844,22 @@ def test_sequence_schema_defaults_with_items():
         "type": "record",
     }
     assert_schema(PyType, expected)
+
+
+def test_field_alias():
+    @dataclasses.dataclass
+    class PyType:
+        field_b: Annotated[str, Alias("field_a")]
+
+    expected = {
+        "type": "record",
+        "name": "PyType",
+        "fields": [
+            {
+                "aliases": ["field_a"],
+                "name": "field_b",
+                "type": "string",
+            }
+        ],
+    }
+    assert_schema(PyType, expected)

{localstack_py_avro_schema-3.9.0 → localstack_py_avro_schema-3.9.2}/tests/test_plain_class.py

@@ -15,10 +15,12 @@ from typing import Annotated
 import pytest
 
 import py_avro_schema
+from py_avro_schema._alias import Alias, register_type_aliases
 from py_avro_schema._testing import assert_schema
 
 
 def test_plain_class_with_type_hints():
+    @register_type_aliases(aliases=["test_plain_class.OldPyType"])
     class PyType:
         """A port, not using dataclass"""
 
@@ -33,6 +35,8 @@ def test_plain_class_with_type_hints():
     expected = {
         "type": "record",
         "name": "PyType",
+        "namespace": "test_plain_class",
+        "aliases": ["test_plain_class.OldPyType"],
         "fields": [
             {
                 "name": "name",
@@ -54,7 +58,7 @@ def test_plain_class_with_type_hints():
         ],
     }
 
-    assert_schema(PyType, expected)
+    assert_schema(PyType, expected, do_auto_namespace=True)
 
 
 def test_plain_class_annotated():
@@ -78,6 +82,25 @@ def test_plain_class_annotated():
     assert_schema(Annotated[PyType, ...], expected)
 
 
+def test_field_alias():
+    class PyType:
+        def __init__(self, name: Annotated[str, Alias("old_name")]):
+            self.name = name
+
+    expected = {
+        "type": "record",
+        "name": "PyType",
+        "fields": [
+            {
+                "aliases": ["old_name"],
+                "name": "name",
+                "type": "string",
+            },
+        ],
+    }
+    assert_schema(PyType, expected)
+
+
 def test_plain_class_no_type_hints():
     class PyType:
         """A port, not using dataclass"""

{localstack_py_avro_schema-3.9.0 → localstack_py_avro_schema-3.9.2}/tests/test_pydantic.py

@@ -17,6 +17,7 @@ import pydantic
 import pytest
 
 import py_avro_schema as pas
+from py_avro_schema._alias import Alias
 from py_avro_schema._testing import assert_schema
 
 
@@ -496,6 +497,24 @@ def test_annotated_decimal():
     assert_schema(PyType, expected)
 
 
+def test_field_alias():
+    class PyType(pydantic.BaseModel):
+        field_a: Annotated[str, Alias("field_b")]
+
+    expected = {
+        "type": "record",
+        "name": "PyType",
+        "fields": [
+            {
+                "aliases": ["field_b"],
+                "name": "field_a",
+                "type": "string",
+            }
+        ],
+    }
+    assert_schema(PyType, expected)
+
+
 def test_annotated_decimal_in_base():
     class Base(pydantic.BaseModel):
         field_a: Annotated[

{localstack_py_avro_schema-3.9.0 → localstack_py_avro_schema-3.9.2}/tests/test_typed_dict.py

@@ -1,5 +1,6 @@
-from typing import TypedDict
+from typing import Annotated, TypedDict
 
+from py_avro_schema._alias import Alias, register_type_alias
 from py_avro_schema._testing import assert_schema
 
 
@@ -27,8 +28,9 @@ def test_typed_dict():
 
 
 def test_type_dict_nested():
+    @register_type_alias("test_typed_dict.OldAddress")
     class Address(TypedDict):
-        street: str
+        street: Annotated[str, Alias("address")]
         number: int
 
     class User(TypedDict):
@@ -39,6 +41,7 @@ def test_type_dict_nested():
     expected = {
         "type": "record",
         "name": "User",
+        "namespace": "test_typed_dict",
         "fields": [
             {
                 "name": "name",
@@ -49,13 +52,36 @@ def test_type_dict_nested():
                 "name": "address",
                 "type": {
                     "name": "Address",
+                    "namespace": "test_typed_dict",
+                    "aliases": ["test_typed_dict.OldAddress"],
                     "type": "record",
                     "fields": [
-                        {"name": "street", "type": "string"},
+                        {"aliases": ["address"], "name": "street", "type": "string"},
                         {"name": "number", "type": "long"},
                     ],
                 },
             },
         ],
     }
+    assert_schema(User, expected, do_auto_namespace=True)
+
+
+def test_field_alias():
+    class User(TypedDict):
+        name: Annotated[str, Alias("username")]
+        age: int
+
+    expected = {
+        "type": "record",
+        "name": "User",
+        "fields": [
+            {
+                "aliases": ["username"],
+                "name": "name",
+                "type": "string",
+            },
+            {"name": "age", "type": "long"},
+        ],
+    }
+
     assert_schema(User, expected)

{localstack_py_avro_schema-3.9.0 → localstack_py_avro_schema-3.9.2}/tox.ini

@@ -14,8 +14,6 @@
 
 [tox]
 envlist =
-  py39
-  py310
   py311
   py312
   py313
@@ -28,8 +26,6 @@ skip_missing_interpreters = true
 [gh-actions]
 # Mapping from GitHub Actions Python versions to Tox environments
 python =
-  3.9: py39
-  3.10: py310
   3.11: py311
   3.12: py312
   3.13: py313, linting, docs