pyopenapi-gen 0.8.3__py3-none-any.whl

pyopenapi_gen/ir.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Union
+
+# Import NameSanitizer at the top for type hints and __post_init__ usage
+from pyopenapi_gen.core.utils import NameSanitizer
+
+# Import HTTPMethod as it's used by IROperation
+from .http_types import HTTPMethod
+
+# Forward declaration for IRSchema itself if needed for self-references in type hints
+# class IRSchema:
+#     pass
+
+
+@dataclass
+class IRSchema:
+    name: Optional[str] = None
+    type: Optional[str] = None  # E.g., "object", "array", "string", or a reference to another schema name
+    format: Optional[str] = None
+    description: Optional[str] = None
+    required: List[str] = field(default_factory=list)
+    properties: Dict[str, IRSchema] = field(default_factory=dict)
+    items: Optional[IRSchema] = None  # For type: "array"
+    enum: Optional[List[Any]] = None
+    default: Optional[Any] = None  # Added default value
+    example: Optional[Any] = None  # Added example value
+    additional_properties: Optional[Union[bool, IRSchema]] = None  # True, False, or an IRSchema
+    is_nullable: bool = False
+    any_of: Optional[List[IRSchema]] = None
+    one_of: Optional[List[IRSchema]] = None
+    all_of: Optional[List[IRSchema]] = None  # Store the list of IRSchema objects from allOf
+    title: Optional[str] = None  # Added title
+    is_data_wrapper: bool = False  # True if schema is a simple {{ "data": OtherSchema }} wrapper
+
+    # Internal generator flags/helpers
+    _from_unresolved_ref: bool = field(
+        default=False, repr=False
+    )  # If this IRSchema is a placeholder for an unresolvable $ref
+    _refers_to_schema: Optional[IRSchema] = (
+        None  # If this schema is a reference (e.g. a promoted property), this can link to the actual definition
+    )
+    _is_circular_ref: bool = field(default=False, repr=False)  # If this IRSchema is part of a circular reference chain
+    _circular_ref_path: Optional[str] = field(default=None, repr=False)  # Path of the circular reference
+    _max_depth_exceeded_marker: bool = field(
+        default=False, repr=False
+    )  # If parsing this schema or its components exceeded max depth
+    _is_self_referential_stub: bool = field(default=False, repr=False)  # If this is a placeholder for allowed self-ref
+    _is_name_derived: bool = field(
+        default=False, repr=False
+    )  # True if the name was derived (e.g. for promoted inline objects)
+    _inline_name_resolution_path: Optional[str] = field(
+        default=None, repr=False
+    )  # Path used for resolving inline names
+
+    # Fields for storing final, de-collided names for code generation
+    generation_name: Optional[str] = field(default=None, repr=True)  # Final class/enum name
+    final_module_stem: Optional[str] = field(default=None, repr=True)  # Final module filename stem
+
+    def __post_init__(self) -> None:
+        # Ensure name is always a valid Python identifier if set
+        # This must happen BEFORE type inference that might use the name (though current logic doesn't)
+        if self.name:
+            # Store original name if needed for specific logic before sanitization, though not currently used here.
+            # original_name = self.name
+            self.name = NameSanitizer.sanitize_class_name(self.name)
+
+        # Ensure that if type is a reference (string not matching basic types),
+        # other structural fields like properties/items/enum are usually None or empty.
+        basic_types = ["object", "array", "string", "integer", "number", "boolean", "null"]
+        if self.type and self.type not in basic_types:
+            # This schema acts as a reference by name to another schema.
+            # It shouldn't typically define its own structure beyond description/nullability.
+            pass
+
+        # The check for is_valid_python_identifier is somewhat redundant if sanitize_class_name works correctly,
+        # but can be kept as a safeguard or for logging if a raw name was problematic *before* sanitization.
+        if self.name and not NameSanitizer.is_valid_python_identifier(self.name):
+            pass  # logger.warning or handle as needed elsewhere
+
+        # Ensure nested schemas are IRSchema instances
+        if isinstance(self.items, dict):
+            self.items = IRSchema(**self.items)
+
+        if isinstance(self.properties, dict):
+            new_props = {}
+            for k, v in self.properties.items():
+                if isinstance(v, dict):
+                    new_props[k] = IRSchema(**v)
+                elif isinstance(v, IRSchema):  # Already an IRSchema instance
+                    new_props[k] = v
+                # else: it might be some other unexpected type, raise error or log
+            self.properties = new_props
+
+        if isinstance(self.additional_properties, dict):
+            self.additional_properties = IRSchema(**self.additional_properties)
+
+        for comp_list_attr in ["any_of", "one_of", "all_of"]:
+            comp_list = getattr(self, comp_list_attr)
+            if isinstance(comp_list, list):
+                new_comp_list = []
+                for item in comp_list:
+                    if isinstance(item, dict):
+                        new_comp_list.append(IRSchema(**item))
+                    elif isinstance(item, IRSchema):
+                        new_comp_list.append(item)
+                    # else: item is some other type, could skip or raise
+                setattr(self, comp_list_attr, new_comp_list)
+
+
+# NameSanitizer is now imported at the top
+# from pyopenapi_gen.core.utils import NameSanitizer
+
+
+@dataclass(slots=True)
+class IRParameter:
+    name: str
+    param_in: str  # Renamed from 'in' to avoid keyword clash, was in_: str in original __init__.py
+    required: bool
+    schema: IRSchema
+    description: Optional[str] = None
+    # example: Optional[Any] = None # This was in my latest ir.py but not __init__.py, keeping it from my version
+
+
+# Adding other IR classes from the original __init__.py structure
+@dataclass(slots=True)
+class IRResponse:
+    status_code: str  # can be "default" or specific status like "200"
+    description: Optional[str]
+    content: Dict[str, IRSchema]  # media‑type → schema mapping
+    stream: bool = False  # Indicates a binary or streaming response
+    stream_format: Optional[str] = None  # Indicates the stream type
+
+
+@dataclass(slots=True)
+class IRRequestBody:
+    required: bool
+    content: Dict[str, IRSchema]  # media‑type → schema mapping
+    description: Optional[str] = None
+
+
+@dataclass(slots=True)
+class IROperation:
+    operation_id: str
+    method: HTTPMethod  # Enforced via enum for consistency
+    path: str  # e.g. "/pets/{petId}"
+    summary: Optional[str]
+    description: Optional[str]
+    parameters: List[IRParameter] = field(default_factory=list)
+    request_body: Optional[IRRequestBody] = None
+    responses: List[IRResponse] = field(default_factory=list)
+    tags: List[str] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class IRSpec:
+    title: str
+    version: str
+    description: Optional[str] = None
+    schemas: Dict[str, IRSchema] = field(default_factory=dict)
+    operations: List[IROperation] = field(default_factory=list)
+    servers: List[str] = field(default_factory=list)
+
+    #     self._raw_schema_node = None
+
+    # def __setattr__(self, name, value):

