feat: ability to selectively generate protocol parts

Anders Brams · Anders Brams · commit 3b3f7409d5a0 · 2026-05-17T03:50:47.000+02:00
diff --git a/README.md b/README.md
@@ -24,8 +24,8 @@ Generate a client from an OpenAPI spec in `openapi.json`:
 # Types + HTTP transport
 uv run openapi-python generate --spec ./openapi.json --out ./generated
 
-# Types
-uv run openapi-python generate --spec ./openapi.json --out ./generated --transport-mode protocol-only
+# Types + custom transport protocol
+uv run openapi-python generate --spec ./openapi.json --out ./generated --protocol-only
 ```
 
 ... or programatically:
@@ -87,7 +87,9 @@ book = client.get("/books/{book_id}")(params={"book_id": 1})
 
 Generated clients expose a transport protocol. You can plug in your own transport while keeping route-level typing guarantees.
 
-Use `--transport-mode protocol-only` to generate clients that require a supplied transport and do not emit the built-in `httpx` transport classes. The default `--transport-mode default` includes `DefaultTransport` and `DefaultAsyncTransport`, which require the `httpx` extra when instantiated.
+Use `--protocol-only` to generate clients that require a supplied transport and do not emit the built-in `httpx` transport classes. By default, generated clients include `DefaultTransport` and `DefaultAsyncTransport`, which require the `httpx` extra when instantiated.
+
+Protocol typing can be relaxed independently with `--no-routes`, `--no-requests`, and `--no-responses`. Those flags replace the corresponding route literals, request payload types, or response types with broad catch-all types.
 
 ### Built-in `httpx` transport
 
@@ -128,7 +130,7 @@ uv run openapi-python generate \
   --spec ./openapi.json \
   --out ./generated \
   --package my_client \
-  --transport-mode protocol-only
+  --protocol-only
 ```
 
 Then provide an object that satisfies the generated `Transport` protocol:
diff --git a/openapi_python/cli.py b/openapi_python/cli.py
@@ -30,10 +30,27 @@ def _build_parser() -> argparse.ArgumentParser:
         help="Disable SSL certificate verification for URL specs",
     )
     generate.add_argument(
-        "--transport-mode",
-        choices=["default", "protocol-only"],
-        default="default",
-        help="Generation mode for transport integration",
+        "--protocol-only",
+        action="store_true",
+        help="Require supplied transports instead of generating built-in httpx transports",
+    )
+    generate.add_argument(
+        "--routes",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Generate route literal types and route-specific client overloads (DEFAULT: True)",
+    )
+    generate.add_argument(
+        "--requests",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Generate typed params, query, header, and body protocol arguments (DEFAULT: True)",
+    )
+    generate.add_argument(
+        "--responses",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Generate typed protocol response values (DEFAULT: True)",
     )
     return parser
 
@@ -53,7 +70,10 @@ def main(argv: list[str] | None = None) -> int:
         package_name=args.package,
         overwrite=args.overwrite,
         verify_ssl=not args.no_ssl,
-        transport_mode=args.transport_mode,
+        protocol_only=args.protocol_only,
+        generate_routes=args.routes,
+        generate_requests=args.requests,
+        generate_responses=args.responses,
     )
     result = try_generate_client(request)
 
diff --git a/openapi_python/generator/api.py b/openapi_python/generator/api.py
@@ -19,7 +19,10 @@ class GenerationRequest:
     package_name: str = "my_client"
     overwrite: bool = False
     verify_ssl: bool = True
-    transport_mode: str = "default"
+    protocol_only: bool = False
+    generate_routes: bool = True
+    generate_requests: bool = True
+    generate_responses: bool = True
     extensions: GeneratorExtensions | None = None
     spec_json: str | None = None
 
@@ -38,8 +41,6 @@ def generate_client(request: GenerationRequest) -> GenerationResult:
         raise invalid_request("Exactly one of spec_source or spec_json is required")
     if not request.package_name:
         raise invalid_request("package_name is required")
