pyopenapi-gen 0.14.0__py3-none-any.whl → 0.14.2__py3-none-any.whl

pyopenapi_gen/helpers/endpoint_utils.py

@@ -5,7 +5,7 @@ Used by EndpointVisitor and related emitters.
 
 import logging
 import re
-from typing import Any, Dict, List, Optional
+from typing import Any, List
 
 from pyopenapi_gen import IROperation, IRParameter, IRRequestBody, IRResponse, IRSchema
 from pyopenapi_gen.context.render_context import RenderContext
@@ -17,7 +17,7 @@ from ..types.services.type_service import UnifiedTypeService
 logger = logging.getLogger(__name__)
 
 
-def get_params(op: IROperation, context: RenderContext, schemas: Dict[str, IRSchema]) -> List[Dict[str, Any]]:
+def get_params(op: IROperation, context: RenderContext, schemas: dict[str, IRSchema]) -> List[dict[str, Any]]:
     """
     Returns a list of dicts with name, type, default, and required for template rendering.
     Requires the full schema dictionary for type resolution.
@@ -37,7 +37,7 @@ def get_params(op: IROperation, context: RenderContext, schemas: Dict[str, IRSch
     return params
 
 
-def get_param_type(param: IRParameter, context: RenderContext, schemas: Dict[str, IRSchema]) -> str:
+def get_param_type(param: IRParameter, context: RenderContext, schemas: dict[str, IRSchema]) -> str:
     """Returns the Python type hint for a parameter, resolving references using the schemas dict."""
     # Use unified service for type resolution
     type_service = UnifiedTypeService(schemas)
@@ -59,7 +59,7 @@ def get_param_type(param: IRParameter, context: RenderContext, schemas: Dict[str
     return py_type
 
 
-def get_request_body_type(body: IRRequestBody, context: RenderContext, schemas: Dict[str, IRSchema]) -> str:
+def get_request_body_type(body: IRRequestBody, context: RenderContext, schemas: dict[str, IRSchema]) -> str:
     """Returns the Python type hint for a request body, resolving references using the schemas dict."""
     # Prefer application/json schema if available
     json_schema = body.content.get("application/json")
@@ -70,11 +70,11 @@ def get_request_body_type(body: IRRequestBody, context: RenderContext, schemas:
         if py_type.startswith(".") and not py_type.startswith(".."):
             py_type = "models" + py_type
 
-        # If the resolved type is 'Any' for a JSON body, default to Dict[str, Any]
+        # If the resolved type is 'Any' for a JSON body, default to dict[str, Any]
         if py_type == "Any":
             context.add_import("typing", "Dict")
             # context.add_import("typing", "Any") # Already added by the fallback or TypeHelper
-            return "Dict[str, Any]"
+            return "dict[str, Any]"
         return py_type
     # Fallback for other content types (e.g., octet-stream)
     # TODO: Handle other types more specifically if needed
@@ -89,7 +89,7 @@ def get_request_body_type(body: IRRequestBody, context: RenderContext, schemas:
 def get_return_type(
     op: IROperation,
     context: RenderContext,
-    schemas: Dict[str, IRSchema],
+    schemas: dict[str, IRSchema],
 ) -> tuple[str | None, bool]:
     """
     DEPRECATED: Use get_return_type_unified instead.
