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

pyopenapi_gen/__init__.py

@@ -42,8 +42,8 @@ __all__ = [
     "WarningCollector",
 ]
 
-# Semantic version of the generator core – bumped manually for now.
-__version__: str = "0.6.0"
+# Semantic version of the generator core – automatically managed by semantic-release.
+__version__: str = "0.9.0"
 
 
 # ---------------------------------------------------------------------------

pyopenapi_gen/context/CLAUDE.md

@@ -0,0 +1,284 @@
+# context/ - Rendering Context Management
+
+## Why This Folder?
+Manage stateful information during code generation: imports, templates, file paths, and rendering state. Provides clean interface between visitors and emitters.
+
+## Key Dependencies
+- **Input**: Path configuration, package names, template data
+- **Output**: Import statements, resolved file paths, template rendering
+- **Used by**: All visitors and emitters for consistent code generation
+
+## Essential Architecture
+
+### 1. Context Lifecycle
+```python
+# 1. Create context for generation session
+context = RenderContext(project_root="/path/to/project", output_package="my_client")
+
+# 2. Visitors use context for type resolution and imports
+visitor.visit_schema(schema, context)  # Registers imports
+
+# 3. Emitters use context for file organization
+emitter.emit_models(schemas, context)  # Consumes imports
+```
+
+### 2. State Management
+```python
+# render_context.py
+class RenderContext:
+    def __init__(self, project_root: Path, output_package: str):
+        self.import_collector = ImportCollector()
+        self.file_manager = FileManager(project_root)
+        self.template_vars = {}
+        self.output_package = output_package
+        self.forward_refs = set()
+```
+
+## Critical Components
+
+### render_context.py
+**Purpose**: Main context object passed through generation pipeline
+```python
+class RenderContext:
+    def add_import(self, import_statement: str) -> None:
+        """Register import for current file being generated"""
+        self.import_collector.add_import(import_statement)
+    
+    def get_imports(self) -> List[str]:
+        """Get sorted, deduplicated imports for current file"""
+        return self.import_collector.get_sorted_imports()
+    
+    def clear_imports(self) -> None:
+        """Clear imports for next file generation"""
+        self.import_collector.clear()
+    
+    def resolve_relative_import(self, from_package: str, to_package: str) -> str:
+        """Convert absolute import to relative import"""
+        return self.import_collector.make_relative_import(from_package, to_package)
+```
+
+### import_collector.py
+**Purpose**: Collect and manage import statements during code generation
+```python
+class ImportCollector:
+    def __init__(self):
+        self.imports: Set[str] = set()
+        self.from_imports: Dict[str, Set[str]] = defaultdict(set)
+    
+    def add_import(self, import_statement: str) -> None:
+        """Add import statement, handling both 'import' and 'from' forms"""
+        if import_statement.startswith("from "):
+            self.parse_from_import(import_statement)
+        else:
+            self.imports.add(import_statement)
+    
+    def get_sorted_imports(self) -> List[str]:
+        """Return sorted imports: stdlib, third-party, local"""
+        return self.sort_imports_by_category()
+```
+
+### file_manager.py
+**Purpose**: Handle file operations and path resolution
+```python
+class FileManager:
+    def __init__(self, project_root: Path):
+        self.project_root = project_root
+    
+    def write_file(self, file_path: Path, content: str) -> None:
+        """Write file with proper directory creation"""
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        file_path.write_text(content)
+    
+    def resolve_package_path(self, package_name: str) -> Path:
+        """Convert package.name to file system path"""
+        parts = package_name.split(".")
+        return self.project_root / Path(*parts)
+```
+
+## Import Management Patterns
+
+### 1. Import Categories
+```python
+# import_collector.py
+def categorize_import(self, import_statement: str) -> ImportCategory:
+    """Categorize imports for proper sorting"""
+    if self.is_stdlib_import(import_statement):
+        return ImportCategory.STDLIB
+    elif self.is_third_party_import(import_statement):
+        return ImportCategory.THIRD_PARTY
+    else:
+        return ImportCategory.LOCAL
+```
+
+### 2. From Import Consolidation
+```python
+# Convert multiple from imports to single statement
+# "from typing import List"
+# "from typing import Dict"
+# →
+# "from typing import Dict, List"
+
+def consolidate_from_imports(self) -> List[str]:
+    consolidated = []
+    for module, imports in self.from_imports.items():
+        sorted_imports = sorted(imports)
+        consolidated.append(f"from {module} import {', '.join(sorted_imports)}")
+    return consolidated
+```
+
+### 3. Relative Import Conversion
+```python
+def make_relative_import(self, from_package: str, to_package: str) -> str:
+    """Convert absolute import to relative import"""
+    # from my_client.models.user import User
+    # →
+    # from ..models.user import User (when called from my_client.endpoints)
+    
+    from_parts = from_package.split(".")
+    to_parts = to_package.split(".")
+    
+    # Find common prefix
+    common_len = self.find_common_prefix_length(from_parts, to_parts)
+    
+    # Calculate relative depth
+    relative_depth = len(from_parts) - common_len
+    prefix = "." * relative_depth
+    
+    # Build relative import
+    remaining_path = ".".join(to_parts[common_len:])
+    return f"from {prefix}{remaining_path} import"
+```
+
+## Template Management
+
+### 1. Template Variables
+```python
+# Store template variables for consistent rendering
+context.template_vars.update({
+    "client_name": "MyAPIClient",
+    "base_url": "https://api.example.com",
+    "version": "1.0.0",
+    "auth_type": "bearer"
+})
+```
+
+### 2. Template Rendering
+```python
+def render_template(self, template: str, **kwargs) -> str:
+    """Render template with context variables"""
+    all_vars = {**self.template_vars, **kwargs}
+    return template.format(**all_vars)
+```
+
+## Dependencies on Other Systems
+
+### From types/
+- Implements `TypeContext` protocol for type resolution
+- Provides import registration for complex types
+
+### From visit/
+- Receives import registration during code generation
+- Provides path resolution for relative imports
+
+### From emitters/
+- Provides file writing capabilities
+- Supplies consolidated imports for file headers
+
+## Testing Requirements
+
+### Import Management Tests
+```python
+def test_import_collector__multiple_from_imports__consolidates_correctly():
+    # Arrange
+    collector = ImportCollector()
+    collector.add_import("from typing import List")
+    collector.add_import("from typing import Dict")
+    
+    # Act
+    imports = collector.get_sorted_imports()
+    
+    # Assert
+    assert "from typing import Dict, List" in imports
+```
+
+### Path Resolution Tests
+```python
+def test_file_manager__package_path__resolves_correctly():
+    # Test package name to file path conversion
+    manager = FileManager(Path("/project"))
+    path = manager.resolve_package_path("my_client.models")
+    
+    assert path == Path("/project/my_client/models")
+```
+
+## Extension Points
+
+### Custom Import Sorting
+```python
+class CustomImportCollector(ImportCollector):
+    def sort_imports_by_category(self) -> List[str]:
+        # Custom import sorting logic
+        # Example: Group all async imports together
+        pass
+```
+
+### Template System Integration
+```python
+def add_template_engine(self, engine: TemplateEngine) -> None:
+    """Add custom template engine (Jinja2, etc.)"""
+    self.template_engine = engine
+    
+def render_template(self, template_name: str, **kwargs) -> str:
+    """Render template using custom engine"""
+    return self.template_engine.render(template_name, **kwargs)
+```
+
+## Critical Implementation Details
+
+### Thread Safety
+```python
+# Context is NOT thread-safe by design
+# Each generation session gets its own context instance
+def create_context() -> RenderContext:
+    return RenderContext(project_root, output_package)
+```
+
+### Memory Management
+```python
+# Clear context between files to prevent memory leaks
+def emit_file(self, file_path: Path, generator_func: Callable) -> None:
+    self.context.clear_imports()
+    
+    # Generate code
+    code = generator_func(self.context)
+    
+    # Write file with imports
+    imports = self.context.get_imports()
+    final_code = self.combine_imports_and_code(imports, code)
+    
+    self.file_manager.write_file(file_path, final_code)
+```
+
+### Error Context
+```python
+# Always provide context in error messages
+def add_import_with_context(self, import_statement: str, file_context: str) -> None:
+    try:
+        self.import_collector.add_import(import_statement)
+    except Exception as e:
+        raise ImportError(f"Failed to add import '{import_statement}' in {file_context}: {e}")
+```
+
+## Common Pitfalls
+
+1. **Import Leakage**: Not clearing imports between files
+2. **Path Confusion**: Using absolute paths instead of relative
+3. **State Mutation**: Modifying context from multiple threads
+4. **Memory Leaks**: Not cleaning up context after generation
+
+## Best Practices
+
+1. **One Context Per Session**: Create new context for each generation
+2. **Clear Between Files**: Always clear imports between file generations
+3. **Use Relative Imports**: Convert absolute imports to relative
+4. **Error Context**: Include file/operation context in errors

