pyopenapi-gen 0.8.3__py3-none-any.whl

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

@@ -0,0 +1,9 @@
+"""
+Module for handling schema reference resolution.
+"""
+
+from .resolve_schema_ref import resolve_schema_ref
+
+__all__ = [
+    "resolve_schema_ref",
+]

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

@@ -0,0 +1,66 @@
+"""
+Helper module for handling cyclic property references in schemas.
+"""
+
+import logging
+from typing import Set
+
+from pyopenapi_gen.ir import IRSchema
+
+from ....context import ParsingContext
+
+logger = logging.getLogger(__name__)
+
+
+def mark_cyclic_property_references(schema_obj: IRSchema, ref_name: str, context: ParsingContext) -> None:
+    """
+    Marks properties in a schema that form cycles as unresolved.
+
+    Args:
+        schema_obj: The schema object to check for cycles
+        ref_name: The name of the schema being referenced
+        context: The parsing context
+
+    Pre-conditions:
+        - schema_obj is a valid IRSchema instance
+        - ref_name is a non-empty string
+        - context is a valid ParsingContext instance
+
+    Post-conditions:
+        - Properties that form cycles are marked as unresolved
+        - Non-cyclic properties remain unchanged
+    """
+    if not schema_obj.properties:
+        return
+
+    visited: Set[str] = set()
+
+    def _check_cycle(prop_name: str) -> bool:
+        if prop_name in visited:
+            return True
+        visited.add(prop_name)
+
+        prop_schema = schema_obj.properties.get(prop_name)
+        if not prop_schema or not prop_schema._refers_to_schema:
+            return False
+
+        if prop_schema._refers_to_schema.name == ref_name:
+            return True
+
+        if prop_schema._refers_to_schema.properties:
+            for nested_prop_name in prop_schema._refers_to_schema.properties:
+                nested_prop = prop_schema._refers_to_schema.properties[nested_prop_name]
+                if nested_prop._refers_to_schema and nested_prop._refers_to_schema.name == ref_name:
+                    return True
+                if _check_cycle(nested_prop_name):
+                    return True
+
+        return False
+
+    # Check each property for cycles
+    for prop_name, prop_schema in schema_obj.properties.items():
+        if _check_cycle(prop_name):
+            prop_schema._from_unresolved_ref = True
+            prop_schema._is_circular_ref = True
+            context.cycle_detected = True
+            logger.debug(f"Cyclic property reference detected: {ref_name}.{prop_name}")

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

@@ -0,0 +1,33 @@
+"""
+Module for handling direct cycle detection.
+"""
+
+import logging
+
+from pyopenapi_gen.ir import IRSchema
+
+from ....context import ParsingContext
+
+logger = logging.getLogger(__name__)
+
+
+def handle_direct_cycle(ref_name: str, context: ParsingContext) -> IRSchema:
+    """
+    Handles a direct cycle in schema references.
+
+    Contracts:
+        Pre-conditions:
+            - ref_name must be a valid schema name
+            - context must be a valid ParsingContext instance
+            - ref_name must exist in context.parsed_schemas
+        Post-conditions:
+            - Returns the existing schema from context.parsed_schemas
+            - The schema's _from_unresolved_ref flag is set to True
+            - The schema's _is_circular_ref flag is set to True (for harmonized cycle detection)
+    """
+    existing_schema = context.parsed_schemas[ref_name]
+    existing_schema._from_unresolved_ref = True
+    existing_schema._is_circular_ref = True  # Harmonize with cycle detection contract
+    context.cycle_detected = True  # Mark cycle in context
+    logger.debug(f"Direct cycle detected for schema '{ref_name}'")
+    return existing_schema

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

@@ -0,0 +1,22 @@
+"""
+Module for handling existing schema references.
+"""
+
+from pyopenapi_gen.ir import IRSchema
+
+from ....context import ParsingContext
+
+
+def handle_existing_schema(ref_name: str, context: ParsingContext) -> IRSchema:
+    """
+    Handles an existing schema reference.
+
+    Contracts:
+        Pre-conditions:
+            - ref_name must be a valid schema name
+            - context must be a valid ParsingContext instance
+            - ref_name must exist in context.parsed_schemas
+        Post-conditions:
+            - Returns the existing schema from context.parsed_schemas
+    """
+    return context.parsed_schemas[ref_name]

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

