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

pyopenapi_gen/visit/endpoint/endpoint_visitor.py

@@ -42,6 +42,7 @@ class EndpointVisitor(Visitor[IROperation, str]):
         tag: str,
         method_codes: list[str],
         context: RenderContext,
+        operations: list[IROperation] | None = None,
     ) -> str:
         """
         Emit the endpoint client class for a tag, aggregating all endpoint methods.
@@ -50,6 +51,152 @@ class EndpointVisitor(Visitor[IROperation, str]):
             tag: The tag name for the endpoint group.
             method_codes: List of method code blocks as strings.
             context: The RenderContext for import tracking.
+            operations: List of operations for Protocol generation (optional for backwards compatibility).
+        """
+        # Generate Protocol if operations provided
+        protocol_code = ""
+        if operations:
+            protocol_code = self.generate_endpoint_protocol(tag, operations, context)
+
+        # Generate implementation
+        impl_code = self._generate_endpoint_implementation(tag, method_codes, context)
+
+        # Combine Protocol and implementation
+        if protocol_code:
+            return f"{protocol_code}\n\n\n{impl_code}"
+        else:
+            return impl_code
+
+    def generate_endpoint_protocol(self, tag: str, operations: list[IROperation], context: RenderContext) -> str:
+        """
+        Generate Protocol definition for tag-based endpoint client.
+
+        Args:
+            tag: The tag name for the endpoint group
+            operations: List of operations for this tag
+            context: Render context for import management
+
+        Returns:
+            Protocol class code as string with all operation method signatures
+        """
+        # Register Protocol imports
+        context.add_import("typing", "Protocol")
+        context.add_import("typing", "runtime_checkable")
+
+        writer = CodeWriter()
+        class_name = NameSanitizer.sanitize_class_name(tag) + "Client"
+        protocol_name = f"{class_name}Protocol"
+
+        # Protocol class header
+        writer.write_line("@runtime_checkable")
+        writer.write_line(f"class {protocol_name}(Protocol):")
+        writer.indent()
+
+        # Docstring
+        writer.write_line(f'"""Protocol defining the interface of {class_name} for dependency injection."""')
+        writer.write_line("")
+
+        # Generate method signatures from operations
+        # We need to extract complete signatures including multi-line ones and decorators
+        # For Protocol, we only include the method signatures with ..., not implementations
+        # IMPORTANT: Preserve multi-line formatting for readability
+        for op in operations:
+            method_generator = EndpointMethodGenerator(schemas=self.schemas)
+            full_method_code = method_generator.generate(op, context)
+
+            # Parse the generated code to extract method signatures
+            # We want: @overload stubs (already have ...) and final signature converted to stub
+            lines = full_method_code.split("\n")
+            i = 0
+
+            while i < len(lines):
+                line = lines[i]
+                stripped = line.strip()
+
+                # Handle @overload decorator
+                if stripped.startswith("@overload"):
+                    # Write decorator
+                    writer.write_line(stripped)
+                    i += 1
+
+                    # Now process the signature following the decorator
+                    # Keep collecting lines until we hit the end of the overload signature
+                    while i < len(lines):
+                        sig_line = lines[i]
+                        sig_stripped = sig_line.strip()
+
+                        # Write each line of the signature
+                        writer.write_line(sig_stripped)
+
+                        # Check for end of overload signature (ends with `: ...`)
+                        if sig_stripped.endswith(": ..."):
+                            writer.write_line("")  # Blank line after overload
+                            i += 1
+                            break
+
+                        i += 1
+                    continue
+
+                # Handle non-overload method signatures (the final implementation signature)
+                if stripped.startswith("async def ") and "(" in stripped:
+                    # This is the start of a method signature
+                    # We need to collect all lines until we hit the colon
+                    signature_lines = []
+
+                    # Collect signature lines
+                    while i < len(lines):
+                        sig_line = lines[i]
+                        sig_stripped = sig_line.strip()
+
+                        signature_lines.append(sig_stripped)
+
+                        # Check if this completes the signature (ends with :)
+                        if sig_stripped.endswith(":") and not sig_stripped.endswith(","):
+                            # This is the final line of the signature
+                            # For Protocol, convert to stub format
+
+                            # Check if this is an async generator (returns AsyncIterator)
+                            # If so, remove 'async' from the first line
+                            is_async_generator = "AsyncIterator" in sig_stripped
+
+                            # Write all lines except the last
+                            for idx, sig in enumerate(signature_lines[:-1]):
+                                # For async generators, remove 'async ' from method definition
+                                if idx == 0 and is_async_generator and sig.startswith("async def "):
+                                    sig = sig.replace("async def ", "def ", 1)
+                                writer.write_line(sig)
+
+                            # Write last line with ... instead of :
+                            last_line = signature_lines[-1]
+                            if last_line.endswith(":"):
+                                last_line = last_line[:-1]  # Remove trailing :
+                            writer.write_line(f"{last_line}: ...")
+                            writer.write_line("")  # Blank line after method
+
+                            # For Protocol, we only want the signature stub, not the implementation
+                            # Skip all remaining lines of this method by jumping to end
+                            i = len(lines)  # This will exit the while loop
+                            break
+
+                        i += 1
+                    continue
+
+                i += 1
+
+        writer.dedent()  # Close class
+        return writer.get_code()
+
+    def _generate_endpoint_implementation(self, tag: str, method_codes: list[str], context: RenderContext) -> str:
+        """
+        Generate the endpoint client implementation class.
+
+        Args:
+            tag: The tag name for the endpoint group
+            method_codes: List of method code blocks as strings
+            context: Render context for import management
+
+        Returns:
+            Implementation class code as string
         """
         context.add_import("typing", "cast")
         # Import core transport and streaming helpers