pyopenapi_gen/context/import_collector.py

@@ -274,10 +274,10 @@ class ImportCollector:
                 is_core_module_to_be_absolute = True
 
             if is_core_module_to_be_absolute:
-                import_statement = f"from {module_name} import {", ".join(names)}"
+                import_statement = f"from {module_name} import {', '.join(names)}"
                 standard_import_lines.append(import_statement)
             elif is_stdlib_module:
-                import_statement = f"from {module_name} import {", ".join(names)}"
+                import_statement = f"from {module_name} import {', '.join(names)}"
                 standard_import_lines.append(import_statement)
             elif (
                 current_module_dot_path_to_use
@@ -286,13 +286,13 @@ class ImportCollector:
             ):
                 try:
                     relative_module = make_relative_import(current_module_dot_path_to_use, module_name)
-                    import_statement = f"from {relative_module} import {", ".join(names)}"
+                    import_statement = f"from {relative_module} import {', '.join(names)}"
                     standard_import_lines.append(import_statement)
                 except ValueError as e:
-                    import_statement = f"from {module_name} import {", ".join(names)}"
+                    import_statement = f"from {module_name} import {', '.join(names)}"
                     standard_import_lines.append(import_statement)
             else:
-                import_statement = f"from {module_name} import {", ".join(names)}"
+                import_statement = f"from {module_name} import {', '.join(names)}"
                 standard_import_lines.append(import_statement)
 
         plain_import_lines: List[str] = []
