modwire-siren 0.1.0__py3-none-any.whl

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/_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/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/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/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/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/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/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/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/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/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/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/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 {},
+        )

modwire_siren/factories/link.py

@@ -0,0 +1,62 @@
+from abc import ABC, abstractmethod
+from collections.abc import Iterable, Mapping
+from typing import Any
+
+from ..contracts.link import SirenLink
+from ..contracts.resource import SirenRelation, SirenResource
+from ..openapi.catalog import SirenResourceCatalog
+from ..openapi.error import OpenApiError
+from ..standards import SirenMediaType, SirenRelationName
+from .resource import SirenResourceHrefResolver
+
+
+class SirenLinkFactory(ABC):
+    @abstractmethod
+    def create(self, resource: SirenResource, properties: Mapping[str, Any]) -> tuple[SirenLink, ...]:
+        raise NotImplementedError
+
+
+class OpenApiSirenLinkFactory(SirenLinkFactory):
+    def __init__(self, catalog: SirenResourceCatalog, hrefs: SirenResourceHrefResolver):
+        self._catalog = catalog
+        self._hrefs = hrefs
+
+    def create(self, resource: SirenResource, properties: Mapping[str, Any]) -> tuple[SirenLink, ...]:
+        return (self._self_link(resource, properties), *self._relation_links(resource, properties))
+
+    def _self_link(self, resource: SirenResource, properties: Mapping[str, Any]) -> SirenLink:
+        return SirenLink(
+            rel=(SirenRelationName.SELF,),
+            href=self._hrefs.href(resource, properties),
+            title=resource.resource_class,
+            media_type=SirenMediaType.ENTITY,
+        )
+
+    def _relation_links(self, resource: SirenResource, properties: Mapping[str, Any]) -> tuple[SirenLink, ...]:
+        return tuple(
+            self._relation_link(relation, value)
+            for relation in resource.relations
+            if relation.field in properties
+            for value in self._relation_values(relation, properties[relation.field])
+        )
+
+    def _relation_link(self, relation: SirenRelation, value: Any) -> SirenLink:
+        target = self._catalog.resource(relation.resource)
+        return SirenLink(
+            rel=(relation.rel,),
+            href=self._hrefs.href(target, {target.identifier: value}),
+            title=relation.rel,
+            media_type=SirenMediaType.ENTITY,
+        )
+
+    def _relation_values(self, relation: SirenRelation, value: Any) -> tuple[Any, ...]:
+        if value is None:
+            raise OpenApiError(f"Relation {relation.rel!r} requires a non-null value")
+        if relation.many:
+            if isinstance(value, (str, bytes, Mapping)) or not isinstance(value, Iterable):
+                raise OpenApiError(f"Relation {relation.rel!r} requires an iterable value")
+            values = tuple(value)
+            if any(item is None for item in values):
+                raise OpenApiError(f"Relation {relation.rel!r} requires non-null values")
+            return values
+        return (value,)

modwire_siren/factories/resource.py

@@ -0,0 +1,31 @@
+from abc import ABC, abstractmethod
+from collections.abc import Mapping
+from typing import Any
+
+from ..contracts.resource import SirenResource
+from ..openapi.error import OpenApiError
+from ..openapi.href import SirenHrefResolver
+
+
+class SirenResourceHrefResolver(ABC):
+    @abstractmethod
+    def href(self, resource: SirenResource, values: Mapping[str, Any]) -> str:
+        raise NotImplementedError
+
+    @abstractmethod
+    def path_values(self, resource: SirenResource, values: Mapping[str, Any]) -> dict[str, Any]:
+        raise NotImplementedError
+
+
+class OpenApiSirenResourceHrefResolver(SirenResourceHrefResolver):
+    def __init__(self, hrefs: SirenHrefResolver):
+        self._hrefs = hrefs
+
+    def href(self, resource: SirenResource, values: Mapping[str, Any]) -> str:
+        return self._hrefs.resolve(resource.path, self.path_values(resource, values))
+
+    def path_values(self, resource: SirenResource, values: Mapping[str, Any]) -> dict[str, Any]:
+        missing = set(resource.path_parameters.values()) - set(values)
+        if missing:
+            raise OpenApiError(f"Missing properties {sorted(missing)} for resource {resource.name!r}")
+        return {parameter: values[property_name] for parameter, property_name in resource.path_parameters.items()}

modwire_siren/integrations/ninja_extra.py

