qstd-openapi 0.1.0__py3-none-any.whl

qstd_openapi/sanic.py

@@ -0,0 +1,343 @@
+"""Sanic integration: route source, publishing endpoint and a documenting router.
+
+Install with ``qstd-openapi[sanic]``.
+
+Usage::
+
+    from qstd_openapi import OpenAPI
+    from qstd_openapi.sanic import OpenAPIBlueprint, SanicRoutes, mount
+
+    users = OpenAPIBlueprint(Blueprint('Users', url_prefix='/users'))
+
+    @users.post(
+        '/register',
+        tags=['Users'],
+        body=UserRegisterInput,
+        responses={201: UserDTO},
+    )
+    async def register_user(request): ...
+
+    app.blueprint(users.blueprint)
+    spec = OpenAPI(info={'title': 'Users API', 'version': '1.0.0'})
+    spec.include(SanicRoutes(app))
+    mount(app, spec, json_path='/openapi.json')
+"""
+
+from __future__ import annotations
+
+import datetime
+import importlib
+import re
+import uuid
+
+from collections.abc import Iterable, Mapping, Sequence
+from types import MappingProxyType
+from typing import Any, Callable, Generic, Optional, TypeVar, Union, cast
+
+from typing_extensions import Unpack
+
+from qstd_openapi import openapi
+from qstd_openapi.core.document import OpenAPI
+from qstd_openapi.core.sources import HTTP_METHODS, RouteEntry, SourceEntry
+from qstd_openapi.meta.model import Parameter
+from qstd_openapi.serialization import dumps, dumps_yaml
+from qstd_openapi.ui import DocsRenderer
+
+try:
+    _sanic: Any = importlib.import_module('sanic')
+except ImportError as exc:  # pragma: no cover - extra not installed
+    raise ImportError(
+        'qstd_openapi.sanic needs Sanic: install qstd-openapi[sanic]',
+    ) from exc
+
+__all__ = ('OpenAPIBlueprint', 'SanicRouteOptions', 'SanicRoutes', 'mount')
+
+F = TypeVar('F', bound=Callable[..., Any])
+B = TypeVar('B')
+
+_PARAMETER = re.compile(r'^<([^:>]+)(?::([^>]+))?>$')
+_LABEL_TYPES: Mapping[str, Any] = MappingProxyType(
+    {
+        'int': int,
+        'float': float,
+        'uuid': uuid.UUID,
+        'ymd': datetime.date,
+    },
+)
+_DESCRIBE_OPTIONS = frozenset(openapi.DescribeOptions.__annotations__)
+_SKIPPED_METHODS = frozenset({'head', 'options'})
+
+
+def _path_and_parameters(parts: Sequence[str]) -> tuple[str, tuple[Parameter, ...]]:
+    """``('users', '<user_id:int>')`` -> ``('/users/{user_id}', (Parameter...))``."""
+    segments: list[str] = []
+    parameters: list[Parameter] = []
+    for part in parts:
+        match = _PARAMETER.match(part)
+        if match is None:
+            segments.append(part)
+            continue
+        name, label = match.group(1), match.group(2) or 'str'
+        segments.append(f'{{{name}}}')
+        parameters.append(Parameter('path', name, _LABEL_TYPES.get(label, str)))
+    return '/' + '/'.join(segment for segment in segments if segment), tuple(parameters)
+
+
+class SanicRoutes:
+    """Operations of a Sanic application.
+
+    - path parameters come from the URL template with types from Sanic
+      labels (``int``, ``float``, ``uuid``, ``ymd``; anything else is a string);
+    - class-based views are documented per HTTP method;
+    - ``HEAD``/``OPTIONS``, static files and websockets are skipped;
+    - with ``blueprint_tags`` an operation without tags gets its blueprint's
+      name as the tag.
+
+    Routes are read when the document is built, so routes registered later
+    are included as long as the document is (re)built afterwards.
+    """
+
+    def __init__(self, app: Any, *, blueprint_tags: bool = True) -> None:
+        self.app = app
+        self.blueprint_tags = blueprint_tags
+
+    def collect(self) -> Iterable[SourceEntry]:
+        blueprints: dict[int, str] = {}
+        for name, blueprint in self.app.blueprints.items():
+            for route in blueprint.routes:
+                blueprints[id(route)] = name
+        seen: set[tuple[str, str, int]] = set()
+        entries: list[SourceEntry] = []
+        for route in sorted(self.app.router.routes, key=lambda r: (r.path, r.name)):
+            if route.extra.static or route.extra.websocket:
+                continue
+            path, parameters = _path_and_parameters(route.parts)
+            tags = (
+                (blueprints[id(route)],)
+                if (self.blueprint_tags and id(route) in blueprints)
+                else ()
+            )
+            name = _route_name(self.app.name, route.name)
+            for method in sorted(m.lower() for m in route.methods):
+                if method in _SKIPPED_METHODS or method not in HTTP_METHODS:
+                    continue
+                handler = self._handler(route.handler, method)
+                # strict_slashes=False may register "/x" and "/x/" for one handler.
+                key = (path.rstrip('/') or '/', method, id(handler))
+                if key in seen:
+                    continue
+                seen.add(key)
+                entries.append(
+                    RouteEntry(path, method, handler, tags, parameters, name=name),
+                )
+        return entries
+
+    @staticmethod
+    def _handler(handler: Any, method: str) -> Any:
+        view_class = getattr(handler, 'view_class', None)
+        if view_class is not None:
+            return getattr(view_class, method, handler)
+        return handler
+
+
+def _route_name(app_name: str, route_name: Optional[str]) -> Optional[str]:
+    """``'<app>.<blueprint>.<handler>'`` → ``'<blueprint>_<handler>'``."""
+    if not route_name:
+        return None
+    prefix = f'{app_name}.'
+    if route_name.startswith(prefix):
+        route_name = route_name[len(prefix) :]
+    return route_name.replace('.', '_')
+
+
+def mount(
+    app: Any,
+    spec: OpenAPI,
+    *,
+    json_path: Optional[str] = '/openapi.json',
+    yaml_path: Optional[str] = None,
+    ui: Optional[Mapping[str, DocsRenderer]] = None,
+    spec_url: Optional[str] = None,
+    title: Optional[str] = None,
+    name: str = 'qstd_openapi',
+    decorators: Sequence[Callable[[Any], Any]] = (),
+    build_on_start: bool = True,
+) -> None:
+    """Publish the document of ``spec``.
+
+    - ``json_path`` / ``yaml_path``: endpoints with the document (YAML needs
+      the ``yaml`` extra); ``None`` disables one;
+    - ``ui``: ``{path: renderer}``, e.g. ``{'/docs': Redoc(), '/swagger': SwaggerUI()}``;
+      pages load the document from ``spec_url`` (default: ``json_path``, or
+      ``yaml_path`` if JSON is disabled) — set it when the app is served under a
+      prefix or behind a proxy;
+    - ``decorators`` wrap every endpoint (for example an auth check), innermost
+      last as with stacked decorators;
+    - ``build_on_start`` builds the document before the server starts, so a
+      broken description fails the start instead of the first request.
+
+    Route names are ``{name}_json``, ``{name}_yaml`` and ``{name}_ui_<n>``; the
+    endpoints are excluded from the document.
+    """
+    http = _sanic.response.HTTPResponse
+
+    async def openapi_json(request: Any) -> Any:  # noqa: ARG001
+        return http(dumps(spec.build().document), content_type='application/json')
+
+    async def openapi_yaml(request: Any) -> Any:  # noqa: ARG001
+        return http(dumps_yaml(spec.build().document), content_type='application/yaml')
+
+    if json_path:
+        _add_endpoint(app, openapi_json, json_path, f'{name}_json', decorators)
+    if yaml_path:
+        _add_endpoint(app, openapi_yaml, yaml_path, f'{name}_yaml', decorators)
+
+    document_url = spec_url or json_path or yaml_path
+    if ui and not document_url:
+        raise ValueError('ui pages need spec_url, json_path or yaml_path')
+    page_title = title or str(spec.info.get('title', 'API'))
+    for index, (path, renderer) in enumerate((ui or {}).items()):
+        page = renderer.render(spec_url=cast(str, document_url), title=page_title)
+
+        async def docs_page(request: Any, _page: str = page) -> Any:  # noqa: ARG001
+            return http(_page, content_type='text/html; charset=utf-8')
+
+        _add_endpoint(app, docs_page, path, f'{name}_ui_{index}', decorators)
+
+    if build_on_start:
+
+        async def build_document(*_: Any) -> None:
+            spec.build()
+
+        app.register_listener(build_document, 'before_server_start')
+
+
+def _add_endpoint(
+    app: Any,
+    endpoint: Callable[..., Any],
+    path: str,
+    name: str,
+    decorators: Sequence[Callable[[Any], Any]],
+) -> None:
+    handler: Any = openapi.exclude()(endpoint)
+    for decorator in reversed(decorators):
+        handler = decorator(handler)
+    if handler is not endpoint and hasattr(handler, '__dict__'):
+        openapi.exclude()(handler)
+    app.add_route(handler, path, methods=['GET'], name=name)
+
+
+class SanicRouteOptions(openapi.DescribeOptions, total=False):
+    """``describe`` options plus Sanic's own route options."""
+
+    host: Union[str, list[str], None]
+    strict_slashes: Optional[bool]
+    stream: bool
+    version: Union[int, str, float, None]
+    name: Optional[str]
+    ignore_body: bool
+    apply: bool
+    subprotocols: Optional[list[str]]
+    websocket: bool
+    unquote: bool
+    static: bool
+    version_prefix: str
+    error_format: Optional[str]
+    ctx: Mapping[str, Any]
+    """Route context: ``ctx={'auth': False}`` is Sanic's ``ctx_auth=False``."""
+
+
+class OpenAPIBlueprint(Generic[B]):
+    """A Sanic ``Blueprint`` (or app) whose route decorators also take ``describe`` options.
+
+    ``users.post('/register', tags=['Users'], body=Model, name='register')``
+    registers the route with Sanic (``name`` and other Sanic options are passed
+    through) and attaches the documentation options to the handler. The
+    wrapped object is ``.blueprint`` (typed); other attributes (``middleware``,
+    ``exception``...) are also delegated to it, untyped.
+    """
+
+    def __init__(self, blueprint: B) -> None:
+        self.blueprint: B = blueprint
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self.blueprint, name)
+
+    def route(
+        self,
+        uri: str,
+        methods: Iterable[str] = ('GET',),
+        **options: Unpack[SanicRouteOptions],
+    ) -> Callable[[F], F]:
+        return self._register('route', uri, {'methods': list(methods), **options})
+
+    def get(self, uri: str, **options: Unpack[SanicRouteOptions]) -> Callable[[F], F]:
+        return self._register('get', uri, dict(options))
+
+    def post(self, uri: str, **options: Unpack[SanicRouteOptions]) -> Callable[[F], F]:
+        return self._register('post', uri, dict(options))
+
+    def put(self, uri: str, **options: Unpack[SanicRouteOptions]) -> Callable[[F], F]:
+        return self._register('put', uri, dict(options))
+
+    def patch(self, uri: str, **options: Unpack[SanicRouteOptions]) -> Callable[[F], F]:
+        return self._register('patch', uri, dict(options))
+
+    def delete(
+        self,
+        uri: str,
+        **options: Unpack[SanicRouteOptions],
+    ) -> Callable[[F], F]:
+        return self._register('delete', uri, dict(options))
+
+    def add_route(
+        self,
+        handler: F,
+        uri: str,
+        methods: Iterable[str] = ('GET',),
+        **options: Unpack[SanicRouteOptions],
+    ) -> F:
+        described, sanic_options = _split(dict(options))
+        self._describe(handler, described)
+        blueprint: Any = self.blueprint
+        blueprint.add_route(handler, uri, methods=list(methods), **sanic_options)
+        return handler
+
+    def _register(
+        self,
+        method: str,
+        uri: str,
+        options: Mapping[str, object],
+    ) -> Callable[[F], F]:
+        described, sanic_options = _split(options)
+        register = getattr(self.blueprint, method)(uri, **sanic_options)
+
+        def decorate(handler: F) -> F:
+            self._describe(handler, described)
+            register(handler)
+            return handler
+
+        return decorate
+
+    @staticmethod
+    def _describe(handler: Any, described: dict[str, Any]) -> None:
+        if not described:
+            return
+        view_class = getattr(handler, 'view_class', None)
+        targets = (
+            [getattr(view_class, m) for m in HTTP_METHODS if hasattr(view_class, m)]
+            if view_class is not None
+            else [handler]
+        )
+        for target in targets:
+            openapi.attach(target, **described)
+
+
+def _split(options: Mapping[str, Any]) -> tuple[dict[str, Any], dict[str, Any]]:
+    described = {k: v for k, v in options.items() if k in _DESCRIBE_OPTIONS}
+    rest = {
+        k: v for k, v in options.items() if k not in _DESCRIBE_OPTIONS and k != 'ctx'
+    }
+    for key, value in cast('Mapping[str, Any]', options.get('ctx', {})).items():
+        rest[f'ctx_{key}'] = value
+    return described, rest