pyopenapi_gen/py.typed

@@ -0,0 +1 @@
+ 

pyopenapi_gen/types/__init__.py

@@ -0,0 +1,11 @@
+"""
+Unified type resolution service for OpenAPI schema to Python type conversion.
+
+This package provides a clean, testable architecture for resolving OpenAPI schemas,
+references, and operation responses to Python type strings.
+
+Architecture:
+- contracts/: Interfaces and protocols
+- resolvers/: Core resolution logic
+- services/: High-level orchestration
+"""

pyopenapi_gen/types/contracts/__init__.py

@@ -0,0 +1,13 @@
+"""Type resolution contracts and interfaces."""
+
+from .protocols import ReferenceResolver, ResponseTypeResolver, SchemaTypeResolver, TypeContext
+from .types import ResolvedType, TypeResolutionError
+
+__all__ = [
+    "ReferenceResolver",
+    "SchemaTypeResolver",
+    "ResponseTypeResolver",
+    "TypeContext",
+    "ResolvedType",
+    "TypeResolutionError",
+]

pyopenapi_gen/types/contracts/protocols.py

@@ -0,0 +1,106 @@
+"""Protocols for type resolution components."""
+
+from abc import ABC, abstractmethod
+from typing import Dict, Optional, Protocol, runtime_checkable
+
+from pyopenapi_gen import IROperation, IRResponse, IRSchema
+
+from .types import ResolvedType
+
+
+@runtime_checkable
+class TypeContext(Protocol):
+    """Context for type resolution operations."""
+
+    def add_import(self, module: str, name: str) -> None:
+        """Add an import to the context."""
+        ...
+
+    def add_conditional_import(self, condition: str, module: str, name: str) -> None:
+        """Add a conditional import (e.g., TYPE_CHECKING)."""
+        ...
+
+
+class ReferenceResolver(ABC):
+    """Resolves OpenAPI $ref references to target schemas."""
+
+    # Concrete implementations should have these attributes
+    schemas: Dict[str, IRSchema]
+    responses: Dict[str, IRResponse]
+
+    @abstractmethod
+    def resolve_ref(self, ref: str) -> Optional[IRSchema]:
+        """
+        Resolve a $ref string to the target schema.
+
+        Args:
+            ref: Reference string like "#/components/schemas/User"
+
+        Returns:
+            Target schema or None if not found
+        """
+        pass
+
+    @abstractmethod
+    def resolve_response_ref(self, ref: str) -> Optional[IRResponse]:
+        """
+        Resolve a response $ref to the target response.
+
+        Args:
+            ref: Reference string like "#/components/responses/UserResponse"
+
+        Returns:
+            Target response or None if not found
+        """
+        pass
+
+
+class SchemaTypeResolver(ABC):
+    """Resolves IRSchema objects to Python types."""
+
+    @abstractmethod
+    def resolve_schema(self, schema: IRSchema, context: TypeContext, required: bool = True) -> ResolvedType:
+        """
+        Resolve a schema to a Python type.
+
+        Args:
+            schema: The schema to resolve
+            context: Type resolution context
+            required: Whether the field is required
+
+        Returns:
+            Resolved Python type information
+        """
+        pass
+
+
+class ResponseTypeResolver(ABC):
+    """Resolves operation responses to Python types."""
+
+    @abstractmethod
+    def resolve_operation_response(self, operation: IROperation, context: TypeContext) -> ResolvedType:
+        """
+        Resolve an operation's primary response to a Python type.
+
+        Args:
+            operation: The operation to resolve
+            context: Type resolution context
+
+        Returns:
+            Resolved Python type information
+        """
+        pass
+
+    @abstractmethod
+    def resolve_specific_response(self, response: IRResponse, context: TypeContext) -> ResolvedType:
+        """
+        Resolve a specific response to a Python type.
+
+        Args:
+            response: The response to resolve
+            context: Type resolution context
+
+        Returns:
+            Resolved Python type information
+        """
+        pass

