httpxgen 0.1.0__py3-none-any.whl

httpxgen/__init__.py

@@ -0,0 +1,12 @@
+from .generator import GenerationError, generate_client
+from .io import filter_operations_by_tags, load_openapi, write_client
+from .openapi import OpenAPISpec
+
+__all__ = [
+    "GenerationError",
+    "OpenAPISpec",
+    "filter_operations_by_tags",
+    "generate_client",
+    "load_openapi",
+    "write_client",
+]

httpxgen/cli.py

@@ -0,0 +1,78 @@
+import argparse
+from pathlib import Path
+
+from httpxgen.generator import GenerationError
+from httpxgen.io import (
+    filter_operations_by_tags,
+    load_openapi,
+    write_client,
+)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Generate a typed async Python client from OpenAPI JSON or YAML."
+    )
+    parser.add_argument("openapi", type=Path, help="OpenAPI JSON or YAML file")
+    parser.add_argument(
+        "output",
+        type=Path,
+        help="target package directory, or the root holding one package per tag "
+        "when more than one --tag is given",
+    )
+    parser.add_argument(
+        "--package-name",
+        help="generated import package name; defaults to the output directory name",
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="do not write; fail when generated output is stale",
+    )
+    parser.add_argument(
+        "--tag",
+        dest="tags",
+        action="append",
+        default=[],
+        metavar="TAG",
+        help="include only operations with this OpenAPI tag; repeat it to generate "
+        "one package per tag around a shared support package",
+    )
+    parser.add_argument(
+        "--schema-tag",
+        dest="schema_tags",
+        action="append",
+        default=[],
+        metavar="TAG",
+        help="retain schemas referenced by this tag without generating its operations",
+    )
+    args = parser.parse_args()
+
+    try:
+        spec = load_openapi(args.openapi)
+        if len(args.tags) <= 1:
+            spec = filter_operations_by_tags(
+                spec,
+                args.tags,
+                schema_tags=args.schema_tags,
+            )
+        changed = write_client(
+            spec=spec,
+            package_dir=args.output,
+            package_name=args.package_name,
+            tags=args.tags,
+            schema_tags=args.schema_tags,
+            check=args.check,
+        )
+    except (GenerationError, OSError, ValueError) as error:
+        parser.exit(1, f"error: {error}\n")
+
+    if args.check:
+        print("Generated HTTP client is current.")
+    else:
+        print(f"Generated {len(changed)} file(s) in package {args.output}.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

httpxgen/generator/__init__.py

@@ -0,0 +1,4 @@
+from .build import generate_client, generate_workspace
+from .errors import GenerationError
+
+__all__ = ["GenerationError", "generate_client", "generate_workspace"]

httpxgen/generator/build.py

@@ -0,0 +1,162 @@
+from collections import Counter
+from collections.abc import Sequence
+
+from httpxgen.generator.client import Layout, render_client, render_serialization
+from httpxgen.generator.models import exported_model_names, render_models
+from httpxgen.generator.naming import class_name, identifier
+from httpxgen.generator.normalize import normalize_inline_schemas
+from httpxgen.generator.operations import (
+    read_operations,
+    read_security_schemes,
+    response_model_names,
+)
+from httpxgen.generator.package import (
+    render_client_package_init,
+    render_package_init,
+    render_workspace_init,
+    validate_package_names,
+    validate_workspace_names,
+)
+from httpxgen.generator.templates import (
+    GENERATED_HEADER,
+    TemplateName,
+    render_template,
+)
+from httpxgen.openapi import OpenAPISpec
+from httpxgen.selection import filter_operations_by_tags
+
+_SHARED = "shared"
+
+
+def generate_client(spec: OpenAPISpec, package_name: str) -> dict[str, str]:
+    """Render a single client package as {relative path: file content}."""
+    spec = normalize_inline_schemas(spec)
+    schemas = spec.components.schemas
+    operations = read_operations(spec)
+    client_name = f"{class_name(package_name)}Client"
+    validate_package_names(schemas, operations, client_name)
+    layout = Layout(
+        exceptions=f"{package_name}.exceptions",
+        serialization=f"{package_name}.serialization",
+        models=f"{package_name}.models",
+        http_methods=f"{package_name}.http_methods",
+    )
+    return _finish(
+        {
+            "client.py": render_client(operations, schemas, client_name, layout),
+            "models.py": render_models(schemas, operations),
+            "exceptions.py": render_template(TemplateName.EXCEPTIONS),
+            "http_methods.py": render_template(TemplateName.HTTP_METHODS),
+            "serialization.py": render_serialization(read_security_schemes(spec)),
+            "__init__.py": render_package_init(schemas, client_name, operations),
+        }
+    )
+
+
+def generate_workspace(
+    spec: OpenAPISpec,
+    tags: Sequence[str],
+    package_name: str,
+    *,
+    schema_tags: Sequence[str] = (),
+) -> dict[str, str]:
+    """Render one client package per tag around a shared support package."""
+    tags = tuple(dict.fromkeys(tags))
+    spec = normalize_inline_schemas(
+        filter_operations_by_tags(spec, tags, schema_tags=schema_tags)
+    )
+    schemas = spec.components.schemas
+    operations_by_tag = {
+        tag: read_operations(_only(spec, tag, tags, schema_tags)) for tag in tags
+    }
+    validate_workspace_names(
+        schemas,
+        operations_by_tag,
+        [f"{class_name(identifier(tag))}Client" for tag in tags],
+    )
+    owners = _schema_owners(spec, tags)
+    shared_schemas = {
+        name: schema for name, schema in schemas.items() if owners[name] is None
+    }
+    shared_names = frozenset(exported_model_names(shared_schemas))
+    shared_module = f"{package_name}.{_SHARED}"
+
+    files = {
+        f"{_SHARED}/exceptions.py": render_template(TemplateName.EXCEPTIONS),
+        f"{_SHARED}/http_methods.py": render_template(TemplateName.HTTP_METHODS),
+        f"{_SHARED}/serialization.py": render_serialization(
+            read_security_schemes(spec)
+        ),
+        f"{_SHARED}/models.py": render_models(schemas, defined=shared_schemas),
+        f"{_SHARED}/__init__.py": render_template(TemplateName.SHARED_INIT),
+    }
+    clients: list[tuple[str, str]] = []
+    exports: dict[str, list[str]] = {}
+    for tag in tags:
+        module = identifier(tag)
+        client_name = f"{class_name(module)}Client"
+        operations = operations_by_tag[tag]
+        validate_package_names(schemas, operations, client_name)
+        defined = {name for name, owner in owners.items() if owner == tag}
+        layout = Layout(
+            exceptions=shared_module,
+            serialization=shared_module,
+            models=f"{package_name}.{module}.models",
+            http_methods=shared_module,
+            shared_models=f"{shared_module}.models",
+            shared_names=shared_names,
+        )
+        models = sorted(
+            [
+                *exported_model_names({name: schemas[name] for name in defined}),
+                *(
+                    name
+                    for operation in operations
+                    for name in response_model_names(operation)
+                ),
+            ]
+        )
+        files[f"{module}/client.py"] = render_client(
+            operations, schemas, client_name, layout
+        )
+        files[f"{module}/models.py"] = render_models(
+            schemas,
+            operations,
+            defined=defined,
+            external=[(f"{shared_module}.models", sorted(shared_names))],
+        )
+        files[f"{module}/__init__.py"] = render_client_package_init(client_name, models)
+        clients.append((module, client_name))
+        exports[module] = models
+    files["__init__.py"] = render_workspace_init(clients, exports, sorted(shared_names))
+    return _finish(files)
+
+
+def _schema_owners(spec: OpenAPISpec, tags: Sequence[str]) -> dict[str, str | None]:
+    """Map every schema to the single tag using it, or None when it is shared."""
+    reachable = {
+        tag: set(filter_operations_by_tags(spec, [tag]).components.schemas)
+        for tag in tags
+    }
+    counts = Counter(name for names in reachable.values() for name in names)
+    return {
+        name: next(
+            (tag for tag in tags if counts[name] == 1 and name in reachable[tag]),
+            None,
+        )
+        for name in spec.components.schemas
+    }
+
+
+def _only(
+    spec: OpenAPISpec, tag: str, tags: Sequence[str], schema_tags: Sequence[str]
+) -> OpenAPISpec:
+    others = [item for item in tags if item != tag]
+    return filter_operations_by_tags(spec, [tag], schema_tags=[*others, *schema_tags])
+
+
+def _finish(files: dict[str, str]) -> dict[str, str]:
+    return {
+        relative: f"{GENERATED_HEADER}\n\n{content.rstrip()}\n"
+        for relative, content in files.items()
+    } | {"py.typed": ""}