qstd_openapi/serialization.py

@@ -0,0 +1,63 @@
+"""Stable JSON and YAML serialization for built OpenAPI documents."""
+
+from __future__ import annotations
+
+import importlib
+import json
+
+from collections.abc import Mapping
+from typing import Any, Optional, cast
+
+
+def dumps(
+    document: Mapping[str, Any],
+    *,
+    canonical: bool = False,
+    indent: Optional[int] = None,
+) -> str:
+    """Serialize a document to JSON.
+
+    ``canonical=True`` sorts keys and drops whitespace, so the same inputs
+    always give byte-identical output.
+    """
+    if canonical:
+        return json.dumps(
+            document,
+            ensure_ascii=False,
+            sort_keys=True,
+            separators=(',', ':'),
+        )
+    return json.dumps(document, ensure_ascii=False, indent=indent)
+
+
+def dumps_yaml(document: Mapping[str, Any], *, canonical: bool = False) -> str:
+    """Serialize a document to YAML (needs the ``yaml`` extra: PyYAML).
+
+    ``canonical=True`` sorts keys, so the same inputs give identical output.
+    """
+    try:
+        yaml: Any = importlib.import_module('yaml')
+    except ImportError as exc:
+        raise ImportError(
+            'YAML output needs PyYAML: install qstd-openapi[yaml]',
+        ) from exc
+    return cast(
+        str,
+        yaml.safe_dump(
+            _plain(document),
+            sort_keys=canonical,
+            allow_unicode=True,
+            default_flow_style=False,
+        ),
+    )
+
+
+def _plain(value: Any) -> Any:
+    """Plain dicts/lists so PyYAML's safe dumper accepts any Mapping/Sequence."""
+    if isinstance(value, Mapping):
+        return {
+            str(k): _plain(v) for k, v in cast('Mapping[object, object]', value).items()
+        }
+    if isinstance(value, (list, tuple)):
+        return [_plain(v) for v in cast('list[object]', value)]
+    return value

