pyopenapi-gen 2.7.2__py3-none-any.whl

pyopenapi_gen/core/writers/python_construct_renderer.py

@@ -0,0 +1,321 @@
+"""
+PythonConstructRenderer: Renders Python language constructs like classes, enums, and type aliases.
+
+This module provides the PythonConstructRenderer class, which is responsible for
+generating well-formatted Python code for common constructs used in the generated client.
+It handles all the details of formatting, import registration, and docstring generation
+for these constructs.
+"""
+
+from typing import List, Tuple
+
+from pyopenapi_gen.context.render_context import RenderContext
+
+from .code_writer import CodeWriter
+from .documentation_writer import DocumentationBlock, DocumentationWriter
+
+
+class PythonConstructRenderer:
+    """
+    Generates Python code for common constructs like dataclasses, enums, and type aliases.
+
+    This class provides methods to render different Python language constructs with
+    proper formatting, documentation, and import handling. It uses CodeWriter and
+    DocumentationWriter internally to ensure consistent output and automatically
+    registers necessary imports into the provided RenderContext.
+
+    The renderer handles:
+    - Type aliases (e.g., UserId = str)
+    - Enums (with str or int values)
+    - Dataclasses (with required and optional fields)
+    - Generic classes (with bases, docstrings, and body)
+    """
+
+    def render_alias(
+        self,
+        alias_name: str,
+        target_type: str,
+        description: str | None,
+        context: RenderContext,
+    ) -> str:
+        """
+        Render a type alias assignment as Python code.
+
+        Args:
+            alias_name: The name for the type alias
+            target_type: The target type expression
+            description: Optional description for the docstring
+            context: The rendering context for import registration
+
+        Returns:
+            Formatted Python code for the type alias
+
+        Example:
+            ```python
+            # Assuming: from typing import TypeAlias
+            UserId: TypeAlias = str
+            '''Alias for a user identifier'''  # Reverted to triple-single for example
+            ```
+        """
+        writer = CodeWriter()
+        # Add TypeAlias import
+        context.add_import("typing", "TypeAlias")
+        # Register imports needed by the target type itself
+        context.add_typing_imports_for_type(target_type)
+
+        # Add __all__ export
+        writer.write_line(f'__all__ = ["{alias_name}"]')
+        writer.write_line("")  # Add a blank line for separation
+
+        writer.write_line(f"{alias_name}: TypeAlias = {target_type}")
+        if description:
+            # Sanitize description for use within a triple-double-quoted string for the actual docstring
+            safe_desc_content = description.replace("\\", "\\\\")  # Escape backslashes first
+            safe_desc_content = safe_desc_content.replace('"""', '\\"\\"\\"')  # Escape triple-double-quotes
+            writer.write_line(f'"""Alias for {safe_desc_content}"""')  # Actual generated docstring uses """
+        return writer.get_code()
+
+    def render_enum(
+        self,
+        enum_name: str,
+        base_type: str,  # 'str' or 'int'
+        values: List[Tuple[str, str | int]],  # List of (MEMBER_NAME, value)
+        description: str | None,
+        context: RenderContext,
+    ) -> str:
+        """
+        Render an Enum class as Python code.
+
+        Args:
+            enum_name: The name of the enum class
+            base_type: The base type, either 'str' or 'int'
+            values: List of (member_name, value) pairs
+            description: Optional description for the docstring
+            context: The rendering context for import registration
+
+        Returns:
+            Formatted Python code for the enum class
+
+        Example:
+            ```python
+            @unique
+            class Color(str, Enum):
+                \"\"\"Color options available in the API\"\"\"
+                RED = "red"
+                GREEN = "green"
+                BLUE = "blue"
+            ```
+        """
+        writer = CodeWriter()
+        context.add_import("enum", "Enum")
+        context.add_import("enum", "unique")
+
+        # Add __all__ export
+        writer.write_line(f'__all__ = ["{enum_name}"]')
+        writer.write_line("")  # Add a blank line for separation
+
+        writer.write_line("@unique")
+        writer.write_line(f"class {enum_name}(" + base_type + ", Enum):")
+        writer.indent()
+
+        # Build and write docstring
+        doc_args: list[tuple[str, str, str] | tuple[str, str]] = []
+        for member_name, value in values:
+            doc_args.append((str(value), base_type, f"Value for {member_name}"))
+        doc_block = DocumentationBlock(
+            summary=description or f"{enum_name} Enum",
+            args=doc_args if doc_args else None,
+        )
+        docstring = DocumentationWriter(width=88).render_docstring(doc_block, indent=0)
+        for line in docstring.splitlines():
+            writer.write_line(line)
+
+        # Write Enum members
+        for member_name, value in values:
+            if base_type == "str":
+                writer.write_line(f'{member_name} = "{value}"')
+            else:  # int
+                writer.write_line(f"{member_name} = {value}")
+
+        writer.dedent()
+        return writer.get_code()
+
+    def render_dataclass(
+        self,
+        class_name: str,
+        fields: List[Tuple[str, str, str | None, str | None]],  # name, type_hint, default_expr, description
+        description: str | None,
+        context: RenderContext,
+        field_mappings: dict[str, str] | None = None,
+    ) -> str:
+        """
+        Render a dataclass as Python code with cattrs field mapping support.
+
+        Args:
+            class_name: The name of the dataclass
+            fields: List of (name, type_hint, default_expr, description) tuples for each field
+            description: Optional description for the class docstring
+            context: The rendering context for import registration
+            field_mappings: Optional mapping of API field names to Python field names (Meta class)
+
+        Returns:
+            Formatted Python code for the dataclass
+
+        Example:
+            ```python
+            @dataclass
+            class User:
+                \"\"\"User information with automatic JSON field mapping via cattrs.\"\"\"
+                id_: str
+                first_name: str
+                email: str | None = None
+                is_active: bool = True
+
+                class Meta:
+                    \"\"\"Configure field name mapping for JSON conversion.\"\"\"
+                    key_transform_with_load = {
+                        'id': 'id_',
+                        'firstName': 'first_name'
+                    }
+            ```
+        """
+        writer = CodeWriter()
+        context.add_import("dataclasses", "dataclass")
+
+        # No BaseSchema needed - using cattrs for serialization
+        # Field mappings will be handled by cattrs converter
+
+        # Add __all__ export
+        writer.write_line(f'__all__ = ["{class_name}"]')
+        writer.write_line("")  # Add a blank line for separation
+
+        writer.write_line("@dataclass")
+        writer.write_line(f"class {class_name}:")
+        writer.indent()
+
+        # Build and write docstring
+        field_args: list[tuple[str, str, str] | tuple[str, str]] = []
+        for name, type_hint, _, field_desc in fields:
+            field_args.append((name, type_hint, field_desc or ""))
+
+        # Simple description
+        base_description = description or f"{class_name} dataclass"
+        enhanced_description = base_description
+
+        doc_block = DocumentationBlock(
+            summary=enhanced_description,
+            args=field_args if field_args else None,
+        )
+        docstring = DocumentationWriter(width=88).render_docstring(doc_block, indent=0)
+        for line in docstring.splitlines():
+            writer.write_line(line)
+
+        # Write fields
+        if not fields:
+            writer.write_line("# No properties defined in schema")
+            writer.write_line("pass")
+        else:
+            # Separate required and optional fields for correct ordering (no defaults first)
+            required_fields = [f for f in fields if f[2] is None]  # default_expr is None
+            optional_fields = [f for f in fields if f[2] is not None]  # default_expr is not None
+
+            # Required fields
+            for name, type_hint, _, field_desc in required_fields:
+                line = f"{name}: {type_hint}"
+                if field_desc:
+                    comment_text = field_desc.replace("\n", " ")
+                    line += f"  # {comment_text}"
+                writer.write_line(line)
+
+            # Optional fields
+            for name, type_hint, default_expr, field_desc in optional_fields:
+                if default_expr and "default_factory" in default_expr:
+                    context.add_import("dataclasses", "field")  # Ensure field is imported
+                line = f"{name}: {type_hint} = {default_expr}"
+                if field_desc:
+                    comment_text = field_desc.replace("\n", " ")
+                    line += f"  # {comment_text}"
+                writer.write_line(line)
+
+        # Add Meta class if field mappings are provided (for cattrs field mapping)
+        if field_mappings:
+            writer.write_line("")  # Blank line before Meta class
+            writer.write_line("class Meta:")
+            writer.indent()
+            writer.write_line('"""Configure field name mapping for JSON conversion."""')
+
+            # key_transform_with_load: API field name -> Python field name (for deserialization)
+            writer.write_line("key_transform_with_load = {")
+            writer.indent()
+            for api_field, python_field in sorted(field_mappings.items()):
+                writer.write_line(f'"{api_field}": "{python_field}",')
+            writer.dedent()
+            writer.write_line("}")
+
+            # key_transform_with_dump: Python field name -> API field name (for serialization)
+            writer.write_line("key_transform_with_dump = {")
+            writer.indent()
+            # Reverse the mapping for dump
+            for api_field, python_field in sorted(field_mappings.items(), key=lambda x: x[1]):
+                writer.write_line(f'"{python_field}": "{api_field}",')
+            writer.dedent()
+            writer.write_line("}")
+
+            writer.dedent()
+
+        writer.dedent()
+        return writer.get_code()
+
+    def render_class(
+        self,
+        class_name: str,
+        base_classes: List[str] | None,
+        docstring: str | None,
+        body_lines: List[str] | None,
+        context: RenderContext,
+    ) -> str:
+        """
+        Render a generic class definition as Python code.
+
+        Args:
+            class_name: The name of the class
+            base_classes: Optional list of base class names (for inheritance)
+            docstring: Optional class docstring content
+            body_lines: Optional list of code lines for the class body
+            context: The rendering context (not used for generic classes)
+
+        Returns:
+            Formatted Python code for the class
+
+        Example:
+            ```python
+            class CustomError(Exception):
+                \"\"\"Raised when a custom error occurs.\"\"\"
+                def __init__(self, message: str, code: int):
+                    self.code = code
+                    super().__init__(message)
+            ```
+        """
+        writer = CodeWriter()
+        bases = f"({', '.join(base_classes)})" if base_classes else ""
+        writer.write_line(f"class {class_name}{bases}:")
+        writer.indent()
+        has_content = False
+        if docstring:
+            # Simple triple-quoted docstring is sufficient for exceptions
+            writer.write_line(f'"""{docstring}"""')
+            has_content = True
+        if body_lines:
+            for line in body_lines:
+                # Handle empty lines without adding indentation (Ruff W293)
+                if line == "":
+                    writer.writer.newline()  # Just add a newline, no indent
+                else:
+                    writer.write_line(line)
+            has_content = True
+
+        if not has_content:
+            writer.write_line("pass")  # Need pass if class is completely empty
+
+        writer.dedent()
+        return writer.get_code()

