fix: properly handling union aliases

Author: Minibrams

README.md

@@ -1,31 +1,31 @@
 # openapi-python
 
-`openapi-python` generates strongly typed Python API clients from OpenAPI specs, with a developer-friendly and ergonomic string-literal-based interface strongly inspired by [openapi-typescript](https://openapi-ts.dev/).
+`openapi-python` generates typed Python API clients from OpenAPI specs, with a developer-friendly and ergonomic string-literal-based interface strongly inspired by [openapi-typescript](https://openapi-ts.dev/).
 
 ## Installation
 
-For generated clients that use the built-in `httpx` transport:
-
 ```bash
+# For built-in httpx transport:
 uv add openapi-python[httpx]
-```
-
-For protocol-only generated clients where you provide the transport:
 
-```bash
+# If you want to define your own HTTP transport (requests, asyncio, ...)
 uv add openapi-python
 ```
 
 
-## CLI
+## Client generation
 
 Generate a client from an OpenAPI spec in `openapi.json`:
 
 ```bash
-uv run openapi-python generate --spec ./openapi.json --out ./generated --package my_client
+# Types + HTTP client/transport
+uv run openapi-python generate --spec ./openapi.json --out ./generated
+
+# Just types, use your own HTTP client/transport
+uv run openapi-python generate --spec ./openapi.json --out ./generated --transport-mode protocol-only
 ```
 
-## Programmatic API
+... or programatically:
 
 ```python
 from pathlib import Path

openapi_python/generator/normalize.py

@@ -237,7 +237,9 @@ def _ensure_component(state: _TypeState, name: str) -> tuple[str, _TypeState]:
     type_name = _is_unique_type_name(state, _pascal(name))
 
     state = _with_component_type_name(state, name, type_name)
-    _, state = _schema_to_type(state, schema, type_name, component_name=name)
+    annotation, state = _schema_to_type(state, schema, type_name, component_name=name)
+    if not _is_registered_type_name(state, type_name):
+        state = _with_alias(state, TypeAliasDef(name=type_name, annotation=annotation))
     return type_name, state
 
 

openapi_python/generator/render.py

@@ -109,6 +109,36 @@ def _typed_dict_dependencies(defn: TypedDictDef, names: set[str]) -> set[str]:
     return dependencies
 
 
+def _alias_dependencies(defn: TypeAliasDef, names: set[str]) -> set[str]:
+    return {
+        name
+        for name in names
+        if name != defn.name and re.search(rf"\b{re.escape(name)}\b", defn.annotation)
+    }
+
+
+def _order_aliases(defns: tuple[TypeAliasDef, ...]) -> list[TypeAliasDef]:
+    by_name = {item.name: item for item in defns}
+    names = set(by_name)
+    ordered: list[TypeAliasDef] = []
+    temporary: set[str] = set()
+    permanent: set[str] = set()
+
+    def visit(name: str) -> None:
+        if name in permanent or name in temporary:
+            return
+        temporary.add(name)
+        for dependency in sorted(_alias_dependencies(by_name[name], names)):
+            visit(dependency)
+        temporary.remove(name)
+        permanent.add(name)
+        ordered.append(by_name[name])
+
+    for name in sorted(by_name):
+        visit(name)
+    return ordered
+
+
 def _order_typeddicts(defns: tuple[TypedDictDef, ...]) -> list[TypedDictDef]:
     by_name = {item.name: item for item in defns}
     names = set(by_name)
@@ -205,7 +235,7 @@ def _fallback_method_block(
 def _render_types(spec: NormalizedSpec) -> str:
     blocks = (
         [_format_enum(item) for item in spec.enums]
-        + [_format_alias(alias) for alias in spec.aliases]
+        + [_format_alias(alias) for alias in _order_aliases(spec.aliases)]
         + [_format_typeddict(item) for item in _order_typeddicts(spec.typed_dicts)]
     )
     return _render_template(

tests/contract/component_union_alias/generate.py

@@ -0,0 +1,77 @@
+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": "Component union alias", "version": "1.0.0"},
+    "paths": {
+        "/check": {
+            "post": {
+                "requestBody": {
+                    "required": True,
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "$ref": "#/components/schemas/UserFGACheckRequest"
+                            }
+                        }
+                    },
+                },
+                "responses": {
+                    "200": {
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/UserFGACheckRequest"
+                                }
+                            }
+                        }
+                    }
+                },
+            }
+        }
+    },
+    "components": {
+        "schemas": {
+            "FGAObjectType": {
+                "anyOf": [
+                    {"type": "string", "enum": ["user", "sensor", "organization"]},
+                    {"type": "string"},
+                ]
+            },
+            "FGARelation": {
+                "anyOf": [
+                    {"type": "string", "enum": ["owner", "member", "can_read"]},
+                    {"type": "string"},
+                ]
+            },
+            "UserFGACheckRequest": {
+                "type": "object",
+                "properties": {
+                    "relation": {"$ref": "#/components/schemas/FGARelation"},
+                    "object_type": {"$ref": "#/components/schemas/FGAObjectType"},
+                    "object_id": {"type": "string"},
+                },
+                "required": ["relation", "object_type", "object_id"],
+            },
+        }
+    },
+}
+
+
+def main() -> None:
+    generate_client(
+        GenerationRequest(
+            output_dir=Path(__file__).parent / "generated",
+            spec_json=json.dumps(SPEC),
+            overwrite=True,
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()

tests/contract/component_union_alias/pyrightconfig.json

@@ -0,0 +1,15 @@
+{
+  "include": [
+    "."
+  ],
+  "exclude": [
+    "generated"
+  ],
+  "typeCheckingMode": "standard",
+  "reportMissingImports": true,
+  "reportUnusedVariable": true,
+  "reportOptionalSubscript": true,
+  "reportOptionalMemberAccess": true,
+  "reportOptionalCall": true,
+  "pythonVersion": "3.12"
+}

tests/contract/component_union_alias/usage_async.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import assert_type
+
+from generated.my_client import AsyncClient
+from generated.my_client.types import FGAObjectType, FGARelation, UserFGACheckRequest
+
+async_client = AsyncClient(base_url="http://testserver")
+
+
+async def use_async_client() -> None:
+    body: UserFGACheckRequest = {
+        "relation": "owner",
+        "object_type": "sensor",
+        "object_id": "sensor-1",
+    }
+    assert_type(body["relation"], FGARelation)
+    assert_type(body["object_type"], FGAObjectType)
+
+    response = await async_client.post("/check")(body=body)
+    assert_type(response, UserFGACheckRequest)
+    assert_type(response["relation"], FGARelation)
+    assert_type(response["object_type"], FGAObjectType)

tests/contract/component_union_alias/usage_sync.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from typing import assert_type
+
+from generated.my_client import Client
+from generated.my_client.types import FGAObjectType, FGARelation, UserFGACheckRequest
+
+client = Client(base_url="http://testserver")
+
+body: UserFGACheckRequest = {
+    "relation": "owner",
+    "object_type": "sensor",
+    "object_id": "sensor-1",
+}
+assert_type(body["relation"], FGARelation)
+assert_type(body["object_type"], FGAObjectType)
+
+response = client.post("/check")(body=body)
+assert_type(response, UserFGACheckRequest)
+assert_type(response["relation"], FGARelation)
+assert_type(response["object_type"], FGAObjectType)