qstd_openapi/tags.py

@@ -0,0 +1,58 @@
+"""Tag descriptions kept as Markdown files next to the code.
+
+A common layout keeps one file per tag, one directory per service or
+document::
+
+    docs/openapi/users_api/Users.md
+    docs/openapi/users_api/Profile.md
+
+Usage::
+
+    from qstd_openapi import OpenAPI, tags_from_markdown
+
+    spec = OpenAPI(
+        info={'title': 'Users API', 'version': '1.0.0'},
+        tags=tags_from_markdown('docs/openapi/users_api'),
+    )
+"""
+
+from __future__ import annotations
+
+import copy
+import os
+
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any, Union
+
+__all__ = ('tags_from_markdown',)
+
+
+def tags_from_markdown(
+    directory: Union[str, os.PathLike[str]],
+    tags: Sequence[Mapping[str, Any]] = (),
+    *,
+    encoding: str = 'utf-8',
+) -> list[dict[str, Any]]:
+    """Tag objects whose descriptions come from ``<directory>/<tag name>.md``.
+
+    ``tags`` are explicit tag objects: they keep their order and fields, and
+    a tag without a ``description`` gets the one from its file. Files for
+    other tags are appended, sorted by name. Hidden files and files with
+    other extensions are ignored; a missing directory is an error.
+    """
+    root = Path(directory)
+    texts = {
+        path.stem: path.read_text(encoding=encoding).strip()
+        for path in sorted(root.iterdir())
+        if path.is_file() and path.suffix == '.md' and not path.name.startswith('.')
+    }
+    result: list[dict[str, Any]] = []
+    for tag in tags:
+        item = copy.deepcopy(dict(tag))
+        text = texts.pop(str(item.get('name')), None)
+        if text and not item.get('description'):
+            item['description'] = text
+        result.append(item)
+    result.extend({'name': name, 'description': text} for name, text in texts.items())
+    return result