@@ -59,7 +206,10 @@ class EndpointVisitor(Visitor[IROperation, str]):
         context.add_import("typing", "Optional")
         writer = CodeWriter()
         class_name = NameSanitizer.sanitize_class_name(tag) + "Client"
-        writer.write_line(f"class {class_name}:")
+        protocol_name = f"{class_name}Protocol"
+
+        # Class definition - implements Protocol
+        writer.write_line(f"class {class_name}({protocol_name}):")
         writer.indent()
         writer.write_line(f'"""Client for {tag} endpoints. Uses HttpTransport for all HTTP and header management."""')
         writer.write_line("")
@@ -82,3 +232,61 @@ class EndpointVisitor(Visitor[IROperation, str]):
 
         writer.dedent()  # Dedent to close the class block
         return writer.get_code()
+
+    def generate_endpoint_mock_class(self, tag: str, operations: list[IROperation], context: RenderContext) -> str:
+        """
+        Generate mock implementation class for tag-based endpoint client.
+
+        Args:
+            tag: The tag name for the endpoint group
+            operations: List of operations for this tag
+            context: Render context for import management
+
+        Returns:
+            Mock class code as string with all operation method stubs
+        """
+        from .generators.mock_generator import MockGenerator
+
+        # Import Protocol for type checking
+        context.add_import("typing", "TYPE_CHECKING")
+
+        writer = CodeWriter()
+        class_name = NameSanitizer.sanitize_class_name(tag) + "Client"
+        protocol_name = f"{class_name}Protocol"
+        mock_class_name = f"Mock{class_name}"
+
+        # TYPE_CHECKING import for Protocol
+        writer.write_line("if TYPE_CHECKING:")
+        writer.indent()
+        writer.write_line(f"from ...endpoints.{NameSanitizer.sanitize_module_name(tag)} import {protocol_name}")
+        writer.dedent()
+        writer.write_line("")
+
+        # Class header with docstring
+        writer.write_line(f"class {mock_class_name}:")
+        writer.indent()
+        writer.write_line('"""')
+        writer.write_line(f"Mock implementation of {class_name} for testing.")
+        writer.write_line("")
+        writer.write_line("Provides default implementations that raise NotImplementedError.")
+        writer.write_line("Override methods as needed in your tests.")
+        writer.write_line("")
+        writer.write_line("Example:")
+        writer.write_line(f"    class Test{class_name}({mock_class_name}):")
+        writer.write_line("        async def method_name(self, ...) -> ReturnType:")
+        writer.write_line("            return test_data")
+        writer.write_line('"""')
+        writer.write_line("")
+
+        # Generate mock methods
+        mock_generator = MockGenerator(schemas=self.schemas)
+        for i, op in enumerate(operations):
+            mock_method_code = mock_generator.generate(op, context)
+            writer.write_block(mock_method_code)
+
+            if i < len(operations) - 1:
+                writer.write_line("")  # Blank line between methods
+                writer.write_line("")  # Second blank line for consistency
+
+        writer.dedent()  # Close class
+        return writer.get_code()

pyopenapi_gen/visit/endpoint/generators/mock_generator.py

