pyopenapi-gen 2.7.2__py3-none-any.whl

pyopenapi_gen/helpers/type_resolution/finalizer.py

@@ -0,0 +1,105 @@
+"""Finalizes and cleans Python type strings."""
+
+import logging
+
+from pyopenapi_gen import IRSchema
+from pyopenapi_gen.context.render_context import RenderContext
+from pyopenapi_gen.helpers.type_cleaner import TypeCleaner
+
+logger = logging.getLogger(__name__)
+
+
+class TypeFinalizer:
+    """Handles final wrapping (Optional) and cleaning of type strings."""
+
+    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: 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(
+                f"[TypeFinalizer] Received None as py_type for schema "
+                f"'{schema.name or 'anonymous'}'. Defaulting to 'Any'."
+            )
+            self.context.add_import("typing", "Any")
+            py_type = "Any"
+
+        # 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 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 final_type or final_type == "List":
+            self.context.add_import("typing", "List")
+        if "Tuple[" in final_type or final_type == "Tuple":  # Tuple might also appear bare
+            self.context.add_import("typing", "Tuple")
+        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 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 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 `... | 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:
+            return py_type  # Not optional by usage, so don't wrap.
+
+        # At this point, usage implies optional. Now check if py_type inherently is.
+
+        if py_type == "Any":
+            # 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 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]"
+        )
+        if is_union_with_none:
+            return py_type  # Already a Union with None.
+
+        # New check: if py_type refers to a named schema that IS ITSELF nullable,
+        # its alias definition (if it's an alias) or its usage as a dataclass field type
+        # will effectively be Optional. So, if field usage is optional, we don't ADD another Optional layer.
+        if py_type in self.all_schemas:  # Check if py_type is a known schema name
+            referenced_schema = self.all_schemas[py_type]
+            # If the schema being referenced is itself nullable, its definition (if alias)
+            # or its direct usage (if dataclass) will incorporate Optional via the resolver calling this finalizer.
+            # Thus, we avoid double-wrapping if the *usage* of this type is also optional.
+            if referenced_schema.is_nullable:
+                return 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."""
+        return TypeCleaner.clean_type_parameters(type_str)

pyopenapi_gen/helpers/type_resolution/named_resolver.py

@@ -0,0 +1,172 @@
+"""Resolves IRSchema to Python named types (classes, enums)."""
+
+import logging
+import os
+
+from pyopenapi_gen import IRSchema
+from pyopenapi_gen.context.render_context import RenderContext
+from pyopenapi_gen.core.utils import NameSanitizer
+
+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]):
+        self.context = context
+        self.all_schemas = all_schemas
+
+    def _is_self_reference(self, target_module_name: str, target_class_name: str) -> bool:
+        """Check if the target class is the same as the one currently being generated."""
+        if not self.context.current_file:
+            return False
+
+        # Extract current module name from the file path
+        current_file_name = self.context.current_file
+        current_module_name = os.path.splitext(os.path.basename(current_file_name))[0]
+
+        # For self-reference detection, we need to check if:
+        # 1. The target module name matches the current module name
+        # 2. The target class name is likely the class being defined in this file
+        #
+        # The target_class_name should match the class being generated in the current file
+        # For example, if we're in tree_node.py generating TreeNode class, and we're trying
+        # to reference TreeNode, then this is a self-reference
+        return current_module_name == target_module_name and self._class_being_generated_matches(target_class_name)
+
+    def _class_being_generated_matches(self, target_class_name: str) -> bool:
+        """Check if the target class name matches what's being generated in the current file."""
+        # This is a simple heuristic: if the file is tree_node.py, we expect TreeNode class
+        # More sophisticated logic could be added by tracking what class is currently being generated
+        if not self.context.current_file:
+            return False
+
+        current_file_name = self.context.current_file
+        current_module_name = os.path.splitext(os.path.basename(current_file_name))[0]
+
+        # Convert module name to expected class name (snake_case to PascalCase)
+        expected_class_name = self._module_name_to_class_name(current_module_name)
+
+        return target_class_name == expected_class_name
+
+    def _module_name_to_class_name(self, module_name: str) -> str:
+        """Convert module name (snake_case) to class name (PascalCase)."""
+        # Convert snake_case to PascalCase
+        # tree_node -> TreeNode
+        # message -> Message
+        parts = module_name.split("_")
+        return "".join(word.capitalize() for word in parts)
+
+    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.
+
+        Args:
+            schema: The IRSchema to resolve.
+            resolve_alias_target: If true, the resolver should return the Python type string for the
+                                 *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", "MyModel | None".
+        """
+
+        if schema.name and schema.name in self.all_schemas:
+            # This schema is a REFERENCE to a globally defined schema (e.g., in components/schemas)
+            ref_schema = self.all_schemas[schema.name]  # Get the actual definition
+            if ref_schema.name is None:
+                raise RuntimeError(f"Schema '{schema.name}' resolved to ref_schema with None name.")
+
+            # NEW: Use generation_name and final_module_stem from the referenced schema
+            if ref_schema.generation_name is None:
+                raise RuntimeError(f"Referenced schema '{ref_schema.name}' must have generation_name set.")
+            if ref_schema.final_module_stem is None:
+                raise RuntimeError(f"Referenced schema '{ref_schema.name}' must have final_module_stem set.")
+
+            class_name_for_ref = ref_schema.generation_name
+            module_name_for_ref = ref_schema.final_module_stem
+
+            model_module_path_for_ref = (
+                f"{self.context.get_current_package_name_for_generated_code()}.models.{module_name_for_ref}"
+            )
+
+            key_to_check = model_module_path_for_ref
+            name_to_add = class_name_for_ref
+
+            if not resolve_alias_target:
+                # Check for self-reference: if we're generating the same class that we're trying to import
+                is_self_reference = self._is_self_reference(module_name_for_ref, class_name_for_ref)
+
+                if is_self_reference:
+                    # For self-references, don't add import and return quoted type name
+                    return f'"{name_to_add}"'
+                else:
+                    # For external references, add import and return unquoted type name
+                    self.context.add_import(logical_module=key_to_check, name=name_to_add)
+                    return name_to_add
+            else:
+                # self.resolve_alias_target is TRUE. We are trying to find the *actual underlying type*
+                # of 'ref_schema' for use in an alias definition (e.g., MyStringAlias: TypeAlias = str).
+                # Check if ref_schema is structurally a simple alias (no properties, enum, composition)
+                is_structurally_simple_alias = not (
+                    ref_schema.properties
+                    or ref_schema.enum
+                    or ref_schema.any_of
+                    or ref_schema.one_of
+                    or ref_schema.all_of
+                )
+
+                if is_structurally_simple_alias:
+                    # It's an alias to a primitive, array, or simple object.
+                    # We need to return the Python type of its target.
+                    # For this, we delegate back to the main resolver, but on ref_schema's definition,
+                    # and crucially, with resolve_alias_target=False for that sub-call to avoid loops
+                    # and to get the structural type.
+                    # Also, treat ref_schema as anonymous for this sub-resolution so it's purely structural.
+
+                    # Construct a temporary schema that is like ref_schema but anonymous
+                    # to force structural resolution by the main resolver.
+                    # This is a bit of a workaround for not having direct access to other resolvers here.
+                    # A better design might involve passing the main SchemaTypeResolver instance.
+                    # For now, returning None effectively tells TypeHelper to do this.
+
+                    return None  # Signal to TypeHelper to resolve ref_schema structurally.
+                else:
+                    # ref_schema is NOT structurally alias-like (e.g., it's a full object schema).
+                    # If we are resolving an alias target, and the target is a full object schema,
+                    # the "target type" IS that object schema's name.
+                    # e.g. MyDataAlias = DataObject. Here, DataObject is the target.
+                    # The AliasGenerator will then generate "MyDataAlias: TypeAlias = DataObject".
+                    # It needs "DataObject" as the string.
+                    # The import for DataObject will be handled by TypeHelper when generating that alias
+                    # file itself, using the regular non-alias-target path.
+
+                    self.context.add_import(logical_module=key_to_check, name=name_to_add)
+                    return name_to_add  # Return name_to_add
+
+        elif schema.enum:
+            # This is an INLINE enum definition (not a reference to a global enum)
+            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)
+                model_module_path = f"{self.context.get_current_package_name_for_generated_code()}.models.{module_name}"
+                self.context.add_import(logical_module=model_module_path, name=enum_name)
+                return enum_name
+            else:  # Inline anonymous enum, falls back to primitive type of its values
+                # (Handled by PrimitiveTypeResolver if this returns None or specific primitive)
+                # For now, this path might lead to PrimitiveTypeResolver via TypeHelper's main loop.
+                # Let's try to return the primitive type directly if possible.
+                primitive_type_of_enum = "str"  # Default for enums if type not specified
+                if schema.type == "integer":
+                    primitive_type_of_enum = "int"
+                elif schema.type == "number":
+                    primitive_type_of_enum = "float"
+                # other types for enums are unusual.
+                return primitive_type_of_enum
+        else:
+            # Not a reference to a known schema, and not an inline enum.
+            # This could be an anonymous complex type, or an unresolved reference.
+            # Defer to other resolvers by returning None.
+
+            return None

pyopenapi_gen/helpers/type_resolution/object_resolver.py

@@ -0,0 +1,216 @@
+"""Resolves IRSchema to Python object types (classes, dicts)."""
+
+import logging
+import os
+from typing import TYPE_CHECKING
+
+from pyopenapi_gen import IRSchema
+from pyopenapi_gen.context.render_context import RenderContext
+from pyopenapi_gen.core.utils import NameSanitizer
+
+if TYPE_CHECKING:
+    from .resolver import SchemaTypeResolver  # Avoid circular import
+
+logger = logging.getLogger(__name__)
+
+
+class ObjectTypeResolver:
+    """Resolves IRSchema instances of type 'object'."""
+
+    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 nested types
+
+    def _promote_anonymous_object_schema_if_needed(
+        self,
+        schema_to_promote: IRSchema,
+        proposed_name_base: str | None,
+    ) -> str | None:
+        """Gives a name to an anonymous object schema and registers it."""
+        if not proposed_name_base:
+            return None
+
+        class_name_base = NameSanitizer.sanitize_class_name(proposed_name_base)
+        # Suffix logic can be refined here if needed (e.g. Property vs Item)
+        potential_new_name = f"{class_name_base}Item"
+        counter = 1
+        final_new_name = potential_new_name
+        while final_new_name in self.all_schemas:
+            final_new_name = f"{potential_new_name}{counter}"
+            counter += 1
+            if counter > 10:  # Safety break
+                logger.error(
+                    f"[ObjectTypeResolver._promote] Could not find unique name "
+                    f"for base '{potential_new_name}' after 10 tries."
+                )
+                return None
+
+        schema_to_promote.name = final_new_name  # Assign the new name
+        # Set generation_name and final_module_stem after the new name is assigned
+        schema_to_promote.generation_name = NameSanitizer.sanitize_class_name(final_new_name)
+        schema_to_promote.final_module_stem = NameSanitizer.sanitize_module_name(final_new_name)
+
+        self.all_schemas[final_new_name] = schema_to_promote  # Register in global schemas
+
+        # Add import for this newly named model
+        module_to_import_from = f"models.{NameSanitizer.sanitize_module_name(final_new_name)}"
+        self.context.add_import(module_to_import_from, final_new_name)
+        return final_new_name
+
+    def resolve(self, schema: IRSchema, parent_schema_name_for_anon_promotion: str | None = None) -> str | None:
+        """
+        Resolves an IRSchema of `type: "object"`.
+        Args:
+            schema: The IRSchema, expected to have `type: "object"`.
+            parent_schema_name_for_anon_promotion: Contextual name for promoting anonymous objects.
+        Returns:
+            A Python type string or None.
+        """
+        if schema.type == "object":
+            # Path A: additionalProperties is True (boolean)
+            if isinstance(schema.additional_properties, bool) and schema.additional_properties:
+                self.context.add_import("typing", "Dict")
+                self.context.add_import("typing", "Any")
+                return "dict[str, Any]"
+
+            # Path B: additionalProperties is an IRSchema instance
+            if isinstance(schema.additional_properties, IRSchema):
+                ap_schema_instance = schema.additional_properties
+                is_ap_schema_defined = (
+                    ap_schema_instance.type is not None
+                    or ap_schema_instance.format is not None
+                    or ap_schema_instance.properties
+                    or ap_schema_instance.items
+                    or ap_schema_instance.enum
+                    or ap_schema_instance.any_of
+                    or ap_schema_instance.one_of
+                    or ap_schema_instance.all_of
+                )
+                if is_ap_schema_defined:
+                    additional_prop_type = self.main_resolver.resolve(ap_schema_instance, required=True)
+                    self.context.add_import("typing", "Dict")
+                    return f"dict[str, {additional_prop_type}]"
+
+            # Path C: additionalProperties is False, None, or empty IRSchema.
+            if schema.properties:  # Object has its own properties
+                if not schema.name:  # Anonymous object with properties
+                    if parent_schema_name_for_anon_promotion:
+                        promoted_name = self._promote_anonymous_object_schema_if_needed(
+                            schema, parent_schema_name_for_anon_promotion
+                        )
+                        if promoted_name:
+                            return promoted_name
+                    # Fallback for unpromoted anonymous object with properties
+                    logger.warning(
+                        f"[ObjectTypeResolver] Anonymous object with properties not promoted. "
+                        f"-> dict[str, Any]. Schema: {schema}"
+                    )
+                    self.context.add_import("typing", "Dict")
+                    self.context.add_import("typing", "Any")
+                    return "dict[str, Any]"
+                else:  # Named object with properties
+                    # If this named object is a component schema, ensure it's imported.
+                    if schema.name and schema.name in self.all_schemas:
+                        actual_schema_def = self.all_schemas[schema.name]
+                        if actual_schema_def.generation_name is None:
+                            raise RuntimeError(
+                                f"Actual schema '{actual_schema_def.name}' for '{schema.name}' must have generation_name."
+                            )
+                        if actual_schema_def.final_module_stem is None:
+                            raise RuntimeError(
+                                f"Actual schema '{actual_schema_def.name}' for '{schema.name}' must have final_module_stem."
+                            )
+
+                        class_name_to_use = actual_schema_def.generation_name
+                        module_stem_to_use = actual_schema_def.final_module_stem
+
+                        base_model_path_part = f"models.{module_stem_to_use}"
+                        model_module_path = base_model_path_part
+
+                        if self.context.package_root_for_generated_code and self.context.overall_project_root:
+                            abs_pkg_root = os.path.abspath(self.context.package_root_for_generated_code)
+                            abs_overall_root = os.path.abspath(self.context.overall_project_root)
+                            if abs_pkg_root.startswith(abs_overall_root) and abs_pkg_root != abs_overall_root:
+                                rel_pkg_path = os.path.relpath(abs_pkg_root, abs_overall_root)
+                                current_gen_pkg_dot_path = rel_pkg_path.replace(os.sep, ".")
+                                model_module_path = f"{current_gen_pkg_dot_path}.{base_model_path_part}"
+                            elif abs_pkg_root == abs_overall_root:
+                                model_module_path = base_model_path_part
+                        elif self.context.package_root_for_generated_code:
+                            current_gen_pkg_name_from_basename = os.path.basename(
+                                os.path.normpath(self.context.package_root_for_generated_code)
+                            )
+                            if current_gen_pkg_name_from_basename and current_gen_pkg_name_from_basename != ".":
+                                model_module_path = f"{current_gen_pkg_name_from_basename}.{base_model_path_part}"
+
+                        current_module_dot_path = self.context.get_current_module_dot_path()
+                        if model_module_path != current_module_dot_path:  # Avoid self-imports
+                            self.context.add_import(model_module_path, class_name_to_use)
+                        return class_name_to_use  # Return the potentially de-collided name
+                    else:
+                        # This case should ideally not be hit if all named objects are in all_schemas
+                        # Or, it's a named object that isn't a global component (e.g. inline named object for promotion)
+                        # For safety, use schema.name if it's not in all_schemas (might be a freshly promoted name)
+                        class_name_to_use = NameSanitizer.sanitize_class_name(schema.name)
+                        logger.warning(
+                            f"[ObjectTypeResolver] Named object '{schema.name}' not in all_schemas, "
+                            f"using its own name '{class_name_to_use}'. "
+                            f"This might occur for locally promoted anonymous objects."
+                        )
+                        return class_name_to_use
+            else:  # Object has NO properties
+                if (
+                    schema.name and schema.name in self.all_schemas
+                ):  # Named object, no properties, AND it's a known component
+                    actual_schema_def = self.all_schemas[schema.name]
+                    if actual_schema_def.generation_name is None:
+                        raise RuntimeError(
+                            f"Actual schema (no props) '{actual_schema_def.name}' "
+                            f"for '{schema.name}' must have generation_name."
+                        )
+                    if actual_schema_def.final_module_stem is None:
+                        raise RuntimeError(
+                            f"Actual schema (no props) '{actual_schema_def.name}' "
+                            f"for '{schema.name}' must have final_module_stem."
+                        )
+
+                    class_name_to_use = actual_schema_def.generation_name
+                    module_stem_to_use = actual_schema_def.final_module_stem
+
+                    base_model_path_part = f"models.{module_stem_to_use}"
+                    model_module_path = base_model_path_part
+
+                    if self.context.package_root_for_generated_code and self.context.overall_project_root:
+                        abs_pkg_root = os.path.abspath(self.context.package_root_for_generated_code)
+                        abs_overall_root = os.path.abspath(self.context.overall_project_root)
+                        if abs_pkg_root.startswith(abs_overall_root) and abs_pkg_root != abs_overall_root:
+                            rel_pkg_path = os.path.relpath(abs_pkg_root, abs_overall_root)
+                            current_gen_pkg_dot_path = rel_pkg_path.replace(os.sep, ".")
+                            model_module_path = f"{current_gen_pkg_dot_path}.{base_model_path_part}"
+                        elif abs_pkg_root == abs_overall_root:
+                            model_module_path = base_model_path_part
+                    elif self.context.package_root_for_generated_code:
+                        current_gen_pkg_name_from_basename = os.path.basename(
+                            os.path.normpath(self.context.package_root_for_generated_code)
+                        )
+                        if current_gen_pkg_name_from_basename and current_gen_pkg_name_from_basename != ".":
+                            model_module_path = f"{current_gen_pkg_name_from_basename}.{base_model_path_part}"
+
+                    current_module_dot_path = self.context.get_current_module_dot_path()
+                    if model_module_path != current_module_dot_path:  # Avoid self-imports
+                        self.context.add_import(model_module_path, class_name_to_use)
+                    return class_name_to_use  # Return the potentially de-collided name
+                elif schema.name:  # Named object, no properties, but NOT a known component
+                    self.context.add_import("typing", "Dict")
+                    self.context.add_import("typing", "Any")
+                    return "dict[str, Any]"
+                else:  # Anonymous object, no properties
+                    if schema.additional_properties is None:  # Default OpenAPI behavior allows additional props
+                        self.context.add_import("typing", "Dict")
+                        self.context.add_import("typing", "Any")
+                        return "dict[str, Any]"
+                    else:  # additionalProperties was False or restrictive empty schema
+                        self.context.add_import("typing", "Any")
+                        return "Any"
+        return None

pyopenapi_gen/helpers/type_resolution/primitive_resolver.py

@@ -0,0 +1,109 @@
+"""Resolves IRSchema to Python primitive types."""
+
+import logging
+
+from pyopenapi_gen import IRSchema
+from pyopenapi_gen.context.render_context import RenderContext
+
+logger = logging.getLogger(__name__)
+
+
+class PrimitiveTypeResolver:
+    """Resolves IRSchema to Python primitive type strings."""
+
+    def __init__(self, context: RenderContext):
+        self.context = context
+
+    def resolve(self, schema: IRSchema) -> str | None:
+        """
+        Resolves an IRSchema to a Python primitive type string based on its 'type' and 'format'.
+
+        Handles standard OpenAPI types and formats:
+        - integer -> "int" (also int32, int64 formats)
+        - number -> "float" (also float, double formats)
+        - boolean -> "bool"
+        - string -> "str"
+        - string with format "date-time" -> "datetime" (imports `datetime.datetime`)
+        - string with format "date" -> "date" (imports `datetime.date`)
+        - string with format "time" -> "time" (imports `datetime.time`)
+        - string with format "duration" -> "timedelta" (imports `datetime.timedelta`)
+        - string with format "uuid" -> "UUID" (imports `uuid.UUID`)
+        - string with format "binary" or "byte" -> "bytes"
+        - string with format "ipv4" -> "IPv4Address" (imports `ipaddress.IPv4Address`)
+        - string with format "ipv6" -> "IPv6Address" (imports `ipaddress.IPv6Address`)
+        - string with format "uri", "url", "email", "hostname", "password" -> "str"
+        - null -> "None" (the string literal "None")
+
+        Args:
+            schema: The IRSchema to resolve.
+
+        Returns:
+            The Python primitive type string if the schema matches a known primitive type/format,
+            otherwise None.
+        """
+        if schema.type == "null":
+            return "None"
+
+        # Handle string formats first (before falling through to generic string)
+        if schema.type == "string" and schema.format:
+            return self._resolve_string_format(schema.format)
+
+        # Handle integer formats
+        if schema.type == "integer":
+            # int32 and int64 both map to Python int
+            return "int"
+
+        # Handle number formats
+        if schema.type == "number":
+            # float and double both map to Python float
+            return "float"
+
+        # Handle remaining primitive types
+        primitive_type_map = {
+            "boolean": "bool",
+            "string": "str",
+        }
+        if schema.type in primitive_type_map:
+            return primitive_type_map[schema.type]
+
+        return None
+
+    def _resolve_string_format(self, format_value: str) -> str:
+        """Resolve string type with specific format to Python type."""
+        # Date/time formats
+        if format_value == "date-time":
+            self.context.add_import("datetime", "datetime")
+            return "datetime"
+        if format_value == "date":
+            self.context.add_import("datetime", "date")
+            return "date"
+        if format_value == "time":
+            self.context.add_import("datetime", "time")
+            return "time"
+        if format_value == "duration":
+            self.context.add_import("datetime", "timedelta")
+            return "timedelta"
+
+        # UUID format
+        if format_value == "uuid":
+            self.context.add_import("uuid", "UUID")
+            return "UUID"
+
+        # Binary formats
+        if format_value in ("binary", "byte"):
+            return "bytes"
+
+        # IP address formats
+        if format_value == "ipv4":
+            self.context.add_import("ipaddress", "IPv4Address")
+            return "IPv4Address"
+        if format_value == "ipv6":
+            self.context.add_import("ipaddress", "IPv6Address")
+            return "IPv6Address"
+
+        # String-based formats (no special Python type, just str)
+        if format_value in ("uri", "url", "email", "hostname", "password"):
+            return "str"
+
+        # Unknown format - fall back to str
+        return "str"

pyopenapi_gen/helpers/type_resolution/resolver.py

@@ -0,0 +1,47 @@
+"""Orchestrates IRSchema to Python type resolution."""
+
+import logging
+
+from pyopenapi_gen import IRSchema
+from pyopenapi_gen.context.render_context import RenderContext
+from pyopenapi_gen.types.services.type_service import UnifiedTypeService
+
+from .array_resolver import ArrayTypeResolver
+from .composition_resolver import CompositionTypeResolver
+from .finalizer import TypeFinalizer
+from .named_resolver import NamedTypeResolver
+from .object_resolver import ObjectTypeResolver
+from .primitive_resolver import PrimitiveTypeResolver
+
+logger = logging.getLogger(__name__)
+
+
+class SchemaTypeResolver:
+    """Orchestrates the resolution of IRSchema to Python type strings."""
+
+    def __init__(self, context: RenderContext, all_schemas: dict[str, IRSchema]):
+        self.context = context
+        self.all_schemas = all_schemas
+
+        # Initialize specialized resolvers, passing self for circular dependencies if needed
+        self.primitive_resolver = PrimitiveTypeResolver(context)
+        self.named_resolver = NamedTypeResolver(context, all_schemas)
+        self.array_resolver = ArrayTypeResolver(context, all_schemas, self)
+        self.object_resolver = ObjectTypeResolver(context, all_schemas, self)
+        self.composition_resolver = CompositionTypeResolver(context, all_schemas, self)
+        self.finalizer = TypeFinalizer(context, self.all_schemas)
+
+    def resolve(
+        self,
+        schema: IRSchema,
+        required: bool = True,
+        resolve_alias_target: bool = False,
+        current_schema_context_name: str | None = None,
+    ) -> str:
+        """
+        Determines the Python type string for a given IRSchema.
+        Now delegates to the UnifiedTypeService for consistent type resolution.
+        """
+        # Delegate to the unified type service for all type resolution
+        type_service = UnifiedTypeService(self.all_schemas)
+        return type_service.resolve_schema_type(schema, self.context, required)

pyopenapi_gen/helpers/url_utils.py

@@ -0,0 +1,14 @@
+"""
+Utility for extracting variable names from URL templates.
+"""
+
+import re
+from typing import Set
+
+
+def extract_url_variables(url: str) -> Set[str]:
+    """
+    Extract all variable names (e.g., 'foo' from '{foo}') from a URL template.
+    Returns a set of variable names as strings.
+    """
+    return set(re.findall(r"{([^}]+)}", url))