pyopenapi-gen 2.7.2__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/client_emitter.py

@@ -0,0 +1,51 @@
+import tempfile
+import traceback
+from pathlib import Path
+
+from pyopenapi_gen import IRSpec
+from pyopenapi_gen.context.render_context import RenderContext
+
+from ..visit.client_visitor import ClientVisitor
+
+# NOTE: ClientConfig and transports are only referenced in template strings, not at runtime
+# hence we avoid importing config and http_transport modules to prevent runtime errors
+
+# Jinja template for base async client file with tag-specific clients
+# CLIENT_TEMPLATE = ''' ... removed ... '''
+
+
+class ClientEmitter:
+    """Generates core client files (client.py) from IRSpec using visitor/context."""
+
+    def __init__(self, context: RenderContext) -> None:
+        self.visitor = ClientVisitor()
+        self.context = context
+
+    def emit(self, spec: IRSpec, output_dir_str: str) -> list[str]:
+        error_log = Path(tempfile.gettempdir()) / "pyopenapi_gen_error.log"
+        generated_files = []
+        try:
+            output_dir_abs = Path(output_dir_str)
+            output_dir_abs.mkdir(parents=True, exist_ok=True)
+
+            client_path = output_dir_abs / "client.py"
+
+            self.context.set_current_file(str(client_path))
+
+            client_code = self.visitor.visit(spec, self.context)
+            imports_code = self.context.render_imports()
+            file_content = imports_code + "\n\n" + client_code
+
+            self.context.file_manager.write_file(str(client_path), file_content)
+            generated_files.append(str(client_path))
+
+            pytyped_path = output_dir_abs / "py.typed"
+            if not pytyped_path.exists():
+                self.context.file_manager.write_file(str(pytyped_path), "")
+            generated_files.append(str(pytyped_path))
+            return generated_files
+        except Exception as e:
+            with open(error_log, "a") as f:
+                f.write(f"ERROR in ClientEmitter.emit: {e}\n")
+                f.write(traceback.format_exc())
+            raise

pyopenapi_gen/emitters/core_emitter.py

