pyopenapi-gen 0.8.3__py3-none-any.whl

pyopenapi_gen/visit/model/dataclass_generator.py

@@ -0,0 +1,197 @@
+"""
+Generates Python code for dataclasses from IRSchema objects.
+"""
+
+import json
+import logging
+from typing import Dict, List, Optional, Tuple
+
+from pyopenapi_gen import IRSchema
+from pyopenapi_gen.context.render_context import RenderContext
+from pyopenapi_gen.core.utils import NameSanitizer
+from pyopenapi_gen.core.writers.python_construct_renderer import PythonConstructRenderer
+from pyopenapi_gen.helpers.type_resolution.finalizer import TypeFinalizer
+from pyopenapi_gen.types.services.type_service import UnifiedTypeService
+
+logger = logging.getLogger(__name__)
+
+
+class DataclassGenerator:
+    """Generates Python code for a dataclass."""
+
+    def __init__(
+        self,
+        renderer: PythonConstructRenderer,
+        all_schemas: Optional[Dict[str, IRSchema]],
+    ):
+        """
+        Initialize a new DataclassGenerator.
+
+        Contracts:
+            Pre-conditions:
+                - ``renderer`` is not None.
+        """
+        assert renderer is not None, "PythonConstructRenderer cannot be None."
+        self.renderer = renderer
+        self.all_schemas = all_schemas if all_schemas is not None else {}
+        self.type_service = UnifiedTypeService(self.all_schemas)
+
+    def _get_field_default(self, ps: IRSchema, context: RenderContext) -> Optional[str]:
+        """
+        Determines the default value expression string for a dataclass field.
+        This method is called for fields determined to be optional.
+
+        Args:
+            ps: The property schema to analyze.
+            context: The rendering context.
+
+        Returns:
+            A string representing the Python default value expression or None.
+
+        Contracts:
+            Pre-conditions:
+                - ``ps`` is not None.
+                - ``context`` is not None.
+            Post-conditions:
+                - Returns a valid Python default value string
+                  (e.g., "None", "field(default_factory=list)", "\"abc\"") or None.
+        """
+        assert ps is not None, "Property schema (ps) cannot be None."
+        assert context is not None, "RenderContext cannot be None."
+
+        if ps.type == "array":
+            context.add_import("dataclasses", "field")
+            return "field(default_factory=list)"
+        elif ps.type == "object" and ps.name is None and not ps.any_of and not ps.one_of and not ps.all_of:
+            context.add_import("dataclasses", "field")
+            return "field(default_factory=dict)"
+
+        if ps.default is not None:
+            if isinstance(ps.default, str):
+                escaped_inner_content = json.dumps(ps.default)[1:-1]
+                return '"' + escaped_inner_content + '"'
+            elif isinstance(ps.default, bool):
+                return str(ps.default)
+            elif isinstance(ps.default, (int, float)):
+                return str(ps.default)
+            else:
+                logger.warning(
+                    f"DataclassGenerator: Complex default value '{ps.default}' for field '{ps.name}' of type '{ps.type}"
+                    f" cannot be directly rendered. Falling back to None. Type: {type(ps.default)}"
+                )
+        return "None"
+
+    def generate(
+        self,
+        schema: IRSchema,
+        base_name: str,
+        context: RenderContext,
+    ) -> str:
+        """
+        Generates the Python code for a dataclass.
+
+        Args:
+            schema: The IRSchema for the dataclass.
+            base_name: The base name for the dataclass.
+            context: The render context.
+
+        Returns:
+            The generated Python code string for the dataclass.
+
+        Contracts:
+            Pre-conditions:
+                - ``schema`` is not None and ``schema.name`` is not None.
+                - ``base_name`` is a non-empty string.
+                - ``context`` is not None.
+                - ``schema.type`` is suitable for a dataclass (e.g. "object", or "array" for wrapper style).
+            Post-conditions:
+                - Returns a non-empty string containing valid Python code for a dataclass.
+                - ``@dataclass`` decorator is present, implying ``dataclasses.dataclass`` is imported.
+        """
+        assert schema is not None, "Schema cannot be None for dataclass generation."
+        assert schema.name is not None, "Schema name must be present for dataclass generation."
+        assert base_name, "Base name cannot be empty for dataclass generation."
+        assert context is not None, "RenderContext cannot be None."
+        # Additional check for schema type might be too strict here, as ModelVisitor decides eligibility.
+
+        class_name = base_name
+        fields_data: List[Tuple[str, str, Optional[str], Optional[str]]] = []
+
+        if schema.type == "array" and schema.items:
+            field_name_for_array_content = "items"
+            assert schema.items is not None, "Schema items must be present for array type dataclass field."
+
+            list_item_py_type = self.type_service.resolve_schema_type(schema.items, context, required=True)
+            list_item_py_type = TypeFinalizer(context)._clean_type(list_item_py_type)
+            field_type_str = f"List[{list_item_py_type}]"
+
+            final_field_type_str = TypeFinalizer(context).finalize(
+                py_type=field_type_str, schema=schema, required=False
+            )
+
+            synthetic_field_schema_for_default = IRSchema(
+                name=field_name_for_array_content,
+                type="array",
+                items=schema.items,
+                is_nullable=schema.is_nullable,
+                default=schema.default,
+            )
+            array_items_field_default_expr = self._get_field_default(synthetic_field_schema_for_default, context)
+
+            field_description = schema.description
+            if not field_description and list_item_py_type != "Any":
+                field_description = f"A list of {list_item_py_type} items."
+            elif not field_description:
+                field_description = "A list of items."
+
+            fields_data.append(
+                (
+                    field_name_for_array_content,
+                    final_field_type_str,
+                    array_items_field_default_expr,
+                    field_description,
+                )
+            )
+        elif schema.properties:
+            sorted_props = sorted(schema.properties.items(), key=lambda item: (item[0] not in schema.required, item[0]))
+
+            for prop_name, prop_schema in sorted_props:
+                is_required = prop_name in schema.required
+
+                # Sanitize the property name for use as a Python attribute
+                field_name = NameSanitizer.sanitize_method_name(prop_name)
+
+                py_type = self.type_service.resolve_schema_type(prop_schema, context, required=is_required)
+                py_type = TypeFinalizer(context)._clean_type(py_type)
+
+                default_expr: Optional[str] = None
+                if not is_required:
+                    default_expr = self._get_field_default(prop_schema, context)
+
+                field_doc = prop_schema.description
+                fields_data.append((field_name, py_type, default_expr, field_doc))
+
+        # logger.debug(
+        #     f"DataclassGenerator: Preparing to render dataclass '{class_name}' with fields: {fields_data}."
+        # )
+
+        rendered_code = self.renderer.render_dataclass(
+            class_name=class_name,
+            fields=fields_data,
+            description=schema.description,
+            context=context,
+        )
+
+        assert rendered_code.strip(), "Generated dataclass code cannot be empty."
+        # PythonConstructRenderer adds the @dataclass decorator and import
+        assert "@dataclass" in rendered_code, "Dataclass code missing @dataclass decorator."
+        assert (
+            "dataclasses" in context.import_collector.imports
+            and "dataclass" in context.import_collector.imports["dataclasses"]
+        ), "dataclass import was not added to context by renderer."
+        if "default_factory" in rendered_code:  # Check for field import if factory is used
+            assert "field" in context.import_collector.imports.get(
+                "dataclasses", set()
+            ), "'field' import from dataclasses missing when default_factory is used."
+
+        return rendered_code

