pyopenapi-gen 2.7.2__py3-none-any.whl

pyopenapi_gen/core/parsing/common/ref_resolution/helpers/stripped_suffix.py

@@ -0,0 +1,51 @@
+"""
+Module for handling stripped suffix fallback strategy.
+"""
+
+import logging
+from typing import Any, Callable, Mapping
+
+from pyopenapi_gen.ir import IRSchema
+
+from ....context import ParsingContext
+
+logger = logging.getLogger(__name__)
+
+
+def try_stripped_suffix_fallback(
+    ref_name: str,
+    ref_value: str,
+    context: ParsingContext,
+    max_depth: int,
+    parse_fn: Callable[[str | None, Mapping[str, Any] | None, ParsingContext, int], IRSchema],
+) -> IRSchema | None:
+    """
+    Attempts to resolve a reference by stripping common suffixes.
+
+    Contracts:
+        Pre-conditions:
+            - ref_name must be a valid schema name
+            - parse_fn must be a callable that parses schemas
+            - context must be a valid ParsingContext instance
+        Post-conditions:
+            - If successful, returns the resolved IRSchema
+            - If unsuccessful, returns None
+            - Successful resolutions are added to context.parsed_schemas
+    """
+    suffixes = ["Response", "Request", "Input", "Output"]
+
+    for suffix in suffixes:
+        if ref_name.endswith(suffix):
+            base_name = ref_name[: -len(suffix)]
+            referenced_node_data_fallback = context.raw_spec_schemas.get(base_name)
+
+            if referenced_node_data_fallback:
+                resolved_schema = parse_fn(base_name, referenced_node_data_fallback, context, max_depth)
+                if not resolved_schema._from_unresolved_ref:
+                    warning_msg = f"Resolved $ref: {ref_value} by falling back to base name '{base_name}'."
+                    context.collected_warnings.append(warning_msg)
+
+                    context.parsed_schemas[ref_name] = resolved_schema
+                    return resolved_schema
+
+    return None

pyopenapi_gen/core/parsing/common/ref_resolution/resolve_schema_ref.py

@@ -0,0 +1,86 @@
+"""
+Main module for schema reference resolution.
+"""
+
+import logging
+from typing import Any, Callable, Mapping
+
+from pyopenapi_gen.ir import IRSchema
+
+from ...context import ParsingContext
+from .helpers.direct_cycle import handle_direct_cycle
+from .helpers.existing_schema import handle_existing_schema
+from .helpers.missing_ref import handle_missing_ref
+from .helpers.new_schema import parse_new_schema
+
+logger = logging.getLogger(__name__)
+
+
+def resolve_schema_ref(
+    ref_value: str,
+    ref_name: str,
+    context: ParsingContext,
+    max_depth: int,
+    _parse_schema: Callable[[str | None, Mapping[str, Any] | None, ParsingContext, int], IRSchema],
+) -> IRSchema:
+    """
+    Resolves a schema reference in an OpenAPI specification.
+
+    Contracts:
+        Pre-conditions:
+            - ref_value must be a valid reference string (e.g., "#/components/schemas/MySchema")
+            - ref_name must be a valid schema name
+            - context must be a valid ParsingContext instance
+            - max_depth must be a non-negative integer
+            - _parse_schema must be a callable that parses schemas
+        Post-conditions:
+            - Returns a valid IRSchema instance
+            - The schema is registered in context.parsed_schemas
+            - Cyclic references are handled appropriately
+    """
+    # Extract the actual schema name from the reference
+    actual_schema_name = ref_value.split("/")[-1]
+
+    # Check for direct cycles or circular placeholders
+    if actual_schema_name in context.parsed_schemas:
+        existing_schema = context.parsed_schemas[actual_schema_name]
+        if getattr(existing_schema, "_is_circular_ref", False):
+            # logger.debug(f"Returning existing circular reference for '{actual_schema_name}'")
+            return existing_schema
+        # logger.debug(f"Direct cycle detected for '{actual_schema_name}', handling...")
+        return handle_direct_cycle(actual_schema_name, context)
+
+    # Check for existing fully parsed schema
+    if actual_schema_name in context.parsed_schemas:
+        # logger.debug(f"Returning existing fully parsed schema for '{actual_schema_name}'")
+        return handle_existing_schema(actual_schema_name, context)
+
+    # Get referenced node data
+    referenced_node_data = context.raw_spec_schemas.get(actual_schema_name)
+
+    # Handle missing references with stripped suffix fallback
+    if referenced_node_data is None:
+        # Try stripping common suffixes
+        base_name = actual_schema_name
+        for suffix in ["Response", "Request", "Input", "Output"]:
+            if base_name.endswith(suffix):
+                base_name = base_name[: -len(suffix)]
+                if base_name in context.raw_spec_schemas:
+                    # logger.debug(f"Found schema '{base_name}' after stripping suffix '{suffix}'")
+                    referenced_node_data = context.raw_spec_schemas[base_name]
+                    break
+
+        if referenced_node_data is None:
+            logger.warning(f"Missing reference '{ref_value}' for schema '{ref_name}'")
+            return handle_missing_ref(ref_value, ref_name, context, max_depth, _parse_schema)
+
+    # Standard parsing path for a new schema
+    # logger.debug(f"Parsing new schema '{actual_schema_name}'")
+    schema = parse_new_schema(actual_schema_name, dict(referenced_node_data), context, max_depth, _parse_schema)
+
+    # Store the schema under the requested reference name if different
+    # Don't mutate the original schema name to avoid affecting other references
+    if schema.name != ref_name:
+        context.parsed_schemas[ref_name] = schema
+
+    return schema

