pyopenapi-gen 2.7.2__py3-none-any.whl

pyopenapi_gen/__init__.py

@@ -0,0 +1,224 @@
+"""pyopenapi_gen – Core package
+
+This package provides the internal representation (IR) dataclasses that act as an
+intermediate layer between the parsed OpenAPI specification and the code
+emitters.  The IR aims to be a *stable*, *fully‑typed* model that the rest of the
+code‑generation pipeline can rely on.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+# Removed dataclasses, field, Enum, unique from here, they are in ir.py and http_types.py
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    List,
+)
+
+# Kept Any, List, Optional, TYPE_CHECKING for __getattr__ and __dir__
+# Import HTTPMethod from its canonical location
+from .http_types import HTTPMethod
+
+# Import IR classes from their canonical location
+from .ir import (
+    IROperation,
+    IRParameter,
+    IRRequestBody,
+    IRResponse,
+    IRSchema,
+    IRSpec,
+)
+
+__all__ = [
+    # Main API
+    "generate_client",
+    "ClientGenerator",
+    "GenerationError",
+    # IR classes
+    "HTTPMethod",
+    "IRParameter",
+    "IRResponse",
+    "IROperation",
+    "IRSchema",
+    "IRSpec",
+    "IRRequestBody",
+    # Utilities
+    "load_ir_from_spec",
+    "WarningCollector",
+]
+
+# Semantic version of the generator core – automatically managed by semantic-release.
+__version__: str = "2.7.2"
+
+# ---------------------------------------------------------------------------
+# Lazy-loading and autocompletion support (This part remains)
+# ---------------------------------------------------------------------------
+if TYPE_CHECKING:
+    # Imports for static analysis
+    from .core.loader.loader import load_ir_from_spec  # noqa: F401
+    from .core.warning_collector import WarningCollector  # noqa: F401
+    from .generator.client_generator import ClientGenerator, GenerationError  # noqa: F401
+
+# Expose loader and collector at package level
+# __all__ is already updated above
+
+
+def __getattr__(name: str) -> Any:
+    # Lazy-import attributes for runtime, supports IDE completion via TYPE_CHECKING
+    if name == "load_ir_from_spec":
+        from .core.loader.loader import load_ir_from_spec as _func
+
+        return _func
+    if name == "WarningCollector":
+        from .core.warning_collector import WarningCollector as _warning_cls
+
+        return _warning_cls
+    if name == "ClientGenerator":
+        from .generator.client_generator import ClientGenerator as _gen_cls
+
+        return _gen_cls
+    if name == "GenerationError":
+        from .generator.client_generator import GenerationError as _exc
+
+        return _exc
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> List[str]:
+    # Ensure dir() and completion shows all exports
+    return __all__.copy()
+
+
+# ---------------------------------------------------------------------------
+# Main Programmatic API
+# ---------------------------------------------------------------------------
+
+
+def generate_client(
+    spec_path: str,
+    project_root: str,
+    output_package: str,
+    core_package: str | None = None,
+    force: bool = False,
+    no_postprocess: bool = False,
+    verbose: bool = False,
+) -> List[Path]:
+    """Generate a Python client from an OpenAPI specification.
+
+    This is the main entry point for programmatic usage of pyopenapi_gen.
+    It provides a simple function-based API for generating OpenAPI clients
+    without needing to instantiate classes or understand internal structure.
+
+    Args:
+        spec_path: Path or URL to the OpenAPI specification (YAML or JSON).
+                  Can be a relative/absolute file path or HTTP(S) URL.
+                  Examples: "input/spec.yaml", "https://api.example.com/openapi.json"
+
+        project_root: Root directory of your Python project where the generated
+                     client will be placed. This is the directory that contains
+                     your top-level Python packages.
+
+        output_package: Python package name for the generated client.
+                       Uses dot notation (e.g., 'pyapis.my_client').
+                       The client will be generated at:
+                       {project_root}/{output_package_as_path}/
+
+        core_package: Optional Python package name for shared core runtime.
+                     If not specified, defaults to {output_package}.core.
+                     Use this when generating multiple clients that share
+                     common runtime code (auth, config, http transport, etc.).
+
+        force: If True, overwrites existing output without diff checking.
+              If False (default), compares with existing output and only
+              updates if changes are detected.
+
+        no_postprocess: If True, skips post-processing (Black formatting and
+                       mypy type checking). Useful for faster iteration during
+                       development.
+
+        verbose: If True, prints detailed progress information during generation.
+
+    Returns:
+        List of Path objects for all generated files.
+
+    Raises:
+        GenerationError: If generation fails due to invalid spec, file I/O
+                        errors, or other issues during code generation.
+
+    Examples:
+        Basic usage with default settings:
+
+        >>> from pyopenapi_gen import generate_client
+        >>>
+        >>> files = generate_client(
+        ...     spec_path="input/openapi.yaml",
+        ...     project_root=".",
+        ...     output_package="pyapis.my_client"
+        ... )
+        >>> print(f"Generated {len(files)} files")
+
+        Generate multiple clients sharing a common core package:
+
+        >>> from pyopenapi_gen import generate_client
+        >>>
+        >>> # Generate first client (creates shared core)
+        >>> generate_client(
+        ...     spec_path="api_v1.yaml",
+        ...     project_root=".",
+        ...     output_package="pyapis.client_v1",
+        ...     core_package="pyapis.core"
+        ... )
+        >>>
+        >>> # Generate second client (reuses core)
+        >>> generate_client(
+        ...     spec_path="api_v2.yaml",
+        ...     project_root=".",
+        ...     output_package="pyapis.client_v2",
+        ...     core_package="pyapis.core"
+        ... )
+
+        Handle generation errors:
+
+        >>> from pyopenapi_gen import generate_client, GenerationError
+        >>>
+        >>> try:
+        ...     generate_client(
+        ...         spec_path="openapi.yaml",
+        ...         project_root=".",
+        ...         output_package="pyapis.my_client",
+        ...         verbose=True
+        ...     )
+        ... except GenerationError as e:
+        ...     print(f"Generation failed: {e}")
+
+        Force regeneration with verbose output:
+
+        >>> generate_client(
+        ...     spec_path="openapi.yaml",
+        ...     project_root=".",
+        ...     output_package="pyapis.my_client",
+        ...     force=True,
+        ...     verbose=True
+        ... )
+
+    Notes:
+        - Generated clients are completely self-contained and require no
+          runtime dependency on pyopenapi_gen
+        - All generated code is automatically formatted with Black and
+          type-checked with mypy (unless no_postprocess=True)
+        - The generated client uses modern async/await patterns with httpx
+        - Type hints are included for all generated code
+    """
+    from .generator.client_generator import ClientGenerator
+
+    generator = ClientGenerator(verbose=verbose)
+    return generator.generate(
+        spec_path=spec_path,
+        project_root=Path(project_root),
+        output_package=output_package,
+        core_package=core_package,
+        force=force,
+        no_postprocess=no_postprocess,
+    )

pyopenapi_gen/__main__.py

@@ -0,0 +1,6 @@
+"""Main entry point for the pyopenapi_gen CLI."""
+
+from .cli import app
+
+if __name__ == "__main__":
+    app()

pyopenapi_gen/cli.py

@@ -0,0 +1,62 @@
+from pathlib import Path
+
+import typer
+
+from .core.spec_fetcher import is_url
+from .generator.client_generator import ClientGenerator, GenerationError
+
+
+def main(
+    spec: str = typer.Argument(..., help="Path or URL to OpenAPI spec"),
+    project_root: Path = typer.Option(
+        ...,
+        "--project-root",
+        help=(
+            "Path to the directory containing your top-level Python packages. "
+            "Generated code will be placed at project-root + output-package path."
+        ),
+    ),
+    output_package: str = typer.Option(
+        ..., "--output-package", help="Python package path for the generated client (e.g., 'pyapis.my_api_client')."
+    ),
+    force: bool = typer.Option(False, "-f", "--force", help="Overwrite without diff check"),
+    no_postprocess: bool = typer.Option(False, "--no-postprocess", help="Skip post-processing (type checking, etc.)"),
+    core_package: str | None = typer.Option(
+        None,
+        "--core-package",
+        help=(
+            "Python package path for the core package (e.g., 'pyapis.core'). "
+            "If not set, defaults to <output-package>.core."
+        ),
+    ),
+) -> None:
+    """
+    Generate a Python OpenAPI client from a spec file or URL.
+    Only parses CLI arguments and delegates to ClientGenerator.
+    """
+    if core_package is None:
+        core_package = output_package + ".core"
+    generator = ClientGenerator()
+    # Handle both URLs (pass as-is) and file paths (resolve to absolute)
+    spec_path = spec if is_url(spec) else str(Path(spec).resolve())
+    try:
+        generator.generate(
+            spec_path=spec_path,
+            project_root=project_root,
+            output_package=output_package,
+            force=force,
+            no_postprocess=no_postprocess,
+            core_package=core_package,
+        )
+        typer.echo("Client generation complete.")
+    except GenerationError as e:
+        typer.echo(f"Generation failed: {e}", err=True)
+        raise typer.Exit(code=1)
+
+
+app = typer.Typer(help="PyOpenAPI Generator CLI - Generate Python clients from OpenAPI specs.")
+app.command()(main)
+
+
+if __name__ == "__main__":
+    app()

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/file_manager.py

@@ -0,0 +1,52 @@
+"""
+FileManager: Manages file operations for code generation.
+
+This module provides utilities for creating directories and writing
+generated Python code to files, with appropriate logging for debugging.
+"""
+
+import os
+import tempfile
+
+
+class FileManager:
+    """
+    Manages file operations for the code generation process.
+
+    This class provides methods to write content to files and ensure directories
+    exist, with built-in logging for debugging purposes.
+    """
+
+    def write_file(self, path: str, content: str) -> None:
+        """
+        Write content to a file, ensuring the parent directory exists.
+
+        This method also logs the file path and first 10 lines of content
+        to a debug log for troubleshooting purposes.
+
+        Args:
+            path: The absolute path to the file to write
+            content: The string content to write to the file
+        """
+        self.ensure_dir(os.path.dirname(path))
+
+        # Log the file path and first 10 lines of content for debugging
+        debug_log_path = os.path.join(tempfile.gettempdir(), "pyopenapi_gen_file_write_debug.log")
+        with open(debug_log_path, "a") as debug_log:
+            debug_log.write(f"WRITE FILE: {path}\n")
+            for line in content.splitlines()[:10]:
+                debug_log.write(line + "\n")
+            debug_log.write("---\n")
+
+        # Write the content to the file
+        with open(path, "w") as f:
+            f.write(content)
+
+    def ensure_dir(self, path: str) -> None:
+        """
+        Ensure a directory exists, creating it if necessary.
+
+        Args:
+            path: The directory path to ensure exists
+        """
+        os.makedirs(path, exist_ok=True)