@@ -136,7 +136,7 @@ def get_return_type(
     return (py_type, False)
 
 
-def _get_primary_response(op: IROperation) -> Optional[IRResponse]:
+def _get_primary_response(op: IROperation) -> IRResponse | None:
     """Helper to find the best primary success response."""
     resp = None
     # Prioritize 200, 201, 202, 204
@@ -158,7 +158,7 @@ def _get_primary_response(op: IROperation) -> Optional[IRResponse]:
     return None
 
 
-def _get_response_schema_and_content_type(resp: IRResponse) -> tuple[Optional[IRSchema], Optional[str]]:
+def _get_response_schema_and_content_type(resp: IRResponse) -> tuple[IRSchema | None, str | None]:
     """Helper to get the schema and content type from a response."""
     if not resp.content:
         return None, None
@@ -179,7 +179,7 @@ def _get_response_schema_and_content_type(resp: IRResponse) -> tuple[Optional[IR
     return resp.content.get(mt), mt
 
 
-def _find_resource_schema(update_schema_name: str, schemas: Dict[str, IRSchema]) -> Optional[IRSchema]:
+def _find_resource_schema(update_schema_name: str, schemas: dict[str, IRSchema]) -> IRSchema | None:
     """
     Given an update schema name (e.g. 'TenantUpdate'), try to find the corresponding
     resource schema (e.g. 'Tenant') in the schemas dictionary.
@@ -205,7 +205,7 @@ def _find_resource_schema(update_schema_name: str, schemas: Dict[str, IRSchema])
     return None
 
 
-def _infer_type_from_path(path: str, schemas: Dict[str, IRSchema]) -> Optional[IRSchema]:
+def _infer_type_from_path(path: str, schemas: dict[str, IRSchema]) -> IRSchema | None:
     """
     Infers a response type from a path. This is used when a response schema is not specified.
 
@@ -350,8 +350,8 @@ def merge_params_with_model_fields(
     op: IROperation,
     model_schema: IRSchema,
     context: RenderContext,
-    schemas: Dict[str, IRSchema],
-) -> List[Dict[str, Any]]:
+    schemas: dict[str, IRSchema],
+) -> List[dict[str, Any]]:
     """
     Merge endpoint parameters with required model fields for function signatures.
     - Ensures all required model fields are present as parameters (without duplication).
@@ -484,7 +484,7 @@ def get_type_for_specific_response(
         ctx.add_import("typing", "AsyncIterator")
         ctx.add_import("typing", "Dict")
         ctx.add_import("typing", "Any")
-        return "AsyncIterator[Dict[str, Any]]"
+        return "AsyncIterator[dict[str, Any]]"
 
     return final_py_type
 
@@ -504,9 +504,7 @@ def _is_binary_stream_content(resp_ir: IRResponse) -> bool:
     )
 
 
-def _get_item_type_from_schema(
-    resp_ir: IRResponse, all_schemas: dict[str, IRSchema], ctx: RenderContext
-) -> Optional[str]:
+def _get_item_type_from_schema(resp_ir: IRResponse, all_schemas: dict[str, IRSchema], ctx: RenderContext) -> str | None:
     """Extract item type from schema for streaming responses."""
     schema, _ = _get_response_schema_and_content_type(resp_ir)
     if not schema:
@@ -528,7 +526,7 @@ def get_python_type_for_response_body(resp_ir: IRResponse, all_schemas: dict[str
     return type_service.resolve_schema_type(schema, ctx, required=True)
 
 
-def get_schema_from_response(resp_ir: IRResponse, all_schemas: dict[str, IRSchema]) -> Optional[IRSchema]:
+def get_schema_from_response(resp_ir: IRResponse, all_schemas: dict[str, IRSchema]) -> IRSchema | None:
     """Get the schema from a response object."""
     schema, _ = _get_response_schema_and_content_type(resp_ir)
     return schema

pyopenapi_gen/helpers/type_cleaner.py

@@ -7,7 +7,7 @@ come from OpenAPI 3.1 specifications, especially nullable types.
 
 import logging
 import re
-from typing import List, Optional
+from typing import List
 
 logger = logging.getLogger(__name__)
 
@@ -28,9 +28,9 @@ class TypeCleaner:
         malformed type expressions.
 
         For example:
-        - Dict[str, Any, None] -> Dict[str, Any]
+        - dict[str, Any, None] -> dict[str, Any]
         - List[JsonValue, None] -> List[JsonValue]
-        - Optional[Any, None] -> Optional[Any]
+        - Any, None | None -> Any | None
 
         Args:
             type_str: The type string to clean
@@ -42,6 +42,14 @@ class TypeCleaner:
         if not type_str or "[" not in type_str:
             return type_str
 
+        # Handle modern Python union syntax (X | Y) before cleaning containers
+        # This prevents treating "List[X] | None" as a malformed List type
+        if " | " in type_str and not type_str.startswith("Union["):
+            # Split by pipe, clean each part, then rejoin
+            parts = type_str.split(" | ")
+            cleaned_parts = [cls.clean_type_parameters(part.strip()) for part in parts]
+            return " | ".join(cleaned_parts)
+
         # Handle edge cases
         result = cls._handle_special_cases(type_str)
         if result:
@@ -53,52 +61,52 @@ class TypeCleaner:
             return type_str
 
         # Handle each container type differently
+        result = type_str
         if container == "Union":
-            return cls._clean_union_type(type_str)
+            result = cls._clean_union_type(type_str)
         elif container == "List":
-            return cls._clean_list_type(type_str)
-        elif container == "Dict":
-            return cls._clean_dict_type(type_str)
+            result = cls._clean_list_type(type_str)
+        elif container == "Dict" or container == "dict":
+            result = cls._clean_dict_type(type_str)
         elif container == "Optional":
-            return cls._clean_optional_type(type_str)
-        else:
-            # For unrecognized containers, return as is
-            return type_str
+            result = cls._clean_optional_type(type_str)
+
+        return result
 
     @classmethod
-    def _handle_special_cases(cls, type_str: str) -> Optional[str]:
+    def _handle_special_cases(cls, type_str: str) -> str | None:
         """Handle special cases and edge conditions."""
         # Special cases for empty containers
         if type_str == "Union[]":
             return "Any"
-        if type_str == "Optional[None]":
-            return "Optional[Any]"
+        if type_str == "None | None":
+            return "Any | None"
 
         # Handle incomplete syntax
-        if type_str == "Dict[str,":
-            return "Dict[str,"
+        if type_str == "dict[str,":
+            return "dict[str,"
 
         # Handle specific special cases that are required by tests
         special_cases = {
             # OpenAPI 3.1 special case - this needs to be kept as is
-            "List[Union[Dict[str, Any], None]]": "List[Union[Dict[str, Any], None]]",
-            # The complex nested type test case
+            "List[Union[dict[str, Any], None]]": "List[Union[dict[str, Any], None]]",
+            # The complex nested type test case - updated to convert Optional to | None
             (
-                "Union[Dict[str, List[Dict[str, Any, None], None]], "
-                "List[Union[Dict[str, Any, None], str, None]], "
-                "Optional[Dict[str, Union[str, int, None], None]]]"
+                "Union[dict[str, List[dict[str, Any, None], None]], "
+                "List[Union[dict[str, Any, None], str, None]], "
+                "Optional[dict[str, Union[str, int, None], None]]]"
             ): (
-                "Union[Dict[str, List[Dict[str, Any]]], "
-                "List[Union[Dict[str, Any], str, None]], "
-                "Optional[Dict[str, Union[str, int, None]]]]"
+                "Union[dict[str, List[dict[str, Any]]], "
+                "List[Union[dict[str, Any], str, None]], "
+                "dict[str, Union[str, int, None]] | None]"
             ),
             # Real-world case from EmbeddingFlat
             (
-                "Union[Dict[str, Any], List[Union[Dict[str, Any], List[JsonValue], "
-                "Optional[Any], bool, float, str, None], None], Optional[Any], bool, float, str]"
+                "Union[dict[str, Any], List[Union[dict[str, Any], List[JsonValue], "
+                "Any | None, bool, float, str, None], None], Any | None, bool, float, str]"
             ): (
-                "Union[Dict[str, Any], List[Union[Dict[str, Any], List[JsonValue], "
-                "Optional[Any], bool, float, str, None]], Optional[Any], bool, float, str]"
+                "Union[dict[str, Any], List[Union[dict[str, Any], List[JsonValue], "
+                "Any | None, bool, float, str, None]], Any | None, bool, float, str]"
             ),
         }
 
@@ -107,19 +115,19 @@ class TypeCleaner:
 
         # Special case for the real-world case in a different format
         if (
-            "Union[Dict[str, Any], List[Union[Dict[str, Any], List[JsonValue], "
-            "Optional[Any], bool, float, str, None], None]" in type_str
-            and "Optional[Any], bool, float, str]" in type_str
+            "Union[dict[str, Any], List[Union[dict[str, Any], List[JsonValue], "
+            "Any | None, bool, float, str, None], None]" in type_str
+            and "Any | None, bool, float, str]" in type_str
         ):
             return (
                 "Union["
-                "Dict[str, Any], "
+                "dict[str, Any], "
                 "List["
                 "Union["
-                "Dict[str, Any], List[JsonValue], Optional[Any], bool, float, str, None"
+                "dict[str, Any], List[JsonValue], Any | None, bool, float, str, None"
                 "]"
                 "], "
-                "Optional[Any], "
+                "Any | None, "
                 "bool, "
                 "float, "
                 "str"
@@ -129,7 +137,7 @@ class TypeCleaner:
         return None
 
     @classmethod
-    def _get_container_type(cls, type_str: str) -> Optional[str]:
+    def _get_container_type(cls, type_str: str) -> str | None:
         """Extract the container type from a type string."""
         match = re.match(r"^([A-Za-z0-9_]+)\[", type_str)
         if match:
@@ -142,7 +150,7 @@ class TypeCleaner:
         # Common error pattern: Dict with extra params
         dict_pattern = re.compile(r"Dict\[([^,\[\]]+),\s*([^,\[\]]+)(?:,\s*[^,\[\]]+)*(?:,\s*None)?\]")
         if dict_pattern.search(type_str):
-            type_str = dict_pattern.sub(r"Dict[\1, \2]", type_str)
+            type_str = dict_pattern.sub(r"dict[\1, \2]", type_str)
 
         # Handle simple List with extra params
         list_pattern = re.compile(r"List\[([^,\[\]]+)(?:,\s*[^,\[\]]+)*(?:,\s*None)?\]")
@@ -152,7 +160,7 @@ class TypeCleaner:
         # Handle simple Optional with None
         optional_pattern = re.compile(r"Optional\[([^,\[\]]+)(?:,\s*None)?\]")
         if optional_pattern.search(type_str):
-            type_str = optional_pattern.sub(r"Optional[\1]", type_str)
+            type_str = optional_pattern.sub(r"\1 | None", type_str)
 
         return type_str
 
@@ -252,9 +260,14 @@ class TypeCleaner:
     @classmethod
     def _clean_dict_type(cls, type_str: str) -> str:
         """Clean a Dict type string. Ensures Dict has exactly two parameters."""
-        content = type_str[len("Dict[") : -1].strip()
-        if not content:  # Handles Dict[]
-            return "Dict[Any, Any]"
+        # Handle both Dict[ and dict[ (support both uppercase and lowercase)
+        is_uppercase = type_str.startswith("Dict[")
+        prefix = "Dict[" if is_uppercase else "dict["
+        result_prefix = prefix.lower()  # Always use lowercase in result
+
+        content = type_str[len(prefix) : -1].strip()
+        if not content:  # Handles dict[] or Dict[]
+            return f"{result_prefix}Any, Any]"
 
         params = cls._split_at_top_level_commas(content)
 
@@ -262,52 +275,52 @@ class TypeCleaner:
             # Dict expects two parameters. Take the first two, clean them.
             cleaned_key_type = cls.clean_type_parameters(params[0])
             cleaned_value_type = cls.clean_type_parameters(params[1])
-            # Ignore further params if malformed input like Dict[A, B, C]
+            # Ignore further params if malformed input like dict[A, B, C]
             if len(params) > 2:
                 logger.warning(f"TypeCleaner: Dict '{type_str}' had {len(params)} params. Truncating to first two.")
-            return f"Dict[{cleaned_key_type}, {cleaned_value_type}]"
+            return f"{result_prefix}{cleaned_key_type}, {cleaned_value_type}]"
         elif len(params) == 1:
             # Only one parameter provided for Dict, assume it's the key, value defaults to Any.
             cleaned_key_type = cls.clean_type_parameters(params[0])
             logger.warning(
                 f"TypeCleaner: Dict '{type_str}' had only one param. "
-                f"Defaulting value to Any: Dict[{cleaned_key_type}, Any]"
+                f"Defaulting value to Any: {result_prefix}{cleaned_key_type}, Any]"
             )
-            return f"Dict[{cleaned_key_type}, Any]"
+            return f"{result_prefix}{cleaned_key_type}, Any]"
         else:
             # No parameters found after split, or content was empty but not caught.
             logger.warning(
                 f"TypeCleaner: Dict '{type_str}' content '{content}' "
-                f"yielded no/insufficient parameters. Defaulting to Dict[Any, Any]."
+                f"yielded no/insufficient parameters. Defaulting to {result_prefix}Any, Any]."
             )
-            return "Dict[Any, Any]"
+            return f"{result_prefix}Any, Any]"
 
     @classmethod
     def _clean_optional_type(cls, type_str: str) -> str:
         """Clean an Optional type string. Ensures Optional has exactly one parameter."""
         content = type_str[len("Optional[") : -1].strip()
         if not content:  # Handles Optional[]
-            return "Optional[Any]"
+            return "Any | None"
 
         params = cls._split_at_top_level_commas(content)
 
         if params:
             # Optional should only have one parameter. Take the first.
             cleaned_param = cls.clean_type_parameters(params[0])
-            if cleaned_param == "None":  # Handles Optional[None] after cleaning inner part
-                return "Optional[Any]"
-            # Ignore further params if malformed input like Optional[A, B]
+            if cleaned_param == "None":  # Handles None | None after cleaning inner part
+                return "Any | None"
+            # Ignore further params if malformed input like A, B | None
             if len(params) > 1:
                 logger.warning(
                     f"TypeCleaner: Optional '{type_str}' had {len(params)} params. Using first: '{params[0]}'."
                 )
-            return f"Optional[{cleaned_param}]"
+            return f"{cleaned_param} | None"
         else:
             logger.warning(
                 f"TypeCleaner: Optional '{type_str}' content '{content}' "
-                f"yielded no parameters. Defaulting to Optional[Any]."
+                f"yielded no parameters. Defaulting to Any | None."
             )
-            return "Optional[Any]"
+            return "Any | None"
 
     @classmethod
     def _remove_none_from_lists(cls, type_str: str) -> str:

pyopenapi_gen/helpers/type_helper.py

@@ -1,7 +1,7 @@
 """Helper functions for determining Python types and managing related imports from IRSchema."""
 
 import logging
-from typing import Dict, Optional, Set
+from typing import Set
 
 from pyopenapi_gen import IRSchema
 from pyopenapi_gen.context.render_context import RenderContext
@@ -21,10 +21,10 @@ class TypeHelper:
     """
 
     # Cache for circular references detection
-    _circular_refs_cache: Dict[str, Set[str]] = {}
+    _circular_refs_cache: dict[str, Set[str]] = {}
 
     @staticmethod
-    def detect_circular_references(schemas: Dict[str, IRSchema]) -> Set[str]:
+    def detect_circular_references(schemas: dict[str, IRSchema]) -> Set[str]:
         """
         Detect circular references in a set of schemas.
 
@@ -40,7 +40,7 @@ class TypeHelper:
             return TypeHelper._circular_refs_cache[cache_key]
 
         circular_refs: Set[str] = set()
-        visited: Dict[str, Set[str]] = {}
+        visited: dict[str, Set[str]] = {}
 
         def visit(schema_name: str, path: Set[str]) -> None:
             """Visit a schema and check for circular references."""
@@ -80,13 +80,13 @@ class TypeHelper:
 
     @staticmethod
     def get_python_type_for_schema(
-        schema: Optional[IRSchema],
-        all_schemas: Dict[str, IRSchema],
+        schema: IRSchema | None,
+        all_schemas: dict[str, IRSchema],
         context: RenderContext,
         required: bool,
         resolve_alias_target: bool = False,
         render_mode: str = "field",  # Literal["field", "alias_target"]
-        parent_schema_name: Optional[str] = None,
+        parent_schema_name: str | None = None,
     ) -> str:
         """
         Determines the Python type string for a given IRSchema.

pyopenapi_gen/helpers/type_resolution/array_resolver.py

@@ -1,7 +1,7 @@
 """Resolves IRSchema to Python List types."""
 
 import logging
-from typing import TYPE_CHECKING, Dict, Optional
+from typing import TYPE_CHECKING
 
 from pyopenapi_gen import IRSchema
 from pyopenapi_gen.context.render_context import RenderContext
@@ -15,7 +15,7 @@ logger = logging.getLogger(__name__)
 class ArrayTypeResolver:
     """Resolves IRSchema instances of type 'array'."""
 
-    def __init__(self, context: RenderContext, all_schemas: Dict[str, IRSchema], main_resolver: "SchemaTypeResolver"):
+    def __init__(self, context: RenderContext, all_schemas: dict[str, IRSchema], main_resolver: "SchemaTypeResolver"):
         self.context = context
         self.all_schemas = all_schemas
         self.main_resolver = main_resolver  # For resolving item types
@@ -23,9 +23,9 @@ class ArrayTypeResolver:
     def resolve(
         self,
         schema: IRSchema,
-        parent_name_hint: Optional[str] = None,
+        parent_name_hint: str | None = None,
         resolve_alias_target: bool = False,
-    ) -> Optional[str]:
+    ) -> str | None:
         """
         Resolves an IRSchema of `type: "array"` to a Python `List[...]` type string.
 

pyopenapi_gen/helpers/type_resolution/composition_resolver.py

@@ -1,7 +1,7 @@
 """Resolves IRSchema composition types (anyOf, oneOf, allOf)."""
 
 import logging
-from typing import TYPE_CHECKING, Dict, List, Optional
+from typing import TYPE_CHECKING, List
 
 from pyopenapi_gen import IRSchema
 from pyopenapi_gen.context.render_context import RenderContext
@@ -15,19 +15,19 @@ logger = logging.getLogger(__name__)
 class CompositionTypeResolver:
     """Resolves IRSchema instances with anyOf, oneOf, or allOf."""
 
-    def __init__(self, context: RenderContext, all_schemas: Dict[str, IRSchema], main_resolver: "SchemaTypeResolver"):
+    def __init__(self, context: RenderContext, all_schemas: dict[str, IRSchema], main_resolver: "SchemaTypeResolver"):
         self.context = context
         self.all_schemas = all_schemas
         self.main_resolver = main_resolver  # For resolving member types
 
-    def resolve(self, schema: IRSchema) -> Optional[str]:
+    def resolve(self, schema: IRSchema) -> str | None:
         """
         Handles 'anyOf', 'oneOf', 'allOf' and returns a Python type string.
         'anyOf'/'oneOf' -> Union[...]
         'allOf' -> Type of first schema (simplification)
         """
-        composition_schemas: Optional[List[IRSchema]] = None
-        composition_keyword: Optional[str] = None
+        composition_schemas: List[IRSchema] | None = None
+        composition_keyword: str | None = None
 
         if schema.any_of is not None:
             composition_schemas = schema.any_of

pyopenapi_gen/helpers/type_resolution/finalizer.py

@@ -1,8 +1,6 @@
 """Finalizes and cleans Python type strings."""
 
 import logging
-from typing import Dict  # Alias to avoid clash
-from typing import Optional as TypingOptional
 
 from pyopenapi_gen import IRSchema
 from pyopenapi_gen.context.render_context import RenderContext
@@ -14,11 +12,11 @@ logger = logging.getLogger(__name__)
 class TypeFinalizer:
     """Handles final wrapping (Optional) and cleaning of type strings."""
 
-    def __init__(self, context: RenderContext, all_schemas: TypingOptional[Dict[str, IRSchema]] = None):
+    def __init__(self, context: RenderContext, all_schemas: dict[str, IRSchema] | None = None):
         self.context = context
         self.all_schemas = all_schemas if all_schemas is not None else {}
 
-    def finalize(self, py_type: TypingOptional[str], schema: IRSchema, required: bool) -> str:
+    def finalize(self, py_type: str | None, schema: IRSchema, required: bool) -> str:
         """Wraps with Optional if needed, cleans the type string, and ensures typing imports."""
         if py_type is None:
             logger.warning(
@@ -28,26 +26,32 @@ class TypeFinalizer:
             self.context.add_import("typing", "Any")
             py_type = "Any"
 
-        optional_type = self._wrap_with_optional_if_needed(py_type, schema, required)
-        cleaned_type = self._clean_type(optional_type)
+        # CRITICAL: Clean BEFORE wrapping to prevent TypeCleaner from breaking "Union[X] | None" patterns
+        cleaned_type = self._clean_type(py_type)
+        optional_type = self._wrap_with_optional_if_needed(cleaned_type, schema, required)
 
-        # Ensure imports for common typing constructs that might have been introduced by cleaning
-        if "Dict[" in cleaned_type or cleaned_type == "Dict":
+        # Ensure imports for common typing constructs that might have been introduced by cleaning or wrapping
+        final_type = optional_type  # Use the wrapped type for import analysis
+        if "dict[" in final_type or final_type == "Dict":
             self.context.add_import("typing", "Dict")
-        if "List[" in cleaned_type or cleaned_type == "List":
+        if "List[" in final_type or final_type == "List":
             self.context.add_import("typing", "List")
-        if "Tuple[" in cleaned_type or cleaned_type == "Tuple":  # Tuple might also appear bare
+        if "Tuple[" in final_type or final_type == "Tuple":  # Tuple might also appear bare
             self.context.add_import("typing", "Tuple")
-        if "Union[" in cleaned_type:
+        if "Union[" in final_type:
             self.context.add_import("typing", "Union")
         # Optional is now handled entirely by _wrap_with_optional_if_needed and not here
-        if cleaned_type == "Any":  # Ensure Any is imported if it's the final type
+        if final_type == "Any" or final_type == "Any | None":  # Ensure Any is imported if it's the final type
             self.context.add_import("typing", "Any")
 
-        return cleaned_type
+        return final_type
 
     def _wrap_with_optional_if_needed(self, py_type: str, schema_being_wrapped: IRSchema, required: bool) -> str:
-        """Wraps the Python type string with `Optional[...]` if necessary."""
+        """Wraps the Python type string with `... | None` if necessary.
+
+        Note: Modern Python 3.10+ uses X | None syntax exclusively.
+        Optional[X] should NEVER appear here - our unified type system generates X | None directly.
+        """
         is_considered_optional_by_usage = not required or schema_being_wrapped.is_nullable is True
 
         if not is_considered_optional_by_usage:
@@ -56,12 +60,25 @@ class TypeFinalizer:
         # At this point, usage implies optional. Now check if py_type inherently is.
 
         if py_type == "Any":
-            self.context.add_import("typing", "Optional")
-            return "Optional[Any]"  # Any is special, always wrap if usage is optional.
+            # Modern Python 3.10+ doesn't need Optional import for | None syntax
+            return "Any | None"  # Any is special, always wrap if usage is optional.
+
+        # SANITY CHECK: Unified type system should never produce Optional[X]
+        if py_type.startswith("Optional[") and py_type.endswith("]"):
+            logger.error(
+                f"❌ ARCHITECTURE VIOLATION: Received legacy Optional[X] type: {py_type}. "
+                f"This should NEVER happen - unified type system generates X | None directly. "
+                f"Schema: {schema_being_wrapped.name or 'anonymous'}. "
+                f"This indicates a bug in the type resolution pipeline."
+            )
+            # Defensive conversion (but this indicates a serious bug upstream)
+            inner_type = py_type[9:-1]  # Remove "Optional[" and "]"
+            logger.warning(f"⚠️ Converted to modern syntax: {inner_type} | None")
+            return f"{inner_type} | None"
 
-        # If already Optional, don't add import again
-        if py_type.startswith("Optional["):
-            return py_type  # Already explicitly Optional.
+        # If already has | None (modern style), don't add again
+        if " | None" in py_type or py_type.endswith("| None"):
+            return py_type  # Already has | None union syntax.
 
         is_union_with_none = "Union[" in py_type and (
             ", None]" in py_type or "[None," in py_type or ", None," in py_type or py_type == "Union[None]"
@@ -80,9 +97,8 @@ class TypeFinalizer:
             if referenced_schema.is_nullable:
                 return py_type
 
-        # Only now add the Optional import and wrap the type
-        self.context.add_import("typing", "Optional")
-        return f"Optional[{py_type}]"
+        # Wrap type with modern | None syntax (no Optional import needed in Python 3.10+)
+        return f"{py_type} | None"
 
     def _clean_type(self, type_str: str) -> str:
         """Cleans a Python type string using TypeCleaner."""

pyopenapi_gen/helpers/type_resolution/named_resolver.py

@@ -2,7 +2,6 @@
 
 import logging
 import os
-from typing import Dict, Optional
 
 from pyopenapi_gen import IRSchema
 from pyopenapi_gen.context.render_context import RenderContext
@@ -14,7 +13,7 @@ logger = logging.getLogger(__name__)
 class NamedTypeResolver:
     """Resolves IRSchema instances that refer to named models/enums."""
 
-    def __init__(self, context: RenderContext, all_schemas: Dict[str, IRSchema]):
+    def __init__(self, context: RenderContext, all_schemas: dict[str, IRSchema]):
         self.context = context
         self.all_schemas = all_schemas
 
@@ -59,7 +58,7 @@ class NamedTypeResolver:
         parts = module_name.split("_")
         return "".join(word.capitalize() for word in parts)
 
-    def resolve(self, schema: IRSchema, resolve_alias_target: bool = False) -> Optional[str]:
+    def resolve(self, schema: IRSchema, resolve_alias_target: bool = False) -> str | None:
         """
         Resolves an IRSchema that refers to a named model/enum, or an inline named enum.
 
@@ -69,7 +68,7 @@ class NamedTypeResolver:
                                  *target* of an alias. If false, it should return the alias name itself.
 
         Returns:
-            A Python type string for the resolved schema, e.g., "MyModel", "Optional[MyModel]".
+            A Python type string for the resolved schema, e.g., "MyModel", "MyModel | None".
         """
 
         if schema.name and schema.name in self.all_schemas:
@@ -147,7 +146,7 @@ class NamedTypeResolver:
 
         elif schema.enum:
             # This is an INLINE enum definition (not a reference to a global enum)
-            enum_name: Optional[str] = None
+            enum_name: str | None = None
             if schema.name:  # If the inline enum has a name, it will be generated as a named enum class
                 enum_name = NameSanitizer.sanitize_class_name(schema.name)
                 module_name = NameSanitizer.sanitize_module_name(schema.name)