pyopenapi_gen/core_package_template/README.md

@@ -0,0 +1,21 @@
+# Core Runtime Components
+
+This directory contains the core runtime components required by the generated API client.
+
+## Client Independence
+
+**The generated API client is fully independent and does NOT require the `pyopenapi_gen` package to be installed at runtime.**
+
+All necessary base classes, protocols, transport implementations, and utility functions are included directly within this `core` package. You can safely use the generated client in any Python environment without installing the generator itself.
+
+## Shared Core (Optional)
+
+In scenarios where multiple API clients are generated (perhaps for different services within the same ecosystem), you might want to share a single instance of this `core` package to avoid duplication.
+
+To achieve this:
+1.  Generate the first client normally. This will create the `core` package.
+2.  Move or copy this `core` package to a location accessible by all your client packages (e.g., a shared `libs` directory).
+3.  Ensure this shared location is included in your Python environment's `PYTHONPATH`.
+4.  When generating subsequent clients, use the `--core-import-path <path_to_shared_core>` option with `pyopenapi-gen`. This tells the generator *not* to create a new `core` directory but instead to generate imports relative to the specified shared path (e.g., `from shared_libs.core.http_transport import HttpTransport`).
+
+This allows multiple clients to reuse the same base implementation, reducing code size and ensuring consistency. 