@@ -0,0 +1,80 @@
+import inspect
+from collections.abc import Awaitable, Callable, Mapping
+from functools import wraps
+from typing import Any, TypeVar, cast
+
+from ..contracts.entity import SirenEmbeddedEntity, SirenEntityRequest
+from ..facade import ModwireSiren
+
+Result = Mapping[str, Any]
+F = TypeVar("F", bound=Callable[..., Result | Awaitable[Result]])
+
+
+class NinjaExtraSirenController:
+    """Framework-light base for Ninja Extra controllers that emit Siren documents."""
+
+    def __init__(self, siren: ModwireSiren):
+        self._siren = siren
+
+    def siren_document(
+        self,
+        resource_name: str,
+        properties: Mapping[str, Any],
+        operation_ids: tuple[str, ...],
+        path_values: Mapping[str, Any],
+        entities: tuple[SirenEmbeddedEntity, ...] = (),
+    ) -> dict[str, Any]:
+        return self._siren.document(
+            SirenEntityRequest(
+                resource_name=resource_name,
+                properties=dict(properties),
+                operation_ids=operation_ids,
+                path_values=dict(path_values),
+                entities=entities,
+            )
+        )
+
+
+class SirenEntityDecorator:
+    """Turn a controller method's property mapping into a Siren entity document."""
+
+    def __init__(self, resource_name: str, *, operations: tuple[str, ...]):
+        if not resource_name.strip():
+            raise ValueError("Siren resource name must not be blank")
+        self._resource_name = resource_name
+        self._operations = operations
+
+    def __call__(self, function: F) -> F:
+        signature = inspect.signature(function)
+        resource_name = self._resource_name
+        operations = self._operations
+
+        def path_values(args: tuple[Any, ...], kwargs: dict[str, Any]) -> dict[str, Any]:
+            arguments = signature.bind(*args, **kwargs).arguments
+            return {name: value for name, value in arguments.items() if name not in {"self", "request"}}
+
+        if inspect.iscoroutinefunction(function):
+
+            @wraps(function)
+            async def async_wrapper(self: NinjaExtraSirenController, *args: Any, **kwargs: Any) -> dict[str, Any]:
+                properties = await function(self, *args, **kwargs)
+                return self.siren_document(
+                    resource_name,
+                    properties,
+                    operations,
+                    path_values((self, *args), kwargs),
+                )
+
+            return cast(F, async_wrapper)
+
+        @wraps(function)
+        def wrapper(self: NinjaExtraSirenController, *args: Any, **kwargs: Any) -> dict[str, Any]:
+            properties = function(self, *args, **kwargs)
+            return self.siren_document(
+                resource_name,
+                properties,
+                operations,
+                path_values((self, *args), kwargs),
+            )
+
+        return cast(F, wrapper)

modwire_siren/openapi/catalog.py

@@ -0,0 +1,62 @@
+import re
+from abc import ABC, abstractmethod
+from collections.abc import Iterable
+
+from ..contracts.operation import OpenApiOperation
+from ..contracts.resource import SirenResource
+from .error import OpenApiError
+
+
+class SirenResourceCatalog(ABC):
+    @abstractmethod
+    def operation(self, operation_id: str) -> OpenApiOperation:
+        raise NotImplementedError
+
+    @abstractmethod
+    def resource(self, name: str) -> SirenResource:
+        raise NotImplementedError
+
+
+class OpenApiCatalog(SirenResourceCatalog):
+    def __init__(self, operations: tuple[OpenApiOperation, ...], resources: tuple[SirenResource, ...]):
+        self._reject_duplicates("OpenAPI operationId", (item.operation_id for item in operations))
+        self._reject_duplicates("Siren resource name", (item.name for item in resources))
+        self._operations = {item.operation_id: item for item in operations}
+        self._resources = {item.name: item for item in resources}
+        self._validate_resources()
+
+    @staticmethod
+    def _reject_duplicates(label: str, values: Iterable[str]) -> None:
+        seen: set[str] = set()
+        duplicates: set[str] = set()
+        for value in values:
+            if value in seen:
+                duplicates.add(value)
+            seen.add(value)
+        if duplicates:
+            raise OpenApiError(f"Duplicate {label}: {sorted(duplicates)}")
+
+    def operation(self, operation_id: str) -> OpenApiOperation:
+        try:
+            return self._operations[operation_id]
+        except KeyError as error:
+            raise OpenApiError(f"Unknown OpenAPI operation: {operation_id}") from error
+
+    def resource(self, name: str) -> SirenResource:
+        try:
+            return self._resources[name]
+        except KeyError as error:
+            raise OpenApiError(f"Unknown Siren resource: {name}") from error
+
+    def _validate_resources(self) -> None:
+        for resource in self._resources.values():
+            placeholders = set(re.findall(r"{([^}]+)}", resource.path))
+            declared = set(resource.path_parameters)
+            if placeholders != declared:
+                raise OpenApiError(
+                    f"Resource {resource.name!r} path parameters must explicitly map "
+                    f"{sorted(placeholders)}; received {sorted(declared)}"
+                )
+            unknown = {relation.resource for relation in resource.relations} - set(self._resources)
+            if unknown:
+                raise OpenApiError(f"Resource {resource.name!r} references unknown resources: {sorted(unknown)}")

