pyopenapi-gen 2.7.2__py3-none-any.whl

pyopenapi_gen/emitters/endpoints_emitter.py

@@ -0,0 +1,247 @@
+import logging
+from pathlib import Path
+from typing import List, Tuple
+
+from pyopenapi_gen import IROperation, IRParameter, IRRequestBody
+from pyopenapi_gen.context.render_context import RenderContext
+from pyopenapi_gen.visit.endpoint.endpoint_visitor import EndpointVisitor
+
+from ..core.utils import Formatter, NameSanitizer
+
+logger = logging.getLogger(__name__)
+
+# Basic OpenAPI schema to Python type mapping for parameters
+PARAM_TYPE_MAPPING = {
+    "integer": "int",
+    "number": "float",
+    "boolean": "bool",
+    "string": "str",
+    "array": "List",
+    "object": "dict[str, Any]",
+}
+# Format-specific overrides
+PARAM_FORMAT_MAPPING = {
+    "int32": "int",
+    "int64": "int",
+    "float": "float",
+    "double": "float",
+    "byte": "str",
+    "binary": "bytes",
+    "date": "date",
+    "date-time": "datetime",
+}
+
+# Default tag for untagged operations
+DEFAULT_TAG = "default"
+
+
+def schema_to_type(schema: IRParameter) -> str:
+    """Convert an IRParameter's schema to a Python type string."""
+    s = schema.schema  # s is an IRSchema instance
+    py_type: str = "Any"  # Default base type
+
+    # 1. Determine base type (without Optional wrapper yet)
+    # Format-specific override has highest precedence for base type determination
+    if s.format and s.format in PARAM_FORMAT_MAPPING:
+        py_type = PARAM_FORMAT_MAPPING[s.format]
+    # Array handling
+    elif s.type == "array" and s.items:
+        # For array items, we recursively call schema_to_type.
+        # The nullability of the item_type itself (e.g. List[int | None])
+        # will be handled by the recursive call based on s.items.is_nullable.
+        item_schema_as_param = IRParameter(name="_item", param_in="_internal", required=False, schema=s.items)
+        item_type_str = schema_to_type(item_schema_as_param)
+        py_type = f"List[{item_type_str}]"
+    # Default mapping based on s.type (primary type)
+    elif s.type and s.type in PARAM_TYPE_MAPPING:
+        py_type = PARAM_TYPE_MAPPING[s.type]
+    # Fallback if type is None or not in mappings (and not format override/array)
+    # If s.type is None and there was no format override, it defaults to "Any".
+    # If s.type is something not recognized, it also defaults to "Any".
+    elif not s.type and not s.format:  # Type is None, no format override
+        py_type = "Any"
+    elif s.type:  # Type is some string not in PARAM_TYPE_MAPPING and not an array handled above
+        # This could be a reference to a model. For now, schema_to_type is simple and returns Any.
+        # A more sophisticated version would return the schema name for model visitor to handle.
+        # However, based on existing PARAM_TYPE_MAPPING, unknown types become "Any".
+        py_type = "Any"
+    # If py_type is still "Any" here, it means none of the above conditions strongly set a type.
+
+    # 2. Apply nullability based on IRSchema's is_nullable field
+    # This s.is_nullable should be the source of truth from the IR after parsing.
+    if s.is_nullable:
+        # Ensure "Any" also gets wrapped, e.g. Any | None
+        py_type = f"{py_type} | None"
+
+    return py_type
+
+
+def _get_request_body_type(body: IRRequestBody) -> str:
+    """Determine the Python type for a request body schema."""
+    for mt, sch in body.content.items():
+        if "json" in mt.lower():
+            return schema_to_type(IRParameter(name="body", param_in="body", required=body.required, schema=sch))
+    # Fallback to generic dict
+    return "dict[str, Any]"
+
+
+def _deduplicate_tag_clients(client_classes: List[Tuple[str, str]]) -> List[Tuple[str, str]]:
+    """
+    Deduplicate client class/module pairs by canonical module/class name.
+    Returns a list of unique (class_name, module_name) pairs.
+    """
+    seen = set()
+    unique = []
+    for cls, mod in client_classes:
+        key = (cls.lower(), mod.lower())
+        if key not in seen:
+            seen.add(key)
+            unique.append((cls, mod))
+    return unique
+
+
+class EndpointsEmitter:
+    """Generates endpoint modules organized by tag from IRSpec using the visitor/context architecture."""
+
+    def __init__(self, context: RenderContext) -> None:
+        self.context = context
+        self.formatter = Formatter()
+        self.visitor: EndpointVisitor | None = None
+
+    def _deduplicate_operation_ids_globally(self, operations: List[IROperation]) -> None:
+        """
+        Ensures all operations have unique method names globally across all tags.
+
+        This prevents the bug where operations with multiple tags share the same
+        IROperation object reference, causing _deduplicate_operation_ids() to
+        modify the same object multiple times and accumulate _2_2 suffixes.
+
+        Args:
+            operations: List of all operations across all tags.
+        """
+        seen_methods: dict[str, int] = {}
+        for op in operations:
+            method_name = NameSanitizer.sanitize_method_name(op.operation_id)
+            if method_name in seen_methods:
+                seen_methods[method_name] += 1
+                new_op_id = f"{op.operation_id}_{seen_methods[method_name]}"
+                op.operation_id = new_op_id
+            else:
+                seen_methods[method_name] = 1
+
+    def emit(self, operations: List[IROperation], output_dir_str: str) -> List[str]:
+        """Render endpoint client files per tag under <output_dir>/endpoints.
+        Returns a list of generated file paths."""
+        output_dir = Path(output_dir_str)
+        endpoints_dir = output_dir / "endpoints"
+
+        self.context.file_manager.ensure_dir(str(endpoints_dir))
+
+        # Manage __init__.py and py.typed files
+        common_files_to_ensure = [
+            (endpoints_dir / "__init__.py", ""),
+            (output_dir / "__init__.py", ""),  # Ensure root client package __init__.py
+            (endpoints_dir / "py.typed", ""),
+        ]
+        for file_path, content in common_files_to_ensure:
+            if not file_path.exists():
+                self.context.file_manager.write_file(str(file_path), content)
+
+        # Ensure parsed_schemas is at least an empty dict if None,
+        # as EndpointVisitor expects dict[str, IRSchema]
+        current_parsed_schemas = self.context.parsed_schemas
+        if current_parsed_schemas is None:
+            logger.warning(
+                "[EndpointsEmitter] RenderContext.parsed_schemas was None. "
+                "Defaulting to empty dict for EndpointVisitor."
+            )
+            current_parsed_schemas = {}  # Default to empty dict if None
+
+        if self.visitor is None:
+            self.visitor = EndpointVisitor(current_parsed_schemas)  # Pass the (potentially defaulted) dict
+
+        # Deduplicate operation IDs globally BEFORE tag grouping to prevent
+        # multi-tag operations from accumulating _2_2 suffixes
+        self._deduplicate_operation_ids_globally(operations)
+
+        tag_key_to_ops: dict[str, List[IROperation]] = {}
+        tag_key_to_candidates: dict[str, List[str]] = {}
+        for op in operations:
+            tags = op.tags or [DEFAULT_TAG]
+            for tag in tags:
+                key = NameSanitizer.normalize_tag_key(tag)
+                tag_key_to_ops.setdefault(key, []).append(op)
+                tag_key_to_candidates.setdefault(key, []).append(tag)
+
+        def tag_score(t: str) -> tuple[bool, int, int, str]:
+            import re
+
+            is_pascal = bool(re.search(r"[a-z][A-Z]", t)) or bool(re.search(r"[A-Z]{2,}", t))
+            words = re.findall(r"[A-Z]?[a-z]+|[A-Z]+(?![a-z])|[0-9]+", t)
+            words += re.split(r"[_-]+", t)
+            word_count = len([w for w in words if w])
+            upper = sum(1 for c in t if c.isupper())
+            return (is_pascal, word_count, upper, t)
+
+        tag_map: dict[str, str] = {}
+        for key, candidates in tag_key_to_candidates.items():
+            best_tag_for_key = DEFAULT_TAG  # Default if no candidates somehow
+            if candidates:
+                best_tag_for_key = max(candidates, key=tag_score)
+            tag_map[key] = best_tag_for_key
+
+        generated_files: List[str] = []
+        client_classes: List[Tuple[str, str]] = []
+
+        for key, ops_for_tag in tag_key_to_ops.items():
+            canonical_tag_name = tag_map[key]
+            module_name = NameSanitizer.sanitize_module_name(canonical_tag_name)
+            class_name = NameSanitizer.sanitize_class_name(canonical_tag_name) + "Client"
+            protocol_name = f"{class_name}Protocol"
+            file_path = endpoints_dir / f"{module_name}.py"
+
+            # This will set current_file and reset+reinit import_collector's context
+            self.context.set_current_file(str(file_path))
+
+            # Deduplication now done globally before tag grouping (see above)
+
+            # EndpointVisitor must exist here due to check above
+            if self.visitor is None:
+                raise RuntimeError("EndpointVisitor not initialized")
+            methods = [self.visitor.visit(op, self.context) for op in ops_for_tag]
+            # Pass operations to emit_endpoint_client_class for Protocol generation
+            class_content = self.visitor.emit_endpoint_client_class(
+                canonical_tag_name, methods, self.context, operations=ops_for_tag
+            )
+
+            imports = self.context.render_imports()
+            file_content = imports + "\n\n" + class_content
+            self.context.file_manager.write_file(str(file_path), file_content)
+            # Store both class and protocol for __init__.py generation
+            client_classes.append((class_name, module_name))
+            generated_files.append(str(file_path))
+
+        unique_clients = _deduplicate_tag_clients(client_classes)
+        init_lines = []
+        if unique_clients:
+            # Export both implementation classes and Protocol classes
+            all_list_items = []
+            for cls, _ in unique_clients:
+                protocol_name = f"{cls}Protocol"
+                all_list_items.append(f'"{cls}"')
+                all_list_items.append(f'"{protocol_name}"')
+
+            all_list_items = sorted(all_list_items)
+            init_lines.append(f"__all__ = [{', '.join(all_list_items)}]")
+
+            # Import both implementation and Protocol from each module
+            for cls, mod in sorted(unique_clients):
+                protocol_name = f"{cls}Protocol"
+                init_lines.append(f"from .{mod} import {cls}, {protocol_name}")
+
+        endpoints_init_path = endpoints_dir / "__init__.py"
+        self.context.file_manager.write_file(str(endpoints_init_path), "\n".join(init_lines) + "\n")
+        if str(endpoints_init_path) not in generated_files:
+            generated_files.append(str(endpoints_init_path))
+
+        return generated_files