pyopenapi_gen/emit/models_emitter.py

@@ -0,0 +1,143 @@
+import logging
+from pathlib import Path
+from typing import List
+
+from pyopenapi_gen.context.render_context import RenderContext
+from pyopenapi_gen.core.utils import NameSanitizer
+from pyopenapi_gen.core.writers.code_writer import CodeWriter
+from pyopenapi_gen.ir import IRSchema
+from pyopenapi_gen.visit.model.model_visitor import ModelVisitor
+
+logger = logging.getLogger(__name__)
+
+
+class ModelsEmitter:
+    """Emits model files (dataclasses, enums) from IRSchema definitions."""
+
+    def __init__(self, context: RenderContext):
+        self.context = context
+        # self.import_collector is available via self.context.import_collector
+        # self.writer an instance CodeWriter() here seems unused globally for this emitter.
+        # Each file generation part either writes directly or uses a local CodeWriter.
+
+    def _generate_model_file(self, schema_ir: IRSchema, models_dir: Path) -> str | None:
+        """Generates a single Python file for a given IRSchema. Returns file path if generated."""
+        if not schema_ir.name:
+            logger.warning(f"Skipping model generation for schema without a name: {schema_ir}")
+            return None
+
+        # Ensure context has parsed_schemas before ModelVisitor uses it
+        if not self.context.parsed_schemas:
+            logger.error(
+                "[ModelsEmitter._generate_model_file] RenderContext is missing parsed_schemas. Cannot generate model."
+            )
+            return None
+
+        module_name = NameSanitizer.sanitize_module_name(schema_ir.name)
+        # class_name = NameSanitizer.sanitize_class_name(schema_ir.name) # Not directly used here for file content
+        file_path = models_dir / f"{module_name}.py"
+
+        # Set current file on RenderContext. This also resets its internal ImportCollector.
+        self.context.set_current_file(str(file_path))
+
+        # ModelsEmitter's import_collector should be the same instance as RenderContext's.
+        # The line `self.import_collector = self.context.import_collector` was added in __init__
+        # or after set_current_file previously. Let's ensure it's correctly synced if there was any doubt.
+        current_ic = self.context.import_collector  # Use the collector from the context
+
+        # Instantiate ModelVisitor
+        # ModelVisitor will use self.context (and thus current_ic) to add imports.
+        visitor = ModelVisitor(schemas=self.context.parsed_schemas)
+        rendered_model_str = visitor.visit(schema_ir, self.context)
+
+        # Get collected imports for the current file.
+        imports_list = current_ic.get_import_statements()
+        imports_code = "\n".join(imports_list)
+
+        # The model_code is what the visitor returned.
+        model_code = rendered_model_str
+
+        full_code = imports_code + "\n\n" + model_code if imports_code else model_code
+
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        with file_path.open("w", encoding="utf-8") as f:
+            f.write(full_code)
+        # self.writer.clear() # ModelsEmitter's self.writer is not used for individual model file body
+        # logger.debug(f"Generated model file: {file_path} for schema: {schema_ir.name}")
+        return str(file_path)
+
+    def _generate_init_py(self, models_dir: Path) -> str:
+        """Generates the models/__init__.py file and returns its path."""
+        init_writer = CodeWriter()
+        # ... (content generation as before) ...
+        all_class_names: List[str] = []
+        # Ensure self.context.parsed_schemas is not None before iterating
+        if not self.context.parsed_schemas:
+            logger.warning("No parsed schemas found in context for generating models/__init__.py")
+            # Still create an empty __init__.py with basic imports
+            init_writer.write_line("from typing import List, Optional, Union, Any, Dict, Generic, TypeVar")
+            init_writer.write_line("from dataclasses import dataclass, field")
+            init_writer.write_line("__all__ = []")
+            init_content = str(init_writer)
+            init_file_path = models_dir / "__init__.py"
+            with init_file_path.open("w", encoding="utf-8") as f:
+                f.write(init_content)
+            return str(init_file_path)
+
+        # This point onwards, self.context.parsed_schemas is guaranteed to be non-None
+        sorted_schema_items = sorted(self.context.parsed_schemas.items())
+
+        for schema_key, s in sorted_schema_items:
+            if not s.name:
+                logger.warning(f"Schema with key '{schema_key}' has no name, skipping for __init__.py")
+                continue
+            module_name = NameSanitizer.sanitize_module_name(s.name)
+            class_name = NameSanitizer.sanitize_class_name(s.name)
+            if module_name == "__init__":
+                logger.warning(f"Skipping import for schema '{s.name}' as its module name is __init__.")
+                continue
+            init_writer.write_line(f"from .{module_name} import {class_name}")
+            all_class_names.append(class_name)
+
+        init_writer.write_line("from typing import List, Optional, Union, Any, Dict, Generic, TypeVar")
+        init_writer.write_line("from dataclasses import dataclass, field")
+        init_writer.write_line("")
+
+        # Re-add imports for each class to ensure they are structured correctly by CodeWriter
+        # This is a bit redundant if CodeWriter handles sections, but safe.
+        # For __init__.py, it might be simpler to just list exports.
+
+        init_writer.write_line("")
+        init_writer.write_line("__all__ = [")
+        for name in sorted(all_class_names):
+            init_writer.write_line(f"    '{name}',")
+        init_writer.write_line("]")
+        init_content = str(init_writer)  # This needs to be CodeWriter.render() or similar if sections are used
+
+        init_file_path = models_dir / "__init__.py"
+        with init_file_path.open("w", encoding="utf-8") as f:
+            f.write(init_content)
+        return str(init_file_path)
+
+    def emit(self, output_base_dir: Path) -> List[str]:
+        """Emits all model files and the models/__init__.py file into <output_base_dir>/models/."""
+        models_dir = output_base_dir / "models"
+        models_dir.mkdir(parents=True, exist_ok=True)
+        generated_files: List[str] = []
+
+        if not self.context.parsed_schemas:
+            logger.warning("No parsed schemas found in context. Skipping model file generation.")
+        else:
+            sorted_schemas = sorted(self.context.parsed_schemas.values(), key=lambda s: s.name or "")
+            for schema_ir in sorted_schemas:
+                if schema_ir.name:
+                    file_path = self._generate_model_file(schema_ir, models_dir)
+                    if file_path:
+                        generated_files.append(file_path)
+                else:
+                    # logger.debug(f"Skipping file generation for unnamed schema: {schema_ir.type}")
+                    pass  # Schema has no name, already warned in _generate_model_file or skipped if truly unnamed
+
+        init_py_path = self._generate_init_py(models_dir)
+        generated_files.append(init_py_path)
+        return generated_files