pyopenapi_gen/visit/model/enum_generator.py

@@ -0,0 +1,200 @@
+"""
+Generates Python code for enums from IRSchema objects.
+"""
+
+import keyword
+import logging
+import re
+from typing import List, Tuple
+
+from pyopenapi_gen import IRSchema
+from pyopenapi_gen.context.render_context import RenderContext
+from pyopenapi_gen.core.writers.python_construct_renderer import PythonConstructRenderer
+
+logger = logging.getLogger(__name__)
+
+
+class EnumGenerator:
+    """Generates Python code for an enum."""
+
+    def __init__(self, renderer: PythonConstructRenderer):
+        # Pre-condition
+        assert renderer is not None, "PythonConstructRenderer cannot be None"
+        self.renderer = renderer
+
+    def _generate_member_name_for_string_enum(self, value: str) -> str:
+        """
+        Generates a Python-valid member name from a string enum value.
+
+        Contracts:
+            Pre-conditions:
+                - ``value`` is a string.
+            Post-conditions:
+                - Returns a non-empty string that is a valid Python identifier, typically uppercase.
+        """
+        assert isinstance(value, str), "Input value must be a string."
+        base_member_name = str(value).upper().replace("-", "_").replace(" ", "_")
+        sanitized_member_name = re.sub(r"[^A-Z0-9_]", "", base_member_name)
+
+        if not sanitized_member_name:
+            # Handle empty string or string that became empty after sanitization
+            # Using a generic placeholder if original value was also effectively empty/non-descriptive
+            # Or try to derive something if the original string had some content before stripping
+            original_alnum = re.sub(r"[^A-Za-z0-9]", "", str(value))
+            if not original_alnum:
+                sanitized_member_name = "MEMBER_EMPTY_STRING"
+            else:
+                # Attempt to form a name from original alphanumeric chars if sanitization wiped it
+                sanitized_member_name = f"MEMBER_{original_alnum.upper()}"
+                if sanitized_member_name[0].isdigit():  # Check if this new form starts with a digit
+                    sanitized_member_name = f"MEMBER_{sanitized_member_name}"  # MEMBER_MEMBER_... is ok
+        elif sanitized_member_name[0].isdigit():
+            sanitized_member_name = f"MEMBER_{sanitized_member_name}"
+
+        if keyword.iskeyword(sanitized_member_name.lower()):  # Check lowercase version for keyword
+            sanitized_member_name += "_"
+
+        # Final check for safety: if it's still not a valid start (e.g. _MEMBER_...)
+        if not re.match(r"^[A-Z_]", sanitized_member_name.upper()):
+            sanitized_member_name = f"MEMBER_{sanitized_member_name}"
+
+        assert sanitized_member_name and re.match(r"^[A-Z_][A-Z0-9_]*$", sanitized_member_name.upper()), (
+            f"Generated string enum member name '{sanitized_member_name}' "
+            f"is not a valid Python identifier from value '{value}'."
+        )
+        return sanitized_member_name
+
+    def _generate_member_name_for_integer_enum(self, value: str | int, int_value_for_fallback: int) -> str:
+        """
+        Generates a Python-valid member name from an integer enum value (or its string representation).
+
+        Contracts:
+            Pre-conditions:
+                - ``value`` is a string or an int.
+                - ``int_value_for_fallback`` is an int.
+            Post-conditions:
+                - Returns a non-empty string that is a valid Python identifier, typically uppercase.
+        """
+        assert isinstance(value, (str, int)), "Input value for integer enum naming must be str or int."
+        assert isinstance(int_value_for_fallback, int), "Fallback integer value must be an int."
+
+        name_basis = str(value)  # Use string representation as basis for name
+        base_member_name = name_basis.upper().replace("-", "_").replace(" ", "_").replace(".", "_DOT_")
+        sanitized_member_name = re.sub(r"[^A-Z0-9_]", "", base_member_name)
+
+        if not sanitized_member_name:
+            # If string value like "-" or "." became empty, use the int value directly
+            if int_value_for_fallback < 0:
+                sanitized_member_name = f"VALUE_NEG_{abs(int_value_for_fallback)}"
+            else:
+                sanitized_member_name = f"VALUE_{int_value_for_fallback}"
+            # This form should be inherently valid (VALUE_ + digits or VALUE_NEG_ + digits)
+        elif not re.match(r"^[A-Z_]", sanitized_member_name.upper()):  # Check if starts with letter/underscore
+            # If it starts with a digit, or some other non-alpha (though re.sub should prevent others)
+            sanitized_member_name = f"VALUE_{sanitized_member_name}"
+
+        if keyword.iskeyword(sanitized_member_name.lower()):  # Check lowercase version
+            sanitized_member_name += "_"
+
+        # One final check: ensure it starts with an uppercase letter or underscore
+        if not re.match(r"^[A-Z_]", sanitized_member_name.upper()):
+            # This is a last resort, should be rare. Prefix to ensure validity.
+            sanitized_member_name = f"ENUM_MEMBER_{sanitized_member_name}"
+            # And re-sanitize this new prefixed name just in case the original had problematic chars
+            sanitized_member_name = re.sub(r"[^A-Z0-9_]", "", sanitized_member_name.upper())
+            if not sanitized_member_name:  # Should be impossible
+                sanitized_member_name = f"ENUM_MEMBER_UNKNOWN_{abs(int_value_for_fallback)}"
+
+        assert sanitized_member_name and re.match(r"^[A-Z_][A-Z0-9_]*$", sanitized_member_name.upper()), (
+            f"Generated integer enum member name '{sanitized_member_name}' "
+            f"is not a valid Python identifier from value '{value}'."
+        )
+        return sanitized_member_name
+
+    def generate(
+        self,
+        schema: IRSchema,
+        base_name: str,  # This is the class name, will be sanitized by PythonConstructRenderer
+        context: RenderContext,
+    ) -> str:
+        """
+        Generates the Python code for an enum.
+
+        Args:
+            schema: The IRSchema for the enum.
+            base_name: The base name for the enum class.
+            context: The render context.
+
+        Returns:
+            The generated Python code string for the enum.
+
+        Contracts:
+            Pre-conditions:
+                - ``schema`` is not None, ``schema.name`` is not None, and ``schema.enum`` is not None and not empty.
+                - ``schema.type`` is either "string" or "integer".
+                - ``base_name`` is a non-empty string.
+                - ``context`` is not None.
+            Post-conditions:
+                - Returns a non-empty string containing valid Python code for an enum.
+                - ``Enum`` from the ``enum`` module is imported in the context.
+        """
+        assert schema is not None, "Schema cannot be None for enum generation."
+        assert schema.name is not None, "Schema name must be present for enum generation."
+        assert base_name, "Base name cannot be empty for enum generation."
+        assert context is not None, "RenderContext cannot be None."
+        assert schema.enum, "Schema must have enum values for enum generation."
+        assert schema.type in ("string", "integer"), "Enum schema type must be 'string' or 'integer'."
+
+        enum_class_name = base_name  # PythonConstructRenderer will sanitize this class name
+        base_type = "str" if schema.type == "string" else "int"
+        values: List[Tuple[str, str | int]] = []
+        processed_member_names = set()
+
+        for val_from_spec in schema.enum:
+            member_name: str
+            member_value: str | int
+
+            if base_type == "str":
+                member_value = str(val_from_spec)
+                member_name = self._generate_member_name_for_string_enum(member_value)
+            else:  # Integer enum
+                try:
+                    actual_int_value = int(val_from_spec)
+                except (ValueError, TypeError):
+                    logger.warning(
+                        f"EnumGenerator: Could not convert enum value '{val_from_spec}' "
+                        f"to int for schema '{schema.name}'. Using value 0."
+                    )
+                    actual_int_value = 0  # Fallback value
+                member_value = actual_int_value
+                # Pass original spec value for naming, and the actual int value for fallback naming
+                member_name = self._generate_member_name_for_integer_enum(val_from_spec, actual_int_value)
+
+            # Handle duplicate member names by appending a counter
+            unique_member_name = member_name
+            counter = 1
+            while unique_member_name in processed_member_names:
+                unique_member_name = f"{member_name}_{counter}"
+                counter += 1
+            processed_member_names.add(unique_member_name)
+
+            values.append((unique_member_name, member_value))
+
+        # logger.debug(
+        #     f"EnumGenerator: Preparing to render enum '{enum_class_name}' "
+        #     f"with base type '{base_type}' and members: {values}."
+        # )
+        rendered_code = self.renderer.render_enum(
+            enum_name=enum_class_name,  # Pass the original base_name; renderer handles class name sanitization
+            base_type=base_type,
+            values=values,
+            description=schema.description,
+            context=context,
+        )
+
+        assert rendered_code.strip(), "Generated enum code cannot be empty."
+        assert (
+            "enum" in context.import_collector.imports and "Enum" in context.import_collector.imports["enum"]
+        ), "Enum import was not added to context by renderer."
+
+        return rendered_code