pyopenapi_gen/types/contracts/types.py

@@ -0,0 +1,30 @@
+"""Core types for type resolution."""
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+class TypeResolutionError(Exception):
+    """Raised when type resolution fails."""
+
+    pass
+
+
+@dataclass
+class ResolvedType:
+    """Result of type resolution."""
+
+    python_type: str
+    needs_import: bool = False
+    import_module: Optional[str] = None
+    import_name: Optional[str] = None
+    is_optional: bool = False
+    is_forward_ref: bool = False
+    was_unwrapped: bool = False
+
+    def __post_init__(self) -> None:
+        """Validate resolved type data."""
+        if self.needs_import and not self.import_module:
+            raise ValueError("needs_import=True requires import_module")
+        if self.needs_import and not self.import_name:
+            raise ValueError("needs_import=True requires import_name")

pyopenapi_gen/types/resolvers/__init__.py

@@ -0,0 +1,7 @@
+"""Type resolution implementations."""
+
+from .reference_resolver import OpenAPIReferenceResolver
+from .response_resolver import OpenAPIResponseResolver
+from .schema_resolver import OpenAPISchemaResolver
+
+__all__ = ["OpenAPIReferenceResolver", "OpenAPISchemaResolver", "OpenAPIResponseResolver"]

pyopenapi_gen/types/resolvers/reference_resolver.py

