fastapi-streams 0.0.1__py3-none-any.whl

fastapi_streams/__init__.py

@@ -0,0 +1,4 @@
+from fastapi_streams.router import StreamRouter
+
+__all__ = ["StreamRouter"]
+__version__ = "0.0.1"

fastapi_streams/codegen/cli.py

@@ -0,0 +1,120 @@
+import argparse
+import importlib
+import json
+import sys
+from pathlib import Path
+from typing import cast
+
+from fastapi import FastAPI
+
+from fastapi_streams.codegen.openapi import ContractError, Document, export_schema
+from fastapi_streams.codegen.writer import write_files
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="fastapi-streams")
+    commands = parser.add_subparsers(dest="command", required=True)
+    schema = commands.add_parser("schema", help="Export and validate OpenAPI 3.2")
+    schema.add_argument("--app", required=True)
+    schema.add_argument("--output", required=True, type=Path)
+    schema.add_argument("--check", action="store_true")
+    for name in ("generate", "check"):
+        command = commands.add_parser(
+            name,
+            help="Generate a client"
+            if name == "generate"
+            else "Check schema and generated-client drift",
+        )
+        command.add_argument("--schema", required=True, type=Path)
+        command.add_argument(
+            "--language", choices=["typescript", "python"], default="typescript"
+        )
+        command.add_argument("--output", required=True, type=Path)
+        command.add_argument(
+            "--python-http-client",
+            choices=["httpx", "httpx2"],
+            help="Python HTTP library (default: httpx; opt in with httpx2)",
+        )
+        if name == "generate":
+            command.add_argument("--check", action="store_true")
+        else:
+            command.set_defaults(check=True)
+            command.add_argument(
+                "--app", help="Also compare the app's contract with --schema"
+            )
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "schema":
+            content = (
+                json.dumps(
+                    export_schema(_load_app(args.app)),
+                    indent=2,
+                    sort_keys=True,
+                    ensure_ascii=False,
+                )
+                + "\n"
+            )
+            output = cast(Path, args.output)
+            if args.check:
+                if not output.is_file() or output.read_bytes() != content.encode(
+                    "utf-8"
+                ):
+                    print(f"Out of date: {output}", file=sys.stderr)
+                    return 1
+            else:
+                output.parent.mkdir(parents=True, exist_ok=True)
+                output.write_text(content, encoding="utf-8", newline="\n")
+        else:
+            if args.language != "python" and args.python_http_client is not None:
+                raise ContractError("--python-http-client requires --language python")
+            from fastapi_streams.codegen.ir import build_ir
+            from fastapi_streams.codegen.python import generate_python
+            from fastapi_streams.codegen.typescript import generate_typescript
+
+            document = json.loads(args.schema.read_text(encoding="utf-8"))
+            if not isinstance(document, dict):
+                raise ContractError("The OpenAPI document must be an object")
+            if args.command == "check" and args.app:
+                expected = export_schema(_load_app(args.app))
+                if expected != document:
+                    print(
+                        f"Out of date: {args.schema} (application contract changed)",
+                        file=sys.stderr,
+                    )
+                    return 1
+            contract = build_ir(cast(Document, document))
+            generated = (
+                generate_python(
+                    contract, http_client=args.python_http_client or "httpx"
+                )
+                if args.language == "python"
+                else generate_typescript(contract)
+            )
+            changed = write_files(args.output, generated, check=args.check)
+            if args.check and changed:
+                for path in changed:
+                    print(f"Out of date: {path}", file=sys.stderr)
+                return 1
+    except (ContractError, OSError, ValueError, ImportError, AttributeError) as exc:
+        message = str(exc)
+        if isinstance(exc, ImportError) and exc.name in {"jinja2", "jsonschema"}:
+            message = "Install fastapi-streams[codegen] to generate clients"
+        print(f"fastapi-streams: {message}", file=sys.stderr)
+        return 2
+    return 0
+
+
+def _load_app(value: str) -> FastAPI:
+    module, separator, attribute = value.partition(":")
+    if not separator or not module or not attribute:
+        raise ContractError("--app must use module:attribute syntax")
+    # Console scripts start with their installation directory on sys.path.
+    sys.path.insert(0, str(Path.cwd()))
+    app = getattr(importlib.import_module(module), attribute)
+    if not isinstance(app, FastAPI):
+        raise ContractError(f"{value} is not a FastAPI application")
+    return app
+
+
+if __name__ == "__main__":
+    sys.exit(main())

fastapi_streams/codegen/enums.py

