modwire-siren 0.1.0__tar.gz

modwire_siren-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+dist/

modwire_siren-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: modwire-siren
+Version: 0.1.0
+Summary: Siren hypermedia and OpenAPI integration for Modwire.
+Project-URL: Repository, https://github.com/9orky/modwire-siren
+Project-URL: Issues, https://github.com/9orky/modwire-siren/issues
+Author: 9orky
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.12
+Description-Content-Type: text/markdown
+
+# modwire-siren
+
+Typed Siren documents projected from OpenAPI without application-owned route maps.
+
+Every external boundary is behind a package interface: catalog, href resolution, field policy,
+field creation, link creation, resource hrefs, and serialization. `ModwireSirenFactory` is the
+standard composition root; `ModwireSiren` is the small public façade.
+
+<!-- generated:public-api:start -->
+## Public API
+
+The supported root imports below are generated from `modwire_siren.__all__`.
+
+| Symbol | Purpose | Primary API |
+| --- | --- | --- |
+| `ModwireSiren` | Project validated entity requests into serialized Siren documents. | `document(request: modwire_siren.contracts.entity.SirenEntityRequest) -> dict[str, typing.Any]` |
+| `ModwireSirenFactory` | Build the standard OpenAPI-backed Siren façade. | `standard(schema: dict[str, typing.Any], base_url: str) -> modwire_siren.facade.ModwireSiren` |
+| `NinjaExtraSirenController` | Framework-light base for Ninja Extra controllers that emit Siren documents. | `siren_document(resource_name: str, properties: collections.abc.Mapping[str, typing.Any], operation_ids: tuple[str, ...], path_values: collections.abc.Mapping[str, typing.Any], entities: tuple[modwire_siren.contracts.entity.SirenEmbeddedEntity, ...] = ()) -> dict[str, typing.Any]` |
+| `OpenApiError` | Report invalid or incomplete OpenAPI data used for Siren projection. | — |
+| `SirenEntityDecorator` | Turn a controller method's property mapping into a Siren entity document. | — |
+| `SirenEntityRequest` | Describe the resource data and allowed operations projected into one entity. | — |
+| `__version__` | Installed distribution version. | — |
+
+## Executable example
+
+Source: [`build_document.py`](examples/build_document.py). This file is executed by the test suite.
+
+```python
+from modwire_siren import ModwireSirenFactory, SirenEntityRequest
+
+openapi_schema = {
+    "openapi": "3.1.0",
+    "paths": {
+        "/records/{record_slug}": {
+            "x-siren-resource": {
+                "name": "record",
+                "class": "record",
+                "identifier": "slug",
+                "path-parameters": {"record_slug": "slug"},
+                "relations": {},
+            },
+            "get": {"operationId": "get_record", "summary": "Get record"},
+        }
+    },
+}
+
+siren = ModwireSirenFactory.standard(openapi_schema, "https://api.example.com/")
+document = siren.document(
+    SirenEntityRequest(
+        resource_name="record",
+        properties={"slug": "architecture/aggregate", "title": "Architecture"},
+        operation_ids=("get_record",),
+        path_values={},
+        entities=(),
+    )
+)
+```
+<!-- generated:public-api:end -->
+
+## OpenAPI contract
+
+```yaml
+paths:
+  /records/{record_slug}:
+    x-siren-resource:
+      name: record
+      class: record
+      identifier: slug
+      path-parameters:
+        record_slug: slug
+      relations:
+        section_slug:
+          rel: section
+          resource: section
+          many: false
+    patch:
+      operationId: revise_record
+      summary: Revise record
+```
+
+The strict `OpenApiResourceExtension` validates the extension. Unknown resources, incomplete path
+mappings, absent operation IDs, and unknown schema references fail while building the catalog.
+
+The Pydantic Siren contracts own wire aliases such as `class`, `type`, and `schema`.
+`PydanticSirenSerializer` implements the `SirenSerializer` interface with one model dump; it does
+not redeclare the wire schema.
+
+## Django Ninja Extra
+
+The controller adapter does not import Django or Ninja Extra, so the core package keeps no framework
+dependency. It composes directly with Ninja Extra's controller and route decorators:
+
+```python
+from ninja_extra import ControllerBase, api_controller, route
+from modwire_siren import ModwireSiren, NinjaExtraSirenController, SirenEntityDecorator
+
+@api_controller("/records")
+class RecordController(ControllerBase, NinjaExtraSirenController):
+    def __init__(self, records: RecordService, siren: ModwireSiren):
+        NinjaExtraSirenController.__init__(self, siren)
+        self.records = records
+
+    @route.get("/{record_slug}", operation_id="get_record")
+    @SirenEntityDecorator("record", operations=("revise_record",))
+    def get_record(self, record_slug: str):
+        return self.records.get(record_slug)
+```
+
+The method returns only resource properties. `@SirenEntityDecorator(...)` retains its signature for
+Ninja's parameter inspection, supplies route arguments as path values, supports sync and async
+handlers, and projects the result through the standard `ModwireSiren` composition root.
+
+## Development and release
+
+Run `uv sync --all-groups` and `make verify`. Releases use strict SemVer tags and PyPI Trusted
+Publishing configured for repository `9orky/modwire-siren`, workflow `release.yml`, and environment
+`pypi`.

