qstd-openapi 0.1.0__py3-none-any.whl

qstd_openapi/meta/merge.py

@@ -0,0 +1,271 @@
+"""Merging contributions into a single :class:`OperationMeta`.
+
+Collections accumulate (duplicates are dropped, first occurrence wins the
+position). Single-valued fields go through a :class:`ScalarMergeStrategy`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Hashable, Iterable, Mapping, Sequence
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Any, Literal, Protocol, TypeVar, cast
+
+from qstd_openapi.errors import ScalarConflictError
+from qstd_openapi.meta.model import (
+    BodyPart,
+    Content,
+    Contribution,
+    Example,
+    OperationMeta,
+    Origin,
+    Parameter,
+    ParameterModel,
+    Response,
+    ResponseHeader,
+    ResponsePart,
+    StatusCode,
+)
+from qstd_openapi.meta.storage import read_contributions
+
+T = TypeVar('T')
+
+
+@dataclass(frozen=True)
+class Located:
+    value: Any
+    origin: Origin
+
+
+class ScalarMergeStrategy(Protocol):
+    """Internal: how a single-valued field is chosen.
+
+    Not part of the public API before 1.0; ``scalar_conflicts`` takes the
+    names in :data:`SCALAR_STRATEGIES`.
+    """
+
+    def resolve(self, field: str, values: Sequence[Located]) -> Any:
+        """Pick the value of ``field``; ``values`` are in application order."""
+        ...
+
+
+class ErrorOnConflict:
+    """Different values for the same field are an error."""
+
+    def resolve(self, field: str, values: Sequence[Located]) -> Any:
+        distinct = _unique(item.value for item in values)
+        if len(distinct) > 1:
+            raise ScalarConflictError(
+                field,
+                [(item.value, item.origin) for item in values],
+            )
+        return values[-1].value
+
+
+class LastWins:
+    """The value applied last (the outermost one) wins."""
+
+    def resolve(self, field: str, values: Sequence[Located]) -> Any:  # noqa: ARG002
+        return values[-1].value
+
+
+SCALAR_STRATEGIES: Mapping[str, ScalarMergeStrategy] = MappingProxyType(
+    {'error': ErrorOnConflict(), 'last_wins': LastWins()},
+)
+
+ScalarConflicts = Literal['error', 'last_wins']
+"""``'error'``: different values for one field fail the build; ``'last_wins'``:
+the outermost decorator wins."""
+
+
+def get_scalar_strategy(value: ScalarConflicts) -> ScalarMergeStrategy:
+    raw = cast(object, value)  # callers may pass anything at runtime
+    strategy = SCALAR_STRATEGIES.get(raw) if isinstance(raw, str) else None
+    if strategy is None:
+        known = ', '.join(repr(name) for name in SCALAR_STRATEGIES)
+        raise ValueError(
+            f'Unknown scalar_conflicts {value!r}; expected one of {known}',
+        )
+    return strategy
+
+
+def _unique(items: Iterable[T]) -> list[T]:
+    """Order-preserving de-duplication by equality (values may be unhashable)."""
+    result: list[T] = []
+    for item in items:
+        if item not in result:
+            result.append(item)
+    return result
+
+
+def _normalize_status(status: StatusCode) -> StatusCode:
+    if isinstance(status, str) and status.isdigit():
+        return int(status)
+    return status
+
+
+class _Merger:
+    def __init__(self, strategy: ScalarMergeStrategy) -> None:
+        self._strategy = strategy
+
+    def scalar(self, field: str, values: list[Located]) -> Any:
+        if not values:
+            return None
+        return self._strategy.resolve(field, values)
+
+    def keyed(
+        self,
+        field: str,
+        items: Iterable[tuple[Hashable, Any, Origin]],
+    ) -> list[Any]:
+        """One value per key, conflicts per key go through the strategy."""
+        grouped: dict[Hashable, list[Located]] = {}
+        for key, value, origin in items:
+            grouped.setdefault(key, []).append(Located(value, origin))
+        return [
+            self.scalar(f'{field}[{key!r}]', values) for key, values in grouped.items()
+        ]
+
+    def body(
+        self,
+        parts: Iterable[tuple[BodyPart, Origin]],
+        field: str = 'body',
+    ) -> tuple[Content, ...]:
+        grouped: dict[str, list[Any]] = {}
+        examples: dict[str, list[tuple[str, Example, Origin]]] = {}
+        for part, origin in parts:
+            schemas = grouped.setdefault(part.media_type, [])
+            if part.schema is not None and part.schema not in schemas:
+                schemas.append(part.schema)
+            examples.setdefault(part.media_type, []).extend(
+                (name, example, origin) for name, example in part.examples
+            )
+        return tuple(
+            Content(
+                media,
+                tuple(schemas),
+                tuple(
+                    zip(
+                        _unique(name for name, _, _ in examples[media]),
+                        self.keyed(
+                            f'{field}[{media!r}].examples',
+                            examples[media],
+                        ),
+                    ),
+                ),
+            )
+            for media, schemas in grouped.items()
+        )
+
+    def responses(
+        self,
+        parts: Iterable[tuple[ResponsePart, Origin]],
+    ) -> tuple[Response, ...]:
+        by_status: dict[StatusCode, list[tuple[ResponsePart, Origin]]] = {}
+        for part, origin in parts:
+            by_status.setdefault(_normalize_status(part.status), []).append(
+                (part, origin),
+            )
+        responses: list[Response] = []
+        for status, items in by_status.items():
+            description = self.scalar(
+                f'responses[{status!r}].description',
+                [
+                    Located(part.description, origin)
+                    for part, origin in items
+                    if part.description is not None
+                ],
+            )
+            content = self.body(
+                (
+                    (BodyPart(part.media_type, part.schema, part.examples), origin)
+                    for part, origin in items
+                    if part.media_type is not None
+                    and (part.schema is not None or part.examples)
+                ),
+                f'responses[{status!r}]',
+            )
+            headers: list[ResponseHeader] = self.keyed(
+                f'responses[{status!r}].headers',
+                (
+                    (header.name.lower(), header, origin)
+                    for part, origin in items
+                    for header in part.headers
+                ),
+            )
+            responses.append(Response(status, description, content, tuple(headers)))
+        return tuple(responses)
+
+
+_SCALARS = (
+    'summary',
+    'description',
+    'operation_id',
+    'deprecated',
+    'exclude',
+    'webhook',
+)
+
+
+def merge_contributions(
+    contributions: Iterable[Contribution],
+    scalar_conflicts: ScalarConflicts = 'error',
+) -> OperationMeta:
+    merger = _Merger(get_scalar_strategy(scalar_conflicts))
+    items = list(contributions)
+
+    scalars: dict[str, Any] = {}
+    for name in _SCALARS:
+        located = [
+            Located(getattr(item.patch, name), item.origin)
+            for item in items
+            if getattr(item.patch, name) is not None
+        ]
+        scalars[name] = merger.scalar(name, located)
+
+    explicit: list[tuple[Hashable, Parameter, Origin]] = []
+    models: list[ParameterModel] = []
+    for item in items:
+        for parameter in item.patch.parameters:
+            if isinstance(parameter, Parameter):
+                key = (parameter.location, _parameter_key(parameter))
+                explicit.append((key, parameter, item.origin))
+            elif parameter not in models:
+                models.append(parameter)
+
+    return OperationMeta(
+        summary=scalars['summary'],
+        description=scalars['description'],
+        operation_id=scalars['operation_id'],
+        deprecated=bool(scalars['deprecated']),
+        exclude=bool(scalars['exclude']),
+        webhook=scalars['webhook'],
+        tags=tuple(_unique(tag for item in items for tag in item.patch.tags)),
+        scopes=tuple(_unique(scope for item in items for scope in item.patch.scopes)),
+        security=tuple(
+            _unique(req for item in items for req in item.patch.security),
+        ),
+        parameters=tuple(merger.keyed('parameters', explicit)),
+        parameter_models=tuple(models),
+        body=merger.body(
+            (part, item.origin) for item in items for part in item.patch.body
+        ),
+        responses=merger.responses(
+            (part, item.origin) for item in items for part in item.patch.responses
+        ),
+        errors=tuple(_unique(err for item in items for err in item.patch.errors)),
+        extra=tuple(extra for item in items for extra in item.patch.extra),
+    )
+
+
+def _parameter_key(parameter: Parameter) -> str:
+    # Header names are case-insensitive.
+    return parameter.name.lower() if parameter.location == 'header' else parameter.name
+
+
+def read_operation(
+    obj: object,
+    scalar_conflicts: ScalarConflicts = 'error',
+) -> OperationMeta:
+    """Merged description of a handler, following its ``__wrapped__`` chain."""
+    return merge_contributions(read_contributions(obj), scalar_conflicts)

qstd_openapi/meta/model.py

@@ -0,0 +1,182 @@
+"""Version-neutral description of an operation.
+
+Nothing here is OpenAPI-version specific: schemas are kept as references
+(model classes, Python types, raw JSON Schema dicts, markers from
+:mod:`qstd_openapi.markers`) and are resolved only when a document is built.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Hashable, Mapping
+from dataclasses import dataclass, field
+from typing import Any, Literal, Optional, Union
+
+ParameterLocation = Literal['query', 'path', 'header', 'cookie']
+StatusCode = Union[int, str]
+"""HTTP status code, or an OpenAPI range/default key such as ``'4XX'``."""
+
+
+@dataclass(frozen=True)
+class Example:
+    """A named example of a body, a response or a parameter (OpenAPI Example Object)."""
+
+    value: Any
+    summary: Optional[str] = None
+    description: Optional[str] = None
+
+
+Examples = tuple[tuple[str, Example], ...]
+"""Named examples in the order they were given."""
+
+
+@dataclass(frozen=True)
+class Parameter:
+    """A single named parameter."""
+
+    location: ParameterLocation
+    name: str
+    schema: Any = str
+    required: Optional[bool] = None
+    """``None`` means the default: required for ``path``, optional otherwise."""
+    description: Optional[str] = None
+    deprecated: bool = False
+    examples: Examples = ()
+
+
+@dataclass(frozen=True)
+class ParameterModel:
+    """A model whose fields are expanded into parameters of one location."""
+
+    location: ParameterLocation
+    model: Any
+
+
+@dataclass(frozen=True)
+class BodyPart:
+    media_type: str
+    schema: Any
+    """``None`` adds only ``examples`` to the media type."""
+    examples: Examples = ()
+
+
+@dataclass(frozen=True)
+class ResponseHeader:
+    name: str
+    schema: Any = str
+    description: Optional[str] = None
+    required: bool = False
+
+
+@dataclass(frozen=True)
+class ResponsePart:
+    status: StatusCode
+    media_type: Optional[str] = None
+    schema: Any = None
+    """``None`` means a response without a body."""
+    description: Optional[str] = None
+    headers: tuple[ResponseHeader, ...] = ()
+    examples: Examples = ()
+
+
+@dataclass(frozen=True)
+class ErrorRef:
+    """An error object resolved into a response by an error provider."""
+
+    error: Any
+    media_type: str = 'application/json'
+
+
+@dataclass(frozen=True)
+class Security:
+    """One security requirement object: all schemes listed are required together.
+
+    Several :class:`Security` values on an operation are alternatives.
+    An empty requirement means the operation may also be called anonymously.
+    """
+
+    schemes: tuple[tuple[str, tuple[str, ...]], ...] = ()
+
+
+@dataclass(frozen=True)
+class Webhook:
+    name: str
+    method: str = 'post'
+
+
+@dataclass(frozen=True)
+class OperationPatch:
+    """What a single ``attach``/decorator call contributes.
+
+    ``None`` scalars and empty tuples mean "not set by this call".
+    """
+
+    summary: Optional[str] = None
+    description: Optional[str] = None
+    operation_id: Optional[str] = None
+    deprecated: Optional[bool] = None
+    exclude: Optional[bool] = None
+    webhook: Optional[Webhook] = None
+    tags: tuple[str, ...] = ()
+    scopes: tuple[Hashable, ...] = ()
+    security: tuple[Security, ...] = ()
+    parameters: tuple[Union[Parameter, ParameterModel], ...] = ()
+    body: tuple[BodyPart, ...] = ()
+    responses: tuple[ResponsePart, ...] = ()
+    errors: tuple[ErrorRef, ...] = ()
+    extra: tuple[Mapping[str, Any], ...] = ()
+
+
+@dataclass(frozen=True)
+class Origin:
+    """Where a contribution came from, for diagnostics."""
+
+    owner: str
+    api: str
+    index: int
+
+    def __str__(self) -> str:
+        return f'{self.owner} ({self.api} #{self.index})'
+
+
+@dataclass(frozen=True)
+class Contribution:
+    patch: OperationPatch
+    origin: Origin
+
+
+@dataclass(frozen=True)
+class Content:
+    """Schemas accepted for one media type; several schemas mean ``oneOf``."""
+
+    media_type: str
+    schemas: tuple[Any, ...]
+    examples: Examples = ()
+
+
+@dataclass(frozen=True)
+class Response:
+    status: StatusCode
+    description: Optional[str] = None
+    content: tuple[Content, ...] = ()
+    headers: tuple[ResponseHeader, ...] = ()
+
+
+@dataclass(frozen=True)
+class OperationMeta:
+    """Merged description of one handler, still version-neutral."""
+
+    summary: Optional[str] = None
+    description: Optional[str] = None
+    operation_id: Optional[str] = None
+    deprecated: bool = False
+    exclude: bool = False
+    webhook: Optional[Webhook] = None
+    tags: tuple[str, ...] = ()
+    scopes: tuple[Hashable, ...] = ()
+    security: tuple[Security, ...] = ()
+    parameters: tuple[Parameter, ...] = ()
+    parameter_models: tuple[ParameterModel, ...] = ()
+    body: tuple[Content, ...] = ()
+    responses: tuple[Response, ...] = ()
+    errors: tuple[ErrorRef, ...] = ()
+    extra: tuple[Mapping[str, Any], ...] = field(default=())

