pyopenapi-gen 0.8.3__py3-none-any.whl

pyopenapi_gen/core/parsing/unified_cycle_detection.py

@@ -0,0 +1,293 @@
+"""
+Unified cycle detection system for schema parsing.
+
+This module provides a comprehensive, conflict-free approach to cycle detection
+that handles structural cycles, processing cycles, and depth limits consistently.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Dict, List, Optional, Set
+
+from pyopenapi_gen import IRSchema
+from pyopenapi_gen.core.utils import NameSanitizer
+
+logger = logging.getLogger(__name__)
+
+
+class SchemaState(Enum):
+    """States a schema can be in during parsing."""
+
+    NOT_STARTED = "not_started"
+    IN_PROGRESS = "in_progress"
+    COMPLETED = "completed"
+    PLACEHOLDER_CYCLE = "placeholder_cycle"
+    PLACEHOLDER_DEPTH = "placeholder_depth"
+    PLACEHOLDER_SELF_REF = "placeholder_self_ref"
+
+
+class CycleType(Enum):
+    """Types of cycles that can be detected."""
+
+    STRUCTURAL = "structural"  # Schema references form a loop
+    SELF_REFERENCE = "self_reference"  # Schema directly references itself
+    MAX_DEPTH = "max_depth"  # Recursion depth limit exceeded
+
+
+class CycleAction(Enum):
+    """Actions to take when cycle is detected."""
+
+    CONTINUE_PARSING = "continue"  # No cycle or allowed cycle
+    RETURN_PLACEHOLDER = "placeholder"  # Return pre-made placeholder
+    CREATE_PLACEHOLDER = "create"  # Create new placeholder
+    RETURN_EXISTING = "existing"  # Return existing parsed schema
+
+
+@dataclass
+class CycleInfo:
+    """Information about a detected cycle."""
+
+    schema_name: str
+    cycle_path: List[str]
+    cycle_type: CycleType
+    is_direct_self_reference: bool
+    depth_when_detected: int
+
+
+@dataclass
+class CycleDetectionResult:
+    """Result of cycle detection check."""
+
+    is_cycle: bool
+    cycle_type: Optional[CycleType]
+    action: CycleAction
+    cycle_info: Optional[CycleInfo] = None
+    placeholder_schema: Optional[IRSchema] = None
+
+
+@dataclass
+class UnifiedCycleContext:
+    """Unified context for all cycle detection mechanisms."""
+
+    # Core tracking
+    schema_stack: List[str] = field(default_factory=list)
+    schema_states: Dict[str, SchemaState] = field(default_factory=dict)
+    parsed_schemas: Dict[str, IRSchema] = field(default_factory=dict)
+    recursion_depth: int = 0
+
+    # Detection results
+    detected_cycles: List[CycleInfo] = field(default_factory=list)
+    depth_exceeded_schemas: Set[str] = field(default_factory=set)
+    cycle_detected: bool = False  # Global flag for backward compatibility
+
+    # Configuration
+    max_depth: int = 150
+    allow_self_reference: bool = False
+
+
+def analyze_cycle(schema_name: str, schema_stack: List[str]) -> CycleInfo:
+    """Analyze a detected cycle to determine its characteristics."""
+    try:
+        start_index = schema_stack.index(schema_name)
+        cycle_path = schema_stack[start_index:] + [schema_name]
+    except ValueError:
+        # Schema not in stack - shouldn't happen, but handle gracefully
+        cycle_path = [schema_name, schema_name]
+
+    is_direct_self_reference = len(cycle_path) == 2 and cycle_path[0] == cycle_path[1]
+
+    cycle_type = CycleType.SELF_REFERENCE if is_direct_self_reference else CycleType.STRUCTURAL
+
+    return CycleInfo(
+        schema_name=schema_name,
+        cycle_path=cycle_path,
+        cycle_type=cycle_type,
+        is_direct_self_reference=is_direct_self_reference,
+        depth_when_detected=len(schema_stack),
+    )
+
+
+def create_cycle_placeholder(schema_name: str, cycle_info: CycleInfo) -> IRSchema:
+    """Create a placeholder IRSchema for cycle detection."""
+    sanitized_name = NameSanitizer.sanitize_class_name(schema_name)
+    cycle_path_str = " -> ".join(cycle_info.cycle_path)
+
+    return IRSchema(
+        name=sanitized_name,
+        type="object",
+        description=f"[Circular reference detected: {cycle_path_str}]",
+        _from_unresolved_ref=True,
+        _circular_ref_path=cycle_path_str,
+        _is_circular_ref=True,
+    )
+
+
+def create_self_ref_placeholder(schema_name: str, cycle_info: CycleInfo) -> IRSchema:
+    """Create a placeholder IRSchema for allowed self-reference."""
+    sanitized_name = NameSanitizer.sanitize_class_name(schema_name)
+
+    return IRSchema(
+        name=sanitized_name,
+        type="object",
+        description=f"[Self-referencing schema: {schema_name}]",
+        _is_self_referential_stub=True,
+    )
+
+
+def create_depth_placeholder(schema_name: str, depth: int) -> IRSchema:
+    """Create a placeholder IRSchema for max depth exceeded."""
+    sanitized_name = NameSanitizer.sanitize_class_name(schema_name)
+    description = f"[Maximum recursion depth ({depth}) exceeded for '{schema_name}']"
+
+    # Import cycle_helpers to use its logging functionality
+    from .cycle_helpers import logger as cycle_helpers_logger
+
+    cycle_helpers_logger.warning(description)
+
+    return IRSchema(
+        name=sanitized_name,
+        type="object",
+        description=description,
+        _max_depth_exceeded_marker=True,
+    )
+
+
+def unified_cycle_check(schema_name: Optional[str], context: UnifiedCycleContext) -> CycleDetectionResult:
+    """Unified cycle detection that handles all cases."""
+
+    if schema_name is None:
+        return CycleDetectionResult(False, None, CycleAction.CONTINUE_PARSING)
+
+    # Check current state
+    current_state = context.schema_states.get(schema_name, SchemaState.NOT_STARTED)
+
+    # 1. If already completed, reuse (no cycle)
+    if current_state == SchemaState.COMPLETED:
+        return CycleDetectionResult(False, None, CycleAction.RETURN_EXISTING)
+
+    # 2. If already a placeholder, reuse it
+    if current_state in [
+        SchemaState.PLACEHOLDER_CYCLE,
+        SchemaState.PLACEHOLDER_DEPTH,
+        SchemaState.PLACEHOLDER_SELF_REF,
+    ]:
+        return CycleDetectionResult(True, None, CycleAction.RETURN_PLACEHOLDER)
+
+    # 3. Check depth limit BEFORE checking cycles (dynamically check environment)
+    import os
+
+    max_depth = int(os.environ.get("PYOPENAPI_MAX_DEPTH", context.max_depth))
+    if context.recursion_depth > max_depth:
+        context.depth_exceeded_schemas.add(schema_name)
+        context.schema_states[schema_name] = SchemaState.PLACEHOLDER_DEPTH
+        context.cycle_detected = True  # Max depth exceeded is considered a form of cycle detection
+        placeholder = create_depth_placeholder(schema_name, max_depth)
+        context.parsed_schemas[schema_name] = placeholder
+        return CycleDetectionResult(
+            True, CycleType.MAX_DEPTH, CycleAction.CREATE_PLACEHOLDER, placeholder_schema=placeholder
+        )
+
+    # 4. Check for structural cycle
+    if schema_name in context.schema_stack:
+        cycle_info = analyze_cycle(schema_name, context.schema_stack)
+        context.cycle_detected = True
+
+        # For cycles, create a placeholder for the re-entrant reference, not the original schema
+        # This allows the original schema parsing to complete normally
+        # The re-entrant reference gets a circular placeholder
+
+        # Create a unique key for this specific cycle reference
+        cycle_ref_key = f"{schema_name}_cycle_ref_{len(context.detected_cycles)}"
+
+        # Determine if cycle is allowed
+        if context.allow_self_reference and cycle_info.is_direct_self_reference:
+            placeholder = create_self_ref_placeholder(schema_name, cycle_info)
+        else:
+            context.detected_cycles.append(cycle_info)
+            placeholder = create_cycle_placeholder(schema_name, cycle_info)
+
+        # Determine storage policy based on cycle characteristics
+        is_synthetic_schema = schema_name and (
+            "Item" in schema_name or "Property" in schema_name  # Array item schemas  # Property schemas
+        )
+
+        # Check for specific known patterns
+        cycle_path_str = " -> ".join(cycle_info.cycle_path)
+        is_direct_array_self_ref = (
+            "Children" in cycle_path_str
+            and "ChildrenItem" in cycle_path_str
+            and cycle_info.cycle_path[0] == cycle_info.cycle_path[-1]
+        )
+        is_nested_property_self_ref = (
+            any(
+                name.startswith(schema_name) and name != schema_name and not name.endswith("Item")
+                for name in cycle_info.cycle_path
+            )
+            and cycle_info.cycle_path[0] == cycle_info.cycle_path[-1]
+        )
+
+        should_store_placeholder = (
+            is_synthetic_schema
+            or cycle_info.is_direct_self_reference
+            or is_direct_array_self_ref
+            or is_nested_property_self_ref
+        )
+
+        if should_store_placeholder:
+            context.parsed_schemas[schema_name] = placeholder
+            # Mark schema state appropriately
+            if context.allow_self_reference and cycle_info.is_direct_self_reference:
+                context.schema_states[schema_name] = SchemaState.PLACEHOLDER_SELF_REF
+            else:
+                context.schema_states[schema_name] = SchemaState.PLACEHOLDER_CYCLE
+
+        # Don't mark the original schema as a placeholder - just return the placeholder for this reference
+        return CycleDetectionResult(
+            True,
+            (
+                cycle_info.cycle_type
+                if not (context.allow_self_reference and cycle_info.is_direct_self_reference)
+                else CycleType.SELF_REFERENCE
+            ),
+            CycleAction.CREATE_PLACEHOLDER,
+            cycle_info=cycle_info,
+            placeholder_schema=placeholder,
+        )
+
+    # 5. No cycle detected - proceed with parsing
+    context.schema_states[schema_name] = SchemaState.IN_PROGRESS
+    return CycleDetectionResult(False, None, CycleAction.CONTINUE_PARSING)
+
+
+def unified_enter_schema(schema_name: Optional[str], context: UnifiedCycleContext) -> CycleDetectionResult:
+    """Unified entry point that always maintains consistent state."""
+    context.recursion_depth += 1
+
+    result = unified_cycle_check(schema_name, context)
+
+    # Only add to stack if we're going to continue parsing
+    if result.action == CycleAction.CONTINUE_PARSING and schema_name:
+        context.schema_stack.append(schema_name)
+
+    return result
+
+
+def unified_exit_schema(schema_name: Optional[str], context: UnifiedCycleContext) -> None:
+    """Unified exit that always maintains consistent state."""
+    if context.recursion_depth > 0:
+        context.recursion_depth -= 1
+
+    if schema_name and schema_name in context.schema_stack:
+        context.schema_stack.remove(schema_name)
+
+    # Mark as completed if it was in progress (but don't change placeholder states)
+    if schema_name and context.schema_states.get(schema_name) == SchemaState.IN_PROGRESS:
+        context.schema_states[schema_name] = SchemaState.COMPLETED
+
+
+def get_schema_or_placeholder(schema_name: str, context: UnifiedCycleContext) -> Optional[IRSchema]:
+    """Get an existing schema or placeholder from the context."""
+    return context.parsed_schemas.get(schema_name)

pyopenapi_gen/core/postprocess_manager.py

@@ -0,0 +1,161 @@
+import subprocess
+import sys
+from pathlib import Path
+from typing import List, Union
+
+SUCCESS_LINE = "Success: no issues found in 1 source file"
+
+
+def _print_filtered_stdout(stdout: str) -> None:
+    lines = [line for line in stdout.splitlines() if line.strip() and line.strip() != SUCCESS_LINE]
+    if lines:
+        print("\n".join(lines))
+
+
+class PostprocessManager:
+    """
+    Handles post-processing of generated Python files: import cleanup, formatting, and type checking.
+    Can be used programmatically or as a script.
+    """
+
+    def __init__(self, project_root: str):
+        self.project_root = project_root  # Store project root
+        pass
+
+    def run(self, targets: List[Union[str, Path]]) -> None:
+        """
+        Run Ruff checks on individual files, then run Mypy on the package root.
+        """
+        if not targets:
+            return
+
+        # Ensure all targets are Path objects
+        target_paths = [Path(t) for t in targets]
+
+        # --- RE-ENABLE RUFF CHECKS ---
+        for target_path in target_paths:
+            if target_path.is_file():
+                self.remove_unused_imports(target_path)
+                self.sort_imports(target_path)
+                self.format_code(target_path)
+        # --- END RE-ENABLE ---
+
+        # Determine the package root directory(s) for Mypy
+        package_roots = set()
+        for target_path in target_paths:
+            if target_path.is_file():
+                # Find the first ancestor directory *without* __init__.py
+                # (or stop at workspace root)
+                current = target_path.parent
+                package_root = current
+                while current != Path(self.project_root) and (current / "__init__.py").exists():
+                    package_root = current
+                    current = current.parent
+                package_roots.add(package_root)
+            elif target_path.is_dir():
+                # If a directory is passed, assume it's a package root or contains packages
+                # For simplicity, let's assume it *is* the root to run mypy on
+                package_roots.add(target_path)
+
+        # Run Mypy on each identified package root
+        if package_roots:
+            print(f"Running Mypy on package root(s): {package_roots}")
+        for root_dir in package_roots:
+            print(f"Running mypy on {root_dir}...")
+            self.type_check(root_dir)
+
+    def remove_unused_imports(self, target: Union[str, Path]) -> None:
+        """Remove unused imports from the target using Ruff."""
+        result = subprocess.run(
+            [
+                sys.executable,
+                "-m",
+                "ruff",
+                "check",
+                "--select=F401",
+                "--fix",
+                str(target),
+            ],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+        )
+        if result.returncode != 0 or result.stderr:
+            if result.stdout:
+                _print_filtered_stdout(result.stdout)
+            if result.stderr:
+                print(result.stderr, file=sys.stderr)
+
+    def sort_imports(self, target: Union[str, Path]) -> None:
+        """Sort imports in the target using Ruff."""
+        result = subprocess.run(
+            [
+                sys.executable,
+                "-m",
+                "ruff",
+                "check",
+                "--select=I",
+                "--fix",
+                str(target),
+            ],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+        )
+        if result.returncode != 0 or result.stderr:
+            if result.stdout:
+                _print_filtered_stdout(result.stdout)
+            if result.stderr:
+                print(result.stderr, file=sys.stderr)
+
+    def format_code(self, target: Union[str, Path]) -> None:
+        """Format code in the target using Ruff."""
+        result = subprocess.run(
+            [
+                sys.executable,
+                "-m",
+                "ruff",
+                "format",
+                str(target),
+            ],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+        )
+        if result.returncode != 0 or result.stderr:
+            if result.stdout:
+                _print_filtered_stdout(result.stdout)
+            if result.stderr:
+                print(result.stderr, file=sys.stderr)
+            print(f"Formatting found and fixed issues in {target}.", file=sys.stderr)
+
+    def type_check(self, target_dir: Path) -> None:
+        """Type check the target directory using mypy."""
+        if not target_dir.is_dir():
+            print(f"Skipping Mypy on non-directory: {target_dir}", file=sys.stderr)
+            return
+
+        print(f"Running mypy on {target_dir}...")
+        result = subprocess.run(
+            [sys.executable, "-m", "mypy", str(target_dir), "--strict"],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+        )
+        if result.stdout or result.stderr or result.returncode != 0:
+            if result.stdout:
+                print(result.stdout)
+            if result.stderr:
+                print(result.stderr, file=sys.stderr)
+            if result.returncode != 0:
+                print(f"Type checking failed for {target_dir}. Please fix the above issues.", file=sys.stderr)
+                sys.exit(result.returncode)
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Postprocess generated Python files/directories.")
+    parser.add_argument("targets", nargs="+", help="Files or directories to postprocess.")
+    args = parser.parse_args()
+    PostprocessManager(args.project_root).run(args.targets)

pyopenapi_gen/core/schemas.py

@@ -0,0 +1,40 @@
+from dataclasses import MISSING, dataclass, fields
+from typing import Any, Dict, Type, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass
+class BaseSchema:
+    """Base class for all generated Pydantic models, providing basic validation and dict conversion."""
+
+    @classmethod
+    def model_validate(cls: Type[T], data: Dict[str, Any]) -> T:
+        """Validate and create an instance from a dictionary, akin to Pydantic's model_validate."""
+        if not isinstance(data, dict):
+            raise TypeError(f"Input must be a dictionary, got {type(data).__name__}")
+
+        kwargs: Dict[str, Any] = {}
+        cls_fields = {f.name: f for f in fields(cls)}  # type: ignore[arg-type]
+
+        for field_name, field_def in cls_fields.items():
+            if field_name in data:
+                kwargs[field_name] = data[field_name]
+            elif field_def.default is MISSING and field_def.default_factory is MISSING:
+                raise ValueError(f"Missing required field: '{field_name}' for class {cls.__name__}")
+
+        extra_fields = set(data.keys()) - set(cls_fields.keys())
+        if extra_fields:
+            pass
+
+        return cls(**kwargs)
+
+    def model_dump(self, exclude_none: bool = False) -> Dict[str, Any]:
+        """Convert the model instance to a dictionary, akin to Pydantic's model_dump."""
+        result = {}
+        for field_def in fields(self):
+            value = getattr(self, field_def.name)
+            if exclude_none and value is None:
+                continue
+            result[field_def.name] = value
+        return result