modwire_siren-0.1.0/README.md

@@ -0,0 +1,117 @@
+# modwire-siren
+
+Typed Siren documents projected from OpenAPI without application-owned route maps.
+
+Every external boundary is behind a package interface: catalog, href resolution, field policy,
+field creation, link creation, resource hrefs, and serialization. `ModwireSirenFactory` is the
+standard composition root; `ModwireSiren` is the small public façade.
+
+<!-- generated:public-api:start -->
+## Public API
+
+The supported root imports below are generated from `modwire_siren.__all__`.
+
+| Symbol | Purpose | Primary API |
+| --- | --- | --- |
+| `ModwireSiren` | Project validated entity requests into serialized Siren documents. | `document(request: modwire_siren.contracts.entity.SirenEntityRequest) -> dict[str, typing.Any]` |
+| `ModwireSirenFactory` | Build the standard OpenAPI-backed Siren façade. | `standard(schema: dict[str, typing.Any], base_url: str) -> modwire_siren.facade.ModwireSiren` |
+| `NinjaExtraSirenController` | Framework-light base for Ninja Extra controllers that emit Siren documents. | `siren_document(resource_name: str, properties: collections.abc.Mapping[str, typing.Any], operation_ids: tuple[str, ...], path_values: collections.abc.Mapping[str, typing.Any], entities: tuple[modwire_siren.contracts.entity.SirenEmbeddedEntity, ...] = ()) -> dict[str, typing.Any]` |
+| `OpenApiError` | Report invalid or incomplete OpenAPI data used for Siren projection. | — |
+| `SirenEntityDecorator` | Turn a controller method's property mapping into a Siren entity document. | — |
+| `SirenEntityRequest` | Describe the resource data and allowed operations projected into one entity. | — |
+| `__version__` | Installed distribution version. | — |
+
+## Executable example
+
+Source: [`build_document.py`](examples/build_document.py). This file is executed by the test suite.
+
+```python
+from modwire_siren import ModwireSirenFactory, SirenEntityRequest
+
+openapi_schema = {
+    "openapi": "3.1.0",
+    "paths": {
+        "/records/{record_slug}": {
+            "x-siren-resource": {
+                "name": "record",
+                "class": "record",
+                "identifier": "slug",
+                "path-parameters": {"record_slug": "slug"},
+                "relations": {},
+            },
+            "get": {"operationId": "get_record", "summary": "Get record"},
+        }
+    },
+}
+
+siren = ModwireSirenFactory.standard(openapi_schema, "https://api.example.com/")
+document = siren.document(
+    SirenEntityRequest(
+        resource_name="record",
+        properties={"slug": "architecture/aggregate", "title": "Architecture"},
+        operation_ids=("get_record",),
+        path_values={},
+        entities=(),
+    )
+)
+```
+<!-- generated:public-api:end -->
+
+## OpenAPI contract
+
+```yaml
+paths:
+  /records/{record_slug}:
+    x-siren-resource:
+      name: record
+      class: record
+      identifier: slug
+      path-parameters:
+        record_slug: slug
+      relations:
+        section_slug:
+          rel: section
+          resource: section
+          many: false
+    patch:
+      operationId: revise_record
+      summary: Revise record
+```
+
+The strict `OpenApiResourceExtension` validates the extension. Unknown resources, incomplete path
+mappings, absent operation IDs, and unknown schema references fail while building the catalog.
+
+The Pydantic Siren contracts own wire aliases such as `class`, `type`, and `schema`.
+`PydanticSirenSerializer` implements the `SirenSerializer` interface with one model dump; it does
+not redeclare the wire schema.
+
+## Django Ninja Extra
+
+The controller adapter does not import Django or Ninja Extra, so the core package keeps no framework
+dependency. It composes directly with Ninja Extra's controller and route decorators:
+
+```python
+from ninja_extra import ControllerBase, api_controller, route
+from modwire_siren import ModwireSiren, NinjaExtraSirenController, SirenEntityDecorator
+
+@api_controller("/records")
+class RecordController(ControllerBase, NinjaExtraSirenController):
+    def __init__(self, records: RecordService, siren: ModwireSiren):
+        NinjaExtraSirenController.__init__(self, siren)
+        self.records = records
+
+    @route.get("/{record_slug}", operation_id="get_record")
+    @SirenEntityDecorator("record", operations=("revise_record",))
+    def get_record(self, record_slug: str):
+        return self.records.get(record_slug)
+```
+
+The method returns only resource properties. `@SirenEntityDecorator(...)` retains its signature for
+Ninja's parameter inspection, supplies route arguments as path values, supports sync and async
+handlers, and projects the result through the standard `ModwireSiren` composition root.
+
+## Development and release
+
+Run `uv sync --all-groups` and `make verify`. Releases use strict SemVer tags and PyPI Trusted
+Publishing configured for repository `9orky/modwire-siren`, workflow `release.yml`, and environment
+`pypi`.