pyopenapi_gen/emitters/exceptions_emitter.py

@@ -0,0 +1,187 @@
+import json
+import os
+from pathlib import Path
+
+from pyopenapi_gen import IRSpec
+from pyopenapi_gen.context.render_context import RenderContext
+
+from ..visit.exception_visitor import ExceptionVisitor
+
+
+class ExceptionsEmitter:
+    """Generates spec-specific exception aliases with multi-client support.
+
+    This emitter handles two scenarios:
+    1. **Single client**: Generates exception_aliases.py directly in the core package
+    2. **Shared core**: Maintains a registry of all needed exception codes across clients
+       and regenerates the complete exception_aliases.py file
+
+    The registry file (.exception_registry.json) tracks which status codes are used by
+    which clients, ensuring that when multiple clients share a core package, all required
+    exceptions are available.
+    """
+
+    def __init__(self, core_package_name: str = "core", overall_project_root: str | None = None) -> None:
+        self.visitor = ExceptionVisitor()
+        self.core_package_name = core_package_name
+        self.overall_project_root = overall_project_root
+
+    def emit(
+        self, spec: IRSpec, output_dir: str, client_package_name: str | None = None
+    ) -> tuple[list[str], list[str]]:
+        """Generate exception aliases for the given spec.
+
+        Args:
+            spec: IRSpec containing operations and responses
+            output_dir: Directory where exception_aliases.py will be written
+            client_package_name: Name of the client package (for registry tracking)
+
+        Returns:
+            Tuple of (list of generated file paths, list of exception class names)
+        """
+        file_path = os.path.join(output_dir, "exception_aliases.py")
+        registry_path = os.path.join(output_dir, ".exception_registry.json")
+
+        context = RenderContext(
+            package_root_for_generated_code=output_dir,
+            core_package_name=self.core_package_name,
+            overall_project_root=self.overall_project_root,
+        )
+        context.set_current_file(file_path)
+
+        # Generate exception classes for this spec
+        generated_code, alias_names, status_codes = self.visitor.visit(spec, context)
+
+        # Update registry if we have a client package name (shared core scenario)
+        if client_package_name and self._is_shared_core(output_dir):
+            all_codes = self._update_registry(registry_path, client_package_name, status_codes)
+            # Regenerate with ALL codes from registry
+            generated_code, alias_names = self._generate_for_codes(all_codes, context)
+
+        generated_imports = context.render_imports()
+
+        alias_names.sort()
+
+        # Add __all__ list with proper spacing (2 blank lines after last class - Ruff E305)
+        if alias_names:
+            all_list_str = ", ".join([f'"{name}"' for name in alias_names])
+            all_assignment = f"\n\n\n__all__ = [{all_list_str}]\n"
+            generated_code += all_assignment
+
+        full_content = f"{generated_imports}\n\n{generated_code}"
+        with open(file_path, "w") as f:
+            f.write(full_content)
+
+        return [file_path], alias_names
+
+    def _is_shared_core(self, core_dir: str) -> bool:
+        """Check if this core package is shared between multiple clients.
+
+        Args:
+            core_dir: Path to the core package directory
+
+        Returns:
+            True if the core package is outside the immediate client package
+        """
+        # If overall_project_root is set and different from the core dir's parent,
+        # we're in a shared core scenario
+        if self.overall_project_root:
+            core_path = Path(core_dir).resolve()
+            project_root = Path(self.overall_project_root).resolve()
+            # Check if there are other client directories at the same level
+            parent_dir = core_path.parent
+            return parent_dir == project_root or parent_dir.parent == project_root
+        return False
+
+    def _update_registry(self, registry_path: str, client_name: str, status_codes: list[int]) -> list[int]:
+        """Update the exception registry with this client's status codes.
+
+        Args:
+            registry_path: Path to the .exception_registry.json file
+            client_name: Name of the client package
+            status_codes: List of status codes used by this client
+
+        Returns:
+            Complete list of all status codes across all clients
+        """
+        registry = {}
+        if os.path.exists(registry_path):
+            with open(registry_path) as f:
+                registry = json.load(f)
+
+        # Update this client's codes
+        registry[client_name] = sorted(status_codes)
+
+        # Write back to registry
+        with open(registry_path, "w") as f:
+            json.dump(registry, f, indent=2, sort_keys=True)
+
+        # Return union of all codes
+        all_codes = set()
+        for codes in registry.values():
+            all_codes.update(codes)
+
+        return sorted(all_codes)
+
+    def _generate_for_codes(self, status_codes: list[int], context: RenderContext) -> tuple[str, list[str]]:
+        """Generate exception classes for a specific list of status codes.
+
+        Args:
+            status_codes: List of HTTP status codes to generate exceptions for
+            context: Render context for imports
+
+        Returns:
+            Tuple of (generated_code, exception_class_names)
+        """
+        from ..core.http_status_codes import (
+            get_exception_class_name,
+            get_status_name,
+            is_client_error,
+            is_server_error,
+        )
+        from ..core.writers.python_construct_renderer import PythonConstructRenderer
+
+        renderer = PythonConstructRenderer()
+        all_exception_code = []
+        generated_alias_names = []
+
+        for code in status_codes:
+            # Determine base class
+            if is_client_error(code):
+                base_class = "ClientError"
+            elif is_server_error(code):
+                base_class = "ServerError"
+            else:
+                continue
+
+            # Get human-readable exception class name (e.g., NotFoundError instead of Error404)
+            class_name = get_exception_class_name(code)
+            generated_alias_names.append(class_name)
+
+            # Get human-readable status name for documentation
+            status_name = get_status_name(code)
+            docstring = f"HTTP {code} {status_name}.\n\nRaised when the server responds with a {code} status code."
+
+            # Define the __init__ method body
+            init_method_body = [
+                "def __init__(self, response: Response) -> None:",
+                f'    """Initialise {class_name} with the HTTP response.',
+                "",  # Empty line without trailing whitespace (Ruff W293)
+                "    Args:",
+                "        response: The httpx Response object that triggered this exception",
+                '    """',
+                "    super().__init__(status_code=response.status_code, message=response.text, response=response)",
+            ]
+
+            exception_code = renderer.render_class(
+                class_name=class_name,
+                base_classes=[base_class],
+                docstring=docstring,
+                body_lines=init_method_body,
+                context=context,
+            )
+            all_exception_code.append(exception_code)
+
+        # Join the generated class strings with 2 blank lines between classes (PEP 8 / Ruff E302)
+        final_code = "\n\n\n".join(all_exception_code)
+        return final_code, generated_alias_names