-    if request.transport_mode not in {"default", "protocol-only"}:
-        raise invalid_request("transport_mode must be 'default' or 'protocol-only'")
 
     if request.spec_json is not None:
         document = load_openapi_json(request.spec_json)
@@ -57,7 +58,12 @@ def generate_client(request: GenerationRequest) -> GenerationResult:
             normalized = candidate
 
     artifacts = render_package(
-        normalized, request.extensions, transport_mode=request.transport_mode
+        normalized,
+        request.extensions,
+        protocol_only=request.protocol_only,
+        generate_routes=request.generate_routes,
+        generate_requests=request.generate_requests,
+        generate_responses=request.generate_responses,
     )
     written = write_artifacts(
         output_dir=request.output_dir, artifacts=artifacts, overwrite=request.overwrite
diff --git a/openapi_python/generator/render.py b/openapi_python/generator/render.py
@@ -225,7 +225,15 @@ def _format_type_definition(defn: TypeAliasDef | TypedDictDef) -> str:
             return _format_typeddict(defn)
 
 
-def _call_parameters(op: OperationDef) -> dict[str, str]:
+def _call_parameters(op: OperationDef, *, generate_requests: bool) -> dict[str, str]:
+    if not generate_requests:
+        return {
+            "params": "params: dict[str, Any] | None = None",
+            "query": "query: dict[str, Any] | None = None",
+            "headers": "headers: dict[str, Any] | None = None",
+            "body": "body: object | None = None",
+        }
+
     params = "params: " + _render_annotation(op.params_type)
     if not op.params_required:
         params += " | None = None"
@@ -256,13 +264,22 @@ def _protocol_name(op: OperationDef, *, is_async: bool = False) -> str:
     return f"Async{op.protocol_name}" if is_async else op.protocol_name
 
 
-def _protocol_block(op: OperationDef, *, is_async: bool = False) -> str:
+def _protocol_block(
+    op: OperationDef,
+    *,
+    generate_requests: bool,
+    generate_responses: bool,
+    is_async: bool = False,
+) -> str:
     return _render_template(
         "protocol.py.j2",
         op=op,
         is_async=is_async,
         protocol_name=_protocol_name(op, is_async=is_async),
-        call_parameters=_call_parameters(op),
+        call_parameters=_call_parameters(op, generate_requests=generate_requests),
+        response_type=(
+            _render_annotation(op.response_type) if generate_responses else "Any"
+        ),
     )
 
 
@@ -287,8 +304,8 @@ def _fallback_method_block(
     )
 
 
-def _render_types(spec: NormalizedSpec) -> str:
-    aliases = (*_route_aliases(spec), *spec.aliases)
+def _render_types(spec: NormalizedSpec, *, generate_routes: bool) -> str:
+    aliases = (*_route_aliases(spec, generate_routes=generate_routes), *spec.aliases)
     type_definitions = _order_type_definitions(aliases, spec.typed_dicts)
     blocks = [_format_enum(item) for item in spec.enums] + [
         _format_type_definition(item) for item in type_definitions
@@ -303,7 +320,12 @@ def _literal_annotation(values: set[str]) -> LiteralAnnotation:
     return LiteralAnnotation(tuple(sorted(values)))
 
 
-def _route_aliases(spec: NormalizedSpec) -> tuple[TypeAliasDef, ...]:
+def _route_aliases(
+    spec: NormalizedSpec, *, generate_routes: bool
+) -> tuple[TypeAliasDef, ...]:
+    if not generate_routes:
+        return (TypeAliasDef(name="RouteLiteral", annotation=NamedAnnotation("str")),)
+
     routes_by_method: dict[str, set[str]] = {}
     for op in spec.operations:
         routes_by_method.setdefault(op.method.upper(), set()).add(op.route_literal)
@@ -331,28 +353,50 @@ def _route_aliases(spec: NormalizedSpec) -> tuple[TypeAliasDef, ...]:
     return tuple(aliases)
 
 
-def _render_transport(spec: NormalizedSpec, *, transport_mode: str) -> str:
+def _render_transport(spec: NormalizedSpec, *, protocol_only: bool) -> str:
     return _render_template(
         "transport.py.j2",
-        typing_imports=(
-            "TYPE_CHECKING, Protocol" if transport_mode == "default" else "Protocol"
-        ),
-        include_default_transport=transport_mode == "default",
+        typing_imports="Protocol" if protocol_only else "TYPE_CHECKING, Protocol",
+        include_default_transport=not protocol_only,
     )
 
 
-def _render_client(spec: NormalizedSpec, *, transport_mode: str) -> str:
+def _render_client(
+    spec: NormalizedSpec,
+    *,
+    protocol_only: bool,
+    generate_routes: bool,
+    generate_requests: bool,
+    generate_responses: bool,
+) -> str:
     protocols: list[str] = []
     async_protocols: list[str] = []
     method_overloads: dict[str, list[str]] = {}
     async_method_overloads: dict[str, list[str]] = {}
     for op in spec.operations:
-        protocols.append(_protocol_block(op))
-        async_protocols.append(_protocol_block(op, is_async=True))
-        method_overloads.setdefault(op.method, []).append(_method_overload_line(op))
-        async_method_overloads.setdefault(op.method, []).append(
-            _method_overload_line(op, is_async=True)
-        )
+        if generate_routes:
+            protocols.append(
+                _protocol_block(
+                    op,
+                    generate_requests=generate_requests,
+                    generate_responses=generate_responses,
+                )
+            )
+            async_protocols.append(
+                _protocol_block(
+                    op,
+                    generate_requests=generate_requests,
+                    generate_responses=generate_responses,
+                    is_async=True,
+                )
+            )
+            method_overloads.setdefault(op.method, []).append(_method_overload_line(op))
+            async_method_overloads.setdefault(op.method, []).append(
+                _method_overload_line(op, is_async=True)
+            )
+        else:
+            method_overloads.setdefault(op.method, [])
+            async_method_overloads.setdefault(op.method, [])
 
     method_blocks: list[str] = []
     for method in sorted(method_overloads):
@@ -372,7 +416,7 @@ def _render_client(spec: NormalizedSpec, *, transport_mode: str) -> str:
             )
         )
 