modwire_siren-0.1.0/examples/build_document.py

@@ -0,0 +1,28 @@
+from modwire_siren import ModwireSirenFactory, SirenEntityRequest
+
+openapi_schema = {
+    "openapi": "3.1.0",
+    "paths": {
+        "/records/{record_slug}": {
+            "x-siren-resource": {
+                "name": "record",
+                "class": "record",
+                "identifier": "slug",
+                "path-parameters": {"record_slug": "slug"},
+                "relations": {},
+            },
+            "get": {"operationId": "get_record", "summary": "Get record"},
+        }
+    },
+}
+
+siren = ModwireSirenFactory.standard(openapi_schema, "https://api.example.com/")
+document = siren.document(
+    SirenEntityRequest(
+        resource_name="record",
+        properties={"slug": "architecture/aggregate", "title": "Architecture"},
+        operation_ids=("get_record",),
+        path_values={},
+        entities=(),
+    )
+)

modwire_siren-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling>=1.28", "hatch-vcs>=0.5"]
+build-backend = "hatchling.build"
+
+[project]
+name = "modwire-siren"
+dynamic = ["version"]
+description = "Siren hypermedia and OpenAPI integration for Modwire."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [{ name = "9orky" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Typing :: Typed",
+]
+
+dependencies = ["pydantic>=2.12"]
+
+[dependency-groups]
+dev = ["build>=1.3", "packaging>=25", "pytest>=9", "ruff>=0.14", "twine>=6"]
+
+[project.urls]
+Repository = "https://github.com/9orky/modwire-siren"
+Issues = "https://github.com/9orky/modwire-siren/issues"
+
+[tool.hatch.version]
+source = "vcs"
+tag-pattern = '^v(?P<version>\d+\.\d+\.\d+)$'
+fallback-version = "0.0.0"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/modwire_siren/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/modwire_siren"]
+
+[tool.hatch.build.targets.sdist]
+include = ["examples", "src", "tests", "README.md", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = ["-ra", "--strict-config", "--strict-markers"]
+filterwarnings = ["error"]
+
+[tool.ruff]
+line-length = 120
+extend-exclude = ["**/_version.py"]
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]

modwire_siren-0.1.0/src/modwire_siren/__init__.py

@@ -0,0 +1,16 @@
+from ._version import __version__
+from .composition import ModwireSirenFactory
+from .contracts.entity import SirenEntityRequest
+from .facade import ModwireSiren
+from .integrations.ninja_extra import NinjaExtraSirenController, SirenEntityDecorator
+from .openapi.error import OpenApiError
+
+__all__ = [
+    "ModwireSiren",
+    "ModwireSirenFactory",
+    "NinjaExtraSirenController",
+    "OpenApiError",
+    "SirenEntityDecorator",
+    "SirenEntityRequest",
+    "__version__",
+]

modwire_siren-0.1.0/src/modwire_siren/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

modwire_siren-0.1.0/src/modwire_siren/composition.py

@@ -0,0 +1,28 @@
+from typing import Any
+
+from .facade import ModwireSiren
+from .factories.action import SirenActionFactory
+from .factories.entity import SirenEntityFactory
+from .factories.field import OpenApiSirenFieldFactory
+from .factories.link import OpenApiSirenLinkFactory
+from .factories.resource import OpenApiSirenResourceHrefResolver
+from .openapi.factory import OpenApiCatalogFactory
+from .openapi.href import OpenApiHrefResolver
+from .policies.field_type import OpenApiSirenFieldTypeResolver
+from .serialization import PydanticSirenSerializer
+
+
+class ModwireSirenFactory:
+    """Build the standard OpenAPI-backed Siren façade."""
+
+    @classmethod
+    def standard(cls, schema: dict[str, Any], base_url: str) -> ModwireSiren:
+        """Create a ready-to-use façade from an OpenAPI schema and API base URL."""
+        catalog = OpenApiCatalogFactory.create(schema)
+        hrefs = OpenApiHrefResolver(base_url)
+        resource_hrefs = OpenApiSirenResourceHrefResolver(hrefs)
+        fields = OpenApiSirenFieldFactory(OpenApiSirenFieldTypeResolver())
+        actions = SirenActionFactory(catalog, hrefs, fields)
+        links = OpenApiSirenLinkFactory(catalog, resource_hrefs)
+        entities = SirenEntityFactory(catalog, resource_hrefs, links, actions)
+        return ModwireSiren(entities, PydanticSirenSerializer())

modwire_siren-0.1.0/src/modwire_siren/contracts/action.py

@@ -0,0 +1,28 @@
+from typing import Annotated, Any
+
+from pydantic import Field, field_validator
+
+from .base import SirenContract
+
+
+class SirenField(SirenContract):
+    name: str
+    type: str
+    required: bool
+    title: str
+    options: tuple[dict[str, Any], ...]
+    schema_definition: Annotated[dict[str, Any], Field(validation_alias="schema", serialization_alias="schema")]
+
+
+class SirenAction(SirenContract):
+    name: str
+    href: str
+    method: str
+    title: str
+    media_type: Annotated[str, Field(serialization_alias="type")]
+    fields: tuple[SirenField, ...]
+
+    @field_validator("method")
+    @classmethod
+    def normalize_method(cls, value: str) -> str:
+        return value.upper()

modwire_siren-0.1.0/src/modwire_siren/contracts/base.py

@@ -0,0 +1,5 @@
+from pydantic import BaseModel, ConfigDict
+
+
+class SirenContract(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True, strict=True)

modwire_siren-0.1.0/src/modwire_siren/contracts/entity.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+from pydantic import Field, model_serializer
+
+from .action import SirenAction
+from .base import SirenContract
+from .link import SirenLink
+
+
+class SirenEntity(SirenContract):
+    classes: Annotated[tuple[str, ...], Field(serialization_alias="class")]
+    properties: dict[str, Any]
+    links: tuple[SirenLink, ...]
+    actions: tuple[SirenAction, ...]
+    entities: tuple[SirenEmbeddedEntity, ...]
+
+
+class SirenEmbeddedEntity(SirenContract):
+    rel: tuple[str, ...]
+    entity: SirenEntity
+
+    @model_serializer
+    def serialize(self) -> dict[str, Any]:
+        return {"rel": self.rel, **self.entity.model_dump(mode="json", by_alias=True)}
+
+
+class SirenEntityRequest(SirenContract):
+    """Describe the resource data and allowed operations projected into one entity."""
+
+    resource_name: str
+    properties: dict[str, Any]
+    operation_ids: tuple[str, ...]
+    path_values: dict[str, Any]
+    entities: tuple[SirenEmbeddedEntity, ...]
+
+
+SirenEntity.model_rebuild()

modwire_siren-0.1.0/src/modwire_siren/contracts/link.py

@@ -0,0 +1,12 @@
+from typing import Annotated
+
+from pydantic import Field
+
+from .base import SirenContract
+
+
+class SirenLink(SirenContract):
+    rel: tuple[str, ...]
+    href: str
+    title: str
+    media_type: Annotated[str, Field(serialization_alias="type")]

modwire_siren-0.1.0/src/modwire_siren/contracts/operation.py

@@ -0,0 +1,19 @@
+from typing import Annotated, Any
+
+from pydantic import Field
+
+from .base import SirenContract
+
+
+class OpenApiField(SirenContract):
+    name: str
+    schema_definition: Annotated[dict[str, Any], Field(validation_alias="schema")]
+    required: bool
+
+
+class OpenApiOperation(SirenContract):
+    operation_id: str
+    method: str
+    path: str
+    title: str
+    fields: tuple[OpenApiField, ...]

modwire_siren-0.1.0/src/modwire_siren/contracts/resource.py

@@ -0,0 +1,17 @@
+from .base import SirenContract
+
+
+class SirenRelation(SirenContract):
+    field: str
+    rel: str
+    resource: str
+    many: bool
+
+
+class SirenResource(SirenContract):
+    name: str
+    path: str
+    resource_class: str
+    identifier: str
+    path_parameters: dict[str, str]
+    relations: tuple[SirenRelation, ...]

modwire_siren-0.1.0/src/modwire_siren/facade.py

@@ -0,0 +1,17 @@
+from typing import Any
+
+from .contracts.entity import SirenEntityRequest
+from .factories.entity import SirenEntityFactory
+from .serialization import SirenSerializer
+
+
+class ModwireSiren:
+    """Project validated entity requests into serialized Siren documents."""
+
+    def __init__(self, entities: SirenEntityFactory, serializer: SirenSerializer):
+        self._entities = entities
+        self._serializer = serializer
+
+    def document(self, request: SirenEntityRequest) -> dict[str, Any]:
+        """Build and serialize one Siren entity document."""
+        return self._serializer.serialize(self._entities.create(request))

modwire_siren-0.1.0/src/modwire_siren/factories/action.py

@@ -0,0 +1,30 @@
+from collections.abc import Mapping
+from typing import Any
+
+from ..contracts.action import SirenAction
+from ..openapi.catalog import SirenResourceCatalog
+from ..openapi.href import SirenHrefResolver
+from ..standards import SirenMediaType
+from .field import SirenFieldFactory
+
+
+class SirenActionFactory:
+    def __init__(
+        self,
+        catalog: SirenResourceCatalog,
+        hrefs: SirenHrefResolver,
+        fields: SirenFieldFactory,
+    ):
+        self._catalog = catalog
+        self._hrefs = hrefs
+        self._fields = fields
+
+    def create(self, operation_id: str, path_values: Mapping[str, Any]) -> SirenAction:
+        operation = self._catalog.operation(operation_id)
+        return SirenAction(
+            **operation.model_dump(include={"method", "title"}),
+            name=operation.operation_id,
+            href=self._hrefs.resolve(operation.path, path_values),
+            media_type=SirenMediaType.ACTION,
+            fields=tuple(self._fields.create(field) for field in operation.fields),
+        )

modwire_siren-0.1.0/src/modwire_siren/factories/entity.py

@@ -0,0 +1,38 @@
+from ..contracts.entity import SirenEntity, SirenEntityRequest
+from ..openapi.catalog import SirenResourceCatalog
+from ..openapi.error import OpenApiError
+from .action import SirenActionFactory
+from .link import SirenLinkFactory
+from .resource import SirenResourceHrefResolver
+
+
+class SirenEntityFactory:
+    def __init__(
+        self,
+        catalog: SirenResourceCatalog,
+        hrefs: SirenResourceHrefResolver,
+        links: SirenLinkFactory,
+        actions: SirenActionFactory,
+    ):
+        self._catalog = catalog
+        self._hrefs = hrefs
+        self._links = links
+        self._actions = actions
+
+    def create(self, request: SirenEntityRequest) -> SirenEntity:
+        resource = self._catalog.resource(request.resource_name)
+        operations = tuple(self._catalog.operation(operation_id) for operation_id in request.operation_ids)
+        foreign = tuple(operation.operation_id for operation in operations if operation.path != resource.path)
+        if foreign:
+            raise OpenApiError(f"Operations {list(foreign)} do not belong to resource {resource.name!r}")
+        values = request.properties | request.path_values
+        operation_values = self._hrefs.path_values(resource, values)
+        return SirenEntity(
+            classes=(resource.resource_class,),
+            properties=request.properties,
+            links=self._links.create(resource, values),
+            actions=tuple(
+                self._actions.create(operation.operation_id, operation_values) for operation in operations
+            ),
+            entities=request.entities,
+        )

modwire_siren-0.1.0/src/modwire_siren/factories/field.py

@@ -0,0 +1,28 @@
+from abc import ABC, abstractmethod
+
+from ..contracts.action import SirenField
+from ..contracts.operation import OpenApiField
+from ..policies.field_type import SirenFieldTypeResolver
+from ..standards import SirenFieldType
+
+
+class SirenFieldFactory(ABC):
+    @abstractmethod
+    def create(self, field: OpenApiField) -> SirenField:
+        raise NotImplementedError
+
+
+class OpenApiSirenFieldFactory(SirenFieldFactory):
+    def __init__(self, types: SirenFieldTypeResolver):
+        self._types = types
+
+    def create(self, field: OpenApiField) -> SirenField:
+        field_type = self._types.resolve(field.schema_definition)
+        return SirenField(
+            name=field.name,
+            type=field_type,
+            required=field.required,
+            title=field.schema_definition.get("title", field.name),
+            options=tuple({"value": value, "title": str(value)} for value in field.schema_definition.get("enum", [])),
+            schema=field.schema_definition if field_type is SirenFieldType.JSON else {},
+        )