modwire_siren/openapi/contracts.py

@@ -0,0 +1,19 @@
+from typing import Annotated
+
+from pydantic import Field
+
+from ..contracts.base import SirenContract
+
+
+class OpenApiRelationExtension(SirenContract):
+    rel: str
+    resource: str
+    many: bool
+
+
+class OpenApiResourceExtension(SirenContract):
+    name: str
+    resource_class: Annotated[str, Field(validation_alias="class")]
+    identifier: str
+    path_parameters: Annotated[dict[str, str], Field(validation_alias="path-parameters")]
+    relations: dict[str, OpenApiRelationExtension]

modwire_siren/openapi/error.py

@@ -0,0 +1,4 @@
+class OpenApiError(ValueError):
+    """Report invalid or incomplete OpenAPI data used for Siren projection."""
+
+    pass

modwire_siren/openapi/factory.py

@@ -0,0 +1,16 @@
+from typing import Any
+
+from .catalog import OpenApiCatalog
+from .operation import OpenApiOperationReader
+from .resolver import ComponentSchemaResolver
+from .resource import OpenApiResourceReader
+
+
+class OpenApiCatalogFactory:
+    @classmethod
+    def create(cls, schema: dict[str, Any]) -> OpenApiCatalog:
+        components = schema.get("components", {}).get("schemas", {})
+        paths = schema.get("paths", {})
+        operations = OpenApiOperationReader(ComponentSchemaResolver(components)).read(paths)
+        resources = OpenApiResourceReader().read(paths)
+        return OpenApiCatalog(operations, resources)

modwire_siren/openapi/href.py

@@ -0,0 +1,26 @@
+import re
+from abc import ABC, abstractmethod
+from collections.abc import Mapping
+from typing import Any
+from urllib.parse import quote, urljoin
+
+from .error import OpenApiError
+
+
+class SirenHrefResolver(ABC):
+    @abstractmethod
+    def resolve(self, path: str, values: Mapping[str, Any]) -> str:
+        raise NotImplementedError
+
+
+class OpenApiHrefResolver(SirenHrefResolver):
+    def __init__(self, base_url: str):
+        self._base_url = base_url.rstrip("/") + "/"
+
+    def resolve(self, path: str, values: Mapping[str, Any]) -> str:
+        resolved = path
+        for name in re.findall(r"{([^}]+)}", path):
+            if name not in values:
+                raise OpenApiError(f"Missing path value {name!r} for {path}")
+            resolved = resolved.replace(f"{{{name}}}", quote(str(values[name]), safe=""))
+        return urljoin(self._base_url, resolved.lstrip("/"))

modwire_siren/openapi/method.py

@@ -0,0 +1,12 @@
+from enum import StrEnum
+
+
+class OpenApiHttpMethod(StrEnum):
+    DELETE = "delete"
+    GET = "get"
+    HEAD = "head"
+    OPTIONS = "options"
+    PATCH = "patch"
+    POST = "post"
+    PUT = "put"
+    TRACE = "trace"

modwire_siren/openapi/operation.py

