pyopenapi-gen 0.8.6__py3-none-any.whl → 0.9.0__py3-none-any.whl

pyopenapi_gen/helpers/CLAUDE.md

@@ -0,0 +1,325 @@
+# helpers/ - Legacy Compatibility Layer
+
+## Why This Folder?
+Backward compatibility during transition to unified type system. Delegates to new `types/` system while maintaining old API surface for gradual migration.
+
+## Key Dependencies
+- **Delegates to**: `../types/services/UnifiedTypeService`
+- **Used by**: Legacy code that hasn't migrated to unified system
+- **Status**: Transitional - prefer `types/` for new code
+
+## Critical Architecture
+
+### 1. Legacy → Unified Delegation
+```python
+# type_helper.py
+class TypeHelper:
+    @staticmethod
+    def get_python_type_for_schema(schema: IRSchema, all_schemas: Dict[str, IRSchema], 
+                                   context: RenderContext, required: bool = True,
+                                   resolve_alias_target: bool = False) -> str:
+        """Legacy API - delegates to UnifiedTypeService"""
+        type_service = UnifiedTypeService(all_schemas)
+        return type_service.resolve_schema_type(
+            schema, context, required, resolve_underlying=resolve_alias_target
+        )
+```
+
+### 2. Type Resolution Subdirectory
+```python
+# type_resolution/ - Legacy individual resolvers
+# These now delegate to unified system components
+array_resolver.py → types/resolvers/schema_resolver.py
+composition_resolver.py → types/resolvers/schema_resolver.py
+object_resolver.py → types/resolvers/schema_resolver.py
+primitive_resolver.py → types/resolvers/schema_resolver.py
+```
+
+## Migration Strategy
+
+### 1. Deprecation Pattern
+```python
+import warnings
+from ..types.services import UnifiedTypeService
+
+def legacy_function(schema: IRSchema, context: RenderContext) -> str:
+    """
+    DEPRECATED: Use UnifiedTypeService.resolve_schema_type() instead.
+    This function will be removed in version 2.0.
+    """
+    warnings.warn(
+        "legacy_function is deprecated. Use UnifiedTypeService.resolve_schema_type()",
+        DeprecationWarning,
+        stacklevel=2
+    )
+    
+    # Delegate to new system
+    type_service = UnifiedTypeService({})
+    return type_service.resolve_schema_type(schema, context)
+```
+
+### 2. API Compatibility
+```python
+# Maintain old signatures while delegating
+def get_return_type(operation: IROperation, context: RenderContext, 
+                   schemas: Dict[str, IRSchema]) -> Tuple[str, bool]:
+    """Legacy endpoint_utils function"""
+    type_service = UnifiedTypeService(schemas)
+    return type_service.resolve_operation_response_with_unwrap_info(operation, context)
+```
+
+## Critical Components
+
+### type_helper.py
+**Purpose**: Main legacy entry point for type resolution
+```python
+class TypeHelper:
+    @staticmethod
+    def get_python_type_for_schema(schema: IRSchema, all_schemas: Dict[str, IRSchema], 
+                                   context: RenderContext, required: bool = True,
+                                   resolve_alias_target: bool = False) -> str:
+        """
+        Legacy type resolution - delegates to UnifiedTypeService
+        
+        Args:
+            schema: Schema to resolve
+            all_schemas: All schemas in spec (for references)
+            context: Render context for imports
+            required: Whether field is required (affects Optional[])
+            resolve_alias_target: Whether to resolve through aliases
+            
+        Returns:
+            Python type string
+        """
+        type_service = UnifiedTypeService(all_schemas)
+        return type_service.resolve_schema_type(
+            schema, context, required, resolve_underlying=resolve_alias_target
+        )
+```
+
+### endpoint_utils.py
+**Purpose**: Legacy endpoint-specific utilities
+```python
+def get_return_type(operation: IROperation, context: RenderContext, 
+                   schemas: Dict[str, IRSchema]) -> Tuple[str, bool]:
+    """
+    Legacy function for getting operation return type
+    
+    Returns:
+        Tuple of (python_type, was_unwrapped)
+    """
+    type_service = UnifiedTypeService(schemas)
+    return type_service.resolve_operation_response_with_unwrap_info(operation, context)
+
+def get_endpoint_return_types(operation: IROperation, context: RenderContext,
+                             schemas: Dict[str, IRSchema]) -> Dict[str, str]:
+    """Legacy function for getting all response types"""
+    type_service = UnifiedTypeService(schemas)
+    return type_service.resolve_all_response_types(operation, context)
+```
+
+### type_resolution/ Subdirectory
+**Purpose**: Legacy individual type resolvers
+
+#### array_resolver.py
+```python
+def resolve_array_type(schema: IRSchema, context: RenderContext, 
+                      all_schemas: Dict[str, IRSchema]) -> str:
+    """Legacy array type resolution"""
+    type_service = UnifiedTypeService(all_schemas)
+    return type_service.resolve_schema_type(schema, context)
+```
+
+#### composition_resolver.py
+```python
+def resolve_composition_type(schema: IRSchema, context: RenderContext,
+                           all_schemas: Dict[str, IRSchema]) -> str:
+    """Legacy composition (allOf/oneOf/anyOf) resolution"""
+    type_service = UnifiedTypeService(all_schemas)
+    return type_service.resolve_schema_type(schema, context)
+```
+
+## Usage Patterns (Legacy)
+
+### 1. Type Resolution
+```python
+# OLD WAY (still works, but deprecated)
+from pyopenapi_gen.helpers.type_helper import TypeHelper
+
+python_type = TypeHelper.get_python_type_for_schema(
+    schema, all_schemas, context, required=True
+)
+
+# NEW WAY (preferred)
+from pyopenapi_gen.types.services import UnifiedTypeService
+
+type_service = UnifiedTypeService(all_schemas)
+python_type = type_service.resolve_schema_type(schema, context, required=True)
+```
+
+### 2. Endpoint Type Resolution
+```python
+# OLD WAY (still works, but deprecated)
+from pyopenapi_gen.helpers.endpoint_utils import get_return_type
+
+return_type, was_unwrapped = get_return_type(operation, context, schemas)
+
+# NEW WAY (preferred)
+from pyopenapi_gen.types.services import UnifiedTypeService
+
+type_service = UnifiedTypeService(schemas)
+return_type, was_unwrapped = type_service.resolve_operation_response_with_unwrap_info(
+    operation, context
+)
+```
+
+## Migration Guide
+
+### 1. Type Helper Migration
+```python
+# Before
+from pyopenapi_gen.helpers.type_helper import TypeHelper
+
+class MyVisitor:
+    def resolve_type(self, schema: IRSchema) -> str:
+        return TypeHelper.get_python_type_for_schema(
+            schema, self.all_schemas, self.context, required=True
+        )
+
+# After
+from pyopenapi_gen.types.services import UnifiedTypeService
+
+class MyVisitor:
+    def __init__(self, all_schemas: Dict[str, IRSchema]):
+        self.type_service = UnifiedTypeService(all_schemas)
+    
+    def resolve_type(self, schema: IRSchema) -> str:
+        return self.type_service.resolve_schema_type(
+            schema, self.context, required=True
+        )
+```
+
+### 2. Endpoint Utils Migration
+```python
+# Before
+from pyopenapi_gen.helpers.endpoint_utils import get_return_type
+
+def generate_method(self, operation: IROperation):
+    return_type, was_unwrapped = get_return_type(operation, self.context, self.schemas)
+
+# After
+from pyopenapi_gen.types.services import UnifiedTypeService
+
+def generate_method(self, operation: IROperation):
+    return_type, was_unwrapped = self.type_service.resolve_operation_response_with_unwrap_info(
+        operation, self.context
+    )
+```
+
+## Testing Strategy
+
+### 1. Compatibility Tests
+```python
+def test_type_helper__legacy_api__matches_unified_service():
+    """Ensure legacy API produces same results as unified service"""
+    
+    # Test with legacy API
+    legacy_result = TypeHelper.get_python_type_for_schema(
+        schema, all_schemas, context, required=True
+    )
+    
+    # Test with unified service
+    type_service = UnifiedTypeService(all_schemas)
+    unified_result = type_service.resolve_schema_type(
+        schema, context, required=True
+    )
+    
+    assert legacy_result == unified_result
+```
+
+### 2. Deprecation Warning Tests
+```python
+def test_legacy_function__emits_deprecation_warning():
+    """Ensure legacy functions emit deprecation warnings"""
+    
+    with warnings.catch_warnings(record=True) as w:
+        warnings.simplefilter("always")
+        
+        # Call legacy function
+        TypeHelper.get_python_type_for_schema(schema, all_schemas, context)
+        
+        # Check warning was emitted
+        assert len(w) == 1
+        assert issubclass(w[0].category, DeprecationWarning)
+        assert "deprecated" in str(w[0].message)
+```
+
+## Removal Timeline
+
+### Phase 1: Deprecation (Current)
+- Add deprecation warnings to all legacy functions
+- Update internal code to use unified system
+- Maintain backward compatibility
+
+### Phase 2: Migration (Future)
+- Remove legacy functions
+- Update all external references
+- Remove helpers/ directory
+
+## Extension Points
+
+### Custom Legacy Adapters
+```python
+class CustomLegacyAdapter:
+    """Adapt old custom APIs to unified system"""
+    
+    def __init__(self, type_service: UnifiedTypeService):
+        self.type_service = type_service
+    
+    def old_custom_method(self, schema: IRSchema) -> str:
+        # Convert old API to new unified service call
+        return self.type_service.resolve_schema_type(schema, context)
+```
+
+## Critical Implementation Details
+
+### Error Handling
+```python
+def legacy_function(schema: IRSchema) -> str:
+    """Legacy function with error handling"""
+    try:
+        # Delegate to unified system
+        return unified_function(schema)
+    except Exception as e:
+        # Convert unified errors to legacy error format
+        raise LegacyError(f"Legacy function failed: {e}")
+```
+
+### Performance Considerations
+```python
+# Cache UnifiedTypeService instances to avoid recreation
+_type_service_cache = {}
+
+def get_cached_type_service(schemas: Dict[str, IRSchema]) -> UnifiedTypeService:
+    """Get cached type service for performance"""
+    schema_hash = hash(frozenset(schemas.keys()))
+    
+    if schema_hash not in _type_service_cache:
+        _type_service_cache[schema_hash] = UnifiedTypeService(schemas)
+    
+    return _type_service_cache[schema_hash]
+```
+
+## Common Pitfalls
+
+1. **Direct Usage**: Using legacy functions in new code
+2. **Missing Warnings**: Not emitting deprecation warnings
+3. **Inconsistent Results**: Legacy and unified APIs returning different results
+4. **Performance**: Creating new UnifiedTypeService instances repeatedly
+
+## Best Practices
+
+1. **Prefer Unified System**: Use `types/` for all new code
+2. **Emit Warnings**: Always emit deprecation warnings in legacy functions
+3. **Test Compatibility**: Ensure legacy and unified APIs return same results
+4. **Document Migration**: Provide clear migration paths in docstrings

