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

pyopenapi_gen/emitters/CLAUDE.md

@@ -0,0 +1,286 @@
+# emitters/ - File Organization and Output
+
+## Why This Folder?
+Transform visitor-generated code strings into properly structured Python packages. Handles file creation, import resolution, and package organization.
+
+## Key Dependencies
+- **Input**: Code strings from `../visit/` visitors
+- **Output**: Python files in target package structure
+- **Services**: `FileManager` from `../context/file_manager.py`
+- **Context**: `RenderContext` for import management
+
+## Essential Architecture
+
+### 1. Emitter Responsibilities
+```python
+# Each emitter handles one aspect of the generated client
+models_emitter.py     → models/ directory with dataclasses/enums
+endpoints_emitter.py  → endpoints/ directory with operation methods
+client_emitter.py     → client.py main interface
+core_emitter.py       → core/ directory with runtime dependencies
+exceptions_emitter.py → exceptions.py error hierarchy
+```
+
+### 2. Package Structure Creation
+```python
+# Target structure for generated client
+output_package/
+├── __init__.py           # Package initialization
+├── client.py            # Main client class
+├── models/              # Data models
+│   ├── __init__.py
+│   ├── user.py
+│   └── order.py
+├── endpoints/           # Operation methods
+│   ├── __init__.py
+│   ├── users.py
+│   └── orders.py
+├── core/                # Runtime dependencies
+│   ├── __init__.py
+│   ├── auth/
+│   ├── exceptions.py
+│   └── http_transport.py
+└── exceptions.py        # Exception hierarchy
+```
+
+## Critical Components
+
+### models_emitter.py
+**Purpose**: Create models/ directory with dataclass and enum files
+```python
+def emit_models(self, schemas: Dict[str, IRSchema], context: RenderContext) -> None:
+    # 1. Group schemas by module (one file per schema or logical grouping)
+    # 2. Generate code for each schema using ModelVisitor
+    # 3. Create __init__.py with imports
+    # 4. Write files to models/ directory
+    
+    for schema_name, schema in schemas.items():
+        module_name = self.get_module_name(schema_name)
+        file_path = self.output_path / "models" / f"{module_name}.py"
+        
+        # Generate model code
+        model_code = self.model_visitor.visit_schema(schema, context)
+        
+        # Write file
+        self.file_manager.write_file(file_path, model_code)
+```
+
+### endpoints_emitter.py
+**Purpose**: Create endpoints/ directory with operation methods grouped by tag
+```python
+def emit_endpoints(self, operations: List[IROperation], context: RenderContext) -> None:
+    # 1. Group operations by OpenAPI tag
+    operations_by_tag = self.group_by_tag(operations)
+    
+    # 2. Generate endpoint class for each tag
+    for tag, tag_operations in operations_by_tag.items():
+        class_name = f"{tag.capitalize()}Endpoints"
+        file_path = self.output_path / "endpoints" / f"{tag}.py"
+        
+        # Generate endpoint class code
+        endpoint_code = self.endpoint_visitor.visit_tag_operations(tag_operations, context)
+        
+        # Write file
+        self.file_manager.write_file(file_path, endpoint_code)
+```
+
+### client_emitter.py
+**Purpose**: Create main client.py with tag-grouped properties
+```python
+def emit_client(self, spec: IRSpec, context: RenderContext) -> None:
+    # 1. Generate main client class
+    # 2. Create properties for each tag endpoint
+    # 3. Generate context manager methods
+    # 4. Handle authentication setup
+    
+    client_code = self.client_visitor.visit_spec(spec, context)
+    self.file_manager.write_file(self.output_path / "client.py", client_code)
+```
+
+### core_emitter.py
+**Purpose**: Copy runtime dependencies to core/ directory
+```python
+def emit_core(self, output_package: str, core_package: str) -> None:
+    # 1. Copy auth/ directory
+    # 2. Copy exceptions.py, http_transport.py, etc.
+    # 3. Update import paths for target package
+    # 4. Handle shared core vs embedded core
+    
+    if self.use_shared_core:
+        # Create symlinks or references to shared core
+        pass
+    else:
+        # Copy all core files to client package
+        self.copy_core_files()
+```
+
+## File Management Patterns
+
+### 1. Import Resolution
+```python
+# Always resolve imports after code generation
+def write_file_with_imports(self, file_path: Path, code: str, context: RenderContext) -> None:
+    # 1. Collect imports from context
+    imports = context.get_imports()
+    
+    # 2. Sort and deduplicate imports
+    sorted_imports = self.sort_imports(imports)
+    
+    # 3. Combine imports with code
+    final_code = self.combine_imports_and_code(sorted_imports, code)
+    
+    # 4. Write file
+    self.file_manager.write_file(file_path, final_code)
+```
+
+### 2. Package Initialization
+```python
+# Always create __init__.py files
+def create_package_init(self, package_path: Path, exports: List[str]) -> None:
+    init_content = []
+    
+    # Add imports for all public exports
+    for export in exports:
+        init_content.append(f"from .{export} import {export}")
+    
+    # Add __all__ for explicit exports
+    init_content.append(f"__all__ = {exports}")
+    
+    self.file_manager.write_file(package_path / "__init__.py", "\n".join(init_content))
+```
+
+### 3. Relative Import Handling
+```python
+# Convert absolute imports to relative for generated packages
+def convert_to_relative_imports(self, code: str, current_package: str) -> str:
+    # Replace absolute imports with relative imports
+    # Example: "from my_client.models.user import User" → "from ..models.user import User"
+    
+    import_pattern = re.compile(rf"from {re.escape(current_package)}\.(.+?) import")
+    
+    def replace_import(match):
+        import_path = match.group(1)
+        depth = len(import_path.split("."))
+        relative_prefix = "." * depth
+        return f"from {relative_prefix}{import_path} import"
+    
+    return import_pattern.sub(replace_import, code)
+```
+
+## Dependencies on Other Systems
+
+### From visit/
+- Consumes generated code strings
+- Coordinates with visitors for code generation
+
+### From context/
+- `FileManager` for file operations
+- `RenderContext` for import management
+- Path resolution utilities
+
+### From core/
+- Runtime components copied to generated clients
+- Template files for package structure
+
+## Testing Requirements
+
+### File Creation Tests
+```python
+def test_models_emitter__simple_schema__creates_correct_file():
+    # Arrange
+    schema = IRSchema(name="User", type="object", properties={"name": {"type": "string"}})
+    emitter = ModelsEmitter(output_path="/tmp/test")
+    
+    # Act
+    emitter.emit_models({"User": schema}, context)
+    
+    # Assert
+    assert Path("/tmp/test/models/user.py").exists()
+    content = Path("/tmp/test/models/user.py").read_text()
+    assert "@dataclass" in content
+    assert "name: str" in content
+```
+
+### Import Resolution Tests
+```python
+def test_emitter__complex_types__resolves_imports_correctly():
+    # Test that imports are correctly collected and written
+    # Verify no duplicate imports
+    # Verify correct import sorting
+```
+
+## Extension Points
+
+### Adding New Emitters
+```python
+# Create new emitter for new output aspects
+class CustomEmitter:
+    def __init__(self, output_path: Path, file_manager: FileManager):
+        self.output_path = output_path
+        self.file_manager = file_manager
+    
+    def emit_custom(self, data: Any, context: RenderContext) -> None:
+        # Custom file creation logic
+        pass
+```
+
+### Custom Package Structures
+```python
+# Modify emitters to create different package layouts
+class AlternativeModelsEmitter(ModelsEmitter):
+    def get_file_path(self, schema_name: str) -> Path:
+        # Custom file organization logic
+        # Example: Group models by domain
+        domain = self.get_domain(schema_name)
+        return self.output_path / "models" / domain / f"{schema_name.lower()}.py"
+```
+
+## Critical Implementation Details
+
+### File Path Resolution
+```python
+# Always use pathlib.Path for cross-platform compatibility
+def get_output_path(self, package_name: str, module_name: str) -> Path:
+    # Convert package.module to file path
+    parts = package_name.split(".")
+    path = Path(self.project_root)
+    for part in parts:
+        path = path / part
+    return path / f"{module_name}.py"
+```
+
+### Error Handling
+```python
+def emit_safely(self, generator_func: Callable, context: RenderContext) -> None:
+    try:
+        generator_func(context)
+    except Exception as e:
+        # Add context to file emission errors
+        raise FileEmissionError(f"Failed to emit {self.__class__.__name__}: {e}")
+```
+
+### Atomic File Operations
+```python
+def write_file_atomically(self, file_path: Path, content: str) -> None:
+    # Write to temporary file first, then move
+    temp_path = file_path.with_suffix(f"{file_path.suffix}.tmp")
+    
+    try:
+        temp_path.write_text(content)
+        temp_path.replace(file_path)  # Atomic move
+    except Exception:
+        if temp_path.exists():
+            temp_path.unlink()
+        raise
+```
+
+### Diff Checking
+```python
+def should_write_file(self, file_path: Path, new_content: str) -> bool:
+    # Only write if content changed
+    if not file_path.exists():
+        return True
+    
+    existing_content = file_path.read_text()
+    return existing_content != new_content
+```