pyopenapi_gen/core/streaming_helpers.py

@@ -0,0 +1,86 @@
+import json
+from typing import Any, AsyncIterator, List, Optional
+
+import httpx
+
+
+class SSEEvent:
+    def __init__(
+        self, data: str, event: Optional[str] = None, id: Optional[str] = None, retry: Optional[int] = None
+    ) -> None:
+        self.data: str = data
+        self.event: Optional[str] = event
+        self.id: Optional[str] = id
+        self.retry: Optional[int] = retry
+
+    def __repr__(self) -> str:
+        return f"SSEEvent(data={self.data!r}, event={self.event!r}, id={self.id!r}, retry={self.retry!r})"
+
+
+async def iter_bytes(response: httpx.Response) -> AsyncIterator[bytes]:
+    async for chunk in response.aiter_bytes():
+        yield chunk
+
+
+async def iter_ndjson(response: httpx.Response) -> AsyncIterator[Any]:
+    async for line in response.aiter_lines():
+        line = line.strip()
+        if line:
+            yield json.loads(line)
+
+
+async def iter_sse(response: httpx.Response) -> AsyncIterator[SSEEvent]:
+    """Parse Server-Sent Events (SSE) from a streaming response."""
+    event_lines: list[str] = []
+    async for line in response.aiter_lines():
+        if line == "":
+            # End of event
+            if event_lines:
+                event = _parse_sse_event(event_lines)
+                if event:
+                    yield event
+                event_lines = []
+        else:
+            event_lines.append(line)
+    # Last event (if any)
+    if event_lines:
+        event = _parse_sse_event(event_lines)
+        if event:
+            yield event
+
+
+def _parse_sse_event(lines: List[str]) -> SSEEvent:
+    data = []
+    event = None
+    id = None
+    retry = None
+    for line in lines:
+        if line.startswith(":"):
+            continue  # comment
+        if ":" in line:
+            field, value = line.split(":", 1)
+            value = value.lstrip()
+            if field == "data":
+                data.append(value)
+            elif field == "event":
+                event = value
+            elif field == "id":
+                id = value
+            elif field == "retry":
+                try:
+                    retry = int(value)
+                except ValueError:
+                    pass
+    return SSEEvent(data="\n".join(data), event=event, id=id, retry=retry)
+
+
+async def iter_sse_events_text(response: httpx.Response) -> AsyncIterator[str]:
+    """
+    Parses a Server-Sent Events (SSE) stream and yields the `data` field content
+    as a string for each event.
+    This is specifically for cases where the event data is expected to be a
+    single text payload (e.g., a JSON string) per event.
+    """
+    async for sse_event in iter_sse(response):
+        if sse_event.data:  # Ensure data is not empty
+            yield sse_event.data

