pyopenapi-gen 0.21.1__py3-none-any.whl → 0.22.0__py3-none-any.whl

pyopenapi_gen/__init__.py

@@ -50,7 +50,7 @@ __all__ = [
 ]
 
 # Semantic version of the generator core – automatically managed by semantic-release.
-__version__: str = "0.21.1"
+__version__: str = "0.22.0"
 
 # ---------------------------------------------------------------------------
 # Lazy-loading and autocompletion support (This part remains)

pyopenapi_gen/emitters/endpoints_emitter.py

@@ -197,6 +197,7 @@ class EndpointsEmitter:
             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
@@ -208,21 +209,35 @@ class EndpointsEmitter:
             if self.visitor is None:
                 raise RuntimeError("EndpointVisitor not initialized")
             methods = [self.visitor.visit(op, self.context) for op in ops_for_tag]
-            class_content = self.visitor.emit_endpoint_client_class(canonical_tag_name, methods, self.context)
+            # 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:
-            all_list_items = sorted([f'"{cls}"' for cls, _ in 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):
-                init_lines.append(f"from .{mod} import {cls}")
+                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")

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)

pyopenapi_gen/generator/client_generator.py

@@ -19,6 +19,7 @@ from pyopenapi_gen.emitters.client_emitter import ClientEmitter
 from pyopenapi_gen.emitters.core_emitter import CoreEmitter
 from pyopenapi_gen.emitters.endpoints_emitter import EndpointsEmitter
 from pyopenapi_gen.emitters.exceptions_emitter import ExceptionsEmitter
+from pyopenapi_gen.emitters.mocks_emitter import MocksEmitter
 from pyopenapi_gen.emitters.models_emitter import ModelsEmitter
 
 logger = logging.getLogger(__name__)
@@ -277,6 +278,13 @@ class ClientGenerator:
                 temp_generated_files += client_files
                 self._log_progress(f"Generated {len(client_files)} client files (temp)", "EMIT_CLIENT_TEMP")
 
+                # 7. MocksEmitter (emits mock files to tmp_out_dir_for_diff)
+                self._log_progress("Generating mock helper classes (temp)", "EMIT_MOCKS_TEMP")
+                mocks_emitter = MocksEmitter(context=tmp_render_context_for_diff)
+                mock_files = [Path(p) for p in mocks_emitter.emit(ir, str(tmp_out_dir_for_diff))]
+                temp_generated_files += mock_files
+                self._log_progress(f"Generated {len(mock_files)} mock files (temp)", "EMIT_MOCKS_TEMP")
+
                 # Post-processing should run on the temporary files if enabled
                 if not no_postprocess:
                     self._log_progress("Running post-processing on temporary files", "POSTPROCESS_TEMP")
@@ -431,6 +439,13 @@ class ClientGenerator:
             generated_files += client_files
             self._log_progress(f"Generated {len(client_files)} client files", "EMIT_CLIENT")
 
+            # 7. MocksEmitter
+            self._log_progress("Generating mock helper classes", "EMIT_MOCKS")
+            mocks_emitter = MocksEmitter(context=main_render_context)
+            mock_files = [Path(p) for p in mocks_emitter.emit(ir, str(out_dir))]
+            generated_files += mock_files
+            self._log_progress(f"Generated {len(mock_files)} mock files", "EMIT_MOCKS")
+
             # After all emitters, if core_package is specified (external core),
             # create a rich __init__.py in the client's output_package (out_dir).
             if core_package:  # core_package is the user-provided original arg

pyopenapi_gen/visit/client_visitor.py

@@ -24,6 +24,7 @@ class ClientVisitor:
         pass
 
     def visit(self, spec: IRSpec, context: RenderContext) -> str:
+        # Step 1: Process tags and build tag_tuples
         tag_candidates: dict[str, list[str]] = {}
         for op in spec.operations:
             # Use DEFAULT_TAG consistent with EndpointsEmitter
@@ -60,11 +61,38 @@ class ClientVisitor:
             )
             for key in sorted(tag_map)
         ]
+
+        # Step 2: Generate Protocol definition
+        protocol_code = self.generate_client_protocol(spec, context, tag_tuples)
+
+        # Step 3: Generate implementation class
+        impl_code = self._generate_client_implementation(spec, context, tag_tuples)
+
+        # Step 4: Combine Protocol and implementation
+        return f"{protocol_code}\n\n\n{impl_code}"
+
+    def _generate_client_implementation(
+        self, spec: IRSpec, context: RenderContext, tag_tuples: list[tuple[str, str, str]]
+    ) -> str:
+        """
+        Generate the APIClient implementation class.
+
+        Args:
+            spec: The IR specification
+            context: Render context for import management
+            tag_tuples: List of (tag_name, class_name, module_name) tuples
+
+        Returns:
+            Implementation class code as string
+        """
         writer = CodeWriter()
         # Register all endpoint client imports using relative imports (endpoints are within the same package)
         for _, class_name, module_name in tag_tuples:
             # Use relative imports for endpoints since they're part of the same generated package
