alt-stack-openapi-pydantic 1.6.2__py3-none-any.whl

alt_stack_openapi_pydantic/emission.py

@@ -0,0 +1,725 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .dependencies import topological_sort_schemas
+from .lowering import LoweringContext, NamedSchema, lower_named_schema
+from .rendering import (
+    RenderContext,
+    decode_component_ref,
+    extra_field_annotation,
+    is_object_model_schema,
+    root_model_annotation,
+    schema_to_type_expr,
+)
+from .routes import (
+    RouteInfo,
+    build_route_path_name,
+    build_route_schema_name,
+    generate_route_schema_names,
+    parse_openapi_paths,
+)
+from .schema_dedup import (
+    NamedSchema as DedupNamedSchema,
+)
+from .schema_dedup import (
+    create_schema_registry,
+    find_common_schemas,
+    get_schema_fingerprint,
+    pre_register_schema,
+    register_schema,
+)
+from .types import AnySchema
+
+_VALID_IDENTIFIER_CHARS = set("_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789")
+
+
+@dataclass(slots=True)
+class EmissionState:
+    render_context: RenderContext = field(default_factory=RenderContext)
+    rebuild_names: list[str] = field(default_factory=list)
+
+
+def openapi_to_pydantic_code(
+    openapi: dict[str, Any],
+    custom_import_lines: list[str] | None = None,
+    options: dict[str, Any] | None = None,
+) -> str:
+    include_routes = bool(options.get("include_routes") if options else False)
+    components = openapi.get("components")
+    schemas = components.get("schemas") if isinstance(components, dict) else {}
+    if not isinstance(schemas, dict):
+        schemas = {}
+
+    lowering_context = LoweringContext(set(schemas.keys()))
+    lowered_components: list[NamedSchema] = []
+    for name in topological_sort_schemas(schemas):
+        schema = schemas.get(name)
+        if schema is None:
+            continue
+        lowered_components.extend(lower_named_schema(lowering_context, name, schema))
+
+    lines = _build_module_preamble(custom_import_lines)
+    state = EmissionState()
+    registry = create_schema_registry()
+
+    for named_schema in lowered_components:
+        lines.extend(_emit_named_schema(named_schema.name, named_schema.schema, state))
+        pre_register_schema(
+            registry,
+            named_schema.name,
+            get_schema_fingerprint(named_schema.schema),
+        )
+
+    if include_routes:
+        routes = parse_openapi_paths(openapi)
+        if routes:
+            route_lines, schema_name_to_canonical = _emit_route_schemas(
+                routes,
+                lowering_context,
+                registry,
+                state,
+            )
+            if route_lines:
+                lines.append("# Route Schemas")
+                lines.extend(route_lines)
+                lines.append("")
+
+            lines.extend(_emit_model_rebuilds(state.rebuild_names))
+            if route_lines:
+                lines.append("")
+            lines.extend(_generate_request_response_objects(routes, schema_name_to_canonical))
+            return _finalize_module(lines)
+
+    lines.extend(_emit_model_rebuilds(state.rebuild_names))
+    return _finalize_module(lines)
+
+
+_ALL_OF_HELPER = [
+    "def all_of(*types: Any) -> Any:",
+    "    adapters = [TypeAdapter(t) for t in types]",
+    "",
+    "    def validate(value: Any) -> Any:",
+    "        for adapter in adapters:",
+    "            adapter.validate_python(value)",
+    "        return value",
+    "",
+    "    return Annotated[Any, BeforeValidator(validate)]",
+    "",
+]
+
+
+def _finalize_module(lines: list[str]) -> str:
+    """Inline the ``all_of`` intersection helper when the module uses it.
+
+    Generated modules depend only on pydantic and ``alt_stack_http_client_httpx`` at runtime,
+    not on the generator package.
+    """
+    anchor = "_omit_not_null = BeforeValidator(_reject_explicit_none)"
+    if any("all_of(" in line for line in lines) and anchor in lines:
+        index = lines.index(anchor) + 1
+        lines[index:index] = ["", *_ALL_OF_HELPER[:-1]]
+    return "\n".join(lines)
+
+
+def _build_module_preamble(custom_import_lines: list[str] | None) -> list[str]:
+    lines = [
+        "# This file was automatically generated from OpenAPI schema",
+        "# Do not manually edit this file",
+        "from __future__ import annotations",
+        "",
+        "from typing import Any, Annotated, Final, Literal, Optional, TypedDict, Union",
+        "from typing import cast, overload",
+        "from datetime import date, datetime",
+        "from uuid import UUID",
+        "",
+        "from pydantic import BaseModel, BeforeValidator, ConfigDict, Field, RootModel",
+        "from pydantic import TypeAdapter",
+        "from pydantic import AnyUrl, EmailStr",
+        "import alt_stack_http_client_httpx as _client",
+        "",
+        "def _reject_explicit_none(value: Any) -> Any:",
+        "    if value is None:",
+        '        raise ValueError("Field may be omitted but may not be null")',
+        "    return value",
+        "",
+        "_omit_not_null = BeforeValidator(_reject_explicit_none)",
+        "",
+    ]
+    if custom_import_lines:
+        lines.extend(custom_import_lines)
+        lines.append("")
+    return lines
+
+
+def _emit_named_schema(name: str, schema: AnySchema, state: EmissionState) -> list[str]:
+    if is_object_model_schema(schema) and not _has_root_model_allof_base(schema, state):
+        return _emit_object_model(name, schema, state)
+    return _emit_root_model(name, schema, state)
+
+
+def _has_root_model_allof_base(schema: AnySchema, state: EmissionState) -> bool:
+    if not isinstance(schema, dict):
+        return False
+    all_of = schema.get("allOf")
+    if not isinstance(all_of, list):
+        return False
+    return any(
+        isinstance(part, dict)
+        and isinstance(part.get("$ref"), str)
+        and decode_component_ref(part["$ref"]) in state.render_context.root_model_names
+        for part in all_of
+    )
+
+
+def _emit_object_model(name: str, schema: AnySchema, state: EmissionState) -> list[str]:
+    all_of = schema.get("allOf") if isinstance(schema, dict) else None
+    if isinstance(all_of, list):
+        base_classes, merged_schema = _merge_allof_object_schema(all_of)
+        model_lines = _build_model_lines(name, merged_schema, base_classes=base_classes or None)
+        model_lines.insert(1, f"    __openapi_allof__ = {all_of!r}")
+    else:
+        model_lines = _build_model_lines(name, schema)
+
+    state.rebuild_names.append(name)
+    return [*model_lines, ""]
+
+
+def _emit_root_model(name: str, schema: AnySchema, state: EmissionState) -> list[str]:
+    state.render_context.root_model_names.add(name)
+    type_expr = schema_to_type_expr(schema, context=state.render_context)
+    state.rebuild_names.append(name)
+    return [
+        f"class {name}({root_model_annotation(type_expr)}):",
+        "    pass",
+        "",
+    ]
+
+
+def _merge_allof_object_schema(all_of: list[Any]) -> tuple[list[str], dict[str, Any]]:
+    base_classes: list[str] = []
+    inline_properties: dict[str, Any] = {}
+    inline_required: list[str] = []
+    additional_properties: Any = None
+
+    for part in all_of:
+        if not isinstance(part, dict):
+            continue
+        if isinstance(part.get("$ref"), str):
+            base_classes.append(decode_component_ref(part["$ref"]))
+            continue
+
+        if part.get("type") == "object" or "properties" in part:
+            props = part.get("properties")
+            if isinstance(props, dict):
+                inline_properties.update(props)
+
+            required = part.get("required")
+            if isinstance(required, list):
+                for item in required:
+                    if item not in inline_required:
+                        inline_required.append(item)
+
+            additional = part.get("additionalProperties")
+            if additional is False:
+                additional_properties = False
+            elif isinstance(additional, dict):
+                additional_properties = additional
+
+    merged_schema: dict[str, Any] = {
+        "type": "object",
+        "properties": inline_properties,
+        "required": inline_required,
+    }
+    if additional_properties is not None:
+        merged_schema["additionalProperties"] = additional_properties
+    return base_classes, merged_schema
+
+
+def _build_model_lines(
+    name: str,
+    schema: AnySchema,
+    *,
+    base_classes: list[str] | None = None,
+) -> list[str]:
+    properties = schema.get("properties") if isinstance(schema, dict) else None
+    required = set(schema.get("required", [])) if isinstance(schema, dict) else set()
+    additional = schema.get("additionalProperties") if isinstance(schema, dict) else None
+
+    bases = base_classes or ["BaseModel"]
+    lines = [f"class {name}({', '.join(bases)}):"]
+
+    alias_used = False
+    field_lines: list[str] = []
+    used_names: set[str] = set()
+
+    if isinstance(properties, dict):
+        for prop_name, prop_schema in properties.items():
+            attr_name = _dedupe_name(_sanitize_identifier(prop_name), used_names)
+            alias = prop_name if attr_name != prop_name else None
+            if alias:
+                alias_used = True
+
+            type_expr = schema_to_type_expr(prop_schema)
+            is_required = prop_name in required
+            if is_required:
+                default_expr = f" = Field(alias={alias!r})" if alias else ""
+            else:
+                if not isinstance(prop_schema, dict) or prop_schema.get("nullable") is not True:
+                    type_expr = f"Annotated[Optional[{type_expr}], _omit_not_null]"
+                default_expr = f" = Field(default=None, alias={alias!r})" if alias else " = None"
+
+            field_lines.append(f"    {attr_name}: {type_expr}{default_expr}")
+
+    config_args: list[str] = []
+    extra_line: str | None = None
+    if alias_used:
+        config_args.append("populate_by_name=True")
+
+    if additional is False:
+        config_args.append("extra='forbid'")
+    elif additional is True or additional is None:
+        config_args.append("extra='allow'")
+    elif isinstance(additional, dict):
+        config_args.append("extra='allow'")
+        extra_type = schema_to_type_expr(additional)
+        extra_line = (
+            f"    __pydantic_extra__: {extra_field_annotation(extra_type)} = Field(init=False)"
+        )
+
+    if config_args:
+        lines.append(f"    model_config = ConfigDict({', '.join(config_args)})")
+    if extra_line:
+        lines.append(extra_line)
+
+    if field_lines:
+        lines.extend(field_lines)
+    elif len(lines) == 1:
+        lines.append("    pass")
+
+    return lines
+
+
+def _emit_model_rebuilds(names: list[str]) -> list[str]:
+    if not names:
+        return []
+    return [*(f"{name}.model_rebuild()" for name in names), ""]
+
+
+def _emit_route_schemas(
+    routes: list[RouteInfo],
+    lowering_context: LoweringContext,
+    registry: Any,
+    state: EmissionState,
+) -> tuple[list[str], dict[str, str]]:
+    lines: list[str] = []
+    route_named_schemas: list[NamedSchema] = []
+
+    schema_name_to_canonical: dict[str, str] = {}
+
+    def register_named_schema_batch(named_schemas: list[NamedSchema]) -> None:
+        local_canonical: dict[str, str] = {}
+        for named_schema in named_schemas:
+            canonical_schema = _rewrite_schema_refs(named_schema.schema, local_canonical)
+            result = register_schema(registry, named_schema.name, canonical_schema)
+            schema_name_to_canonical[named_schema.name] = result.canonical_name
+            local_canonical[named_schema.name] = result.canonical_name
+            if result.is_new:
+                route_named_schemas.append(
+                    NamedSchema(name=named_schema.name, schema=canonical_schema)
+                )
+
+    for common in find_common_schemas(_collect_route_schemas(routes), 2):
+        if common.fingerprint in registry.fingerprint_to_name:
+            continue
+        register_named_schema_batch(
+            lower_named_schema(lowering_context, common.name, common.schema)
+        )
+
+    def register_route_schema(name: str, schema: AnySchema) -> None:
+        if _route_schema_ref_target(schema):
+            return
+        register_named_schema_batch(lower_named_schema(lowering_context, name, schema))
+
+    for route in routes:
+        names = generate_route_schema_names(route)
+        path_params = [p for p in route.parameters if p.location == "path"]
+        query_params = [p for p in route.parameters if p.location == "query"]
+        header_params = [p for p in route.parameters if p.location == "header"]
+
+        if names.params_schema_name and path_params:
+            register_route_schema(
+                names.params_schema_name,
+                _build_openapi_object_schema(
+                    [{"name": p.name, "schema": p.schema, "required": True} for p in path_params]
+                ),
+            )
+
+        if names.query_schema_name and query_params:
+            register_route_schema(
+                names.query_schema_name,
+                _build_openapi_object_schema(
+                    [
+                        {"name": p.name, "schema": p.schema, "required": p.required}
+                        for p in query_params
+                    ]
+                ),
+            )
+
+        if names.headers_schema_name and header_params:
+            register_route_schema(
+                names.headers_schema_name,
+                _build_openapi_object_schema(
+                    [
+                        {"name": p.name, "schema": p.schema, "required": p.required}
+                        for p in header_params
+                    ]
+                ),
+            )
+
+        if names.body_schema_name and route.request_body is not None:
+            register_route_schema(names.body_schema_name, route.request_body)
+
+        for status_code, response_schema in route.responses.items():
+            if not response_schema:
+                continue
+            suffix = "Response" if status_code.startswith("2") else "ErrorResponse"
+            register_route_schema(
+                build_route_schema_name(route.path, route.method, f"{status_code}{suffix}"),
+                response_schema,
+            )
+
+    for named_schema in route_named_schemas:
+        lines.extend(_emit_named_schema(named_schema.name, named_schema.schema, state))
+
+    return lines, schema_name_to_canonical
+
+
+def _collect_route_schemas(routes: list[RouteInfo]) -> list[DedupNamedSchema]:
+    collected: list[DedupNamedSchema] = []
+    for route in routes:
+        for status_code, response_schema in route.responses.items():
+            if not response_schema:
+                continue
+            suffix = "Response" if status_code.startswith("2") else "ErrorResponse"
+            collected.append(
+                {
+                    "name": build_route_schema_name(
+                        route.path,
+                        route.method,
+                        f"{status_code}{suffix}",
+                    ),
+                    "schema": response_schema,
+                }
+            )
+    return collected
+
+
+RouteMap = dict[str, dict[str, dict[str, str]]]
+"""path -> METHOD -> request part or status code -> model class name."""
+
+
+def _generate_request_response_objects(
+    routes: list[RouteInfo],
+    schema_name_to_canonical: dict[str, str],
+) -> list[str]:
+    request_paths: RouteMap = {}
+    response_paths: RouteMap = {}
+
+    def resolve_schema_name(name: str, schema: AnySchema) -> str:
+        ref_target = _route_schema_ref_target(schema)
+        if ref_target:
+            return ref_target
+        return schema_name_to_canonical.get(name, name)
+
+    for route in routes:
+        names = generate_route_schema_names(route)
+        path_params = [p for p in route.parameters if p.location == "path"]
+        query_params = [p for p in route.parameters if p.location == "query"]
+        header_params = [p for p in route.parameters if p.location == "header"]
+
+        request_parts: dict[str, str] = {}
+
+        if names.params_schema_name and path_params:
+            schema = _build_openapi_object_schema(
+                [{"name": p.name, "schema": p.schema, "required": True} for p in path_params]
+            )
+            request_parts["params"] = resolve_schema_name(names.params_schema_name, schema)
+
+        if names.query_schema_name and query_params:
+            schema = _build_openapi_object_schema(
+                [{"name": p.name, "schema": p.schema, "required": p.required} for p in query_params]
+            )
+            request_parts["query"] = resolve_schema_name(names.query_schema_name, schema)
+
+        if names.headers_schema_name and header_params:
+            schema = _build_openapi_object_schema(
+                [
+                    {"name": p.name, "schema": p.schema, "required": p.required}
+                    for p in header_params
+                ]
+            )
+            request_parts["headers"] = resolve_schema_name(names.headers_schema_name, schema)
+
+        if names.body_schema_name and route.request_body is not None:
+            request_parts["body"] = resolve_schema_name(names.body_schema_name, route.request_body)
+
+        # Bare methods keep an empty entry so `Request[path][METHOD]` is a closed,
+        # statically known shape, matching the TypeScript `as const` maps.
+        request_paths.setdefault(route.path, {})[route.method] = request_parts
+
+        response_statuses: dict[str, str] = {}
+        for status_code, response_schema in route.responses.items():
+            if not response_schema:
+                continue
+            suffix = "Response" if status_code.startswith("2") else "ErrorResponse"
+            schema_name = build_route_schema_name(
+                route.path,
+                route.method,
+                f"{status_code}{suffix}",
+            )
+            response_statuses[status_code] = resolve_schema_name(schema_name, response_schema)
+        response_paths.setdefault(route.path, {})[route.method] = response_statuses
+
+    used_type_names: set[str] = set()
+    lines = _emit_route_map("Request", request_paths, used_type_names)
+    lines.append("")
+    lines.extend(_emit_route_map("Response", response_paths, used_type_names))
+    lines.append("")
+    lines.extend(_emit_typed_client(request_paths, response_paths))
+    return lines
+
+
+def _emit_route_map(name: str, paths: RouteMap, used_type_names: set[str]) -> list[str]:
+    """Emit a closed ``TypedDict`` shape for a route map plus its runtime dictionary.
+
+    Every level of the map gets its own ``TypedDict`` so a type checker resolves
+    ``Map[path][METHOD][key]`` to the exact ``type[Model]`` and rejects keys that are
+    not in the OpenAPI document. The runtime value stays a plain nested ``dict``.
+    """
+    lines: list[str] = []
+    path_type_names: dict[str, str] = {}
+
+    for path, methods in paths.items():
+        method_type_names: dict[str, str] = {}
+        for method, leaves in methods.items():
+            leaf_type_name = _dedupe_name(
+                f"_{build_route_schema_name(path, method, name)}", used_type_names
+            )
+            method_type_names[method] = leaf_type_name
+            lines.extend(
+                _emit_typed_dict(
+                    leaf_type_name,
+                    {key: f"type[{model_name}]" for key, model_name in leaves.items()},
+                )
+            )
+
+        path_type_name = _dedupe_name(
+            f"_{build_route_path_name(path)}{name}Methods", used_type_names
+        )
+        path_type_names[path] = path_type_name
+        lines.extend(_emit_typed_dict(path_type_name, method_type_names))
+
+    map_type_name = _dedupe_name(f"_{name}Map", used_type_names)
+    lines.extend(_emit_typed_dict(map_type_name, path_type_names))
+    lines.append("")
+
+    lines.append(f"{name}: Final[{map_type_name}] = {{")
+    for path, methods in paths.items():
+        lines.append(f"    {path!r}: {{")
+        for method, leaves in methods.items():
+            if not leaves:
+                lines.append(f"        {method!r}: {{}},")
+                continue
+            lines.append(f"        {method!r}: {{")
+            for key, model_name in leaves.items():
+                lines.append(f"            {key!r}: {model_name},")
+            lines.append("        },")
+        lines.append("    },")
+    lines.append("}")
+    return lines
+
+
+_CLIENT_METHOD_ORDER = ("GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS")
+
+
+def _emit_typed_client(request_paths: RouteMap, response_paths: RouteMap) -> list[str]:
+    """Emit ``{Method}{Path}Result`` unions and an ``ApiClient`` with typed route methods.
+
+    Python cannot derive a call signature from the ``TypedDict`` maps the way TypeScript
+    maps over ``typeof Request``, so each route gets an explicit ``Literal`` path overload
+    carrying its exact request models and result union. Methods with a single route are
+    emitted as a plain typed signature because a lone ``@overload`` is invalid.
+    """
+    lines: list[str] = ["# Typed Client"]
+    routes_by_method: dict[str, list[tuple[str, dict[str, str], str]]] = {}
+
+    for path, methods in request_paths.items():
+        for method, parts in methods.items():
+            result_name = build_route_schema_name(path, method, "Result")
+            statuses = response_paths.get(path, {}).get(method, {})
+            lines.extend(_emit_result_alias(result_name, statuses))
+            routes_by_method.setdefault(method, []).append((path, parts, result_name))
+
+    lines.append("")
+    lines.append("# Typed route methods; construct HttpxApiClient(url, request_map=Request,")
+    lines.append("# response_map=Response) or ApiClient(url, transport=..., request_map=..., ...).")
+    lines.append("class ApiClient(_client.BaseApiClient):")
+    for index, method in enumerate(m for m in _CLIENT_METHOD_ORDER if m in routes_by_method):
+        if index:
+            lines.append("")
+        lines.extend(_emit_client_method(method, routes_by_method[method]))
+
+    lines.append("")
+    lines.append("class HttpxApiClient(ApiClient, _client.HttpxApiClient):")
+    lines.append("    pass")
+    return lines
+
+
+def _emit_result_alias(result_name: str, statuses: dict[str, str]) -> list[str]:
+    members: list[str] = []
+    for status_code, model_name in statuses.items():
+        result_class = "ApiSuccess" if status_code.startswith("2") else "ApiFailure"
+        members.append(f"_client.{result_class}[Literal[{status_code!r}], {model_name}]")
+    if not any(status_code.startswith("2") for status_code in statuses):
+        # No documented 2xx body (for example 204): success carries the raw payload.
+        members.append("_client.ApiSuccess[str, Any]")
+    members.append("_client.ApiUnexpectedError")
+    return [f"{result_name} = Union[", *(f"    {member}," for member in members), "]"]
+
+
+def _emit_client_method(method: str, routes: list[tuple[str, dict[str, str], str]]) -> list[str]:
+    method_name = method.lower()
+    lines: list[str] = []
+
+    if len(routes) == 1:
+        path, parts, result_name = routes[0]
+        lines.extend(_emit_route_signature(method_name, path, parts, result_name, overload=False))
+        forwarded = ", ".join(f"{key}={key}" for key in parts if key != "headers")
+        call_args = ", ".join(filter(None, [f"{method!r}", "path", forwarded, "options=options"]))
+        lines.append("        return cast(")
+        lines.append(f"            {result_name},")
+        lines.append(f"            await self.request({call_args}),")
+        lines.append("        )")
+        return lines
+
+    for path, parts, result_name in routes:
+        lines.extend(_emit_route_signature(method_name, path, parts, result_name, overload=True))
+        lines.append("")
+    lines.append(f"    async def {method_name}(")
+    lines.append("        self,")
+    lines.append("        path: str,")
+    lines.append("        *,")
+    lines.append("        params: Any = None,")
+    lines.append("        query: Any = None,")
+    lines.append("        body: Any = None,")
+    lines.append("        options: _client.RequestOptions | None = None,")
+    lines.append("    ) -> Any:")
+    lines.append("        return await self.request(")
+    lines.append(
+        f"            {method!r}, path, params=params, query=query, body=body, options=options"
+    )
+    lines.append("        )")
+    return lines
+
+
+def _emit_route_signature(
+    method_name: str,
+    path: str,
+    parts: dict[str, str],
+    result_name: str,
+    *,
+    overload: bool,
+) -> list[str]:
+    lines: list[str] = []
+    if overload:
+        lines.append("    @overload")
+    lines.append(f"    async def {method_name}(")
+    lines.append("        self,")
+    lines.append(f"        path: Literal[{path!r}],")
+    lines.append("        *,")
+    if "params" in parts:
+        lines.append(f"        params: {parts['params']},")
+    if "query" in parts:
+        lines.append(f"        query: {parts['query']} | None = None,")
+    if "body" in parts:
+        lines.append(f"        body: {parts['body']},")
+    lines.append("        options: _client.RequestOptions | None = None,")
+    lines.append(f"    ) -> {result_name}:{' ...' if overload else ''}")
+    return lines
+
+
+def _emit_typed_dict(type_name: str, fields: dict[str, str]) -> list[str]:
+    if not fields:
+        return [f"{type_name} = TypedDict({type_name!r}, {{}})"]
+    return [
+        f"{type_name} = TypedDict({type_name!r}, {{",
+        *(f"    {key!r}: {value}," for key, value in fields.items()),
+        "})",
+    ]
+
+
+def _build_openapi_object_schema(params: list[dict[str, Any]]) -> dict[str, Any]:
+    return {
+        "type": "object",
+        "properties": {param["name"]: param["schema"] for param in params},
+        "required": [param["name"] for param in params if param.get("required")],
+        "additionalProperties": False,
+    }
+
+
+def _route_schema_ref_target(schema: AnySchema) -> str | None:
+    if not isinstance(schema, dict):
+        return None
+    ref = schema.get("$ref")
+    if not isinstance(ref, str) or schema.get("nullable") is True:
+        return None
+    if set(schema.keys()) != {"$ref"}:
+        return None
+    return decode_component_ref(ref)
+
+
+def _rewrite_schema_refs(schema: AnySchema, aliases: dict[str, str]) -> AnySchema:
+    if not isinstance(schema, dict):
+        return schema
+
+    rewritten = dict(schema)
+    ref = rewritten.get("$ref")
+    if isinstance(ref, str):
+        name = decode_component_ref(ref)
+        canonical = aliases.get(name)
+        if canonical and canonical != name:
+            rewritten["$ref"] = f"#/components/schemas/{canonical}"
+
+    for key, value in list(rewritten.items()):
+        if isinstance(value, dict):
+            rewritten[key] = _rewrite_schema_refs(value, aliases)
+        elif isinstance(value, list):
+            rewritten[key] = [
+                _rewrite_schema_refs(item, aliases) if isinstance(item, dict) else item
+                for item in value
+            ]
+
+    return rewritten
+
+
+def _sanitize_identifier(name: str) -> str:
+    result = "".join(ch if ch in _VALID_IDENTIFIER_CHARS else "_" for ch in name)
+    if result and result[0].isupper() and result[1:].islower():
+        result = result[0].lower() + result[1:]
+    if not result or result[0].isdigit():
+        result = f"_{result}"
+    return f"{result}_" if result in {"class", "from", "global", "pass"} else result
+
+
+def _dedupe_name(name: str, used: set[str]) -> str:
+    if name not in used:
+        used.add(name)
+        return name
+    index = 2
+    while f"{name}_{index}" in used:
+        index += 1
+    deduped = f"{name}_{index}"
+    used.add(deduped)
+    return deduped