-    if transport_mode == "default":
+    if not protocol_only:
         transport_imports = (
             "from .transport import AsyncTransport, DefaultAsyncTransport, "
             "DefaultTransport, Transport"
@@ -406,20 +450,29 @@ def render_package(
     spec: NormalizedSpec,
     extensions: GeneratorExtensions | None = None,
     *,
-    transport_mode: str = "default",
+    protocol_only: bool = False,
+    generate_routes: bool = True,
+    generate_requests: bool = True,
+    generate_responses: bool = True,
 ) -> list[GeneratedArtifact]:
     context = {
-        "types": _render_types(spec),
-        "transport": _render_transport(spec, transport_mode=transport_mode),
-        "client": _render_client(spec, transport_mode=transport_mode),
+        "types": _render_types(spec, generate_routes=generate_routes),
+        "transport": _render_transport(spec, protocol_only=protocol_only),
+        "client": _render_client(
+            spec,
+            protocol_only=protocol_only,
+            generate_routes=generate_routes,
+            generate_requests=generate_requests,
+            generate_responses=generate_responses,
+        ),
     }
 
     if extensions:
         for hook in extensions.render_context_hooks:
             context = hook(spec, context)
 
     init_content = _render_template(
-        "init.py.j2", include_default_transport=transport_mode == "default"
+        "init.py.j2", include_default_transport=not protocol_only
     )
 
     return [
diff --git a/openapi_python/generator/templates/method_block.py.j2 b/openapi_python/generator/templates/method_block.py.j2
@@ -1,8 +1,10 @@
 {{ overloads }}
+{% if overloads %}
 @overload
 def {{ method }}(self, route: str) -> Callable[..., {{ callable_return }}]: ...
+{% endif %}
 def {{ method }}(self, route: str) -> Callable[..., {{ callable_return }}]:
-    {{ "async " if is_async else "" }}def _call(*, params: dict[str, object] | None = None, query: dict[str, object] | None = None, headers: dict[str, object] | None = None, body: object | None = None) -> {{ call_return }}:
+    {{ "async " if is_async else "" }}def _call(*, params: dict[str, Any] | None = None, query: dict[str, Any] | None = None, headers: dict[str, Any] | None = None, body: object | None = None) -> {{ call_return }}:
         return {{ "await " if is_async else "" }}self._transport.request(
             method={{ method|repr }},
             route=route,
diff --git a/openapi_python/generator/templates/protocol.py.j2 b/openapi_python/generator/templates/protocol.py.j2
@@ -1,2 +1,2 @@
 class {{ protocol_name }}(Protocol):
-    {{ "async " if is_async else "" }}def __call__(self, *, {{ call_parameters.params }}, {{ call_parameters.query }}, {{ call_parameters.headers }}, {{ call_parameters.body }}) -> {{ op.response_type | annotation }}: ...
+    {{ "async " if is_async else "" }}def __call__(self, *, {{ call_parameters.params }}, {{ call_parameters.query }}, {{ call_parameters.headers }}, {{ call_parameters.body }}) -> {{ response_type }}: ...
diff --git a/tests/contract/protocol_no_requests/generate.py b/tests/contract/protocol_no_requests/generate.py
@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from openapi_python.generator import GenerationRequest, generate_client
+
+SPEC = {
+    "openapi": "3.1.0",
+    "info": {"title": "Protocol Flags", "version": "1.0.0"},
+    "paths": {
+        "/books/{book_id}": {
+            "get": {
+                "parameters": [
+                    {
+                        "name": "book_id",
+                        "in": "path",
+                        "required": True,
+                        "schema": {"type": "integer"},
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "content": {
+                            "application/json": {
+                                "schema": {"$ref": "#/components/schemas/Book"}
+                            }
+                        },
+                    }
+                },
+            }
+        }
+    },
+    "components": {
+        "schemas": {
+            "Book": {
+                "type": "object",
+                "required": ["id", "title"],
+                "properties": {
+                    "id": {"type": "integer"},
+                    "title": {"type": "string"},
+                },
+            }
+        }
+    },
+}
+
+
+def main() -> None:
+    generate_client(
+        GenerationRequest(
+            output_dir=Path(__file__).parent / "generated",
+            spec_json=json.dumps(SPEC),
+            overwrite=True,
+            generate_requests=False,
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()
diff --git a/tests/contract/protocol_no_requests/usage_sync.py b/tests/contract/protocol_no_requests/usage_sync.py
@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from typing import assert_type
+
+from generated.my_client import Client
+from generated.my_client.types import Book
+
+client = Client(base_url="http://testserver")
+
+book = client.get("/books/{book_id}")(
+    params={"book_id": "not statically constrained"},
+    query={"unexpected": object()},
+    headers={"x-test": object()},
+)
+assert_type(book, Book)
+assert_type(book["title"], str)
diff --git a/tests/contract/protocol_no_responses/generate.py b/tests/contract/protocol_no_responses/generate.py
diff --git a/tests/contract/protocol_no_responses/usage_sync.py b/tests/contract/protocol_no_responses/usage_sync.py
diff --git a/tests/contract/protocol_no_routes/generate.py b/tests/contract/protocol_no_routes/generate.py
diff --git a/tests/contract/protocol_no_routes/usage_sync.py b/tests/contract/protocol_no_routes/usage_sync.py

Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,2 @@`
`1`	`1`	`class {{ protocol_name }}(Protocol):`
`2`		`- {{ "async " if is_async else "" }}def __call__(self, *, {{ call_parameters.params }}, {{ call_parameters.query }}, {{ call_parameters.headers }}, {{ call_parameters.body }}) -> {{ op.response_type \| annotation }}: ...`
	`2`	`+ {{ "async " if is_async else "" }}def __call__(self, *, {{ call_parameters.params }}, {{ call_parameters.query }}, {{ call_parameters.headers }}, {{ call_parameters.body }}) -> {{ response_type }}: ...`