@@ -0,0 +1,71 @@
+"""Reference resolver implementation."""
+
+import logging
+from typing import Dict, Optional
+
+from pyopenapi_gen import IRResponse, IRSchema
+
+from ..contracts.protocols import ReferenceResolver
+
+logger = logging.getLogger(__name__)
+
+
+class OpenAPIReferenceResolver(ReferenceResolver):
+    """Resolves OpenAPI $ref references."""
+
+    def __init__(self, schemas: Dict[str, IRSchema], responses: Optional[Dict[str, IRResponse]] = None):
+        """
+        Initialize reference resolver.
+
+        Args:
+            schemas: Dictionary of schemas by name
+            responses: Dictionary of responses by name (optional)
+        """
+        self.schemas = schemas
+        self.responses = responses or {}
+
+    def resolve_ref(self, ref: str) -> Optional[IRSchema]:
+        """
+        Resolve a schema $ref to the target schema.
+
+        Args:
+            ref: Reference string like "#/components/schemas/User"
+
+        Returns:
+            Target schema or None if not found
+        """
+        if not ref.startswith("#/components/schemas/"):
+            logger.warning(f"Unsupported schema ref format: {ref}")
+            return None
+
+        schema_name = ref.split("/")[-1]
+        schema = self.schemas.get(schema_name)
+
+        if not schema:
+            logger.warning(f"Schema not found for ref: {ref}")
+            return None
+
+        return schema
+
+    def resolve_response_ref(self, ref: str) -> Optional[IRResponse]:
+        """
+        Resolve a response $ref to the target response.
+
+        Args:
+            ref: Reference string like "#/components/responses/UserResponse"
+
+        Returns:
+            Target response or None if not found
+        """
+        if not ref.startswith("#/components/responses/"):
+            logger.warning(f"Unsupported response ref format: {ref}")
+            return None
+
+        response_name = ref.split("/")[-1]
+        response = self.responses.get(response_name)
+
+        if not response:
+            logger.warning(f"Response not found for ref: {ref}")
+            return None
+
+        return response

pyopenapi_gen/types/resolvers/response_resolver.py

