openframe-core 3.2.0__tar.gz → 3.2.1__tar.gz

{openframe_core-3.2.0 → openframe_core-3.2.1}/.github/CHANGELOG.md

@@ -58,6 +58,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## v3.2.1
+
+### Added
+
+- `openframe.core.schemas` — new experimental module providing
+  the `@contract(name, version)` decorator, `ContractMeta` dataclass,
+  and `get_contract_meta()` helper. Marks Pydantic models as
+  published cross-service contracts. The schema export, registry,
+  breaking-change diff, and codegen machinery lives in the
+  separate `openframe-schemas` package (openframe-tooling repo).
+
+---
+
 ## v3.2.0
 
 ### Added

{openframe_core-3.2.0 → openframe_core-3.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openframe-core
-Version: 3.2.0
+Version: 3.2.1
 Summary: OpenFrame Microservice Suite - platform kernel. Port contracts, testing utilities, plugin registry, and composition root.
 Project-URL: Homepage, https://github.com/Furious-Meteors/openframe-core
 Project-URL: Documentation, https://furious-meteors.github.io/openframe-core/

openframe_core-3.2.1/openframe/core/schemas/__init__.py

@@ -0,0 +1,128 @@
+"""
+openframe.core.schemas
+========================
+Cross-service data shape governance (ADR-007).
+
+The @contract decorator marks a Pydantic model as a published
+cross-service contract — a shape that crosses a service boundary
+(via REST, Kafka, gRPC, or any other transport) and must be
+governed for breaking changes.
+
+This module owns only the *marker*. The machinery that acts on
+the marker — schema export, version registry, breaking-change diff,
+codegen — lives in the separate openframe-schemas package, which
+has its own dependencies and release cadence.
+
+Dependency order:
+    core/schemas → stdlib only (no pydantic, no openframe imports)
+
+Usage::
+
+    from openframe.core.schemas import contract
+
+    @contract(name="item", version="1.0")
+    class Item(BaseModel):
+        id: str
+        name: str
+        description: str | None = None
+        status: str = "active"
+
+The @contract decorator does not change the class in any way that
+affects Pydantic validation, serialization, or runtime behaviour.
+It attaches __contract__ as a class attribute that openframe-schemas
+reads at schema-export time.
+
+.. stability: experimental
+   Experimental — the decorator signature (name, version) is stable;
+   the ContractMeta attributes may gain additional fields in future
+   minor versions.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+__all__ = ["ContractMeta", "contract", "get_contract_meta"]
+
+__stability__ = "experimental"
+
+
+@dataclass
+class ContractMeta:
+    """
+    Metadata attached to a @contract-decorated model.
+
+    .. stability: experimental
+
+    Attributes:
+        name:    The contract's stable name (e.g. ``"item"``). Identifies
+                 the contract independently of the Python class name.
+        version: The contract's version string (e.g. ``"1.0"``). Governed
+                 by openframe-schemas' breaking-change diff tooling.
+    """
+
+    name: str
+    version: str
+
+    __stability__ = "experimental"
+
+
+def contract(name: str, version: str):
+    """
+    Mark a class as a published cross-service contract.
+
+    Attaches a :class:`ContractMeta` instance to the decorated class as
+    ``cls.__contract__``. Returns the class unchanged — pure decoration,
+    no wrapping — so Pydantic validation, serialization, and any other
+    runtime behaviour are unaffected.
+
+    Works with any class, not just Pydantic ``BaseModel`` subclasses, but
+    the intended use is always Pydantic models.
+
+    .. stability: experimental
+
+    Args:
+        name:    The contract's stable name.
+        version: The contract's version string.
+
+    Returns:
+        A decorator that attaches ``__contract__`` to the class and
+        returns it unchanged.
+
+    Usage::
+
+        @contract(name="item", version="1.0")
+        class Item(BaseModel):
+            id: str
+            name: str
+    """
+
+    def _decorate(cls: type) -> type:
+        cls.__contract__ = ContractMeta(name=name, version=version)
+        return cls
+
+    return _decorate
+
+
+contract.__stability__ = "experimental"
+
+
+def get_contract_meta(cls: type) -> ContractMeta | None:
+    """
+    Return the ContractMeta attached to a class, if any.
+
+    Safe on any class — undecorated classes simply return ``None``
+    rather than raising.
+
+    .. stability: experimental
+
+    Args:
+        cls: The class to inspect.
+
+    Returns:
+        The :class:`ContractMeta` attached via :func:`contract`, or
+        ``None`` if the class is not @contract-decorated.
+    """
+    return getattr(cls, "__contract__", None)
+
+
+get_contract_meta.__stability__ = "experimental"

{openframe_core-3.2.0 → openframe_core-3.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "openframe-core"
-version = "3.2.0"
+version = "3.2.1"
 description = "OpenFrame Microservice Suite - platform kernel. Port contracts, testing utilities, plugin registry, and composition root."
 readme = "README.md"
 requires-python = ">=3.11"

openframe_core-3.2.1/tests/test_schemas.py

@@ -0,0 +1,91 @@
+"""
+tests/test_schemas.py
+========================
+Tests for openframe.core.schemas — the @contract marker (ADR-007).
+"""
+from __future__ import annotations
+
+import pytest
+from pydantic import BaseModel
+
+from openframe.core.schemas import ContractMeta, contract, get_contract_meta
+
+
+def test_contract_decorator_attaches_meta() -> None:
+    @contract(name="item", version="1.0")
+    class Item(BaseModel):
+        id: str
+        name: str
+
+    assert Item.__contract__.name == "item"
+    assert Item.__contract__.version == "1.0"
+
+
+def test_contract_decorator_returns_class_unchanged() -> None:
+    class RawItem(BaseModel):
+        id: str
+        name: str
+
+    DecoratedItem = contract(name="item", version="1.0")(RawItem)
+
+    assert DecoratedItem is RawItem
+    instance = DecoratedItem(id="1", name="widget")
+    assert isinstance(instance, RawItem)
+    assert DecoratedItem.model_json_schema() == RawItem.model_json_schema()
+
+
+def test_get_contract_meta_returns_meta_for_decorated_class() -> None:
+    @contract(name="order", version="2.1")
+    class Order(BaseModel):
+        id: str
+
+    meta = get_contract_meta(Order)
+    assert meta is not None
+    assert meta.name == "order"
+    assert meta.version == "2.1"
+
+
+def test_get_contract_meta_returns_none_for_undecorated_class() -> None:
+    class PlainModel(BaseModel):
+        id: str
+
+    assert get_contract_meta(PlainModel) is None
+
+
+def test_contract_decorator_works_on_nested_model() -> None:
+    class Address(BaseModel):
+        street: str
+        city: str
+
+    @contract(name="customer", version="1.0")
+    class Customer(BaseModel):
+        id: str
+        address: Address
+
+    instance = Customer(id="1", address=Address(street="Main St", city="Springfield"))
+    assert instance.address.city == "Springfield"
+    assert get_contract_meta(Customer).name == "customer"
+
+
+def test_contract_meta_repr() -> None:
+    assert repr(ContractMeta("item", "1.0")) == "ContractMeta(name='item', version='1.0')"
+
+
+def test_contract_marker_does_not_affect_pydantic_validation() -> None:
+    class PlainModel(BaseModel):
+        id: str
+        count: int
+
+    @contract(name="counted", version="1.0")
+    class DecoratedModel(BaseModel):
+        id: str
+        count: int
+
+    plain = PlainModel(id="1", count=5)
+    decorated = DecoratedModel(id="1", count=5)
+    assert plain.model_dump() == decorated.model_dump()
+
+    with pytest.raises(Exception):
+        PlainModel(id="1", count="not-an-int")
+    with pytest.raises(Exception):
+        DecoratedModel(id="1", count="not-an-int")