@@ -0,0 +1,73 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+from ..contracts.operation import OpenApiField, OpenApiOperation
+from ..standards import SirenMediaType
+from .error import OpenApiError
+from .method import OpenApiHttpMethod
+from .resolver import OpenApiSchemaResolver
+
+
+class OpenApiOperationSource(ABC):
+    @abstractmethod
+    def read(self, paths: dict[str, Any]) -> tuple[OpenApiOperation, ...]:
+        raise NotImplementedError
+
+
+class OpenApiOperationReader(OpenApiOperationSource):
+    def __init__(self, schemas: OpenApiSchemaResolver):
+        self._schemas = schemas
+
+    def read(self, paths: dict[str, Any]) -> tuple[OpenApiOperation, ...]:
+        return tuple(
+            self._operation(path, method, specification, path_item.get("parameters", ()))
+            for path, path_item in paths.items()
+            for method, specification in path_item.items()
+            if method.lower() in OpenApiHttpMethod and isinstance(specification, dict)
+        )
+
+    def _operation(
+        self,
+        path: str,
+        method: str,
+        specification: dict[str, Any],
+        path_parameters: list[dict[str, Any]] | tuple[dict[str, Any], ...],
+    ) -> OpenApiOperation:
+        operation_id = specification.get("operationId")
+        if not operation_id:
+            raise OpenApiError(f"Siren requires operationId for {method.upper()} {path}")
+        return OpenApiOperation(
+            operation_id=operation_id,
+            method=method.upper(),
+            path=path,
+            title=specification.get("summary", operation_id),
+            fields=self._fields(specification, path_parameters),
+        )
+
+    def _fields(
+        self,
+        specification: dict[str, Any],
+        path_parameters: list[dict[str, Any]] | tuple[dict[str, Any], ...],
+    ) -> tuple[OpenApiField, ...]:
+        parameters = {
+            (parameter.get("name"), parameter.get("in")): parameter
+            for parameter in (*path_parameters, *specification.get("parameters", ()))
+        }
+        query = tuple(
+            OpenApiField(
+                name=parameter["name"],
+                schema=self._schemas.resolve(parameter.get("schema", {})),
+                required=parameter.get("required", False),
+            )
+            for parameter in parameters.values()
+            if parameter.get("in") == "query"
+        )
+        content = specification.get("requestBody", {}).get("content", {})
+        media = content.get(SirenMediaType.ACTION) or next(iter(content.values()), {})
+        schema = self._schemas.resolve(media.get("schema", {}))
+        required = set(schema.get("required", []))
+        body = tuple(
+            OpenApiField(name=name, schema=self._schemas.resolve(value), required=name in required)
+            for name, value in schema.get("properties", {}).items()
+        )
+        return query + body

modwire_siren/openapi/resolver.py

@@ -0,0 +1,56 @@
+from abc import ABC, abstractmethod
+from copy import deepcopy
+from typing import Any
+
+from .error import OpenApiError
+
+
+class OpenApiSchemaResolver(ABC):
+    @abstractmethod
+    def resolve(self, schema: dict[str, Any]) -> dict[str, Any]:
+        raise NotImplementedError
+
+
+class ComponentSchemaResolver(OpenApiSchemaResolver):
+    def __init__(self, components: dict[str, Any]):
+        self._components = deepcopy(components)
+
+    def resolve(self, schema: dict[str, Any]) -> dict[str, Any]:
+        return self._resolve(schema, ())
+
+    def _resolve(self, schema: dict[str, Any], resolving: tuple[str, ...]) -> dict[str, Any]:
+        resolved = deepcopy(schema)
+        reference = resolved.pop("$ref", None)
+        if reference:
+            component_name = reference.rsplit("/", 1)[-1]
+            if component_name not in self._components:
+                raise OpenApiError(f"Unknown OpenAPI schema reference: {reference}")
+            if component_name in resolving:
+                chain = " -> ".join((*resolving, component_name))
+                raise OpenApiError(f"Circular OpenAPI schema reference: {chain}")
+            resolved = deepcopy(self._components[component_name]) | resolved
+            resolving = (*resolving, component_name)
+        merged: dict[str, Any] = {}
+        for part in resolved.pop("allOf", ()):
+            merged = self._merge(merged, self._resolve(part, resolving))
+        resolved = self._merge(merged, resolved)
+        for keyword in ("anyOf", "oneOf", "prefixItems"):
+            if keyword in resolved:
+                resolved[keyword] = [self._resolve(item, resolving) for item in resolved[keyword]]
+        for keyword in ("items", "additionalProperties"):
+            if isinstance(resolved.get(keyword), dict):
+                resolved[keyword] = self._resolve(resolved[keyword], resolving)
+        if "properties" in resolved:
+            resolved["properties"] = {
+                name: self._resolve(value, resolving) for name, value in resolved["properties"].items()
+            }
+        return resolved
+
+    @staticmethod
+    def _merge(left: dict[str, Any], right: dict[str, Any]) -> dict[str, Any]:
+        merged = left | right
+        if "properties" in left or "properties" in right:
+            merged["properties"] = left.get("properties", {}) | right.get("properties", {})
+        if "required" in left or "required" in right:
+            merged["required"] = list(dict.fromkeys((*left.get("required", ()), *right.get("required", ()))))
+        return merged