pyopenapi_gen/visit/model/model_visitor.py

@@ -0,0 +1,197 @@
+"""
+ModelVisitor: Transforms IRSchema objects into Python model code (dataclasses and enums).
+
+This module provides the ModelVisitor class that generates Python code for data models
+defined in OpenAPI specifications, supporting type aliases, enums, and dataclasses.
+"""
+
+import logging
+from typing import Dict, Optional
+
+from pyopenapi_gen import IRSchema
+from pyopenapi_gen.context.render_context import RenderContext
+from pyopenapi_gen.core.utils import Formatter
+from pyopenapi_gen.core.writers.python_construct_renderer import PythonConstructRenderer
+from pyopenapi_gen.helpers.type_helper import TypeHelper
+
+from ..visitor import Visitor  # Relative import from parent package
+
+# Import new generators from the current 'model' package
+from .alias_generator import AliasGenerator
+from .dataclass_generator import DataclassGenerator
+from .enum_generator import EnumGenerator
+
+logger = logging.getLogger(__name__)
+
+
+class ModelVisitor(Visitor[IRSchema, str]):
+    """
+    Visitor for rendering a Python model (dataclass, enum, or type alias) from an IRSchema.
+    It determines the model type and delegates to specialized generators.
+
+    Contracts:
+        Post-conditions:
+            - Returns a valid Python code string representing the model.
+            - Returns an empty string if the schema should not be rendered as a standalone model.
+            - All necessary imports for the generated model are registered in the context.
+    """
+
+    def __init__(self, schemas: Optional[Dict[str, IRSchema]] = None) -> None:
+        """
+        Initialize a new ModelVisitor.
+
+        Args:
+            schemas: Dictionary of all schemas for reference resolution.
+        """
+        self.formatter = Formatter()
+        self.all_schemas = schemas or {}
+
+        # Initialize PythonConstructRenderer once; it's passed to generators.
+        self.renderer = PythonConstructRenderer()
+
+        # Initialize generators, passing the shared renderer and all_schemas (where needed).
+        self.alias_generator = AliasGenerator(self.renderer, self.all_schemas)
+        self.enum_generator = EnumGenerator(self.renderer)
+        self.dataclass_generator = DataclassGenerator(self.renderer, self.all_schemas)
+
+    def visit_IRSchema(self, schema: IRSchema, context: RenderContext) -> str:
+        """
+        Visit an IRSchema node, determine model type, and delegate to the appropriate generator.
+
+        Args:
+            schema: The schema to visit.
+            context: The rendering context for imports and configuration.
+
+        Returns:
+            Formatted Python code for the model as a string, or an empty string if not generated.
+
+        Contracts:
+            Pre-conditions:
+                - ``schema`` is a valid ``IRSchema`` object.
+                - ``context`` is a valid ``RenderContext`` object.
+            Post-conditions:
+                - If a model is generated, it's a valid Python code string.
+                - If ``schema.name`` is None and the schema would be a complex type (alias, enum, dataclass),
+                  an empty string is returned.
+                - Necessary imports for the generated types are added to ``context``.
+        """
+        # --- Model Type Detection Logic ---
+        is_enum = bool(schema.name and schema.enum and schema.type in ("string", "integer"))
+
+        is_type_alias = bool(schema.name and not schema.properties and not is_enum and schema.type != "object")
+
+        if schema.type == "array" and schema.items and schema.items.type == "object" and schema.items.name is None:
+            if is_type_alias:
+                # logger.debug(
+                #     f"ModelVisitor: Schema '{schema.name}' is an array of anonymous items. "
+                #     "It will be rendered as a dataclass instead of a TypeAlias."
+                # )
+                is_type_alias = False
+                schema.is_data_wrapper = True
+
+        is_dataclass = not is_enum and not is_type_alias
+        # --- End of Detection Logic ---
+
+        if not schema.name and (is_type_alias or is_enum or is_dataclass):
+            # logger.debug(f"ModelVisitor: Skipping anonymous schema that would be a standalone model: {schema}")
+            return ""
+
+        # Pre-condition check after filtering anonymous
+        # schema.name is the original sanitized name. schema.generation_name is the de-collided one.
+        # For standalone models, generation_name should be set and used.
+        if schema.generation_name:
+            base_name_for_construct = schema.generation_name
+            # logger.debug(f"Using schema.generation_name ('{schema.generation_name}') for construct base name.")
+        elif (
+            schema.name
+        ):  # Fallback for schemas not processed by emitter pre-naming (e.g. inline, or if generation_name wasn't set)
+            base_name_for_construct = schema.name
+            # logger.debug(f"Using schema.name ('{schema.name}') for construct base name, "
+            #               f"as generation_name is not set.")
+        else:
+            # This case should ideally be caught by the "not schema.name and (is_type_alias...)" check above
+            # or by assertions in generators if they receive a schema without a usable name.
+            logger.error(
+                f"ModelVisitor: Schema has no usable name (name or generation_name) for model generation: {schema}"
+            )
+            assert False, "Schema must have a name or generation_name for model code generation at this point."
+            # return "" # Should not reach here if assertions are active
+
+        # --- Import Registration ---
+        # Analyze the schema for all necessary type imports and register them.
+        _ = TypeHelper.get_python_type_for_schema(
+            schema, self.all_schemas, context, required=True, resolve_alias_target=True
+        )
+
+        if context.current_file:
+            context.mark_generated_module(context.current_file)
+
+        # --- Code Generation Dispatch ---
+        rendered_code = ""
+        if is_type_alias:
+            # logger.debug(f"ModelVisitor: Dispatching to AliasGenerator for schema: {schema.name}")
+            rendered_code = self.alias_generator.generate(schema, base_name_for_construct, context)
+        elif is_enum:
+            # logger.debug(f"ModelVisitor: Dispatching to EnumGenerator for schema: {schema.name}")
+            rendered_code = self.enum_generator.generate(schema, base_name_for_construct, context)
+        elif is_dataclass:
+            # logger.debug(f"ModelVisitor: Dispatching to DataclassGenerator for schema: {schema.name}")
+            rendered_code = self.dataclass_generator.generate(schema, base_name_for_construct, context)
+        else:
+            # logger.debug(
+            #     f"ModelVisitor: Schema '{schema.name if schema.name else 'Unnamed'}' "
+            #     f"(type: {schema.type}) did not map to a dedicated "
+            #     "alias, enum, or dataclass. No standalone model generated by ModelVisitor."
+            # )
+            # Post-condition: returns empty string if no specific generator called
+            assert not rendered_code, "Rendered code should be empty if no generator was matched."
+            return ""
+
+        # Post-condition: ensure some code was generated if a generator was called
+        assert rendered_code.strip() or not (
+            is_type_alias or is_enum or is_dataclass
+        ), f"Code generation resulted in an empty string for schema '{schema.name}' which was matched as a model type."
+
+        return self.formatter.format(rendered_code)
+
+    def _get_field_default(self, ps: IRSchema, context: RenderContext) -> Optional[str]:
+        """
+        Determines the default value expression string for a dataclass field.
+        This method is called for fields determined to be optional.
+
+        Args:
+            ps: The property schema to analyze
+            context: The rendering context
+
+        Returns:
+            A string representing the Python default value expression
+        """
+        # Restore logic for default_factory for list and dict
+        if ps.type == "array":
+            context.add_import("dataclasses", "field")
+            return "field(default_factory=list)"
+        elif ps.type == "object" and ps.name is None and not ps.any_of and not ps.one_of and not ps.all_of:
+            # This condition aims for anonymous objects that are not part of a union/composition.
+            # These should get default_factory=dict if they are optional fields.
+            context.add_import("dataclasses", "field")
+            return "field(default_factory=dict)"
+        else:
+            # Primitives, enums, named objects, unions default to None when optional
+            return "None"
+
+    def _analyze_and_register_imports(self, schema: IRSchema, context: RenderContext) -> None:
+        """
+        Analyze a schema and register necessary imports for the generated code.
+
+        This ensures that all necessary types used in the model are properly imported
+        in the generated Python file.
+
+        Args:
+            schema: The schema to analyze
+            context: The rendering context for import registration
+        """
+        # Call the helper to ensure types within properties/items/composition are analyzed
+        # and imports registered
+        _ = TypeHelper.get_python_type_for_schema(
+            schema, self.all_schemas, context, required=True, resolve_alias_target=True
+        )