pyopenapi_gen/core/telemetry.py

@@ -0,0 +1,67 @@
+"""
+Telemetry client for usage tracking and analytics.
+
+This module provides the TelemetryClient class, which handles anonymous
+usage telemetry for PyOpenAPI Generator. Telemetry is opt-in only.
+"""
+
+import json
+import os
+import time
+from typing import Any, Dict, Optional
+
+
+class TelemetryClient:
+    """
+    Client for sending opt-in telemetry events.
+
+    This class handles emitting usage events to understand how the generator
+    is being used. Telemetry is disabled by default and must be explicitly
+    enabled either through the PYOPENAPI_TELEMETRY_ENABLED environment
+    variable or by passing enabled=True to the constructor.
+
+    Attributes:
+        enabled: Whether telemetry is currently enabled
+    """
+
+    def __init__(self, enabled: Optional[bool] = None) -> None:
+        """
+        Initialize a new TelemetryClient.
+
+        Args:
+            enabled: Explicitly enable or disable telemetry. If None, the environment
+                    variable PYOPENAPI_TELEMETRY_ENABLED is checked.
+        """
+        if enabled is None:
+            env = os.getenv("PYOPENAPI_TELEMETRY_ENABLED", "false").lower()
+            self.enabled = env in ("1", "true", "yes")
+        else:
+            self.enabled = enabled
+
+    def track_event(self, event: str, properties: Optional[Dict[str, Any]] = None) -> None:
+        """
+        Track a telemetry event if telemetry is enabled.
+
+        This method sends a telemetry event with additional properties.
+        Events are silently dropped if telemetry is disabled.
+
+        Args:
+            event: The name of the event to track
+            properties: Optional dictionary of additional properties to include
+        """
+        if not self.enabled:
+            return
+
+        data: Dict[str, Any] = {
+            "event": event,
+            "properties": properties or {},
+            "timestamp": time.time(),
+        }
+
+        try:
+            # Using print as a stub for actual telemetry transport
+            # In production, this would be replaced with a proper telemetry client
+            print("TELEMETRY", json.dumps(data))
+        except Exception:
+            # Silently ignore any telemetry errors to avoid affecting main execution
+            pass