pyopenapi-gen 2.7.2__py3-none-any.whl

pyopenapi_gen/http_types.py

@@ -0,0 +1,20 @@
+from enum import Enum, unique
+
+
+@unique
+class HTTPMethod(str, Enum):
+    """Canonical HTTP method names supported by OpenAPI.
+
+    Implemented as `str` subclass to allow seamless usage anywhere a plain
+    string is expected (e.g., httpx, logging), while still providing strict
+    enumeration benefits.
+    """
+
+    GET = "GET"
+    POST = "POST"
+    PUT = "PUT"
+    PATCH = "PATCH"
+    DELETE = "DELETE"
+    OPTIONS = "OPTIONS"
+    HEAD = "HEAD"
+    TRACE = "TRACE"

pyopenapi_gen/ir.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, List, 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: str | None = None
+    type: str | None = None  # E.g., "object", "array", "string", or a reference to another schema name
+    format: str | None = None
+    description: str | None = None
+    required: List[str] = field(default_factory=list)
+    properties: dict[str, IRSchema] = field(default_factory=dict)
+    items: IRSchema | None = None  # For type: "array"
+    enum: List[Any] | None = None
+    default: Any | None = None  # Added default value
+    example: Any | None = None  # Added example value
+    additional_properties: Union[bool, IRSchema] | None = None  # True, False, or an IRSchema
+    is_nullable: bool = False
+    any_of: List[IRSchema] | None = None
+    one_of: List[IRSchema] | None = None
+    all_of: List[IRSchema] | None = None  # Store the list of IRSchema objects from allOf
+    title: str | None = 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: IRSchema | None = (
+        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: str | None = 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: str | None = field(default=None, repr=False)  # Path used for resolving inline names
+
+    # Fields for storing final, de-collided names for code generation
+    generation_name: str | None = field(default=None, repr=True)  # Final class/enum name
+    final_module_stem: str | None = 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: str | None = None
+    # example: Any | None = 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: str | None
+    content: dict[str, IRSchema]  # media‑type → schema mapping
+    stream: bool = False  # Indicates a binary or streaming response
+    stream_format: str | None = None  # Indicates the stream type
+
+
+@dataclass(slots=True)
+class IRRequestBody:
+    required: bool
+    content: dict[str, IRSchema]  # media‑type → schema mapping
+    description: str | None = None
+
+
+@dataclass(slots=True)
+class IROperation:
+    operation_id: str
+    method: HTTPMethod  # Enforced via enum for consistency
+    path: str  # e.g. "/pets/{petId}"
+    summary: str | None
+    description: str | None
+    parameters: List[IRParameter] = field(default_factory=list)
+    request_body: IRRequestBody | None = 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: str | None = 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/CLAUDE.md

@@ -0,0 +1,140 @@
+# types/ - Unified Type Resolution System
+
+## Why This Folder?
+Central, testable type resolution replacing scattered type conversion logic. Single source of truth for OpenAPI → Python type mappings with dependency injection architecture.
+
+## Key Dependencies
+- **Input**: `IRSchema`, `IRResponse`, `IROperation` from `../../ir.py`
+- **Output**: Python type strings (`str`, `List[User]`, `Optional[Dict[str, Any]]`)
+- **Context**: `RenderContext` from `../../context/render_context.py`
+
+## Essential Patterns
+
+### 1. Service → Resolvers → Contracts
+```python
+# Main entry point (services/)
+UnifiedTypeService → SchemaResolver/ResponseResolver → TypeContext protocol
+
+# Usage pattern
+type_service = UnifiedTypeService(schemas, responses)
+python_type = type_service.resolve_schema_type(schema, context, required=True)
+```
+
+### 2. Protocol-Based Dependency Injection
+```python
+# contracts/protocols.py - Define interfaces
+class TypeContext(Protocol):
+    def add_import(self, import_str: str) -> None: ...
+
+# resolvers/ - Use protocols, not concrete types
+def resolve_type(schema: IRSchema, context: TypeContext) -> str:
+    # Implementation uses context protocol
+```
+
+### 3. Error Handling
+```python
+from .contracts.types import TypeResolutionError
+
+# Always wrap resolution failures
+try:
+    return resolve_complex_type(schema)
+except Exception as e:
+    raise TypeResolutionError(f"Failed to resolve {schema.name}: {e}")
+```
+
+## Critical Implementation Details
+
+### Schema Type Resolution Priority
+1. **Enum**: `schema.enum` → `UserStatusEnum`
+2. **Named Reference**: `schema.type` as schema name → `User`
+3. **Primitive**: `schema.type` → `str`, `int`, `bool`
+4. **Array**: `schema.type="array"` → `List[ItemType]`
+5. **Object**: `schema.type="object"` → `Dict[str, Any]` or dataclass
+6. **Composition**: `allOf`/`oneOf`/`anyOf` → `Union[...]`
+
+### Forward Reference Handling
+```python
+# For circular dependencies
+if schema.name in context.forward_refs:
+    return f'"{schema.name}"'  # String annotation
+```
+
+### Response Unwrapping Logic
+```python
+# Detect wrapper responses with single 'data' field
+if (response.schema.type == "object" and 
+    "data" in response.schema.properties and 
+    len(response.schema.properties) == 1):
+    return resolve_schema_type(response.schema.properties["data"])
+```
+
+## Dependencies on Other Systems
+
+### From core/
+- `IRSchema`, `IRResponse`, `IROperation` definitions
+- Parsing context for cycle detection state
+
+### From context/
+- `RenderContext` for import management and rendering state
+- Import collection and deduplication
+
+### From helpers/ (Legacy)
+- `TypeHelper` delegates to `UnifiedTypeService`
+- Maintains backward compatibility during transition
+
+## Testing Requirements
+
+### Unit Test Pattern
+```python
+def test_resolve_schema_type__string_schema__returns_str():
+    # Arrange
+    schema = IRSchema(type="string")
+    mock_context = Mock(spec=TypeContext)
+    resolver = OpenAPISchemaResolver({})
+    
+    # Act
+    result = resolver.resolve_type(schema, mock_context)
+    
+    # Assert
+    assert result == "str"
+```
+
+### Integration Test Pattern
+```python
+def test_type_service__complex_schema__resolves_correctly():
+    # Test with real schemas and context
+    schemas = {"User": IRSchema(...)}
+    responses = {"UserResponse": IRResponse(...)}
+    service = UnifiedTypeService(schemas, responses)
+    # Test actual resolution
+```
+
+## Common Pitfalls
+
+1. **Context Mutation**: Always pass context, never mutate globally
+2. **Missing Imports**: Resolver must call `context.add_import()` for complex types
+3. **Circular Dependencies**: Check `context.forward_refs` before resolution
+4. **Error Swallowing**: Wrap exceptions in `TypeResolutionError`
+
+## Extension Points
+
+### Adding New Resolvers
+```python
+# Create new resolver implementing protocols
+class CustomResolver:
+    def resolve_type(self, schema: IRSchema, context: TypeContext) -> str:
+        # Custom logic
+        pass
+
+# Register in UnifiedTypeService
+service.register_resolver(CustomResolver())
+```
+
+### New Response Strategies
+```python
+# strategies/response_strategy.py
+class CustomResponseStrategy:
+    def should_unwrap(self, response: IRResponse) -> bool:
+        # Custom unwrapping logic
+        pass
+```

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 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) -> IRSchema | None:
+        """
+        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) -> IRResponse | None:
+        """
+        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,28 @@
+"""Core types for type resolution."""
+
+from dataclasses import dataclass
+
+
+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: str | None = None
+    import_name: str | None = None
+    is_optional: bool = False
+    is_forward_ref: 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
+
+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: Dict[str, IRResponse] | None = 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) -> IRSchema | None:
+        """
+        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) -> IRResponse | None:
+        """
+        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