fastapi-streams 0.0.1__py3-none-any.whl

fastapi_streams/codegen/openapi.py

@@ -0,0 +1,154 @@
+import copy
+import json
+from importlib.resources import files
+from typing import Any, cast
+from urllib.parse import unquote
+
+from fastapi import FastAPI
+
+type Document = dict[str, Any]
+
+
+class ContractError(ValueError):
+    """An invalid or unsupported OpenAPI contract."""
+
+
+def resolve_pointer(document: Document, ref: str) -> Any:
+    if not ref.startswith("#/"):
+        raise ContractError(f"Only local OpenAPI references are supported: {ref!r}")
+    target: Any = document
+    try:
+        for part in unquote(ref[2:]).split("/"):
+            key = part.replace("~1", "/").replace("~0", "~")
+            target = (
+                cast(list[Any], target)[int(key)]
+                if isinstance(target, list)
+                else target[key]
+            )
+    except (KeyError, TypeError, IndexError, ValueError) as exc:
+        raise ContractError(f"Unresolved reference: {ref}") from exc
+    return target
+
+
+def resolve_ref(document: Document, value: Document) -> Document:
+    """Resolve local JSON Pointer references, detecting reference-only cycles."""
+    seen: set[str] = set()
+    while "$ref" in value:
+        ref: str = value["$ref"]
+        if ref in seen:
+            raise ContractError(f"Cyclic reference: {ref}")
+        seen.add(ref)
+        target = resolve_pointer(document, ref)
+        if not isinstance(target, dict):
+            raise ContractError(f"Reference does not point to an object: {ref}")
+        value = {**target, **{k: v for k, v in value.items() if k != "$ref"}}
+    return value
+
+
+def validate_contract(document: Document) -> None:
+    """Validate structure, JSON Schemas, and local reference closure offline.
+
+    The official OpenAPI meta-schema deliberately omits Schema Object validation;
+    those objects are checked separately with JSON Schema Draft 2020-12.
+    """
+    try:
+        from jsonschema import Draft202012Validator
+        from jsonschema.exceptions import SchemaError
+    except ImportError as exc:
+        raise ContractError(
+            "Install fastapi-streams[codegen] to validate contracts"
+        ) from exc
+
+    meta = json.loads(
+        files(__package__).joinpath("schemas/openapi-3.2.json").read_text()
+    )
+    errors = sorted(
+        Draft202012Validator(meta).iter_errors(document),  # pyright: ignore[reportUnknownMemberType]
+        key=lambda e: str(e.json_path),
+    )
+    if errors:
+        error = errors[0]
+        raise ContractError(
+            f"Invalid OpenAPI 3.2 at {error.json_path}: {error.message}"
+        )
+    dialect = document.get("jsonSchemaDialect", "")
+    if dialect and dialect not in {
+        "https://spec.openapis.org/oas/3.2/dialect/2026-02-26",
+        "https://json-schema.org/draft/2020-12/schema",
+    }:
+        raise ContractError(f"Unsupported JSON Schema dialect: {dialect}")
+
+    def walk_schema(node: Any, path: str) -> None:
+        try:
+            Draft202012Validator.check_schema(node)
+        except SchemaError as exc:
+            raise ContractError(
+                f"Invalid JSON Schema at {path}: {exc.message}"
+            ) from exc
+        if not isinstance(node, dict):
+            return
+        schema = cast(Document, node)
+        if "$ref" in schema:
+            resolve_pointer(document, schema["$ref"])
+        for keyword in ("$defs", "properties", "patternProperties", "dependentSchemas"):
+            for name, child in schema.get(keyword, {}).items():
+                walk_schema(child, f"{path}/{keyword}/{name}")
+        for keyword in ("allOf", "anyOf", "oneOf", "prefixItems"):
+            for index, child in enumerate(schema.get(keyword, [])):
+                walk_schema(child, f"{path}/{keyword}/{index}")
+        for keyword in (
+            "items",
+            "additionalProperties",
+            "unevaluatedProperties",
+            "unevaluatedItems",
+            "contains",
+            "not",
+            "if",
+            "then",
+            "else",
+            "propertyNames",
+            "contentSchema",
+        ):
+            if keyword in schema:
+                walk_schema(schema[keyword], f"{path}/{keyword}")
+
+    def walk(node: Any, path: str) -> None:
+        if isinstance(node, dict):
+            if "$ref" in node:
+                resolve_ref(document, cast(Document, node))
+            for key, value in cast(Document, node).items():
+                if key in {"example", "examples", "default", "enum", "const"}:
+                    continue
+                if path == "$/components/schemas" or key in {"schema", "itemSchema"}:
+                    walk_schema(value, f"{path}/{key}")
+                else:
+                    walk(value, f"{path}/{key}")
+        elif isinstance(node, list):
+            for index, value in enumerate(cast(list[Any], node)):
+                walk(value, f"{path}/{index}")
+
+    walk(document, "$")
+
+
+def export_schema(app: FastAPI) -> Document:
+    """Copy native OpenAPI output, promote compatible 3.1 output, then validate.
+
+    FastAPI emits the 3.2 itemSchema/contentSchema structure under a 3.1 version.
+    Its JSON Schema dialect is already Draft 2020-12. No stream schemas are
+    synthesized and the application's cached document is never modified.
+    Incompatible custom OpenAPI extensions fail validation instead of being lost.
+    """
+    document = copy.deepcopy(app.openapi())
+    version = document.get("openapi", "")
+    if not version.startswith(("3.1.", "3.2.")):
+        raise ContractError(f"Expected OpenAPI 3.1 or 3.2, got {version!r}")
+    if (
+        document.get("jsonSchemaDialect")
+        == "https://spec.openapis.org/oas/3.1/dialect/base"
+    ):
+        document["jsonSchemaDialect"] = (
+            "https://spec.openapis.org/oas/3.2/dialect/2026-02-26"
+        )
+    document["openapi"] = "3.2.0"
+    validate_contract(document)
+    return document