@@ -331,7 +331,7 @@ class ImportCollector:
 
         for module in stdlib_modules:
             names = sorted(self.imports[module])
-            statements.append(f"from {module} import {", ".join(names)}")
+            statements.append(f"from {module} import {', '.join(names)}")
 
         # Then third-party and app imports
         other_modules = sorted([m for m in self.imports.keys() if not _is_stdlib(m)])
@@ -341,7 +341,7 @@ class ImportCollector:
 
         for module in other_modules:
             names = sorted(self.imports[module])
-            statements.append(f"from {module} import {", ".join(names)}")
+            statements.append(f"from {module} import {', '.join(names)}")
 
         # Then plain imports
         if self.plain_imports:
@@ -357,7 +357,7 @@ class ImportCollector:
 
         for module in sorted(self.relative_imports.keys()):
             names = sorted(self.relative_imports[module])
-            statements.append(f"from {module} import {", ".join(names)}")
+            statements.append(f"from {module} import {', '.join(names)}")
 
         return "\n".join(statements)
 

pyopenapi_gen/core/CLAUDE.md

@@ -0,0 +1,224 @@
+# core/ - OpenAPI Parsing and Runtime Components
+
+## Why This Folder?
+Raw OpenAPI spec → Intermediate Representation (IR) transformation. Contains parsing logic, cycle detection, and runtime components that get copied to generated clients.
+
+## Key Dependencies
+- **Input**: Raw OpenAPI spec dicts from YAML/JSON
+- **Output**: `IRSpec`, `IRSchema`, `IRResponse`, `IROperation` objects
+- **Runtime**: Components copied to generated clients (`auth/`, `exceptions.py`, `http_transport.py`)
+
+## Essential Architecture
+
+### 1. Parsing Pipeline
+```mermaid
+graph LR
+    A[Raw OpenAPI] --> B[loader/] --> C[parsing/] --> D[IRSpec]
+    B --> E[schemas/extractor.py]
+    C --> F[unified_cycle_detection.py]
+    C --> G[transformers/]
+```
+
+### 2. Cycle Detection State Machine
+```python
+# parsing/unified_cycle_detection.py
+@dataclass
+class CycleInfo:
+    type: CycleType  # STRUCTURAL, SELF_REF, DEPTH_LIMIT
+    action: CycleAction  # PLACEHOLDER, FORWARD_REF, DEPTH_CUTOFF
+    depth: int
+    
+# Usage in parsing
+if context.detect_cycle(schema_name, current_depth):
+    return create_cycle_placeholder(schema_name, cycle_info)
+```
+
+## Critical Components
+
+### parsing/schema_parser.py
+**Purpose**: Main schema parsing with cycle detection
+```python
+def parse_schema(schema_data: Dict[str, Any], context: ParsingContext) -> IRSchema:
+    # 1. Cycle detection
+    # 2. Keyword parsing (allOf, oneOf, anyOf)
+    # 3. Transformer application
+    # 4. IR object creation
+```
+
+### parsing/transformers/
+**Purpose**: Modify parsed schemas before IR creation
+- **inline_enum_extractor.py**: Extract inline enums to global schemas
+- **inline_object_promoter.py**: Promote inline objects to named schemas
+
+### loader/
+**Purpose**: Load and validate OpenAPI specs
+```python
+# loader/loader.py
+def load_spec(spec_path: str) -> IRSpec:
+    # 1. Load YAML/JSON
+    # 2. Validate OpenAPI format
+    # 3. Parse operations, schemas, responses
+    # 4. Build IRSpec
+```
+
+### Runtime Components (Copied to Clients)
+
+#### auth/
+```python
+# auth/base.py - Base authentication classes
+class AuthBase(ABC):
+    async def apply_auth(self, request: httpx.Request) -> httpx.Request:
+        # Modify request with auth info
+        
+# auth/plugins.py - Concrete implementations
+class BearerAuth(AuthBase):
+    def __init__(self, token: str): ...
+```
+
+#### exceptions.py
+```python
+# Exception hierarchy for generated clients
+class ClientError(Exception): ...
+class ServerError(ClientError): ...
+class ValidationError(ClientError): ...
+```
+
+#### http_transport.py
+```python
+# HTTP client abstraction
+class HTTPTransport:
+    def __init__(self, base_url: str, auth: Optional[AuthBase] = None):
+        self.client = httpx.AsyncClient(base_url=base_url)
+```
+
+## Environment Variables
+```python
+# parsing/unified_cycle_detection.py
+PYOPENAPI_MAX_DEPTH = int(os.getenv("PYOPENAPI_MAX_DEPTH", "150"))
+PYOPENAPI_MAX_CYCLES = int(os.getenv("PYOPENAPI_MAX_CYCLES", "0"))
+```
+
+## Dependencies on Other Systems
+
+### From types/
+- Schema → Python type conversion after parsing
+- Type resolution for complex compositions
+
+### From context/
+- `ParsingContext` for cycle detection state
+- Import management during parsing
+
+### To visit/
+- Provides `IRSpec` for visitor pattern traversal
+- IR objects consumed by code generators
+
+## Common Parsing Patterns
+
+### 1. Keyword Composition
+```python
+# parsing/keywords/all_of_parser.py
+def parse_all_of(all_of_items: List[Dict], context: ParsingContext) -> IRSchema:
+    # Merge all schemas into single IR object
+    merged_schema = IRSchema(type="object")
+    for item in all_of_items:
+        parsed_item = parse_schema(item, context)
+        merged_schema = merge_schemas(merged_schema, parsed_item)
+    return merged_schema
+```
+
+### 2. Reference Resolution
+```python
+# parsing/common/ref_resolution/resolve_schema_ref.py
+def resolve_schema_ref(ref: str, context: ParsingContext) -> IRSchema:
+    if ref.startswith("#/components/schemas/"):
+        schema_name = ref.split("/")[-1]
+        return context.get_schema(schema_name)
+    raise ValueError(f"Unsupported ref: {ref}")
+```
+
+### 3. Cycle Detection
+```python
+# parsing/unified_cycle_detection.py
+def detect_cycle(schema_name: str, current_depth: int, context: ParsingContext) -> Optional[CycleInfo]:
+    if current_depth > PYOPENAPI_MAX_DEPTH:
+        return CycleInfo(CycleType.DEPTH_LIMIT, CycleAction.DEPTH_CUTOFF, current_depth)
+    
+    if schema_name in context.parsing_stack:
+        return CycleInfo(CycleType.STRUCTURAL, CycleAction.PLACEHOLDER, current_depth)
+    
+    return None
+```
+
+## Testing Requirements
+
+### Parser Tests
+```python
+def test_parse_schema__all_of_composition__merges_correctly():
+    # Test keyword parsers with real OpenAPI data
+    schema_data = {
+        "allOf": [
+            {"type": "object", "properties": {"name": {"type": "string"}}},
+            {"type": "object", "properties": {"age": {"type": "integer"}}}
+        ]
+    }
+    # Test parsing result
+```
+
+### Cycle Detection Tests
+```python
+def test_unified_cycle_detection__structural_cycle__creates_placeholder():
+    # Test cycle detection with circular references
+    context = ParsingContext()
+    # Create circular reference scenario
+    # Verify placeholder creation
+```
+
+## Extension Points
+
+### Adding New Keywords
+```python
+# parsing/keywords/new_keyword_parser.py
+def parse_new_keyword(keyword_data: Any, context: ParsingContext) -> IRSchema:
+    # Custom keyword parsing logic
+    pass
+```
+
+### Adding New Transformers
+```python
+# parsing/transformers/new_transformer.py
+def transform_schema(schema: IRSchema, context: ParsingContext) -> IRSchema:
+    # Custom transformation logic
+    return modified_schema
+```
+
+## Critical Implementation Details
+
+### IR Object Creation
+```python
+# Always use IRSchema constructor with all required fields
+schema = IRSchema(
+    name=schema_name,
+    type=schema_type,
+    properties=properties,
+    required=required_fields,
+    description=description,
+    enum=enum_values,
+    is_nullable=is_nullable
+)
+```
+
+### Context State Management
+```python
+# parsing/context.py
+class ParsingContext:
+    def __init__(self):
+        self.parsed_schemas: Dict[str, IRSchema] = {}
+        self.parsing_stack: List[str] = []  # For cycle detection
+        self.forward_refs: Set[str] = set()
+        
+    def enter_schema(self, schema_name: str):
+        self.parsing_stack.append(schema_name)
+        
+    def exit_schema(self, schema_name: str):
+        self.parsing_stack.remove(schema_name)
+```