pyopenapi_gen/core/parsing/common/type_parser.py

@@ -0,0 +1,73 @@
+"""
+Dedicated parser for determining primary type and nullability from a schema's 'type' field.
+"""
+
+from __future__ import annotations
+
+from typing import (
+    Any,
+    List,
+    Tuple,
+)
+
+# Note: IRSchema is not needed here as this function doesn't construct it.
+
+
+def extract_primary_type_and_nullability(
+    type_node: Any, schema_name: str | None = None
+) -> Tuple[str | None, bool, List[str]]:
+    """Extract the primary type and nullability from a schema's 'type' field.
+
+    Contracts:
+        Pre-conditions:
+            - type_node is the value of the 'type' field from a schema
+        Post-conditions:
+            - Returns a tuple of (primary_type, is_nullable, warnings)
+            - primary_type is None if type_node is None or invalid
+            - is_nullable is True if type_node is 'null' or contains 'null'
+            - warnings contains any warnings about type handling
+    """
+    warnings: List[str] = []
+    is_nullable = False
+
+    if type_node is None:
+        return None, False, warnings
+
+    # Handle array of types
+    if isinstance(type_node, list):
+        if not type_node:
+            warnings.append(f"Empty type array in schema '{schema_name}'")
+            return None, False, warnings
+
+        # Check for nullability
+        if "null" in type_node:
+            is_nullable = True
+            type_node = [t for t in type_node if t != "null"]
+
+        if not type_node:
+            warnings.append(f"Only 'null' type in array for schema '{schema_name}'")
+            return None, True, warnings
+
+        # Use the first non-null type
+        primary_type = type_node[0]
+        if len(type_node) > 1:
+            warnings.append(f"Multiple types in array for schema '{schema_name}'. Using first type: {primary_type}")
+    else:
+        primary_type = type_node
+
+    # Validate the type
+    if not isinstance(primary_type, str):
+        warnings.append(f"Invalid type value '{primary_type}' in schema '{schema_name}'")
+        return None, is_nullable, warnings
+
+    # Normalize the type
+    primary_type = primary_type.lower()
+    if primary_type not in {"string", "number", "integer", "boolean", "object", "array", "null"}:
+        warnings.append(f"Unknown type '{primary_type}' in schema '{schema_name}'")
+        return None, is_nullable, warnings
+
+    # If the determined primary_type is "null", it means the actual type is None, but it IS nullable.
+    if primary_type == "null":
+        return None, True, warnings  # Ensure is_nullable is True
+
+    return primary_type, is_nullable, warnings

pyopenapi_gen/core/parsing/context.py