@@ -0,0 +1,172 @@
+from dataclasses import replace
+
+from fastapi_streams.codegen.ir import (
+    Contract,
+    Declaration,
+    EnumAlias,
+    EnumMember,
+    EnumValue,
+    Field,
+    LiteralType,
+    Object,
+    Operation,
+    Reference,
+    StringEnum,
+    Type,
+    Union,
+)
+from fastapi_streams.codegen.names import identifier, python_identifier
+from fastapi_streams.codegen.openapi import ContractError
+
+
+def with_enums(contract: Contract) -> Contract:
+    declarations = {
+        declaration.name: declaration.type for declaration in contract.declarations
+    }
+    operations: list[Operation] = []
+    for operation in contract.operations:
+        if isinstance(operation.event, Union) and operation.event.discriminator:
+            name = identifier(operation.operation_id, upper=True) + "Event"
+            if name in declarations:
+                raise ContractError(f"Event alias name collision: {name}")
+            declarations[name] = operation.event
+            operation = replace(operation, event=Reference(name))
+        operations.append(operation)
+    candidates: list[tuple[str, set[tuple[str, str]], set[str]]] = []
+    for name, type_ in sorted(declarations.items()):
+        if not isinstance(type_, Union):
+            continue
+        if all(
+            isinstance(member, LiteralType) and isinstance(member.value, str)
+            for member in type_.members
+        ):
+            values = {
+                member.value
+                for member in type_.members
+                if isinstance(member, LiteralType) and isinstance(member.value, str)
+            }
+            declarations[name] = StringEnum(_members(values))
+        elif type_.discriminator:
+            fields: set[tuple[str, str]] = set()
+            values: set[str] = set()
+            for member in type_.members:
+                if not isinstance(member, Reference):
+                    break
+                model = declarations.get(member.name)
+                if not isinstance(model, Object):
+                    break
+                field = next(
+                    (
+                        field
+                        for field in model.fields
+                        if field.name == type_.discriminator
+                    ),
+                    None,
+                )
+                literals = (
+                    field.type.members
+                    if field and isinstance(field.type, Union)
+                    else (field.type,)
+                    if field
+                    else ()
+                )
+                if not literals or not all(
+                    isinstance(part, LiteralType) and isinstance(part.value, str)
+                    for part in literals
+                ):
+                    break
+                assert field is not None
+                fields.add((member.name, field.name))
+                values.update(
+                    part.value
+                    for part in literals
+                    if isinstance(part, LiteralType) and isinstance(part.value, str)
+                )
+            else:
+                candidates.append(
+                    (name + identifier(type_.discriminator, upper=True), fields, values)
+                )
+    # Overlapping unions share one enum class, keeping Python narrowing consistent.
+    while candidates:
+        name, fields, values = candidates.pop(0)
+        aliases = {name}
+        changed = True
+        while changed:
+            changed = False
+            for candidate in candidates[:]:
+                other_name, other_fields, other_values = candidate
+                if fields & other_fields:
+                    candidates.remove(candidate)
+                    fields |= other_fields
+                    values |= other_values
+                    aliases.add(other_name)
+                    changed = True
+        canonical = min(aliases)
+        enum = StringEnum(_members(values))
+        for alias in sorted(aliases):
+            if alias in declarations and declarations[alias] != enum:
+                raise ContractError(f"Enum type name collision: {alias}")
+            declarations[alias] = enum if alias == canonical else EnumAlias(canonical)
+        by_value = {member.value: member.name for member in enum.members}
+        for model_name, field_name in fields:
+            model = declarations[model_name]
+            assert isinstance(model, Object)
+            declarations[model_name] = replace(
+                model,
+                fields=tuple(
+                    replace(field, type=_enum_literals(field.type, canonical, by_value))
+                    if field.name == field_name
+                    else field
+                    for field in model.fields
+                ),
+            )
+    for name, type_ in list(declarations.items()):
+        if not isinstance(type_, Object):
+            continue
+        model_fields: list[Field] = []
+        for field in type_.fields:
+            literals = (
+                field.type.members if isinstance(field.type, Union) else (field.type,)
+            )
+            values = {
+                part.value
+                for part in literals
+                if isinstance(part, LiteralType) and isinstance(part.value, str)
+            }
+            if values and len(values) == len(literals):
+                enum_name = name + identifier(field.name, upper=True)
+                enum = StringEnum(_members(values))
+                if enum_name in declarations and declarations[enum_name] != enum:
+                    raise ContractError(f"Enum type name collision: {enum_name}")
+                declarations[enum_name] = enum
+                field = replace(
+                    field,
+                    type=Reference(enum_name)
+                    if len(values) > 1
+                    else EnumValue(enum_name, enum.members[0].name),
+                )
+            model_fields.append(field)
+        declarations[name] = replace(type_, fields=tuple(model_fields))
+    return replace(
+        contract,
+        operations=tuple(operations),
+        declarations=tuple(
+            Declaration(name, type_) for name, type_ in sorted(declarations.items())
+        ),
+    )
+
+
+def _members(values: set[str]) -> tuple[EnumMember, ...]:
+    result = tuple(
+        EnumMember(python_identifier(value).upper(), value) for value in sorted(values)
+    )
+    if len({member.name for member in result}) != len(result):
+        raise ContractError(f"Enum member names collide: {sorted(values)}")
+    return result
+
+
+def _enum_literals(type_: Type, enum: str, members: dict[str, str]) -> Type:
+    if isinstance(type_, LiteralType) and isinstance(type_.value, str):
+        return EnumValue(enum, members[type_.value])
+    assert isinstance(type_, Union)
+    return Union(tuple(_enum_literals(part, enum, members) for part in type_.members))