pyopenapi_gen/emitters/endpoints_emitter.py

@@ -211,7 +211,7 @@ class EndpointsEmitter:
         init_lines = []
         if unique_clients:
             all_list_items = sorted([f'"{cls}"' for cls, _ in unique_clients])
-            init_lines.append(f"__all__ = [{", ".join(all_list_items)}]")
+            init_lines.append(f"__all__ = [{', '.join(all_list_items)}]")
             for cls, mod in sorted(unique_clients):
                 init_lines.append(f"from .{mod} import {cls}")
 

pyopenapi_gen/generator/CLAUDE.md

@@ -0,0 +1,352 @@
+# generator/ - Main Orchestration
+
+## Why This Folder?
+High-level orchestration of the entire code generation pipeline. Coordinates loader → parser → visitors → emitters → post-processing flow.
+
+## Key Dependencies
+- **Input**: CLI arguments, OpenAPI spec path
+- **Output**: Complete generated client package
+- **Orchestrates**: All other system components
+- **Error Handling**: `GenerationError` for CLI reporting
+
+## Essential Architecture
+
+### 1. Generation Pipeline
+```python
+# client_generator.py
+def generate(self, spec_path: str, project_root: Path, output_package: str, 
+             force: bool = False, no_postprocess: bool = False, 
+             core_package: str = None) -> None:
+    
+    # 1. Load OpenAPI spec
+    spec = self.load_spec(spec_path)
+    
+    # 2. Parse to IR
+    ir_spec = self.parse_to_ir(spec)
+    
+    # 3. Generate code
+    self.generate_code(ir_spec, project_root, output_package, core_package)
+    
+    # 4. Post-process (format, typecheck)
+    if not no_postprocess:
+        self.post_process(project_root, output_package)
+```
+
+### 2. Diff Checking
+```python
+def generate_with_diff_check(self, ...) -> None:
+    if not force and self.output_exists():
+        # Generate to temporary location
+        temp_output = self.create_temp_output()
+        self.generate_to_path(temp_output)
+        
+        # Compare with existing
+        if self.has_changes(temp_output, self.final_output):
+            self.prompt_user_for_confirmation()
+        
+        # Move temp to final location
+        self.move_temp_to_final(temp_output, self.final_output)
+```
+
+## Critical Components
+
+### client_generator.py
+**Purpose**: Main entry point for all generation operations
+```python
+class ClientGenerator:
+    def __init__(self):
+        self.loader = SpecLoader()
+        self.parser = SpecParser()
+        self.type_service = None  # Created per generation
+        self.visitors = self.create_visitors()
+        self.emitters = self.create_emitters()
+        self.post_processor = PostProcessManager()
+    
+    def generate(self, spec_path: str, project_root: Path, output_package: str, 
+                 force: bool = False, no_postprocess: bool = False, 
+                 core_package: str = None) -> None:
+        """Main generation method called by CLI"""
+        try:
+            self.validate_inputs(spec_path, project_root, output_package)
+            self.run_generation_pipeline(...)
+        except Exception as e:
+            raise GenerationError(f"Generation failed: {e}")
+```
+
+### Generation Workflow
+```python
+def run_generation_pipeline(self, spec_path: str, project_root: Path, 
+                           output_package: str, core_package: str) -> None:
+    
+    # 1. Load and validate OpenAPI spec
+    raw_spec = self.loader.load(spec_path)
+    
+    # 2. Parse to intermediate representation
+    ir_spec = self.parser.parse(raw_spec)
+    
+    # 3. Create context for generation
+    context = RenderContext(project_root, output_package)
+    
+    # 4. Initialize type service
+    self.type_service = UnifiedTypeService(ir_spec.schemas, ir_spec.responses)
+    
+    # 5. Generate code using visitors
+    self.generate_models(ir_spec.schemas, context)
+    self.generate_endpoints(ir_spec.operations, context)
+    self.generate_client(ir_spec, context)
+    self.generate_exceptions(ir_spec.responses, context)
+    
+    # 6. Emit files using emitters
+    self.emit_all_files(ir_spec, context, core_package)
+    
+    # 7. Post-process (format, typecheck)
+    self.post_process_if_enabled(project_root, output_package)
+```
+
+## Error Handling Strategy
+
+### 1. Structured Error Hierarchy
+```python
+class GenerationError(Exception):
+    """Top-level error for CLI reporting"""
+    pass
+
+class ValidationError(GenerationError):
+    """Input validation failures"""
+    pass
+
+class ParsingError(GenerationError):
+    """OpenAPI parsing failures"""
+    pass
+
+class CodeGenerationError(GenerationError):
+    """Code generation failures"""
+    pass
+```
+
+### 2. Error Context Collection
+```python
+def handle_generation_error(self, error: Exception, context: Dict[str, Any]) -> None:
+    """Add context to errors for better debugging"""
+    error_context = {
+        "spec_path": context.get("spec_path"),
+        "output_package": context.get("output_package"),
+        "current_stage": context.get("current_stage"),
+        "current_schema": context.get("current_schema")
+    }
+    
+    detailed_message = f"Generation failed at {error_context['current_stage']}: {error}"
+    if error_context.get("current_schema"):
+        detailed_message += f" (processing schema: {error_context['current_schema']})"
+    
+    raise GenerationError(detailed_message) from error
+```
+
+## Visitor Coordination
+
+### 1. Visitor Initialization
+```python
+def create_visitors(self) -> Dict[str, Visitor]:
+    """Create all visitors with proper dependencies"""
+    return {
+        "model": ModelVisitor(self.type_service),
+        "endpoint": EndpointVisitor(self.type_service),
+        "client": ClientVisitor(self.type_service),
+        "exception": ExceptionVisitor(self.type_service),
+        "docs": DocsVisitor()
+    }
+```
+
+### 2. Visitor Execution
+```python
+def generate_models(self, schemas: Dict[str, IRSchema], context: RenderContext) -> None:
+    """Generate model code using visitor"""
+    model_codes = {}
+    
+    for schema_name, schema in schemas.items():
+        try:
+            # Generate code for single schema
+            code = self.visitors["model"].visit_schema(schema, context)
+            model_codes[schema_name] = code
+            
+        except Exception as e:
+            # Add schema context to error
+            context_info = {"current_schema": schema_name, "current_stage": "model_generation"}
+            self.handle_generation_error(e, context_info)
+    
+    # Store for emitters
+    self.generated_models = model_codes
+```
+
+## Emitter Coordination
+
+### 1. Emitter Initialization
+```python
+def create_emitters(self, output_path: Path) -> Dict[str, Emitter]:
+    """Create all emitters with proper configuration"""
+    file_manager = FileManager(output_path)
+    
+    return {
+        "models": ModelsEmitter(output_path, file_manager),
+        "endpoints": EndpointsEmitter(output_path, file_manager),
+        "client": ClientEmitter(output_path, file_manager),
+        "core": CoreEmitter(output_path, file_manager),
+        "exceptions": ExceptionsEmitter(output_path, file_manager)
+    }
+```
+
+### 2. Emitter Execution
+```python
+def emit_all_files(self, ir_spec: IRSpec, context: RenderContext, core_package: str) -> None:
+    """Emit all generated code to files"""
+    
+    # Emit in dependency order
+    self.emitters["core"].emit_core(context.output_package, core_package)
+    self.emitters["models"].emit_models(ir_spec.schemas, context)
+    self.emitters["endpoints"].emit_endpoints(ir_spec.operations, context)
+    self.emitters["exceptions"].emit_exceptions(ir_spec.responses, context)
+    self.emitters["client"].emit_client(ir_spec, context)
+```
+
+## Post-Processing
+
+### 1. Format and Typecheck
+```python
+def post_process(self, project_root: Path, output_package: str) -> None:
+    """Run Black formatting and mypy type checking"""
+    
+    package_path = self.resolve_package_path(project_root, output_package)
+    
+    # Format with Black
+    self.run_black_formatting(package_path)
+    
+    # Type check with mypy
+    self.run_mypy_checking(package_path)
+```
+
+### 2. Validation
+```python
+def validate_generated_code(self, package_path: Path) -> None:
+    """Validate generated code can be imported"""
+    
+    # Try to import generated client
+    try:
+        spec = importlib.util.spec_from_file_location("client", package_path / "client.py")
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+    except Exception as e:
+        raise GenerationError(f"Generated code validation failed: {e}")
+```
+
+## Dependencies on Other Systems
+
+### From core/
+- Uses `SpecLoader` for OpenAPI loading
+- Uses `SpecParser` for IR creation
+- Uses `PostProcessManager` for formatting
+
+### From types/
+- Creates `UnifiedTypeService` for visitors
+- Coordinates type resolution across generation
+
+### From visit/
+- Orchestrates all visitors
+- Manages visitor dependencies
+
+### From emitters/
+- Coordinates all emitters
+- Manages file output
+
+## Testing Requirements
+
+### Integration Tests
+```python
+def test_client_generator__complete_generation__creates_working_client():
+    # Test full generation pipeline
+    generator = ClientGenerator()
+    
+    # Generate client
+    generator.generate(
+        spec_path="test_spec.yaml",
+        project_root=temp_dir,
+        output_package="test_client"
+    )
+    
+    # Verify client works
+    assert can_import_client(temp_dir / "test_client")
+    assert client_methods_work(temp_dir / "test_client")
+```
+
+### Error Handling Tests
+```python
+def test_client_generator__invalid_spec__raises_generation_error():
+    generator = ClientGenerator()
+    
+    with pytest.raises(GenerationError) as exc_info:
+        generator.generate(
+            spec_path="invalid_spec.yaml",
+            project_root=temp_dir,
+            output_package="test_client"
+        )
+    
+    assert "parsing failed" in str(exc_info.value)
+```
+
+## Extension Points
+
+### Custom Generation Steps
+```python
+class CustomClientGenerator(ClientGenerator):
+    def run_generation_pipeline(self, *args, **kwargs):
+        # Add custom pre-processing
+        self.custom_pre_process()
+        
+        # Run standard pipeline
+        super().run_generation_pipeline(*args, **kwargs)
+        
+        # Add custom post-processing
+        self.custom_post_process()
+```
+
+### Plugin System
+```python
+def register_plugin(self, plugin: GenerationPlugin) -> None:
+    """Register custom generation plugin"""
+    self.plugins.append(plugin)
+    
+def run_plugins(self, stage: str, context: Dict[str, Any]) -> None:
+    """Run plugins at specific generation stage"""
+    for plugin in self.plugins:
+        if plugin.handles_stage(stage):
+            plugin.execute(context)
+```
+
+## Critical Implementation Details
+
+### Resource Management
+```python
+def generate_safely(self, *args, **kwargs) -> None:
+    """Generate with proper resource cleanup"""
+    temp_files = []
+    
+    try:
+        # Generation logic
+        pass
+    except Exception:
+        # Clean up temporary files
+        for temp_file in temp_files:
+            if temp_file.exists():
+                temp_file.unlink()
+        raise
+```
+
+### Progress Reporting
+```python
+def generate_with_progress(self, *args, **kwargs) -> None:
+    """Generate with progress reporting"""
+    stages = ["loading", "parsing", "code_generation", "file_emission", "post_processing"]
+    
+    for i, stage in enumerate(stages):
+        print(f"[{i+1}/{len(stages)}] {stage.replace('_', ' ').title()}...")
+        self.run_stage(stage)
+```