qstd_openapi/meta/storage.py

@@ -0,0 +1,112 @@
+"""Storing contributions on the described objects themselves.
+
+There is no registry: every function carries an immutable record of what was
+attached to it. The record lives under an attribute name derived from the
+owner's ``id``. ``functools.wraps`` copies the wrapped function's
+``__dict__`` into the wrapper, so with a single shared attribute name the
+copy would overwrite whatever had already been attached to the wrapper
+(and the same record would be read twice while walking ``__wrapped__``).
+With per-owner names the copy lands next to the wrapper's own record and is
+ignored when the wrapper is read.
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+
+from dataclasses import dataclass
+from typing import Any, cast
+
+from qstd_openapi.errors import AttachError
+from qstd_openapi.meta.model import Contribution, OperationPatch, Origin
+
+_ATTR_PREFIX = '__qstd_openapi_'
+
+
+@dataclass(frozen=True)
+class _Record:
+    owner: object
+    entries: tuple[tuple[OperationPatch, str], ...]
+
+
+def _attr_name(holder: object) -> str:
+    return f'{_ATTR_PREFIX}{id(holder):x}__'
+
+
+def _holder(obj: object) -> object:
+    """The object that actually stores metadata for ``obj``."""
+    if isinstance(obj, (staticmethod, classmethod)) or inspect.ismethod(obj):
+        return cast('object', obj.__func__)  # pyright: ignore[reportUnknownMemberType]
+    return obj
+
+
+def describe_owner(obj: object) -> str:
+    module = getattr(obj, '__module__', None)
+    qualname = getattr(obj, '__qualname__', None) or type(obj).__qualname__
+    return f'{module}.{qualname}' if module else qualname
+
+
+def attach_patch(obj: object, patch: OperationPatch, api: str) -> None:
+    holder = _holder(obj)
+    if not hasattr(holder, '__dict__'):
+        raise AttachError(
+            f'Cannot attach OpenAPI metadata to {obj!r}: '
+            f'{type(holder).__qualname__} objects have no __dict__. '
+            'Wrap it in a regular function and describe that function.',
+        )
+    name = _attr_name(holder)
+    record = vars(holder).get(name)
+    if not isinstance(record, _Record) or record.owner is not holder:
+        record = _Record(owner=holder, entries=())
+    try:
+        setattr(holder, name, _Record(holder, (*record.entries, (patch, api))))
+    except (AttributeError, TypeError) as exc:
+        raise AttachError(
+            f'Cannot attach OpenAPI metadata to {obj!r}: {exc}',
+        ) from exc
+
+
+def _own_record(holder: object) -> _Record | None:
+    try:
+        record = vars(holder).get(_attr_name(holder))
+    except TypeError:
+        return None
+    if isinstance(record, _Record) and record.owner is holder:
+        return record
+    return None
+
+
+def _wrap_chain(obj: object) -> list[object]:
+    """Holders from the outermost object down to the innermost wrapped one."""
+    chain: list[object] = []
+    seen: set[int] = set()
+    current: Any = obj
+    while current is not None:
+        holder = _holder(current)
+        if id(holder) in seen:
+            break
+        seen.add(id(holder))
+        chain.append(holder)
+        nxt = getattr(holder, '__wrapped__', None)
+        if nxt is None and isinstance(holder, functools.partial):
+            nxt = holder.func
+        current = nxt
+    return chain
+
+
+def read_contributions(obj: object) -> tuple[Contribution, ...]:
+    """All contributions for ``obj`` in application order.
+
+    The innermost wrapped function comes first and the outermost wrapper
+    last; within one object entries keep the order they were attached in.
+    """
+    contributions: list[Contribution] = []
+    for holder in reversed(_wrap_chain(obj)):
+        record = _own_record(holder)
+        if record is None:
+            continue
+        owner = describe_owner(holder)
+        for index, (patch, api) in enumerate(record.entries):
+            contributions.append(Contribution(patch, Origin(owner, api, index)))
+    return tuple(contributions)