modwire_siren/openapi/resource.py

@@ -0,0 +1,34 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+from ..contracts.resource import SirenRelation, SirenResource
+from ..standards import SirenOpenApiExtension
+from .contracts import OpenApiResourceExtension
+
+
+class OpenApiResourceSource(ABC):
+    @abstractmethod
+    def read(self, paths: dict[str, Any]) -> tuple[SirenResource, ...]:
+        raise NotImplementedError
+
+
+class OpenApiResourceReader(OpenApiResourceSource):
+    def read(self, paths: dict[str, Any]) -> tuple[SirenResource, ...]:
+        return tuple(
+            self._resource(path, raw_extension)
+            for path, path_item in paths.items()
+            if (raw_extension := path_item.get(SirenOpenApiExtension.RESOURCE))
+        )
+
+    def _resource(self, path: str, raw_extension: dict[str, Any]) -> SirenResource:
+        extension = OpenApiResourceExtension.model_validate(raw_extension)
+        return SirenResource(
+            name=extension.name,
+            path=path,
+            resource_class=extension.resource_class,
+            identifier=extension.identifier,
+            path_parameters=extension.path_parameters,
+            relations=tuple(
+                SirenRelation(field=field, **relation.model_dump()) for field, relation in extension.relations.items()
+            ),
+        )

modwire_siren/policies/field_type.py

@@ -0,0 +1,24 @@
+from abc import ABC, abstractmethod
+from typing import ClassVar
+
+from ..standards import SirenFieldType
+
+
+class SirenFieldTypeResolver(ABC):
+    @abstractmethod
+    def resolve(self, schema: dict) -> SirenFieldType:
+        raise NotImplementedError
+
+
+class OpenApiSirenFieldTypeResolver(SirenFieldTypeResolver):
+    TYPE_MAP: ClassVar = {
+        "boolean": SirenFieldType.CHECKBOX,
+        "integer": SirenFieldType.NUMBER,
+        "string": SirenFieldType.TEXT,
+    }
+
+    def resolve(self, schema: dict) -> SirenFieldType:
+        kind = schema.get("type", "string")
+        if kind in {"array", "object"} or "anyOf" in schema:
+            return SirenFieldType.JSON
+        return self.TYPE_MAP.get(kind, SirenFieldType.TEXT)

modwire_siren/py.typed

@@ -0,0 +1 @@
+# typed

modwire_siren/serialization.py

@@ -0,0 +1,15 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+from .contracts.entity import SirenEntity
+
+
+class SirenSerializer(ABC):
+    @abstractmethod
+    def serialize(self, entity: SirenEntity) -> dict[str, Any]:
+        raise NotImplementedError
+
+
+class PydanticSirenSerializer(SirenSerializer):
+    def serialize(self, entity: SirenEntity) -> dict[str, Any]:
+        return entity.model_dump(mode="json", by_alias=True)

modwire_siren/standards.py

@@ -0,0 +1,21 @@
+from enum import StrEnum
+
+
+class SirenMediaType(StrEnum):
+    ACTION = "application/json"
+    ENTITY = "application/vnd.siren+json"
+
+
+class SirenRelationName(StrEnum):
+    SELF = "self"
+
+
+class SirenFieldType(StrEnum):
+    CHECKBOX = "checkbox"
+    JSON = "json"
+    NUMBER = "number"
+    TEXT = "text"
+
+
+class SirenOpenApiExtension(StrEnum):
+    RESOURCE = "x-siren-resource"