fastapi_streams/codegen/python.py

@@ -0,0 +1,473 @@
+import re
+from dataclasses import replace
+from importlib.resources import files
+from typing import Literal
+
+from fastapi_streams.codegen.ir import (
+    Array,
+    Contract,
+    Declaration,
+    EnumAlias,
+    EnumValue,
+    Field,
+    Intersection,
+    LiteralType,
+    Object,
+    Operation,
+    Parameter,
+    Reference,
+    Scalar,
+    StringEnum,
+    Type,
+    Union,
+)
+from fastapi_streams.codegen.names import identifier, python_identifier
+from fastapi_streams.codegen.openapi import ContractError
+from fastapi_streams.codegen.templating import add_filters, environment
+
+_HEADER = "# Generated by fastapi-streams. Do not edit.\n"
+_MODEL_SYMBOLS = {
+    "BaseModel",
+    "ConfigDict",
+    "Field",
+    "JsonValue",
+    "StrEnum",
+    "Literal",
+    "Annotated",
+    "field_validator",
+    "int",
+    "str",
+    "float",
+    "bool",
+    "list",
+    "dict",
+    "object",
+    "classmethod",
+}
+
+
+def generate_python(
+    contract: Contract, *, http_client: Literal["httpx", "httpx2"] = "httpx"
+) -> dict[str, str]:
+    if http_client not in {"httpx", "httpx2"}:
+        raise ContractError(f"Unsupported Python HTTP client: {http_client!r}")
+    http_import = (
+        "import httpx2 as httpx" if http_client == "httpx2" else "import httpx"
+    )
+    models = _Models(contract.declarations)
+    grouped: dict[str, list[Operation]] = {}
+    for operation in contract.operations:
+        name = identifier(operation.operation_id, upper=True)
+        seen = {"self", "options", "query", "headers", "content", "adapter"}
+        parameters: list[Parameter] = []
+        for parameter in operation.parameters:
+            argument = python_identifier(parameter.name)
+            if argument in seen or (operation.body and argument == "body"):
+                raise ContractError(
+                    f"Reserved or duplicate Python argument: {argument}"
+                )
+            seen.add(argument)
+            type_ = parameter.type
+            if not isinstance(type_, Scalar | Reference):
+                type_ = models.add(name + identifier(parameter.name, upper=True), type_)
+            parameters.append(replace(parameter, type=type_))
+        body = operation.body
+        if body:
+            body = replace(body, type=models.add(name + "Body", body.type))
+        event = models.add(name + "Event", operation.event)
+        if operation.errors:
+            models.add(
+                name + "Error", Union(tuple(error.type for error in operation.errors))
+            )
+        operation = replace(
+            operation, parameters=tuple(parameters), body=body, event=event
+        )
+        grouped.setdefault(python_identifier(operation.group), []).append(operation)
+    env = environment()
+
+    def render_type(value: Type) -> str:
+        return models.render_type(value, hint="Anonymous", prefix="Models.")
+
+    add_filters(
+        env,
+        snake=python_identifier,
+        repr=repr,
+        py_type=render_type,
+        py_path=_path,
+    )
+    groups: list[dict[str, str]] = []
+    output: dict[str, str] = {}
+    for name, operations in sorted(grouped.items()):
+        if name in {"models", "runtime", "client", "aclose"}:
+            raise ContractError(f"Reserved Python tag: {name}")
+        if len(
+            {python_identifier(operation.operation_id) for operation in operations}
+        ) != len(operations):
+            raise ContractError(f"Python operation name collision in {name}")
+        class_name = identifier(name, upper=True) + "Api"
+        groups.append(dict(name=name, directory=name, class_name=class_name))
+        functions = ["RequestOptions", "Transport"]
+        for location, function in (
+            ("path", "encode_path"),
+            ("query", "append_query"),
+            ("header", "set_header"),
+        ):
+            if any(
+                parameter.location == location
+                for op in operations
+                for parameter in op.parameters
+            ):
+                functions.append(function)
+        output[f"{name}/api.py"] = env.get_template("python/api.py.j2").render(
+            class_name=class_name,
+            operations=sorted(operations, key=lambda op: op.name),
+            runtime_imports=sorted(functions),
+        )
+        output[f"{name}/__init__.py"] = (
+            _HEADER + f"from .api import {class_name} as {class_name}\n"
+        )
+    output["models.py"] = models.render()
+    output["client.py"] = env.get_template("python/client.py.j2").render(
+        groups=groups, http_import=http_import
+    )
+    output["runtime.py"] = (
+        files(__package__)
+        .joinpath("templates/python/runtime.py")
+        .read_text(encoding="utf-8")
+        .replace("\nimport httpx\n", f"\n{http_import}\n", 1)
+    )
+    output["__init__.py"] = _HEADER + (
+        "from .client import Client as Client\n"
+        "from .runtime import (\n"
+        "    HttpError as HttpError, RequestOptions as RequestOptions,\n"
+        "    StreamParseError as StreamParseError, TransportError as TransportError,\n"
+        ")\n"
+    )
+    for name, type_ in sorted(models.declarations.items()):
+        if isinstance(type_, StringEnum | EnumAlias):
+            if name in {
+                "Client",
+                "RequestOptions",
+                "TransportError",
+                "HttpError",
+                "StreamParseError",
+            }:
+                raise ContractError(f"Reserved Python enum name: {name}")
+            output["__init__.py"] += f"from .models import {name} as {name}\n"
+    output["py.typed"] = ""
+    return output
+
+
+class _Models:
+    def __init__(self, declarations: tuple[Declaration, ...]) -> None:
+        if collisions := _MODEL_SYMBOLS & {
+            declaration.name for declaration in declarations
+        }:
+            raise ContractError(f"Reserved Python model names: {sorted(collisions)}")
+        self.declarations = {
+            declaration.name: declaration.type for declaration in declarations
+        }
+
+    def add(self, name: str, type_: Type) -> Reference:
+        if isinstance(type_, Reference):
+            return type_
+        while name in self.declarations:
+            name += "Value"
+        self.declarations[name] = type_
+        return Reference(name)
+
+    def render_type(self, type_: Type, *, hint: str, prefix: str = "") -> str:
+        match type_:
+            case Scalar(name="JsonValue"):
+                return "JsonValue"
+            case Scalar(name="never"):
+                raise ContractError(
+                    "The Python generator does not support never schemas"
+                )
+            case Scalar(name=name):
+                return {
+                    "string": "str",
+                    "integer": "int",
+                    "number": "float",
+                    "boolean": "bool",
+                    "null": "None",
+                }[name]
+            case LiteralType(value=None):
+                return "None"
+            case LiteralType(value=value):
+                return f"Literal[{value!r}]"
+            case EnumValue(enum=enum, member=member):
+                return f"Literal[{prefix}{enum}.{member}]"
+            case EnumAlias(target=target):
+                return prefix + target
+            case StringEnum():
+                raise ContractError("Enums must be named declarations")
+            case Reference(name=name):
+                return prefix + name
+            case Array(item=item):
+                return (
+                    f"list[{self.render_type(item, hint=hint + 'Item', prefix=prefix)}]"
+                )
+            case Union(members=members, discriminator=discriminator):
+                if members and all(isinstance(part, EnumValue) for part in members):
+                    values = ", ".join(
+                        f"{prefix}{part.enum}.{part.member}"
+                        for part in members
+                        if isinstance(part, EnumValue)
+                    )
+                    return f"Literal[{values}]"
+                union = " | ".join(
+                    self.render_type(member, hint=hint + str(index), prefix=prefix)
+                    for index, member in enumerate(members)
+                )
+                if discriminator:
+                    discriminator = _field_name(discriminator)
+                    return f"Annotated[{union}, Field(discriminator={discriminator!r})]"
+                return union if len(members) == 1 else f"({union})"
+            case Object() | Intersection():
+                reference = self.add(hint, type_)
+                return prefix + reference.name
+
+    def nullable(self, type_: Type, seen: frozenset[str] = frozenset()) -> bool:
+        match type_:
+            case Scalar(name="null" | "JsonValue") | LiteralType(value=None):
+                return True
+            case Union(members=members):
+                return any(self.nullable(member, seen) for member in members)
+            case Reference(name=name) if name not in seen:
+                return self.nullable(self.declarations[name], seen | {name})
+            case _:
+                return False
+
+    def _object(self, type_: Type, seen: frozenset[str] = frozenset()) -> Object:
+        match type_:
+            case Object():
+                return type_
+            case Reference(name=name) if name not in seen:
+                return self._object(self.declarations[name], seen | {name})
+            case Intersection(members=members):
+                fields: dict[str, Field] = {}
+                additional: Type | None = None
+                objects = [self._object(member, seen) for member in members]
+                for obj in objects:
+                    for field in obj.fields:
+                        if (
+                            field.name in fields
+                            and fields[field.name].type != field.type
+                        ):
+                            raise ContractError(
+                                f"Conflicting allOf field: {field.name}"
+                            )
+                        previous = fields.get(field.name)
+                        fields[field.name] = replace(
+                            field,
+                            required=field.required
+                            or bool(previous and previous.required),
+                        )
+                    if obj.additional is not None and obj.additional != Scalar(
+                        "JsonValue"
+                    ):
+                        if additional not in (
+                            None,
+                            Scalar("JsonValue"),
+                            obj.additional,
+                        ):
+                            raise ContractError(
+                                "Conflicting allOf additionalProperties schemas"
+                            )
+                        additional = obj.additional
+                    elif additional is None:
+                        additional = obj.additional
+                forbidden = any(obj.additional_forbidden for obj in objects)
+                for obj in objects:
+                    undeclared = set(fields) - {field.name for field in obj.fields}
+                    if obj.additional_forbidden and undeclared:
+                        raise ContractError(
+                            "Closed-object allOf cannot introduce fields forbidden by "
+                            f"another member: {sorted(undeclared)}"
+                        )
+                    if obj.additional not in (None, Scalar("JsonValue")) and any(
+                        fields[name].type != obj.additional for name in undeclared
+                    ):
+                        raise ContractError(
+                            "Conflicting allOf additionalProperties field types"
+                        )
+                return Object(
+                    tuple(fields[name] for name in sorted(fields)),
+                    None if forbidden else additional,
+                    forbidden,
+                )
+            case _:
+                raise ContractError("Python allOf supports object intersections only")
+
+    def render(self) -> str:
+        blocks: dict[str, str] = {}
+        classes: list[str] = []
+        while pending := sorted(set(self.declarations) - set(blocks)):
+            for name in pending:
+                type_ = self.declarations[name]
+                if isinstance(type_, StringEnum):
+                    members = "\n".join(
+                        f"    {member.name} = {member.value!r}"
+                        for member in type_.members
+                    )
+                    blocks[name] = f"class {name}(StrEnum):\n{members}"
+                elif isinstance(type_, EnumAlias):
+                    blocks[name] = f"{name} = {type_.target}"
+                elif isinstance(type_, Object | Intersection):
+                    obj = self._object(type_)
+                    if obj.additional is not None and not obj.fields:
+                        value = self.render_type(obj.additional, hint=name + "Value")
+                        blocks[name] = f"type {name} = dict[str, {value}]"
+                        continue
+                    lines = [f"class {name}(BaseModel):"]
+                    if obj.additional_forbidden:
+                        lines.append(
+                            "    model_config = ConfigDict("
+                            'populate_by_name=True, extra="forbid")'
+                        )
+                    elif obj.additional is not None:
+                        lines.append(
+                            "    model_config = ConfigDict("
+                            'populate_by_name=True, extra="allow")'
+                        )
+                    else:
+                        lines.append(
+                            "    model_config = ConfigDict(populate_by_name=True)"
+                        )
+                    field_names: set[str] = set()
+                    nonnullable_optional: list[str] = []
+                    for field in obj.fields:
+                        field_name = _field_name(field.name)
+                        if field_name in field_names:
+                            raise ContractError(
+                                f"Python field name collision in {name}: {field_name}"
+                            )
+                        field_names.add(field_name)
+                        annotation = self.render_type(
+                            field.type, hint=name + identifier(field.name, upper=True)
+                        )
+                        literals = (
+                            field.type.members
+                            if isinstance(field.type, Union)
+                            else (field.type,)
+                        )
+                        enum_values = [
+                            part for part in literals if isinstance(part, EnumValue)
+                        ]
+                        constant_default = (
+                            len(enum_values) == len(literals) and not field.required
+                        )
+                        if (
+                            not field.required
+                            and not self.nullable(field.type)
+                            and not constant_default
+                        ):
+                            annotation = f"{annotation} | None"
+                            nonnullable_optional.append(field_name)
+                        default = "None" if not field.required else "..."
+                        if constant_default:
+                            selected = enum_values[0]
+                            for value in enum_values:
+                                enum = self.declarations[value.enum]
+                                assert isinstance(enum, StringEnum)
+                                if field.default and any(
+                                    member.name == value.member
+                                    and member.value == field.default.value
+                                    for member in enum.members
+                                ):
+                                    selected = value
+                                    break
+                            default = f"{selected.enum}.{selected.member}"
+                        assignment = (
+                            f" = Field(default={default}, alias={field.name!r})"
+                            if field_name != field.name
+                            else (f" = {default}" if not field.required else "")
+                        )
+                        lines.append(f"    {field_name}: {annotation}{assignment}")
+                    if obj.additional is not None:
+                        annotation = self.render_type(
+                            obj.additional, hint=name + "Extra"
+                        )
+                        lines.append(
+                            f"    __pydantic_extra__: dict[str, {annotation}]"
+                            " = Field(init=False)"
+                            "  # pyright: ignore[reportIncompatibleVariableOverride]"
+                        )
+                    if nonnullable_optional:
+                        args = ", ".join(repr(name) for name in nonnullable_optional)
+                        lines.extend(
+                            [
+                                "",
+                                f"    @field_validator({args}, mode='before')",
+                                "    @classmethod",
+                                "    def _reject_explicit_null("
+                                "cls, value: object) -> object:",
+                                "        if value is None:",
+                                "            raise ValueError("
+                                "'Field may be omitted but cannot be null')",
+                                "        return value",
+                            ]
+                        )
+                    blocks[name] = "\n".join(lines)
+                    classes.append(name)
+                else:
+                    annotation = self.render_type(type_, hint=name)
+                    blocks[name] = f"type {name} = {annotation}"
+        text = "\n".join(blocks.values())
+        typing_names = [name for name in ("Annotated", "Literal") if name + "[" in text]
+        pydantic_names = [
+            name
+            for name in (
+                "BaseModel",
+                "ConfigDict",
+                "Field",
+                "JsonValue",
+                "field_validator",
+            )
+            if re.search(r"\b" + name + r"\b", text)
+        ]
+        imports = [_HEADER, "from __future__ import annotations", ""]
+        if any(isinstance(type_, StringEnum) for type_ in self.declarations.values()):
+            imports.append("from enum import StrEnum")
+        if typing_names:
+            imports.append("from typing import " + ", ".join(typing_names))
+        if pydantic_names:
+            imports.extend(["", "from pydantic import " + ", ".join(pydantic_names)])
+        return (
+            "\n\n".join(
+                [
+                    "\n".join(imports),
+                    *(
+                        blocks[name]
+                        for name in sorted(
+                            blocks,
+                            key=lambda name: (
+                                not isinstance(
+                                    self.declarations[name], StringEnum | EnumAlias
+                                ),
+                                name,
+                            ),
+                        )
+                    ),
+                    *(f"{name}.model_rebuild()" for name in sorted(classes)),
+                ]
+            )
+            + "\n"
+        )
+
+
+def _field_name(value: str) -> str:
+    name = python_identifier(value)
+    return name + "_" if name in _MODEL_SYMBOLS else name
+
+
+def _path(operation: Operation) -> str:
+    parts: list[str] = []
+    cursor = 0
+    for match in re.finditer(r"\{([^{}]+)\}", operation.path):
+        parts.append(repr(operation.path[cursor : match.start()]))
+        parts.append(f"encode_path({python_identifier(match[1])})")
+        cursor = match.end()
+    parts.append(repr(operation.path[cursor:]))
+    return " + ".join(parts)