@@ -0,0 +1,181 @@
+import importlib.resources
+import os
+from typing import List
+
+from pyopenapi_gen.context.file_manager import FileManager
+
+# Each tuple: (module, filename, destination)
+RUNTIME_FILES = [
+    ("pyopenapi_gen.core", "http_transport.py", "core/http_transport.py"),
+    ("pyopenapi_gen.core", "exceptions.py", "core/exceptions.py"),
+    ("pyopenapi_gen.core", "streaming_helpers.py", "core/streaming_helpers.py"),
+    ("pyopenapi_gen.core", "pagination.py", "core/pagination.py"),
+    ("pyopenapi_gen.core", "cattrs_converter.py", "core/cattrs_converter.py"),
+    ("pyopenapi_gen.core", "utils.py", "core/utils.py"),
+    ("pyopenapi_gen.core.auth", "base.py", "core/auth/base.py"),
+    ("pyopenapi_gen.core.auth", "plugins.py", "core/auth/plugins.py"),
+]
+
+# +++ Add template README location +++
+CORE_README_TEMPLATE_MODULE = "pyopenapi_gen.core_package_template"
+CORE_README_TEMPLATE_FILENAME = "README.md"
+
+CONFIG_TEMPLATE = """
+from dataclasses import dataclass
+@dataclass
+class ClientConfig:
+    base_url: str
+    timeout: float | None = 30.0
+"""
+
+
+class CoreEmitter:
+    """Copies all required runtime files into the generated core module."""
+
+    def __init__(
+        self, core_dir: str = "core", core_package: str = "core", exception_alias_names: List[str] | None = None
+    ):
+        # core_dir is the relative path WITHIN the output package, e.g., "core" or "shared/core"
+        # core_package is the Python import name, e.g., "core" or "shared.core"
+        self.core_dir_name = os.path.basename(core_dir)  # e.g., "core"
+        self.core_dir_relative = core_dir  # e.g., "core" or "shared/core"
+        self.core_package = core_package
+        self.exception_alias_names = exception_alias_names if exception_alias_names is not None else []
+        self.file_manager = FileManager()
+
+    def emit(self, package_output_dir: str) -> list[str]:
+        """
+        Emits the core files into the specified core directory within the package output directory.
+        Args:
+            package_output_dir: The root directory where the generated package is being placed.
+                                  e.g., /path/to/gen/my_client
+        Returns:
+            List of generated file paths relative to the workspace root.
+        """
+        # Determine the absolute path for the core directory, e.g., /path/to/gen/my_client/core
+        actual_core_dir = os.path.join(package_output_dir, self.core_dir_relative)
+
+        generated_files = []
+        # Ensure the core directory exists (e.g., my_client/core or my_client/shared/core)
+        self.file_manager.ensure_dir(actual_core_dir)
+
+        for module, filename, rel_dst in RUNTIME_FILES:
+            # rel_dst is like "core/http_transport.py" or "core/auth/base.py"
+            # We want the part after "core/", e.g., "http_transport.py" or "auth/base.py"
+            # And join it with the actual_core_dir
+            destination_relative_to_core = rel_dst.replace("core/", "", 1)
+            dst = os.path.join(actual_core_dir, destination_relative_to_core)
+
+            self.file_manager.ensure_dir(os.path.dirname(dst))
+            # Use importlib.resources to read the file from the package
+            try:
+                # Read from pyopenapi_gen.core... or pyopenapi_gen.core.auth...
+                with importlib.resources.files(module).joinpath(filename).open("r") as f:
+                    content = f.read()
+                self.file_manager.write_file(dst, content)
+                generated_files.append(dst)
+            except FileNotFoundError:
+                print(f"Warning: Could not find runtime file {filename} in module {module}. Skipping.")
+
+        # Always create __init__.py files for core and subfolders within the actual core dir
+        core_init_path = os.path.join(actual_core_dir, "__init__.py")
+        core_init_content = [
+            "# Re-export core exceptions and generated aliases",
+            "from .exceptions import HTTPError, ClientError, ServerError",
+            "from .exception_aliases import *  # noqa: F403",
+            "",
+            "# Re-export other commonly used core components",
+            "from .http_transport import HttpTransport, HttpxTransport",
+            "from .config import ClientConfig",
+            "from .cattrs_converter import structure_from_dict, unstructure_to_dict, converter",
+            "from .utils import DataclassSerializer",
+            "from .auth.base import BaseAuth",
+            "from .auth.plugins import ApiKeyAuth, BearerAuth, OAuth2Auth",
+            "",
+            "__all__ = [",
+            "    # Base exceptions",
+            '    "HTTPError",',
+            '    "ClientError",',
+            '    "ServerError",',
+            "    # All ErrorXXX from exception_aliases are implicitly in __all__ due to star import",
+            "",
+            "    # Transport layer",
+            '    "HttpTransport",',
+            '    "HttpxTransport",',
+            "",
+            "    # Configuration",
+            '    "ClientConfig",',
+            "",
+            "    # Serialization (cattrs)",
+            '    "structure_from_dict",',
+            '    "unstructure_to_dict",',
+            '    "converter",',
+            "",
+            "    # Utilities",
+            '    "DataclassSerializer",',
+            "",
+            "    # Authentication",
+            '    "BaseAuth",',
+            '    "ApiKeyAuth",',
+            '    "BearerAuth",',
+            '    "OAuth2Auth",',
+        ]
+        # Add discovered exception alias names to __all__
+        if self.exception_alias_names:
+            core_init_content.append("    # Generated exception aliases")
+            for alias_name in sorted(list(set(self.exception_alias_names))):  # Sort and unique
+                core_init_content.append(f'    "{alias_name}",')
+
+        core_init_content.append("]")
+
+        self.file_manager.write_file(core_init_path, "\n".join(core_init_content))
+        generated_files.append(core_init_path)
+
+        auth_dir = os.path.join(actual_core_dir, "auth")
+        if os.path.exists(auth_dir):  # Only create auth/__init__.py if auth files were copied
+            auth_init_path = os.path.join(auth_dir, "__init__.py")
+            self.file_manager.ensure_dir(os.path.dirname(auth_init_path))
+            auth_init_content = [
+                "# Core Auth __init__",
+                "from .base import BaseAuth",
+                "from .plugins import ApiKeyAuth, BearerAuth, OAuth2Auth",
+                "",
+                "__all__ = [",
+                '    "BaseAuth",',
+                '    "ApiKeyAuth",',
+                '    "BearerAuth",',
+                '    "OAuth2Auth",',
+                "]",
+            ]
+            self.file_manager.write_file(auth_init_path, "\n".join(auth_init_content) + "\n")
+            generated_files.append(auth_init_path)
+
+        # Ensure py.typed marker for mypy in the actual core directory
+        pytyped_path = os.path.join(actual_core_dir, "py.typed")
+        if not os.path.exists(pytyped_path):
+            self.file_manager.write_file(pytyped_path, "")  # Create empty py.typed
+        generated_files.append(pytyped_path)
+
+        # Copy the core README template into the actual core directory
+        readme_dst = os.path.join(actual_core_dir, "README.md")
+        try:
+            with (
+                importlib.resources.files(CORE_README_TEMPLATE_MODULE)
+                .joinpath(CORE_README_TEMPLATE_FILENAME)
+                .open("r") as f
+            ):
+                readme_content = f.read()
+            self.file_manager.write_file(readme_dst, readme_content)
+            generated_files.append(readme_dst)
+        except FileNotFoundError:
+            print(
+                f"Warning: Could not find core README template {CORE_README_TEMPLATE_FILENAME} "
+                f"in {CORE_README_TEMPLATE_MODULE}. Skipping."
+            )
+
+        # Generate config.py from template inside the actual core directory
+        config_path = os.path.join(actual_core_dir, "config.py")
+        self.file_manager.write_file(config_path, CONFIG_TEMPLATE)
+        generated_files.append(config_path)
+
+        return generated_files

pyopenapi_gen/emitters/docs_emitter.py

@@ -0,0 +1,44 @@
+import os
+
+from pyopenapi_gen import IRSpec
+from pyopenapi_gen.context.render_context import RenderContext
+
+from ..visit.docs_visitor import DocsVisitor
+
+"""Simple documentation emitter using markdown with Python str.format placeholders."""
+DOCS_INDEX_TEMPLATE = """# API Documentation
+
+Generated documentation for the API.
+
+## Tags
+{tags_list}
+"""
+
+DOCS_TAG_TEMPLATE = """# {tag} Operations
+
+{operations_list}
+"""
+
+DOCS_OPERATION_TEMPLATE = """### {operation_id}
+
+**Method:** `{method}`
+**Path:** `{path}`
+
+{description}
+"""
+
+
+class DocsEmitter:
+    """Generates markdown documentation per tag from IRSpec using visitor/context."""
+
+    def __init__(self) -> None:
+        self.visitor = DocsVisitor()
+
+    def emit(self, spec: IRSpec, output_dir: str) -> None:
+        """Render docs into <output_dir> as markdown files."""
+        docs_dir = os.path.join(output_dir)
+        context = RenderContext()
+        context.file_manager.ensure_dir(docs_dir)
+        docs = self.visitor.visit(spec, context)
+        for filename, content in docs.items():
+            context.file_manager.write_file(os.path.join(docs_dir, filename), content)