pyopenapi_gen/helpers/endpoint_utils.py

@@ -308,10 +308,10 @@ def format_method_args(params: list[dict[str, Any]]) -> str:
     optional = [p for p in params if not p.get("required", True)]
     arg_strs = []
     for p in required:
-        arg_strs.append(f"{p["name"]}: {p["type"]}")
+        arg_strs.append(f"{p['name']}: {p['type']}")
     for p in optional:
         default = p["default"]
-        arg_strs.append(f"{p["name"]}: {p["type"]} = {default}")
+        arg_strs.append(f"{p['name']}: {p['type']} = {default}")
     return ", ".join(arg_strs)
 
 

pyopenapi_gen/helpers/type_cleaner.py

@@ -220,7 +220,7 @@ class TypeCleaner:
         if len(unique_members) == 1:
             return unique_members[0]  # A Union with one member is just that member.
 
-        return f"Union[{", ".join(unique_members)}]"
+        return f"Union[{', '.join(unique_members)}]"
 
     @classmethod
     def _clean_list_type(cls, type_str: str) -> str:

pyopenapi_gen/helpers/type_resolution/composition_resolver.py

@@ -73,7 +73,7 @@ class CompositionTypeResolver:
                 return unique_types[0]
 
             self.context.add_import("typing", "Union")