+            # Import both the implementation and the Protocol
+            protocol_name = f"{class_name}Protocol"
             context.import_collector.add_relative_import(f".endpoints.{module_name}", class_name)
+            context.import_collector.add_relative_import(f".endpoints.{module_name}", protocol_name)
 
         # Register core/config/typing imports for class signature
         # Use LOGICAL import path for core components
@@ -82,8 +110,8 @@ class ClientVisitor:
         context.add_typing_imports_for_type("HttpTransport | None")
         context.add_typing_imports_for_type("Any")
         context.add_typing_imports_for_type("Dict")
-        # Class definition
-        writer.write_line("class APIClient:")
+        # Class definition - implements Protocol
+        writer.write_line("class APIClient(APIClientProtocol):")
         writer.indent()
         # Build docstring for APIClient
         docstring_lines = []
@@ -224,3 +252,226 @@ class ClientVisitor:
         context.add_import(f"{context.core_package_name}.config", "ClientConfig")
 
         return writer.get_code()
+
+    def generate_client_protocol(
+        self, spec: IRSpec, context: RenderContext, tag_tuples: list[tuple[str, str, str]]
+    ) -> str:
+        """
+        Generate APIClientProtocol defining the client interface.
+
+        Args:
+            spec: The IR specification
+            context: Render context for import management
+            tag_tuples: List of (tag_name, class_name, module_name) tuples
+
+        Returns:
+            Protocol class code as string with:
+            - Tag-based endpoint properties
+            - Standard methods (request, close, __aenter__, __aexit__)
+        """
+        # Register Protocol imports
+        context.add_typing_imports_for_type("Protocol")
+        context.add_import("typing", "runtime_checkable")
+        context.add_typing_imports_for_type("Any")
+
+        writer = CodeWriter()
+
+        # Protocol class header
+        writer.write_line("@runtime_checkable")
+        writer.write_line("class APIClientProtocol(Protocol):")
+        writer.indent()
+
+        # Docstring
+        writer.write_line('"""Protocol defining the interface of APIClient for dependency injection."""')
+        writer.write_line("")
+
+        # Tag-based endpoint properties
+        for tag, class_name, module_name in tag_tuples:
+            # Use forward reference for tag client protocol
+            protocol_name = f"{class_name}Protocol"
+            writer.write_line("@property")
+            writer.write_line(f"def {module_name}(self) -> '{protocol_name}':")
+            writer.indent()
+            writer.write_line("...")
+            writer.dedent()
+            writer.write_line("")
+
+        # Standard methods
+        # request method
+        writer.write_line("async def request(self, method: str, url: str, **kwargs: Any) -> Any:")
+        writer.indent()
+        writer.write_line("...")
+        writer.dedent()
+        writer.write_line("")
+
+        # close method
+        writer.write_line("async def close(self) -> None:")
+        writer.indent()
+        writer.write_line("...")
+        writer.dedent()
+        writer.write_line("")
+
+        # __aenter__ method
+        writer.write_line("async def __aenter__(self) -> 'APIClientProtocol':")
+        writer.indent()
+        writer.write_line("...")
+        writer.dedent()
+        writer.write_line("")
+
+        # __aexit__ method
+        context.add_typing_imports_for_type("type[BaseException] | None")
+        context.add_typing_imports_for_type("BaseException | None")
+        context.add_typing_imports_for_type("object | None")
+        writer.write_line(
+            "async def __aexit__(self, exc_type: type[BaseException] | None, "
+            "exc_val: BaseException | None, exc_tb: object | None) -> None:"
+        )
+        writer.indent()
+        writer.write_line("...")
+        writer.dedent()
+
+        writer.dedent()  # Close class
+        return writer.get_code()
+
+    def generate_client_mock_class(
+        self, spec: IRSpec, context: RenderContext, tag_tuples: list[tuple[str, str, str]]
+    ) -> str:
+        """
+        Generate MockAPIClient for testing.
+
+        Args:
+            spec: The IR specification
+            context: Render context for import management
+            tag_tuples: List of (tag, class_name, module_name) tuples
+
+        Returns:
+            Mock client class code as string
+        """
+        # Import TYPE_CHECKING for Protocol imports
+        context.add_import("typing", "TYPE_CHECKING")
+        context.add_import("typing", "Any")
+
+        writer = CodeWriter()
+
+        # TYPE_CHECKING imports
+        writer.write_line("if TYPE_CHECKING:")
+        writer.indent()
+        writer.write_line("from ..client import APIClientProtocol")
+        for tag, class_name, module_name in tag_tuples:
+            protocol_name = f"{class_name}Protocol"
+            writer.write_line(f"from ..endpoints.{module_name} import {protocol_name}")
+        writer.dedent()
+        writer.write_line("")
+
+        # Import mock endpoint classes
+        for tag, class_name, module_name in tag_tuples:
+            mock_class_name = f"Mock{class_name}"
+            writer.write_line(f"from .endpoints.mock_{module_name} import {mock_class_name}")
+        writer.write_line("")
+
+        # Class definition
+        writer.write_line("class MockAPIClient:")
+        writer.indent()
+
+        # Docstring
+        writer.write_line('"""')
+        writer.write_line("Mock implementation of APIClient for testing.")
+        writer.write_line("")
+        writer.write_line("Auto-creates default mock implementations for all tag-based endpoint clients.")
+        writer.write_line("You can override specific tag clients by passing them to the constructor.")
+        writer.write_line("")
+        writer.write_line("Example:")
+        writer.write_line("    # Use all defaults")
+        writer.write_line("    client = MockAPIClient()")
+        writer.write_line("")
+        writer.write_line("    # Override specific tag client")
+        for tag, class_name, module_name in tag_tuples[:1]:  # Show example with first tag
+            mock_class_name = f"Mock{class_name}"
+            writer.write_line(f"    class My{class_name}Mock({mock_class_name}):")
+            writer.write_line("        async def method_name(self, ...) -> ReturnType:")
+            writer.write_line("            return test_data")
+            writer.write_line("")
+            writer.write_line(f"    client = MockAPIClient({module_name}=My{class_name}Mock())")
+            break
+        writer.write_line('"""')
+        writer.write_line("")
+
+        # Constructor
+        writer.write_line("def __init__(")
+        writer.indent()
+        writer.write_line("self,")
+        for tag, class_name, module_name in tag_tuples:
+            protocol_name = f"{class_name}Protocol"
+            writer.write_line(f'{module_name}: "{protocol_name} | None" = None,')
+        writer.dedent()
+        writer.write_line(") -> None:")
+        writer.indent()
+
+        # Initialize tag clients
+        for tag, class_name, module_name in tag_tuples:
+            mock_class_name = f"Mock{class_name}"
+            writer.write_line(
+                f"self._{module_name} = {module_name} if {module_name} is not None else {mock_class_name}()"
+            )
+        writer.dedent()
+        writer.write_line("")
+
+        # Properties for tag clients
+        for tag, class_name, module_name in tag_tuples:
+            protocol_name = f"{class_name}Protocol"
+            writer.write_line("@property")
+            writer.write_line(f'def {module_name}(self) -> "{protocol_name}":')
+            writer.indent()
+            writer.write_line(f"return self._{module_name}")
+            writer.dedent()
+            writer.write_line("")
+
+        # request() method
+        writer.write_line("async def request(self, method: str, url: str, **kwargs: Any) -> Any:")
+        writer.indent()
+        writer.write_line('"""')
+        writer.write_line("Mock request method - raises NotImplementedError.")
+        writer.write_line("")
+        writer.write_line("This is a low-level method - consider using tag-specific methods instead.")
+        writer.write_line('"""')
+        writer.write_line(
+            "raise NotImplementedError("
+            '"MockAPIClient.request() not implemented. '
+            'Use tag-specific methods instead."'
+            ")"
+        )
+        writer.dedent()
+        writer.write_line("")
+
+        # close() method
+        writer.write_line("async def close(self) -> None:")
+        writer.indent()
+        writer.write_line('"""Mock close method - no-op for testing."""')
+        writer.write_line("pass  # No cleanup needed for mocks")
+        writer.dedent()
+        writer.write_line("")
+
+        # __aenter__() method
+        writer.write_line('async def __aenter__(self) -> "APIClientProtocol":')
+        writer.indent()
+        writer.write_line('"""Enter async context manager."""')
+        writer.write_line("return self")
+        writer.dedent()
+        writer.write_line("")
+
+        # __aexit__() method
+        writer.write_line(
+            "async def __aexit__("
+            "self, "
+            "exc_type: type[BaseException] | None, "
+            "exc_val: BaseException | None, "
+            "exc_tb: object | None"
+            ") -> None:"
+        )
+        writer.indent()
+        writer.write_line('"""Exit async context manager - no-op for mocks."""')
+        writer.write_line("pass  # No cleanup needed for mocks")
+        writer.dedent()
+
+        writer.dedent()  # Close class
+        return writer.get_code()