@@ -0,0 +1,203 @@
+"""Response type resolver implementation."""
+
+import logging
+from typing import Optional
+
+from pyopenapi_gen import IROperation, IRResponse, IRSchema
+
+from ..contracts.protocols import ReferenceResolver, ResponseTypeResolver, SchemaTypeResolver, TypeContext
+from ..contracts.types import ResolvedType
+
+logger = logging.getLogger(__name__)
+
+
+class OpenAPIResponseResolver(ResponseTypeResolver):
+    """Resolves operation responses to Python types."""
+
+    def __init__(self, ref_resolver: ReferenceResolver, schema_resolver: SchemaTypeResolver):
+        """
+        Initialize response resolver.
+
+        Args:
+            ref_resolver: Reference resolver for handling $ref
+            schema_resolver: Schema resolver for handling schemas
+        """
+        self.ref_resolver = ref_resolver
+        self.schema_resolver = schema_resolver
+
+    def resolve_operation_response(self, operation: IROperation, context: TypeContext) -> ResolvedType:
+        """
+        Resolve an operation's primary response to a Python type.
+
+        Args:
+            operation: The operation to resolve
+            context: Type resolution context
+
+        Returns:
+            Resolved Python type information
+        """
+        primary_response = self._get_primary_response(operation)
+
+        if not primary_response:
+            return ResolvedType(python_type="None")
+
+        return self.resolve_specific_response(primary_response, context)
+
+    def resolve_specific_response(self, response: IRResponse, context: TypeContext) -> ResolvedType:
+        """
+        Resolve a specific response to a Python type.
+
+        Args:
+            response: The response to resolve
+            context: Type resolution context
+
+        Returns:
+            Resolved Python type information
+        """
+        # Handle response references
+        if hasattr(response, "ref") and response.ref:
+            return self._resolve_response_reference(response.ref, context)
+
+        # Handle responses without content (e.g., 204)
+        if not hasattr(response, "content") or not response.content:
+            return ResolvedType(python_type="None")
+
+        # Handle streaming responses
+        if hasattr(response, "stream") and response.stream:
+            return self._resolve_streaming_response(response, context)
+
+        # Get the content schema
+        schema = self._get_response_schema(response)
+        if not schema:
+            return ResolvedType(python_type="None")
+
+        # Resolve the schema
+        resolved = self.schema_resolver.resolve_schema(schema, context, required=True)
+
+        # Check for data unwrapping
+        unwrapped = self._try_unwrap_data_property(schema, context)
+        if unwrapped:
+            unwrapped.was_unwrapped = True
+            return unwrapped
+
+        return resolved
+
+    def _resolve_response_reference(self, ref: str, context: TypeContext) -> ResolvedType:
+        """Resolve a response $ref."""
+        target_response = self.ref_resolver.resolve_response_ref(ref)
+        if not target_response:
+            logger.warning(f"Could not resolve response reference: {ref}")
+            return ResolvedType(python_type="None")
+
+        return self.resolve_specific_response(target_response, context)
+
+    def _get_primary_response(self, operation: IROperation) -> Optional[IRResponse]:
+        """Get the primary success response from an operation."""
+        if not operation.responses:
+            return None
+
+        # Priority order: 200, 201, 202, 204, other 2xx, default
+        for code in ["200", "201", "202", "204"]:
+            for response in operation.responses:
+                if response.status_code == code:
+                    return response
+
+        # Other 2xx responses
+        for response in operation.responses:
+            if response.status_code.startswith("2"):
+                return response
+
+        # Default response
+        for response in operation.responses:
+            if response.status_code == "default":
+                return response
+
+        # First response as fallback
+        return operation.responses[0] if operation.responses else None
+
+    def _get_response_schema(self, response: IRResponse) -> IRSchema | None:
+        """Get the schema from a response's content."""
+        if not response.content:
+            return None
+
+        # Prefer application/json
+        content_types = list(response.content.keys())
+        content_type = None
+
+        if "application/json" in content_types:
+            content_type = "application/json"
+        elif any("json" in ct for ct in content_types):
+            content_type = next(ct for ct in content_types if "json" in ct)
+        elif content_types:
+            content_type = content_types[0]
+
+        if not content_type:
+            return None
+
+        return response.content.get(content_type)
+
+    def _try_unwrap_data_property(self, schema: IRSchema | None, context: TypeContext) -> Optional[ResolvedType]:
+        """
+        Try to unwrap a 'data' property if the schema is a wrapper.
+
+        Returns unwrapped type or None if not applicable.
+        """
+        if not schema or not hasattr(schema, "type") or schema.type != "object":
+            return None
+
+        properties = getattr(schema, "properties", None)
+        if not properties or len(properties) != 1:
+            return None
+
+        # Check for 'data' property
+        data_property = properties.get("data")
+        if not data_property:
+            return None
+
+        logger.info(f"Unwrapping 'data' property from response schema")
+        return self.schema_resolver.resolve_schema(data_property, context, required=True)
+
+    def _resolve_streaming_response(self, response: IRResponse, context: TypeContext) -> ResolvedType:
+        """
+        Resolve a streaming response to an AsyncIterator type.
+
+        Args:
+            response: The streaming response
+            context: Type resolution context
+
+        Returns:
+            ResolvedType with AsyncIterator type
+        """
+        # Add AsyncIterator import
+        context.add_import("typing", "AsyncIterator")
+
+        # Determine the item type for the stream
+        if not response.content:
+            # Binary stream with no specific content type
+            return ResolvedType(python_type="AsyncIterator[bytes]")
+
+        # Check for binary content types
+        content_types = list(response.content.keys())
+        is_binary = any(
+            ct in ["application/octet-stream", "application/pdf"] or ct.startswith(("image/", "audio/", "video/"))
+            for ct in content_types
+        )
+
+        if is_binary:
+            return ResolvedType(python_type="AsyncIterator[bytes]")
+
+        # For event streams (text/event-stream) or JSON streams
+        is_event_stream = any("event-stream" in ct for ct in content_types)
+        if is_event_stream:
+            context.add_import("typing", "Dict")
+            context.add_import("typing", "Any")
+            return ResolvedType(python_type="AsyncIterator[Dict[str, Any]]")
+
+        # For other streaming content, try to resolve the schema
+        schema = self._get_response_schema(response)
+        if schema:
+            resolved = self.schema_resolver.resolve_schema(schema, context, required=True)
+            return ResolvedType(python_type=f"AsyncIterator[{resolved.python_type}]")
+
+        # Default to bytes if we can't determine the type
+        return ResolvedType(python_type="AsyncIterator[bytes]")