modwire_siren-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,37 @@
+modwire_siren/__init__.py,sha256=J-p2o0e1M4belucGsiXkKRF71NrJ8OWQYz4mO9XG6Ms,475
+modwire_siren/_version.py,sha256=n_5vdJsPNu7wZ57LGuRL585uvll-hiuvZUBWzdG0RQU,520
+modwire_siren/composition.py,sha256=1rAw--WSHZxdOLsgOKPCrXRNazHxBcl8NlgTTNy_KNI,1317
+modwire_siren/facade.py,sha256=0EFpJclK4vVSCU6D7Ptr5gQ4pl24yx8H9PrVcDw3R5k,627
+modwire_siren/py.typed,sha256=PkRcTGuZkArgW1q-rCE9SkWNSwwdgEXZnIl5CY27NgY,7
+modwire_siren/serialization.py,sha256=Ib0YkbaitVgg2KDA1_iOMMQl6qPok1rr6BT2Cs54l6k,425
+modwire_siren/standards.py,sha256=U1sEaB-WlC7S9jcm4Ih4BEYWG8b8Y8uNsIJIfO5amlE,377
+modwire_siren/contracts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+modwire_siren/contracts/action.py,sha256=Q26YC2xRHATDK_nQyH_pda-EFZoAZc7X7DWaDqbOYSA,686
+modwire_siren/contracts/base.py,sha256=bNXaMJwu7yr-BjfJVDnmDp2zwGRHPNvj21bsqMR1Y5c,149
+modwire_siren/contracts/entity.py,sha256=YSGwTnzPolFRYkp9ilbtVYdfHsesPUrUz51Q8dp1Jfg,1042
+modwire_siren/contracts/link.py,sha256=_w9bxNjQgUrEPSlknIJKtu5Zvid3gtdGDt7Z34jmSMQ,244
+modwire_siren/contracts/operation.py,sha256=rn-aBdXM8bfXF6KuVy7kaJb14HWp2rP-b0dkUNCARGA,393
+modwire_siren/contracts/resource.py,sha256=JxxiZM6a3lk0Bvf9cq5dxN3YXXXZ1fhTf_6BKV091K4,318
+modwire_siren/factories/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+modwire_siren/factories/action.py,sha256=7gGptM6_KTuPXaomqmLkCEFKOCh3sEouql9mTm6_VWk,1028
+modwire_siren/factories/entity.py,sha256=lkDR9b7cZ4bUeUP-gjpGVTQ85VYW06ajWjiHnE6m4cw,1592
+modwire_siren/factories/field.py,sha256=Bc5_t6_7g0-PWZzKzYmfjUqokFsBlVKWqIhD0_K2tfY,1033
+modwire_siren/factories/link.py,sha256=evJv4eXAJajr6wzBeoJgJKTb1YUMA15stoLCVkC4qjU,2685
+modwire_siren/factories/resource.py,sha256=8VvMZe-DeQ7eHgcg5Txe61l5A9I6Kelwp_zLnezJppg,1274
+modwire_siren/integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+modwire_siren/integrations/ninja_extra.py,sha256=5_X5GV5_6UpayiDSAzLo0QpCzNjvjXHIRzoJtxnHaEE,2857
+modwire_siren/openapi/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+modwire_siren/openapi/catalog.py,sha256=OXMUZctNO-rFGL3jQ0mBoLyXbdcbGx5fgVdZEOOJE1I,2553
+modwire_siren/openapi/contracts.py,sha256=B3y76D179HgXq-6vNGAt5IWJ_dCt75CQejLa9L8tXl4,488
+modwire_siren/openapi/error.py,sha256=J3ly-HXuICvUqD6tmWk1KEdmqvIEFE_K5_nei2xQDA0,121
+modwire_siren/openapi/factory.py,sha256=L-v_Gc9vz-AgDZVfpYORUbgAGeJTIDjQM_kkVUuQHms,618
+modwire_siren/openapi/href.py,sha256=znjHK0FfvAYgaFB8w_2095u6Sa2OogBAY-4k6Bhb8Rs,880
+modwire_siren/openapi/method.py,sha256=R2cLl4PolGQNYlFBhXL_U7eh-YElaskk9K0rAvxUnmg,215
+modwire_siren/openapi/operation.py,sha256=NDnB0ZKRAm6HBMn7SXna9PvC6byL-BgaEdNe9Tx3e4s,2855
+modwire_siren/openapi/resolver.py,sha256=UYfrYr4MoFTUEVzCULe1w-i-JNjabEvHxJviQ1BqTao,2530
+modwire_siren/openapi/resource.py,sha256=nJtfsjE_BXwvmNtNdgXQhYuAhucgL2PEj-89dL3yeio,1285
+modwire_siren/policies/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+modwire_siren/policies/field_type.py,sha256=LgTl7u54uIAOJ3yGqfIFuN6pAJ-DiSnigKnVXtgHs6c,731
+modwire_siren-0.1.0.dist-info/METADATA,sha256=iUPdMTJD0KTvnZt5rgFcKNsmjfPFYEoXLbM_APqXNVM,5496
+modwire_siren-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+modwire_siren-0.1.0.dist-info/RECORD,,

modwire_siren-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any