@@ -0,0 +1,140 @@
+"""
+Generator for creating mock method implementations.
+
+This module generates mock methods that raise NotImplementedError,
+allowing users to create test doubles by subclassing and overriding
+only the methods they need.
+"""
+
+from typing import Any
+
+from ....context.render_context import RenderContext
+from ....core.utils import NameSanitizer
+from ....core.writers.code_writer import CodeWriter
+from ....ir import IROperation
+from .endpoint_method_generator import EndpointMethodGenerator
+
+
+class MockGenerator:
+    """
+    Generates mock method implementations for testing.
+
+    Mock methods preserve the exact signature of the real implementation
+    but raise NotImplementedError with helpful error messages instead
+    of performing actual operations.
+    """
+
+    def __init__(self, schemas: dict[str, Any] | None = None) -> None:
+        self.schemas = schemas or {}
+        self.method_generator = EndpointMethodGenerator(self.schemas)
+
+    def generate(self, op: IROperation, context: RenderContext) -> str:
+        """
+        Generate a mock method that raises NotImplementedError.
+
+        Args:
+            op: The operation to generate a mock for
+            context: Render context for import tracking
+
+        Returns:
+            Complete mock method code as string
+        """
+        # Generate the full method using EndpointMethodGenerator
+        full_method = self.method_generator.generate(op, context)
+
+        # Parse and transform it to a mock implementation
+        return self._transform_to_mock(full_method, op)
+
+    def _transform_to_mock(self, full_method_code: str, op: IROperation) -> str:
+        """
+        Transform a full method implementation into a mock that raises NotImplementedError.
+
+        Args:
+            full_method_code: Complete method code from EndpointMethodGenerator
+            op: The operation (for generating error messages)
+
+        Returns:
+            Mock method code with NotImplementedError body
+        """
+        lines = full_method_code.split("\n")
+        writer = CodeWriter()
+
+        i = 0
+        while i < len(lines):
+            line = lines[i]
+            stripped = line.strip()
+
+            # Handle @overload decorator - keep it
+            if stripped.startswith("@overload"):
+                writer.write_line(stripped)
+                i += 1
+
+                # Copy overload signature until we hit `: ...`
+                while i < len(lines):
+                    sig_line = lines[i]
+                    sig_stripped = sig_line.strip()
+                    writer.write_line(sig_stripped)
+
+                    if sig_stripped.endswith(": ..."):
+                        writer.write_line("")  # Blank line after overload
+                        i += 1
+                        break
+
+                    i += 1
+                continue
+
+            # Handle method definition (async def or def)
+            if (stripped.startswith("async def ") or stripped.startswith("def ")) and "(" in stripped:
+                # Determine if this is an async generator
+                is_async_generator = False
+
+                # Collect signature lines to check return type
+                signature_lines = []
+                temp_i = i
+                while temp_i < len(lines):
+                    sig_stripped = lines[temp_i].strip()
+                    signature_lines.append(sig_stripped)
+                    if sig_stripped.endswith(":") and not sig_stripped.endswith(","):
+                        # Check if AsyncIterator in return type
+                        full_sig = " ".join(signature_lines)
+                        is_async_generator = "AsyncIterator" in full_sig
+                        break
+                    temp_i += 1
+
+                # Write signature lines
+                for sig in signature_lines:
+                    writer.write_line(sig)
+
+                # Write mock body
+                writer.indent()
+
+                # Docstring
+                writer.write_line('"""')
+                writer.write_line("Mock implementation that raises NotImplementedError.")
+                writer.write_line("")
+                writer.write_line("Override this method in your test subclass to provide")
+                writer.write_line("the behavior needed for your test scenario.")
+                writer.write_line('"""')
+
+                # Error message
+                method_name = NameSanitizer.sanitize_method_name(op.operation_id)
+                tag = op.tags[0] if op.tags else "Client"
+                class_name = f"Mock{NameSanitizer.sanitize_class_name(tag)}Client"
+                error_msg = (
+                    f'"{class_name}.{method_name}() not implemented. ' f'Override this method in your test subclass."'
+                )
+                writer.write_line(f"raise NotImplementedError({error_msg})")
+
+                # For async generators, add unreachable yield for type checker
+                if is_async_generator:
+                    writer.write_line("yield  # pragma: no cover")
+
+                writer.dedent()
+
+                # Skip the rest of this method implementation in the original code
+                i = len(lines)  # Exit the loop
+                break
+
+            i += 1
+
+        return writer.get_code()