@@ -0,0 +1,54 @@
+"""
+Module for handling ListResponse fallback strategy.
+"""
+
+import logging
+from typing import Any, Callable, Mapping, Optional
+
+from pyopenapi_gen.ir import IRSchema
+
+from ....context import ParsingContext
+
+logger = logging.getLogger(__name__)
+
+
+def try_list_response_fallback(
+    ref_name: str,
+    ref_value: str,
+    context: ParsingContext,
+    max_depth: int,
+    parse_fn: Callable[[Optional[str], Optional[Mapping[str, Any]], ParsingContext, int], IRSchema],
+) -> Optional[IRSchema]:
+    """
+    Attempts to resolve a reference by treating it as a list of a base type.
+
+    Contracts:
+        Pre-conditions:
+            - ref_name must end with "ListResponse"
+            - parse_fn must be a callable that parses schemas
+            - context must be a valid ParsingContext instance
+        Post-conditions:
+            - If successful, returns an array IRSchema with items of the base type
+            - If unsuccessful, returns None
+            - Successful resolutions are added to context.parsed_schemas
+    """
+    list_response_suffix = "ListResponse"
+    if not ref_name.endswith(list_response_suffix):
+        return None
+
+    base_name = ref_name[: -len(list_response_suffix)]
+    referenced_node_data_fallback = context.raw_spec_schemas.get(base_name)
+
+    if not referenced_node_data_fallback:
+        return None
+
+    item_schema = parse_fn(base_name, referenced_node_data_fallback, context, max_depth)
+    if item_schema._from_unresolved_ref:
+        return None
+
+    warning_msg = f"Resolved $ref: {ref_value} by falling back to LIST of base name '{base_name}'."
+    context.collected_warnings.append(warning_msg)
+
+    resolved_schema = IRSchema(name=ref_name, type="array", items=item_schema)
+    context.parsed_schemas[ref_name] = resolved_schema
+    return resolved_schema

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

@@ -0,0 +1,52 @@
+"""
+Module for handling missing schema references.
+"""
+
+import logging
+from typing import Any, Callable, Mapping, Optional
+
+from pyopenapi_gen.ir import IRSchema
+
+from ....context import ParsingContext
+from .list_response import try_list_response_fallback
+from .stripped_suffix import try_stripped_suffix_fallback
+
+logger = logging.getLogger(__name__)
+
+
+def handle_missing_ref(
+    ref_value: str,
+    ref_name: str,
+    context: ParsingContext,
+    max_depth: int,
+    parse_fn: Callable[[Optional[str], Optional[Mapping[str, Any]], ParsingContext, int], IRSchema],
+) -> IRSchema:
+    """
+    Handles a missing schema reference by attempting fallback strategies.
+
+    Contracts:
+        Pre-conditions:
+            - ref_value must be a valid reference string
+            - ref_name must be a valid schema name
+            - context must be a valid ParsingContext instance
+            - max_depth must be a non-negative integer
+            - parse_fn must be a callable that parses schemas
+        Post-conditions:
+            - Returns a valid IRSchema instance
+            - The schema is registered in context.parsed_schemas
+            - If no fallback succeeds, returns an unresolved schema
+    """
+    # Try ListResponse fallback
+    list_response_schema = try_list_response_fallback(ref_name, ref_value, context, max_depth, parse_fn)
+    if list_response_schema is not None:
+        return list_response_schema
+
+    # Try stripped suffix fallback
+    stripped_schema = try_stripped_suffix_fallback(ref_name, ref_value, context, max_depth, parse_fn)
+    if stripped_schema is not None:
+        return stripped_schema
+
+    # If all fallbacks fail, create an unresolved schema
+    unresolved_schema = IRSchema(name=ref_name, _from_unresolved_ref=True)
+    context.parsed_schemas[ref_name] = unresolved_schema
+    return unresolved_schema

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

@@ -0,0 +1,50 @@
+"""
+Module for handling new schema references.
+"""
+
+import logging
+from typing import Any, Callable, Dict, Mapping, Optional
+
+from pyopenapi_gen.ir import IRSchema
+
+from ....context import ParsingContext
+from .cyclic_properties import mark_cyclic_property_references
+
+logger = logging.getLogger(__name__)
+
+
+def parse_new_schema(
+    ref_name: str,
+    node_data: Dict[str, Any],
+    context: ParsingContext,
+    max_depth: int,
+    parse_fn: Callable[[Optional[str], Optional[Mapping[str, Any]], ParsingContext, int], IRSchema],
+) -> IRSchema:
+    """
+    Parses a new schema from raw data.
+
+    Contracts:
+        Pre-conditions:
+            - ref_name must be a valid schema name not already fully parsed
+            - node_data must contain raw schema definition
+            - parse_fn must be a callable that parses schemas
+            - context must be a valid ParsingContext instance
+        Post-conditions:
+            - Returns a valid parsed IRSchema instance
+            - The schema is registered in context.parsed_schemas
+            - Cyclic property references are marked correctly
+    """
+    # Create stub to prevent infinite recursion during parsing
+    stub_schema = IRSchema(name=ref_name)
+    context.parsed_schemas[ref_name] = stub_schema
+
+    # Parse the actual schema
+    schema_obj = parse_fn(ref_name, node_data, context, max_depth)
+
+    # Update the entry in parsed_schemas with the fully parsed schema
+    context.parsed_schemas[ref_name] = schema_obj
+
+    # Mark any property references involved in cycles
+    mark_cyclic_property_references(schema_obj, ref_name, context)
+
+    return schema_obj

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, Optional
+
+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[[Optional[str], Optional[Mapping[str, Any]], ParsingContext, int], IRSchema],
+) -> Optional[IRSchema]:
+    """
+    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, Optional
+
+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[[Optional[str], Optional[Mapping[str, Any]], 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,74 @@
+"""
+Dedicated parser for determining primary type and nullability from a schema's 'type' field.
+"""
+
+from __future__ import annotations
+
+from typing import (
+    Any,
+    List,
+    Optional,
+    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: Optional[str] = None
+) -> Tuple[Optional[str], 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