-            union_str = f"Union[{", ".join(unique_types)}]"
+            union_str = f"Union[{', '.join(unique_types)}]"
             return union_str
 
         return None

pyopenapi_gen/helpers/type_resolution/finalizer.py

@@ -23,7 +23,7 @@ class TypeFinalizer:
         if py_type is None:
             logger.warning(
                 f"[TypeFinalizer] Received None as py_type for schema "
-                f"'{schema.name or "anonymous"}'. Defaulting to 'Any'."
+                f"'{schema.name or 'anonymous'}'. Defaulting to 'Any'."
             )
             self.context.add_import("typing", "Any")
             py_type = "Any"

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/resolvers/schema_resolver.py

@@ -307,7 +307,7 @@ class OpenAPISchemaResolver(SchemaTypeResolver):
         # Sort types for consistent ordering
         resolved_types.sort()
         context.add_import("typing", "Union")
-        union_type = f"Union[{", ".join(resolved_types)}]"
+        union_type = f"Union[{', '.join(resolved_types)}]"
 
         return ResolvedType(python_type=union_type, is_optional=not required)
 
@@ -362,6 +362,6 @@ class OpenAPISchemaResolver(SchemaTypeResolver):
         # Sort types for consistent ordering
         resolved_types.sort()
         context.add_import("typing", "Union")
-        union_type = f"Union[{", ".join(resolved_types)}]"
+        union_type = f"Union[{', '.join(resolved_types)}]"
 
         return ResolvedType(python_type=union_type, is_optional=not required)