pyopenapi_gen/core/loader/operations/parser.py

@@ -120,7 +120,7 @@ def parse_operations(
                         # Handle direct schema references in responses
                         # Convert schema reference to a response with content
                         resp_node_resolved = {
-                            "description": f"Response with {rn_node["$ref"].split("/")[-1]} schema",
+                            "description": f"Response with {rn_node['$ref'].split('/')[-1]} schema",
                             "content": {"application/json": {"schema": {"$ref": rn_node["$ref"]}}},
                         }
                     else:

pyopenapi_gen/core/parsing/cycle_helpers.py

@@ -92,7 +92,7 @@ def _handle_max_depth_exceeded(original_name: Optional[str], context: ParsingCon
 
     # path_prefix = schema_ir_name_attr if schema_ir_name_attr else "<anonymous_schema>"
     # cycle_path_for_desc = f"{path_prefix} -> MAX_DEPTH_EXCEEDED"
-    description = f"[Maximum recursion depth ({max_depth}) exceeded for '{original_name or "anonymous"}']"
+    description = f"[Maximum recursion depth ({max_depth}) exceeded for '{original_name or 'anonymous'}']"
     logger.warning(description)
 
     placeholder_schema = IRSchema(

pyopenapi_gen/core/parsing/keywords/properties_parser.py

@@ -81,15 +81,15 @@ def _parse_properties(
         if promoted_ir is not None:
             properties_map[prop_key] = promoted_ir
             logger.debug(
-                f"Added promoted '{prop_key}' (name: {getattr(promoted_ir, "name", "N/A")}) "
+                f"Added promoted '{prop_key}' (name: {getattr(promoted_ir, 'name', 'N/A')}) "
                 f"to properties_map for '{parent_schema_name}'"
             )
         else:
             properties_map[prop_key] = prop_schema_ir
             logger.debug(
-                f"Added original '{prop_key}' (name: {getattr(prop_schema_ir, "name", "N/A")}, "
-                f"type: {getattr(prop_schema_ir, "type", "N/A")}, "
-                f"circular: {getattr(prop_schema_ir, "_is_circular_ref", "N/A")}) "
+                f"Added original '{prop_key}' (name: {getattr(prop_schema_ir, 'name', 'N/A')}, "
+                f"type: {getattr(prop_schema_ir, 'type', 'N/A')}, "
+                f"circular: {getattr(prop_schema_ir, '_is_circular_ref', 'N/A')}) "
                 f"to properties_map for '{parent_schema_name}'"
             )
 

pyopenapi_gen/core/parsing/schema_parser.py

@@ -42,7 +42,7 @@ def _resolve_ref(
     if not (ref_name_parts and ref_name_parts[-1]):
         logger.warning(
             f"Malformed $ref path '{ref_path_str}' encountered while parsing "
-            f"parent '{parent_schema_name or "anonymous"}'."
+            f"parent '{parent_schema_name or 'anonymous'}'."
         )
         return IRSchema(
             name=None,  # Anonymous placeholder for a bad ref
@@ -60,7 +60,7 @@ def _resolve_ref(
     ref_node = context.raw_spec_schemas.get(ref_name)
     if ref_node is None:
         logger.warning(
-            f"Cannot resolve $ref '{ref_path_str}' for parent '{parent_schema_name or "anonymous"}'. "
+            f"Cannot resolve $ref '{ref_path_str}' for parent '{parent_schema_name or 'anonymous'}'. "
             f"Target '{ref_name}' not in raw_spec_schemas. Returning placeholder."
         )
         return IRSchema(
@@ -142,7 +142,7 @@ def _parse_properties(
     for prop_name, prop_schema_node in properties_node.items():
         if not isinstance(prop_name, str) or not prop_name:
             logger.warning(
-                f"Skipping property with invalid name '{prop_name}' in schema '{parent_schema_name or "anonymous"}'."
+                f"Skipping property with invalid name '{prop_name}' in schema '{parent_schema_name or 'anonymous'}'."
             )
             continue
 
@@ -379,7 +379,7 @@ def _parse_schema(
 
         assert isinstance(
             schema_node, Mapping
-        ), f"Schema node for '{schema_name or "anonymous"}' must be a Mapping (e.g., dict), got {type(schema_node)}"
+        ), f"Schema node for '{schema_name or 'anonymous'}' must be a Mapping (e.g., dict), got {type(schema_node)}"
 
         # If the current schema_node itself is a $ref, resolve it.
         if "$ref" in schema_node:

pyopenapi_gen/core/parsing/transformers/inline_enum_extractor.py

@@ -179,7 +179,7 @@ def _process_standalone_inline_enum(
 
     logger.debug(
         f"STANDALONE_ENUM_CHECK: Processing node for "
-        f"'{schema_name or schema_obj.name or "anonymous_schema"}' for direct enum properties."
+        f"'{schema_name or schema_obj.name or 'anonymous_schema'}' for direct enum properties."
     )
 
     # Ensure basic enum properties are on schema_obj if not already there from initial _parse_schema pass

pyopenapi_gen/core/writers/python_construct_renderer.py

@@ -262,7 +262,7 @@ class PythonConstructRenderer:
 
             # Sort mappings for consistent output
             for api_field, python_field in sorted(field_mappings.items()):
-                writer.write_line(f"'{api_field}': '{python_field}',")
+                writer.write_line(f'"{api_field}": "{python_field}",')
 
             writer.dedent()
             writer.write_line("}")
@@ -302,7 +302,7 @@ class PythonConstructRenderer:
             ```
         """
         writer = CodeWriter()
-        bases = f"({", ".join(base_classes)})" if base_classes else ""
+        bases = f"({', '.join(base_classes)})" if base_classes else ""
         writer.write_line(f"class {class_name}{bases}:")
         writer.indent()
         has_content = False