@@ -0,0 +1,187 @@
+"""
+Defines the ParsingContext dataclass used to manage state during OpenAPI schema parsing.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, List, Mapping, Set, Tuple
+
+if TYPE_CHECKING:
+    from pyopenapi_gen import IRSchema
+
+    # from pyopenapi_gen.core.utils import NameSanitizer # If needed later
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ParsingContext:
+    """Manages shared state and context during the schema parsing process."""
+
+    raw_spec_schemas: dict[str, Mapping[str, Any]] = field(default_factory=dict)
+    raw_spec_components: Mapping[str, Any] = field(default_factory=dict)
+    parsed_schemas: dict[str, IRSchema] = field(default_factory=dict)
+    visited_refs: Set[str] = field(default_factory=set)
+    global_schema_names: Set[str] = field(default_factory=set)
+    package_root_name: str | None = None
+    # name_sanitizer: NameSanitizer = field(default_factory=NameSanitizer) # Decided to instantiate where needed for now
+    collected_warnings: List[str] = field(default_factory=list)  # For collecting warnings from helpers
+
+    # Cycle detection
+    currently_parsing: List[str] = field(default_factory=list)
+    recursion_depth: int = 0
+    cycle_detected: bool = False
+
+    def __post_init__(self) -> None:
+        # Initialize logger for the context instance if needed, or rely on module logger
+        self.logger = logger  # or logging.getLogger(f"{__name__}.ParsingContext")
+
+        # Initialize unified cycle detection context
+        # Import here to avoid circular imports
+        from .unified_cycle_detection import UnifiedCycleContext
+
+        # Get max depth from environment or default
+        max_depth = int(os.environ.get("PYOPENAPI_MAX_DEPTH", 150))
+
+        self.unified_cycle_context = UnifiedCycleContext(
+            parsed_schemas=self.parsed_schemas,
+            max_depth=max_depth,  # Share the same parsed_schemas dict
+        )
+
+    def unified_enter_schema(self, schema_name: str | None) -> Any:
+        """Enter schema using unified cycle detection system."""
+        from .unified_cycle_detection import unified_enter_schema
+
+        result = unified_enter_schema(schema_name, self.unified_cycle_context)
+
+        # Update legacy fields for backward compatibility
+        self.recursion_depth = self.unified_cycle_context.recursion_depth
+        self.cycle_detected = self.unified_cycle_context.cycle_detected
+        self.currently_parsing = self.unified_cycle_context.schema_stack.copy()
+
+        return result
+
+    def unified_exit_schema(self, schema_name: str | None) -> None:
+        """Exit schema using unified cycle detection system."""
+        from .unified_cycle_detection import unified_exit_schema
+
+        unified_exit_schema(schema_name, self.unified_cycle_context)
+
+        # Update legacy fields for backward compatibility
+        self.recursion_depth = self.unified_cycle_context.recursion_depth
+        self.currently_parsing = self.unified_cycle_context.schema_stack.copy()
+
+    def clear_cycle_state(self) -> None:
+        """Clear both legacy and unified cycle detection state."""
+        # Clear legacy state
+        self.currently_parsing.clear()
+        self.recursion_depth = 0
+        self.cycle_detected = False
+
+        # Clear unified context state
+        self.unified_cycle_context.schema_stack.clear()
+        self.unified_cycle_context.schema_states.clear()
+        self.unified_cycle_context.recursion_depth = 0
+        self.unified_cycle_context.detected_cycles.clear()
+        self.unified_cycle_context.depth_exceeded_schemas.clear()
+        self.unified_cycle_context.cycle_detected = False
+
+    def enter_schema(self, schema_name: str | None) -> Tuple[bool, str | None]:
+        self.recursion_depth += 1
+
+        if schema_name is None:
+            return False, None
+
+        # Named cycle detection using ordered list currently_parsing
+        if schema_name in self.currently_parsing:
+            self.cycle_detected = True
+            try:
+                start_index = self.currently_parsing.index(schema_name)
+                # Path is from the first occurrence of schema_name to the current end of stack
+                cycle_path_list = self.currently_parsing[start_index:]
+            except ValueError:  # Should not happen
+                cycle_path_list = list(self.currently_parsing)  # Fallback
+
+            cycle_path_list.append(schema_name)  # Add the re-entrant schema_name to show the loop
+            cycle_path_str = " -> ".join(cycle_path_list)
+
+            return True, cycle_path_str
+
+        self.currently_parsing.append(schema_name)
+        return False, None
+
+    def exit_schema(self, schema_name: str | None) -> None:
+        if self.recursion_depth == 0:
+            self.logger.error("Cannot exit schema: recursion depth would go below zero.")
+            return
+
+        self.recursion_depth -= 1
+        if schema_name is not None:
+            if self.currently_parsing and self.currently_parsing[-1] == schema_name:
+                self.currently_parsing.pop()
+            elif (
+                schema_name in self.currently_parsing
+            ):  # Not last on stack but present: indicates mismatched enter/exit or error
+                self.logger.error(
+                    f"Exiting schema '{schema_name}' which is not at the top of the parsing stack. "
+                    f"Stack: {self.currently_parsing}. This indicates an issue."
+                )
+                # Attempt to remove it to prevent it being stuck, though this is a recovery attempt.
+                try:
+                    self.currently_parsing.remove(schema_name)
+                except ValueError:
+                    pass  # Should not happen if it was in the list.
+            # If schema_name is None, or (it's not None and not in currently_parsing), do nothing to currently_parsing.
+            # The latter case could be if exit_schema is called for a schema_name that wasn't pushed
+            # (e.g., after yielding a placeholder, where the original enter_schema
+            # didn't add it because it was already a cycle).
+
+    def reset_for_new_parse(self) -> None:
+        self.recursion_depth = 0
+        self.cycle_detected = False
+        self.currently_parsing.clear()
+        self.parsed_schemas.clear()
+
+    def get_current_path_for_logging(self) -> str:
+        """Helper to get a string representation of the current parsing path for logs."""
+        return " -> ".join(self.currently_parsing)
+
+    def get_parsed_schemas_for_emitter(self) -> dict[str, IRSchema]:
+        # ---- START RESTORE ----
+        return {
+            name: schema
+            for name, schema in self.parsed_schemas.items()
+            if not getattr(schema, "_is_circular_ref", False)
+            and not getattr(schema, "_from_unresolved_ref", False)
+            and not getattr(schema, "_max_depth_exceeded_marker", False)
+        }
+        # ---- END RESTORE ----
+
+    def is_schema_parsed(self, schema_name: str) -> bool:
+        """Check if a schema with the given name has been parsed.
+
+        Contracts:
+            Preconditions:
+                - schema_name is a valid string
+            Postconditions:
+                - Returns True if the schema exists in parsed_schemas, False otherwise
+        """
+        if not isinstance(schema_name, str):
+            raise TypeError("schema_name must be a string")
+        return schema_name in self.parsed_schemas
+
+    def get_parsed_schema(self, schema_name: str) -> "IRSchema" | None:
+        """Get a parsed schema by its name.
+
+        Contracts:
+            Preconditions:
+                - schema_name is a valid string
+            Postconditions:
+                - Returns the IRSchema if it exists, None otherwise
+        """
+        if not isinstance(schema_name, str):
+            raise TypeError("schema_name must be a string")
+        return self.parsed_schemas.get(schema_name)

pyopenapi_gen/core/parsing/cycle_helpers.py

@@ -0,0 +1,126 @@
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    pass
+
+from pyopenapi_gen import IRSchema
+from pyopenapi_gen.core.utils import NameSanitizer
+
+from .context import ParsingContext
+
+# Define module-level logger
+logger = logging.getLogger(__name__)
+
+
+def _handle_cycle_detection(
+    original_name: str, cycle_path: str, context: ParsingContext, allow_self_reference: bool
+) -> IRSchema:
+    """Handle case where a cycle is detected in schema references.
+
+    Contracts:
+        Pre-conditions:
+            - original_name is not None
+            - context is a valid ParsingContext instance
+            - allow_self_reference indicates if direct self-references are permitted without being treated as errors.
+        Post-conditions:
+            - Returns an IRSchema instance.
+            - If not a permitted self-reference, it's marked as circular and registered.
+            - If a permitted self-reference, a placeholder is returned and not marked as an error cycle.
+    """
+    schema_ir_name_attr = NameSanitizer.sanitize_class_name(original_name)
+
+    # Check for direct self-reference when allowed
+    path_parts = cycle_path.split(" -> ")
+    is_direct_self_ref = len(path_parts) == 2 and path_parts[0] == original_name and path_parts[1] == original_name
+
+    if allow_self_reference and is_direct_self_ref:
+        # Permitted direct self-reference, creating placeholder without marking as error cycle
+        if original_name not in context.parsed_schemas:
+            # Create a basic placeholder. It will be fully populated when its real definition is parsed.
+            # Key is NOT to mark _is_circular_ref = True here.
+            schema = IRSchema(
+                name=schema_ir_name_attr,
+                type="object",  # Default type, might be refined if we parse its own definition later
+                description=f"[Self-referential placeholder for {original_name}]",
+                _from_unresolved_ref=False,  # Not unresolved in the error sense
+                _is_self_referential_stub=True,  # New flag to indicate this state
+            )
+            context.parsed_schemas[original_name] = schema
+            return schema
+        else:
+            # If it's already in parsed_schemas, it means we're re-entering it.
+            # This could happen if it was created as a placeholder by another ref first.
+            # Ensure it's marked as a self-referential stub if not already.
+            existing_schema = context.parsed_schemas[original_name]
+            if not getattr(existing_schema, "_is_self_referential_stub", False):
+                existing_schema._is_self_referential_stub = True  # Mark it
+            return existing_schema
+
+    # If not a permitted direct self-reference, or if self-references are not allowed, proceed with error cycle handling
+    if original_name not in context.parsed_schemas:
+        schema = IRSchema(
+            name=schema_ir_name_attr,
+            type="object",
+            description=f"[Circular reference detected: {cycle_path}]",
+            _from_unresolved_ref=True,
+            _circular_ref_path=cycle_path,
+            _is_circular_ref=True,
+        )
+        context.parsed_schemas[original_name] = schema
+    else:
+        schema = context.parsed_schemas[original_name]
+        schema._is_circular_ref = True
+        schema._from_unresolved_ref = True
+        schema._circular_ref_path = cycle_path
+        if schema.name != schema_ir_name_attr:
+            schema.name = schema_ir_name_attr
+
+    context.cycle_detected = True
+    return schema
+
+
+def _handle_max_depth_exceeded(original_name: str | None, context: ParsingContext, max_depth: int) -> IRSchema:
+    """Handle case where maximum recursion depth is exceeded.
+
+    Contracts:
+        Pre-conditions:
+            - context is a valid ParsingContext instance
+            - max_depth >= 0
+        Post-conditions:
+            - Returns an IRSchema instance marked with _max_depth_exceeded_marker=True
+            - If original_name is provided, the schema is registered in context.parsed_schemas
+    """
+    schema_ir_name_attr = NameSanitizer.sanitize_class_name(original_name) if original_name else None
+
+    # path_prefix = schema_ir_name_attr if schema_ir_name_attr else "<anonymous_schema>"
+    # cycle_path_for_desc = f"{path_prefix} -> MAX_DEPTH_EXCEEDED"
+    description = f"[Maximum recursion depth ({max_depth}) exceeded for '{original_name or 'anonymous'}']"
+    logger.warning(description)
+
+    placeholder_schema = IRSchema(
+        name=schema_ir_name_attr,
+        type="object",  # Default type for a placeholder created due to depth
+        description=description,
+        _max_depth_exceeded_marker=True,
+        # Do NOT set _is_circular_ref or _from_unresolved_ref here just for depth limit
+    )
+
+    if original_name is not None:
+        if original_name not in context.parsed_schemas:
+            context.parsed_schemas[original_name] = placeholder_schema
+        else:
+            # If a schema with this name already exists (e.g. a forward ref stub),
+            # update it to mark that max depth was hit during its resolution attempt.
+            # This is tricky because we don't want to overwrite a fully parsed schema.
+            # For now, let's assume if we are here, the existing one is also some form of placeholder
+            # or its parsing was interrupted to get here.
+            existing_schema = context.parsed_schemas[original_name]
+            existing_schema.description = description  # Update description
+            existing_schema._max_depth_exceeded_marker = True
+            # Avoid re-assigning to placeholder_schema directly to keep existing IR object if it was complex
+            # and just needs this flag + description update.
+            return existing_schema  # Return the (now updated) existing schema
+
+    # context.cycle_detected = True # Max depth is not strictly a cycle in the schema definition itself
+    return placeholder_schema

pyopenapi_gen/core/parsing/keywords/__init__.py

@@ -0,0 +1 @@
+# keyword-specific parsers

pyopenapi_gen/core/parsing/keywords/all_of_parser.py

@@ -0,0 +1,81 @@
+"""
+Handles the 'allOf' keyword in an OpenAPI schema, merging properties and required fields.
+Renamed from all_of_merger to all_of_parser for consistency.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Any, Callable, List, Mapping, Set, Tuple
+
+from pyopenapi_gen import IRSchema
+
+from ..context import ParsingContext
+
+ENV_MAX_DEPTH = int(os.environ.get("PYOPENAPI_MAX_DEPTH", "150"))
+
+if TYPE_CHECKING:
+    pass
+
+
+def _process_all_of(
+    node: Mapping[str, Any],
+    current_schema_name: str | None,
+    context: ParsingContext,
+    _parse_schema_func: Callable[[str | None, Mapping[str, Any] | None, ParsingContext, int | None], IRSchema],
+    max_depth: int = ENV_MAX_DEPTH,
+) -> Tuple[dict[str, IRSchema], Set[str], List[IRSchema]]:
+    """Processes the 'allOf' keyword in a schema node.
+
+    Merges properties and required fields from all sub-schemas listed in 'allOf'
+    and also from any direct 'properties' defined at the same level as 'allOf'.
+
+    Contracts:
+        Pre-conditions:
+            - node is a non-empty mapping representing an OpenAPI schema node.
+            - context is a valid ParsingContext instance.
+            - _parse_schema_func is a callable function.
+            - max_depth is a non-negative integer.
+        Post-conditions:
+            - Returns a tuple containing:
+                - merged_properties: Dict of property names to IRSchema.
+                - merged_required: Set of required property names.
+                - parsed_all_of_components: List of IRSchema for each item in 'allOf' (empty if 'allOf' not present).
+    """
+    # Pre-conditions
+    if not (isinstance(node, Mapping) and node):
+        raise TypeError("node must be a non-empty Mapping")
+    if not isinstance(context, ParsingContext):
+        raise TypeError("context must be a ParsingContext instance")
+    if not callable(_parse_schema_func):
+        raise TypeError("_parse_schema_func must be callable")
+    if not (isinstance(max_depth, int) and max_depth >= 0):
+        raise ValueError("max_depth must be a non-negative integer")
+
+    parsed_all_of_components: List[IRSchema] = []
+    merged_required: Set[str] = set(node.get("required", []))
+    merged_properties: dict[str, IRSchema] = {}
+
+    if "allOf" not in node:
+        current_node_direct_properties = node.get("properties", {})
+        for prop_name, prop_data in current_node_direct_properties.items():
+            prop_schema_name_context = f"{current_schema_name}.{prop_name}" if current_schema_name else prop_name
+            merged_properties[prop_name] = _parse_schema_func(prop_schema_name_context, prop_data, context, max_depth)
+        return merged_properties, merged_required, parsed_all_of_components
+
+    for sub_node in node["allOf"]:
+        sub_schema_ir = _parse_schema_func(None, sub_node, context, max_depth)
+        parsed_all_of_components.append(sub_schema_ir)
+        if sub_schema_ir.properties:
+            for prop_name, prop_schema_val in sub_schema_ir.properties.items():
+                if prop_name not in merged_properties:
+                    merged_properties[prop_name] = prop_schema_val
+        if sub_schema_ir.required:
+            merged_required.update(sub_schema_ir.required)
+
+    current_node_direct_properties = node.get("properties", {})
+    for prop_name, prop_data in current_node_direct_properties.items():
+        prop_schema_name_context = f"{current_schema_name}.{prop_name}" if current_schema_name else prop_name
+        merged_properties[prop_name] = _parse_schema_func(prop_schema_name_context, prop_data, context, max_depth)
+
+    return merged_properties, merged_required, parsed_all_of_components