pyopenapi-gen 2.7.2__py3-none-any.whl

pyopenapi_gen/core/streaming_helpers.py

@@ -0,0 +1,84 @@
+import json
+from typing import Any, AsyncIterator, List
+
+import httpx
+
+
+class SSEEvent:
+    def __init__(self, data: str, event: str | None = None, id: str | None = None, retry: int | None = None) -> None:
+        self.data: str = data
+        self.event: str | None = event
+        self.id: str | None = id
+        self.retry: int | None = 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,69 @@
+"""
+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
+
+
+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: bool | None = 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: dict[str, Any] | None = 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 as e:
+            # Telemetry failures should not affect execution, but log for debugging
+            import logging
+
+            logging.getLogger(__name__).debug(f"Telemetry event failed: {e}")

pyopenapi_gen/core/utils.py

@@ -0,0 +1,456 @@
+"""Utilities for pyopenapi_gen.
+
+This module contains utility classes and functions used across the code generation process.
+"""
+
+import base64
+import dataclasses
+import keyword
+import logging
+import re
+from datetime import datetime
+from typing import Any, Set, Type, TypeVar, cast
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+
+class NameSanitizer:
+    """Helper to sanitize spec names and tags into valid Python identifiers and filenames."""
+
+    # Python built-ins and common problematic names that should be avoided in module names
+    RESERVED_NAMES = {
+        # Built-in types
+        "type",
+        "int",
+        "str",
+        "float",
+        "bool",
+        "list",
+        "dict",
+        "set",
+        "tuple",
+        "bytes",
+        "object",
+        "complex",
+        "frozenset",
+        "bytearray",
+        "memoryview",
+        "range",
+        # Built-in functions
+        "abs",
+        "all",
+        "any",
+        "bin",
+        "callable",
+        "chr",
+        "classmethod",
+        "compile",
+        "delattr",
+        "dir",
+        "divmod",
+        "enumerate",
+        "eval",
+        "exec",
+        "filter",
+        "format",
+        "getattr",
+        "globals",
+        "hasattr",
+        "hash",
+        "help",
+        "hex",
+        "id",
+        "input",
+        "isinstance",
+        "issubclass",
+        "iter",
+        "len",
+        "locals",
+        "map",
+        "max",
+        "min",
+        "next",
+        "oct",
+        "open",
+        "ord",
+        "pow",
+        "print",
+        "property",
+        "repr",
+        "reversed",
+        "round",
+        "setattr",
+        "slice",
+        "sorted",
+        "staticmethod",
+        "sum",
+        "super",
+        "vars",
+        "zip",
+        # Common standard library modules
+        "os",
+        "sys",
+        "json",
+        "time",
+        "datetime",
+        "math",
+        "random",
+        "string",
+        "collections",
+        "itertools",
+        "functools",
+        "typing",
+        "pathlib",
+        "logging",
+        "urllib",
+        "http",
+        "email",
+        "uuid",
+        "hashlib",
+        "base64",
+        "copy",
+        "re",
+        # Other problematic names
+        "data",
+        "model",
+        "models",
+        "client",
+        "api",
+        "config",
+        "utils",
+        "helpers",
+    }
+
+    @staticmethod
+    def sanitize_module_name(name: str) -> str:
+        """Convert a raw name into a valid Python module name in snake_case, splitting camel case and PascalCase."""
+        # # <<< Add Check for problematic input >>>
+        # if '[' in name or ']' in name or ',' in name:
+        #     logger.error(f"sanitize_module_name received potentially invalid input: '{name}'")
+        #     # Optionally, return a default/error value or raise exception
+        #     # For now, just log and continue
+        # # <<< End Check >>>
+
+        # Split on non-alphanumeric and camel case boundaries
+        words = re.findall(r"[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+|[0-9]+", name)
+        if not words:
+            # fallback: split on non-alphanumerics
+            words = re.split(r"\W+", name)
+        module = "_".join(word.lower() for word in words if word)
+        # If it starts with a digit, prefix with underscore
+        if module and module[0].isdigit():
+            module = "_" + module
+        # Avoid Python keywords and reserved names
+        if keyword.iskeyword(module) or module in NameSanitizer.RESERVED_NAMES:
+            module += "_"
+        return module
+
+    @staticmethod
+    def sanitize_class_name(name: str) -> str:
+        """Convert a raw name into a valid Python class name in PascalCase."""
+        # Split on non-alphanumeric and camel case boundaries
+        words = re.findall(r"[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+|[0-9]+", name)
+        if not words:  # Fallback if findall is empty (e.g. if name was all symbols)
+            # Basic split on non-alphanumeric as a last resort if findall yields nothing
+            words = [part for part in re.split(r"[^a-zA-Z0-9]+", name) if part]
+
+        # Capitalize each word and join
+        cls_name = "".join(word.capitalize() for word in words if word)
+
+        if not cls_name:  # If name was e.g. "-" or "_"
+            cls_name = "UnnamedClass"  # Or some other default
+
+        # If it starts with a digit, prefix with underscore
+        if cls_name[0].isdigit():  # Check after ensuring cls_name is not empty
+            cls_name = "_" + cls_name
+        # Avoid Python keywords and reserved names (case-insensitive)
+        if keyword.iskeyword(cls_name.lower()) or cls_name.lower() in NameSanitizer.RESERVED_NAMES:
+            cls_name += "_"
+        return cls_name
+
+    @staticmethod
+    def sanitize_tag_class_name(tag: str) -> str:
+        """Sanitize a tag for use as a PascalCase client class name (e.g., DataSourcesClient)."""
+        words = re.split(r"[\W_]+", tag)
+        return "".join(word.capitalize() for word in words if word) + "Client"
+
+    @staticmethod
+    def sanitize_tag_attr_name(tag: str) -> str:
+        """Sanitize a tag for use as a snake_case attribute name (e.g., data_sources)."""
+        attr = re.sub(r"[\W]+", "_", tag).lower()
+        return attr.strip("_")
+
+    @staticmethod
+    def normalize_tag_key(tag: str) -> str:
+        """Normalize a tag for case-insensitive uniqueness (e.g., datasources)."""
+        return re.sub(r"[\W_]+", "", tag).lower()
+
+    @staticmethod
+    def sanitize_filename(name: str, suffix: str = ".py") -> str:
+        """Generate a valid Python filename from raw name in snake_case."""
+        module = NameSanitizer.sanitize_module_name(name)
+        return module + suffix
+
+    @staticmethod
+    def sanitize_method_name(name: str) -> str:
+        """Convert a raw name into a valid Python method name in snake_case, splitting camelCase and PascalCase."""
+        # Remove curly braces
+        name = re.sub(r"[{}]", "", name)
+        # Split camelCase and PascalCase to snake_case
+        name = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", name)
+        name = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1_\2", name)
+        # Replace non-alphanumerics with underscores
+        name = re.sub(r"[^0-9a-zA-Z_]", "_", name)
+        # Lowercase and collapse multiple underscores
+        name = re.sub(r"_+", "_", name).strip("_").lower()
+        # If it starts with a digit, prefix with underscore
+        if name and name[0].isdigit():
+            name = "_" + name
+        # Avoid Python keywords and reserved names
+        if keyword.iskeyword(name) or name in NameSanitizer.RESERVED_NAMES:
+            name += "_"
+        return name
+
+    @staticmethod
+    def is_valid_python_identifier(name: str) -> bool:
+        """Check if a string is a valid Python identifier."""
+        if not isinstance(name, str) or not name:
+            return False
+        # Check if it's a keyword
+        if keyword.iskeyword(name):
+            return False
+        # Check pattern: starts with letter/underscore, then letter/digit/underscore
+        return re.match(r"^[a-zA-Z_][a-zA-Z0-9_]*$", name) is not None
+
+
+class ParamSubstitutor:
+    """Helper for rendering path templates with path parameters."""
+
+    @staticmethod
+    def render_path(template: str, values: dict[str, Any]) -> str:
+        """Replace placeholders in a URL path template using provided values."""
+        rendered = template
+        for key, val in values.items():
+            rendered = rendered.replace(f"{{{key}}}", str(val))
+        return rendered
+
+
+class KwargsBuilder:
+    """Builder for assembling HTTP request keyword arguments."""
+
+    def __init__(self) -> None:
+        self._kwargs: dict[str, Any] = {}
+
+    def with_params(self, **params: Any) -> "KwargsBuilder":
+        """Add query parameters, skipping None values."""
+        filtered = {k: v for k, v in params.items() if v is not None}
+        if filtered:
+            self._kwargs["params"] = filtered
+        return self
+
+    def with_json(self, body: Any) -> "KwargsBuilder":
+        """Add a JSON body to the request."""
+        self._kwargs["json"] = body
+        return self
+
+    def build(self) -> dict[str, Any]:
+        """Return the assembled kwargs dictionary."""
+        return self._kwargs
+
+
+class Formatter:
+    """Helper to format code using Black, falling back to unformatted content if Black is unavailable or errors."""
+
+    def __init__(self) -> None:
+        from typing import Any, Callable
+
+        self._file_mode: Any | None = None
+        self._format_str: Callable[..., str] | None = None
+        try:
+            from black import FileMode, format_str
+
+            # Suppress blib2to3 debug logging that floods output during formatting
+            blib2to3_logger = logging.getLogger("blib2to3")
+            blib2to3_logger.setLevel(logging.WARNING)
+
+            # Also suppress the driver logger specifically
+            driver_logger = logging.getLogger("blib2to3.pgen2.driver")
+            driver_logger.setLevel(logging.WARNING)
+
+            # Initialize Black formatter
+            self._file_mode = FileMode()
+            self._format_str = format_str
+        except ImportError:
+            self._file_mode = None
+            self._format_str = None
+
+    def format(self, code: str) -> str:
+        """Format the given code string with Black if possible."""
+        if self._format_str is not None and self._file_mode is not None:
+            try:
+                formatted: str = self._format_str(code, mode=self._file_mode)
+                return formatted
+            except Exception:
+                # On any Black formatting error, return original code
+                return code
+        return code
+
+
+# --- Casting Helper ---
+
+
+def safe_cast(expected_type: Type[T], data: Any) -> T:
+    """
+    Performs a cast for the type checker using object cast.
+    (Validation temporarily removed).
+    """
+    # No validation for now
+    # Cast to object first, then to expected_type
+    return cast(expected_type, cast(object, data))  # type: ignore[valid-type]
+
+
+class DataclassSerializer:
+    """Utility for converting dataclass instances to dictionaries for API serialization.
+
+    This enables automatic conversion of dataclass request bodies to JSON-compatible
+    dictionaries in generated client code, providing a better developer experience.
+    """
+
+    @staticmethod
+    def serialize(obj: Any) -> Any:
+        """Convert dataclass instances to dictionaries recursively.
+
+        Args:
+            obj: The object to serialize. Can be a dataclass, list, dict, or primitive.
+
+        Returns:
+            The serialized object with dataclasses converted to dictionaries.
+
+        Handles:
+        - Dataclass instances with Meta.key_transform_with_dump: Applies field name mapping (snake_case → camelCase)
+        - Legacy BaseSchema instances: Falls back to to_dict() if present (backward compatibility)
+        - Regular dataclass instances: Converted to dictionaries using field names
+        - Lists: Recursively serialize each item
+        - Dictionaries: Recursively serialize values
+        - datetime: Convert to ISO format string
+        - Enums: Convert to their value
+        - bytes/bytearray: Convert to base64-encoded ASCII string
+        - Primitives: Return unchanged
+        - None values: Excluded from output
+        """
+        # Track visited objects to handle circular references
+        return DataclassSerializer._serialize_with_tracking(obj, set())
+
+    @staticmethod
+    def _serialize_with_tracking(obj: Any, visited: Set[int]) -> Any:
+        """Internal serialization method with circular reference tracking."""
+        from enum import Enum
+
+        # Handle None values by excluding them
+        if obj is None:
+            return None
+
+        # Handle circular references
+        obj_id = id(obj)
+        if obj_id in visited:
+            # For circular references, return a simple representation
+            if dataclasses.is_dataclass(obj) and not isinstance(obj, type):
+                return f"<Circular reference to {obj.__class__.__name__}>"
+            return obj
+
+        # Handle datetime objects
+        if isinstance(obj, datetime):
+            return obj.isoformat()
+
+        # Handle enum instances
+        if isinstance(obj, Enum) and not isinstance(obj, type):
+            return obj.value
+
+        # Handle legacy BaseSchema instances (backward compatibility)
+        # Check for BaseSchema by looking for both to_dict and _get_field_mappings methods
+        if hasattr(obj, "to_dict") and hasattr(obj, "_get_field_mappings") and callable(obj.to_dict):
+            visited.add(obj_id)
+            try:
+                # Use legacy BaseSchema's to_dict() which handles field name mapping
+                result_dict = obj.to_dict(exclude_none=True)
+                # Recursively serialize nested objects in the result
+                serialized_result = {}
+                for key, value in result_dict.items():
+                    serialized_value = DataclassSerializer._serialize_with_tracking(value, visited)
+                    if serialized_value is not None:
+                        serialized_result[key] = serialized_value
+                return serialized_result
+            finally:
+                visited.discard(obj_id)
+
+        # Handle regular dataclass instances (with cattrs field mapping support)
+        if dataclasses.is_dataclass(obj) and not isinstance(obj, type):
+            visited.add(obj_id)
+            try:
+                # Build dict from dataclass fields without recursive unstructuring
+                data: dict[str, Any] = {}
+                for field in dataclasses.fields(obj):
+                    value = getattr(obj, field.name)
+                    data[field.name] = value
+
+                # Apply field name mapping if Meta class exists
+                if hasattr(obj, "Meta") and hasattr(obj.Meta, "key_transform_with_dump"):
+                    mappings = obj.Meta.key_transform_with_dump
+                    # Transform keys according to mapping
+                    data = {mappings.get(k, k): v for k, v in data.items()}
+
+                # Recursively serialize nested objects and skip None values
+                result = {}
+                for key, value in data.items():
+                    if value is not None:
+                        serialized_value = DataclassSerializer._serialize_with_tracking(value, visited)
+                        if serialized_value is not None:
+                            result[key] = serialized_value
+                return result
+            finally:
+                visited.discard(obj_id)
+
+        # Handle lists and tuples
+        if isinstance(obj, (list, tuple)):
+            return [DataclassSerializer._serialize_with_tracking(item, visited) for item in obj]
+
+        # Handle dictionaries
+        if isinstance(obj, dict):
+            result = {}
+            for key, value in obj.items():
+                serialized_value = DataclassSerializer._serialize_with_tracking(value, visited)
+                if serialized_value is not None:
+                    result[key] = serialized_value
+            return result
+
+        # Handle primitive types and unknown objects
+        if isinstance(obj, (str, int, float, bool)):
+            return obj
+
+        # Handle bytes - encode as base64 for JSON serialization
+        if isinstance(obj, (bytes, bytearray)):
+            return base64.b64encode(bytes(obj)).decode("ascii")
+
+        # For unknown types, try to convert to string as fallback
+        try:
+            # If the object has a __dict__, try to serialize it like a dataclass
+            if hasattr(obj, "__dict__"):
+                visited.add(obj_id)
+                try:
+                    result = {}
+                    for key, value in obj.__dict__.items():
+                        if not key.startswith("_"):  # Skip private attributes
+                            serialized_value = DataclassSerializer._serialize_with_tracking(value, visited)
+                            if serialized_value is not None:
+                                result[key] = serialized_value
+                    return result
+                finally:
+                    visited.discard(obj_id)
+            else:
+                # Fallback to string representation
+                return str(obj)
+        except Exception:
+            # Ultimate fallback
+            return str(obj)

pyopenapi_gen/core/warning_collector.py

@@ -0,0 +1,83 @@
+"""
+Warning collector for the IR layer.
+
+This module provides utilities to collect actionable warnings for incomplete
+metadata in the IR (Intermediate Representation) objects, such as missing tags,
+descriptions, or other quality issues in the OpenAPI spec that may lead to
+suboptimal generated code.
+"""
+
+from dataclasses import dataclass
+from typing import List
+
+from pyopenapi_gen import IRSpec
+
+__all__ = ["WarningReport", "WarningCollector"]
+
+
+@dataclass
+class WarningReport:
+    """
+    Structured warning with a code, human-readable message, and remediation hint.
+
+    Attributes:
+        code: A machine-readable warning code (e.g., "missing_tags")
+        message: A human-readable description of the warning
+        hint: A suggestion for how to fix or improve the issue
+    """
+
+    code: str
+    message: str
+    hint: str
+
+
+class WarningCollector:
+    """
+    Collects warnings about missing or incomplete information in an IRSpec.
+
+    This class analyzes an IRSpec object and identifies potential issues or
+    missing information that might lead to lower quality generated code or
+    documentation. It provides actionable warnings with hints for improvement.
+
+    Attributes:
+        warnings: List of collected WarningReport objects
+    """
+
+    def __init__(self) -> None:
+        """Initialize a new WarningCollector with an empty warning list."""
+        self.warnings: List[WarningReport] = []
+
+    def collect(self, spec: IRSpec) -> List[WarningReport]:
+        """
+        Analyze an IRSpec and collect warnings about potential issues.
+
+        This method traverses the IRSpec and checks for common issues like
+        missing tags, descriptions, or other metadata that would improve
+        the quality of the generated code.
+
+        Args:
+            spec: The IRSpec object to analyze
+
+        Returns:
+            A list of WarningReport objects describing identified issues
+        """
+        # Operations without tags
+        for op in spec.operations:
+            if not op.tags:
+                self.warnings.append(
+                    WarningReport(
+                        code="missing_tags",
+                        message=f"Operation '{op.operation_id}' has no tags.",
+                        hint="Add tags to operations in the OpenAPI spec.",
+                    )
+                )
+            # Missing summary and description
+            if not op.summary and not op.description:
+                self.warnings.append(
+                    WarningReport(
+                        code="missing_description",
+                        message=f"Operation '{op.operation_id}' missing summary/description.",
+                        hint="Provide a summary or description for the operation.",
+                    )
+                )
+        return self.warnings