pyopenapi_gen/emitters/mocks_emitter.py

@@ -0,0 +1,185 @@
+"""
+Emitter for generating mock helper classes.
+
+This module creates the mocks/ directory structure with mock implementations
+for both tag-based endpoint clients and the main API client.
+"""
+
+import tempfile
+import traceback
+from collections import defaultdict
+from pathlib import Path
+
+from pyopenapi_gen import IROperation, IRSpec
+from pyopenapi_gen.context.render_context import RenderContext
+from pyopenapi_gen.core.utils import NameSanitizer
+
+from ..visit.client_visitor import ClientVisitor
+from ..visit.endpoint.endpoint_visitor import EndpointVisitor
+
+
+class MocksEmitter:
+    """Generates mock helper classes for testing."""
+
+    def __init__(self, context: RenderContext) -> None:
+        self.endpoint_visitor = EndpointVisitor()
+        self.client_visitor = ClientVisitor()
+        self.context = context
+
+    def emit(self, spec: IRSpec, output_dir_str: str) -> list[str]:
+        """
+        Generate all mock files in mocks/ directory structure.
+
+        Args:
+            spec: IR specification
+            output_dir_str: Output directory path
+
+        Returns:
+            List of generated file paths
+        """
+        error_log = Path(tempfile.gettempdir()) / "pyopenapi_gen_mocks_error.log"
+        generated_files = []
+
+        try:
+            output_dir_abs = Path(output_dir_str)
+            mocks_dir = output_dir_abs / "mocks"
+            mocks_dir.mkdir(parents=True, exist_ok=True)
+
+            # Group operations by tag
+            operations_by_tag = self._group_operations_by_tag(spec)
+
+            # Track tag information for main client generation
+            tag_tuples = []
+
+            # Generate mock endpoint classes
+            mock_endpoints_dir = mocks_dir / "endpoints"
+            mock_endpoints_dir.mkdir(parents=True, exist_ok=True)
+
+            for tag, ops_for_tag in operations_by_tag.items():
+                if not ops_for_tag:
+                    continue
+
+                canonical_tag_name = tag if tag else "default"
+                class_name = NameSanitizer.sanitize_class_name(canonical_tag_name) + "Client"
+                module_name = NameSanitizer.sanitize_module_name(canonical_tag_name)
+
+                # Track for main client generation
+                tag_tuples.append((canonical_tag_name, class_name, module_name))
+
+                # Generate mock class
+                mock_file_path = mock_endpoints_dir / f"mock_{module_name}.py"
+                self.context.set_current_file(str(mock_file_path))
+
+                mock_code = self.endpoint_visitor.generate_endpoint_mock_class(
+                    canonical_tag_name, ops_for_tag, self.context
+                )
+                imports_code = self.context.render_imports()
+                file_content = imports_code + "\n\n" + mock_code
+
+                self.context.file_manager.write_file(str(mock_file_path), file_content)
+                generated_files.append(str(mock_file_path))
+
+            # Generate mock endpoints __init__.py
+            endpoints_init_path = mock_endpoints_dir / "__init__.py"
+            endpoints_init_content = self._generate_mock_endpoints_init(tag_tuples)
+            self.context.file_manager.write_file(str(endpoints_init_path), endpoints_init_content)
+            generated_files.append(str(endpoints_init_path))
+
+            # Generate main mock client
+            mock_client_path = mocks_dir / "mock_client.py"
+            self.context.set_current_file(str(mock_client_path))
+
+            mock_client_code = self.client_visitor.generate_client_mock_class(spec, self.context, tag_tuples)
+            imports_code = self.context.render_imports()
+            file_content = imports_code + "\n\n" + mock_client_code
+
+            self.context.file_manager.write_file(str(mock_client_path), file_content)
+            generated_files.append(str(mock_client_path))
+
+            # Generate mocks __init__.py
+            mocks_init_path = mocks_dir / "__init__.py"
+            mocks_init_content = self._generate_mocks_init(tag_tuples)
+            self.context.file_manager.write_file(str(mocks_init_path), mocks_init_content)
+            generated_files.append(str(mocks_init_path))
+
+            return generated_files
+
+        except Exception as e:
+            with open(error_log, "a") as f:
+                f.write(f"ERROR in MocksEmitter.emit: {e}\n")
+                f.write(traceback.format_exc())
+            raise
+
+    def _group_operations_by_tag(self, spec: IRSpec) -> dict[str, list[IROperation]]:
+        """Group operations by their OpenAPI tag."""
+        operations_by_tag: dict[str, list[IROperation]] = defaultdict(list)
+
+        for operation in spec.operations:
+            tag = operation.tags[0] if operation.tags else "default"
+            operations_by_tag[tag].append(operation)
+
+        return operations_by_tag
+
+    def _generate_mock_endpoints_init(self, tag_tuples: list[tuple[str, str, str]]) -> str:
+        """Generate __init__.py for mocks/endpoints/ directory."""
+        lines = []
+        lines.append('"""')
+        lines.append("Mock endpoint clients for testing.")
+        lines.append("")
+        lines.append("Import mock classes to use as base classes for your test doubles.")
+        lines.append('"""')
+        lines.append("")
+
+        # Import statements
+        all_exports = []
+        for tag, class_name, module_name in sorted(tag_tuples, key=lambda x: x[2]):
+            mock_class_name = f"Mock{class_name}"
+            lines.append(f"from .mock_{module_name} import {mock_class_name}")
+            all_exports.append(mock_class_name)
+
+        lines.append("")
+        lines.append("__all__ = [")
+        for export in all_exports:
+            lines.append(f'    "{export}",')
+        lines.append("]")
+
+        return "\n".join(lines)
+
+    def _generate_mocks_init(self, tag_tuples: list[tuple[str, str, str]]) -> str:
+        """Generate __init__.py for mocks/ directory."""
+        lines = []
+        lines.append('"""')
+        lines.append("Mock implementations for testing.")
+        lines.append("")
+        lines.append("These mocks implement the Protocol contracts without requiring")
+        lines.append("network transport or authentication. Use them as base classes")
+        lines.append("in your tests.")
+        lines.append("")
+        lines.append("Example:")
+        lines.append("    from myapi.mocks import MockAPIClient, MockPetsClient")
+        lines.append("")
+        lines.append("    class TestPetsClient(MockPetsClient):")
+        lines.append("        async def list_pets(self, limit: int | None = None) -> list[Pet]:")
+        lines.append("            return [Pet(id=1, name='Test Pet')]")
+        lines.append("")
+        lines.append("    client = MockAPIClient(pets=TestPetsClient())")
+        lines.append('"""')
+        lines.append("")
+
+        # Import main mock client
+        lines.append("from .mock_client import MockAPIClient")
+
+        # Import mock endpoint classes
+        all_exports = ["MockAPIClient"]
+        for tag, class_name, module_name in sorted(tag_tuples, key=lambda x: x[2]):
+            mock_class_name = f"Mock{class_name}"
+            lines.append(f"from .endpoints.mock_{module_name} import {mock_class_name}")
+            all_exports.append(mock_class_name)
+
+        lines.append("")
+        lines.append("__all__ = [")
+        for export in all_exports:
+            lines.append(f'    "{export}",')
+        lines.append("]")
+
+        return "\n".join(lines)