qstd_openapi/testing.py

@@ -0,0 +1,98 @@
+"""Keeping the built document under version control.
+
+The document is rendered with sorted keys and indentation, so a snapshot
+committed next to the code shows every change of the API in review::
+
+    from qstd_openapi.testing import assert_matches_snapshot
+
+    def test_openapi_document() -> None:
+        assert_matches_snapshot(build_spec(), 'docs/openapi/users_api.json')
+
+Run the tests with ``QSTD_OPENAPI_UPDATE_SNAPSHOTS=1`` to write (or
+rewrite) snapshots after an intended change. The same check without pytest:
+``python -m qstd_openapi dump package.module:spec -o docs/openapi.json --check``.
+"""
+
+from __future__ import annotations
+
+import difflib
+import json
+import os
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any, Optional, Union
+
+from qstd_openapi.core.document import OpenAPI
+from qstd_openapi.serialization import dumps_yaml
+
+__all__ = ('UPDATE_ENV', 'assert_matches_snapshot', 'diff', 'render')
+
+UPDATE_ENV = 'QSTD_OPENAPI_UPDATE_SNAPSHOTS'
+"""Environment variable that makes :func:`assert_matches_snapshot` write snapshots."""
+
+_MAX_DIFF_LINES = 200
+
+Target = Union[OpenAPI, Mapping[str, Any]]
+
+
+def render(target: Target, *, yaml: bool = False) -> str:
+    """The document of ``target`` (an ``OpenAPI`` or a built document) as stable text."""
+    document = target.build().document if isinstance(target, OpenAPI) else target
+    if yaml:
+        return dumps_yaml(document, canonical=True)
+    return json.dumps(document, ensure_ascii=False, sort_keys=True, indent=2) + '\n'
+
+
+def diff(expected: str, actual: str, *, name: str = 'snapshot') -> str:
+    """A unified diff of two rendered documents, cut to a readable length."""
+    lines = list(
+        difflib.unified_diff(
+            expected.splitlines(keepends=True),
+            actual.splitlines(keepends=True),
+            fromfile=f'{name} (expected)',
+            tofile=f'{name} (built)',
+        ),
+    )
+    if len(lines) > _MAX_DIFF_LINES:
+        hidden = len(lines) - _MAX_DIFF_LINES
+        lines = [*lines[:_MAX_DIFF_LINES], f'... {hidden} more diff lines\n']
+    return ''.join(lines)
+
+
+def assert_matches_snapshot(
+    target: Target,
+    path: Union[str, os.PathLike[str]],
+    *,
+    yaml: Optional[bool] = None,
+    update: Optional[bool] = None,
+) -> None:
+    """Fail with a diff when the document differs from the snapshot at ``path``.
+
+    ``yaml`` defaults to the file extension (``.yaml``/``.yml``); ``update``
+    defaults to the ``QSTD_OPENAPI_UPDATE_SNAPSHOTS`` environment variable.
+    In update mode the snapshot is written and the check passes.
+    """
+    snapshot = Path(path)
+    if yaml is None:
+        yaml = snapshot.suffix in ('.yaml', '.yml')
+    if update is None:
+        update = os.environ.get(UPDATE_ENV, '') not in ('', '0')
+    actual = render(target, yaml=yaml)
+    if update:
+        if not snapshot.exists() or snapshot.read_text(encoding='utf-8') != actual:
+            snapshot.parent.mkdir(parents=True, exist_ok=True)
+            snapshot.write_text(actual, encoding='utf-8')
+        return
+    if not snapshot.exists():
+        raise AssertionError(
+            f'OpenAPI snapshot {snapshot} does not exist; '
+            f'run with {UPDATE_ENV}=1 to create it',
+        )
+    expected = snapshot.read_text(encoding='utf-8')
+    if expected != actual:
+        raise AssertionError(
+            f'OpenAPI document differs from {snapshot}; if the change is '
+            f'intended, run with {UPDATE_ENV}=1 to update it.\n'
+            + diff(expected, actual, name=str(snapshot)),
+        )

qstd_openapi/ui.py

@@ -0,0 +1,109 @@
+"""Documentation pages: Redoc and Swagger UI.
+
+A renderer only knows the URL of the specification; framework integrations
+decide where pages are served. Frontend bundles are loaded from a CDN by
+default; pass your own URLs to self-host them.
+"""
+
+from __future__ import annotations
+
+import html
+import json
+
+from collections.abc import Mapping
+from typing import Any, Optional, Protocol
+
+__all__ = ('DocsRenderer', 'Redoc', 'SwaggerUI')
+
+REDOC_JS = 'https://cdn.jsdelivr.net/npm/redoc@2.5.4/bundles/redoc.standalone.js'
+SWAGGER_UI_JS = (
+    'https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.33.1/swagger-ui-bundle.js'
+)
+SWAGGER_UI_CSS = 'https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.33.1/swagger-ui.css'
+
+
+class DocsRenderer(Protocol):
+    def render(self, *, spec_url: str, title: str) -> str:
+        """A complete HTML page showing the document at ``spec_url``."""
+        ...
+
+
+def _script_json(value: Any) -> str:
+    """JSON safe to embed inside a ``<script>`` element."""
+    return (
+        json.dumps(value, ensure_ascii=False)
+        .replace('<', '\\u003c')
+        .replace('>', '\\u003e')
+        .replace('&', '\\u0026')
+    )
+
+
+def _page(title: str, head: str, body: str) -> str:
+    return (
+        '<!DOCTYPE html>\n'
+        '<html lang="en">\n'
+        '<head>\n'
+        '<meta charset="utf-8">\n'
+        '<meta name="viewport" content="width=device-width, initial-scale=1">\n'
+        f'<title>{html.escape(title)}</title>\n'
+        f'{head}'
+        '</head>\n'
+        f'<body>\n{body}</body>\n'
+        '</html>\n'
+    )
+
+
+class Redoc:
+    """Redoc page; ``options`` are Redoc configuration options."""
+
+    def __init__(
+        self,
+        *,
+        js_url: str = REDOC_JS,
+        options: Optional[Mapping[str, Any]] = None,
+    ) -> None:
+        self.js_url = js_url
+        self.options = dict(options or {})
+
+    def render(self, *, spec_url: str, title: str) -> str:
+        body = (
+            '<div id="redoc-container"></div>\n'
+            f'<script src="{html.escape(self.js_url)}"></script>\n'
+            '<script>\n'
+            f'Redoc.init({_script_json(spec_url)}, {_script_json(self.options)}, '
+            'document.getElementById("redoc-container"));\n'
+            '</script>\n'
+        )
+        return _page(title, '<style>body { margin: 0; padding: 0; }</style>\n', body)
+
+
+class SwaggerUI:
+    """Swagger UI page; ``options`` are passed to ``SwaggerUIBundle``."""
+
+    def __init__(
+        self,
+        *,
+        js_url: str = SWAGGER_UI_JS,
+        css_url: str = SWAGGER_UI_CSS,
+        options: Optional[Mapping[str, Any]] = None,
+    ) -> None:
+        self.js_url = js_url
+        self.css_url = css_url
+        self.options = dict(options or {})
+
+    def render(self, *, spec_url: str, title: str) -> str:
+        options = {
+            'dom_id': '#swagger-ui',
+            'deepLinking': True,
+            **self.options,
+            'url': spec_url,
+        }
+        head = f'<link rel="stylesheet" href="{html.escape(self.css_url)}">\n'
+        body = (
+            '<div id="swagger-ui"></div>\n'
+            f'<script src="{html.escape(self.js_url)}"></script>\n'
+            '<script>\n'
+            f'window.ui = SwaggerUIBundle({_script_json(options)});\n'
+            '</script>\n'
+        )
+        return _page(title, head, body)