pyopenapi-gen 2.7.2__py3-none-any.whl

pyopenapi_gen/core/exceptions.py

@@ -0,0 +1,20 @@
+class HTTPError(Exception):
+    """Base HTTP error with status code and message."""
+
+    def __init__(self, status_code: int, message: str, response: object | None = None) -> None:
+        super().__init__(f"{status_code}: {message}")
+        self.status_code = status_code
+        self.message = message
+        self.response = response
+
+
+class ClientError(HTTPError):
+    """4XX client error responses."""
+
+    pass
+
+
+class ServerError(HTTPError):
+    """5XX server error responses."""
+
+    pass

pyopenapi_gen/core/http_status_codes.py

@@ -0,0 +1,218 @@
+"""HTTP status code definitions and human-readable names.
+
+This module provides a registry of standard HTTP status codes with their
+canonical names according to RFC specifications.
+
+References:
+    - RFC 9110 (HTTP Semantics): https://www.rfc-editor.org/rfc/rfc9110.html
+    - IANA HTTP Status Code Registry: https://www.iana.org/assignments/http-status-codes/
+"""
+
+# Standard HTTP status codes with human-readable names
+HTTP_STATUS_CODES: dict[int, str] = {
+    # 1xx Informational
+    100: "Continue",
+    101: "Switching Protocols",
+    102: "Processing",
+    103: "Early Hints",
+    # 2xx Success
+    200: "OK",
+    201: "Created",
+    202: "Accepted",
+    203: "Non-Authoritative Information",
+    204: "No Content",
+    205: "Reset Content",
+    206: "Partial Content",
+    207: "Multi-Status",
+    208: "Already Reported",
+    226: "IM Used",
+    # 3xx Redirection
+    300: "Multiple Choices",
+    301: "Moved Permanently",
+    302: "Found",
+    303: "See Other",
+    304: "Not Modified",
+    305: "Use Proxy",
+    307: "Temporary Redirect",
+    308: "Permanent Redirect",
+    # 4xx Client Error
+    400: "Bad Request",
+    401: "Unauthorised",
+    402: "Payment Required",
+    403: "Forbidden",
+    404: "Not Found",
+    405: "Method Not Allowed",
+    406: "Not Acceptable",
+    407: "Proxy Authentication Required",
+    408: "Request Timeout",
+    409: "Conflict",
+    410: "Gone",
+    411: "Length Required",
+    412: "Precondition Failed",
+    413: "Payload Too Large",
+    414: "URI Too Long",
+    415: "Unsupported Media Type",
+    416: "Range Not Satisfiable",
+    417: "Expectation Failed",
+    418: "I'm a teapot",
+    421: "Misdirected Request",
+    422: "Unprocessable Entity",
+    423: "Locked",
+    424: "Failed Dependency",
+    425: "Too Early",
+    426: "Upgrade Required",
+    428: "Precondition Required",
+    429: "Too Many Requests",
+    431: "Request Header Fields Too Large",
+    451: "Unavailable For Legal Reasons",
+    # 5xx Server Error
+    500: "Internal Server Error",
+    501: "Not Implemented",
+    502: "Bad Gateway",
+    503: "Service Unavailable",
+    504: "Gateway Timeout",
+    505: "HTTP Version Not Supported",
+    506: "Variant Also Negotiates",
+    507: "Insufficient Storage",
+    508: "Loop Detected",
+    510: "Not Extended",
+    511: "Network Authentication Required",
+}
+
+
+def get_status_name(code: int) -> str:
+    """Get the human-readable name for an HTTP status code.
+
+    Args:
+        code: HTTP status code (e.g., 404)
+
+    Returns:
+        Human-readable status name (e.g., "Not Found"), or "Unknown" if not found
+    """
+    return HTTP_STATUS_CODES.get(code, "Unknown")
+
+
+def is_error_code(code: int) -> bool:
+    """Check if a status code represents an error (4xx or 5xx).
+
+    Args:
+        code: HTTP status code
+
+    Returns:
+        True if the code is a client or server error, False otherwise
+    """
+    return 400 <= code < 600
+
+
+def is_client_error(code: int) -> bool:
+    """Check if a status code represents a client error (4xx).
+
+    Args:
+        code: HTTP status code
+
+    Returns:
+        True if the code is a client error, False otherwise
+    """
+    return 400 <= code < 500
+
+
+def is_server_error(code: int) -> bool:
+    """Check if a status code represents a server error (5xx).
+
+    Args:
+        code: HTTP status code
+
+    Returns:
+        True if the code is a server error, False otherwise
+    """
+    return 500 <= code < 600
+
+
+def is_success_code(code: int) -> bool:
+    """Check if a status code represents success (2xx).
+
+    Args:
+        code: HTTP status code
+
+    Returns:
+        True if the code is a success code, False otherwise
+    """
+    return 200 <= code < 300
+
+
+# Mapping of HTTP status codes to Python exception class names
+# These are semantically meaningful names that Python developers expect
+HTTP_EXCEPTION_NAMES: dict[int, str] = {
+    # 4xx Client Errors
+    400: "BadRequestError",
+    401: "UnauthorisedError",
+    402: "PaymentRequiredError",
+    403: "ForbiddenError",
+    404: "NotFoundError",
+    405: "MethodNotAllowedError",
+    406: "NotAcceptableError",
+    407: "ProxyAuthenticationRequiredError",
+    408: "RequestTimeoutError",
+    409: "ConflictError",
+    410: "GoneError",
+    411: "LengthRequiredError",
+    412: "PreconditionFailedError",
+    413: "PayloadTooLargeError",
+    414: "UriTooLongError",
+    415: "UnsupportedMediaTypeError",
+    416: "RangeNotSatisfiableError",
+    417: "ExpectationFailedError",
+    418: "ImATeapotError",
+    421: "MisdirectedRequestError",
+    422: "UnprocessableEntityError",
+    423: "LockedError",
+    424: "FailedDependencyError",
+    425: "TooEarlyError",
+    426: "UpgradeRequiredError",
+    428: "PreconditionRequiredError",
+    429: "TooManyRequestsError",
+    431: "RequestHeaderFieldsTooLargeError",
+    451: "UnavailableForLegalReasonsError",
+    # 5xx Server Errors
+    500: "InternalServerError",
+    501: "NotImplementedError",  # Note: Conflicts with Python built-in, will be handled
+    502: "BadGatewayError",
+    503: "ServiceUnavailableError",
+    504: "GatewayTimeoutError",
+    505: "HttpVersionNotSupportedError",
+    506: "VariantAlsoNegotiatesError",
+    507: "InsufficientStorageError",
+    508: "LoopDetectedError",
+    510: "NotExtendedError",
+    511: "NetworkAuthenticationRequiredError",
+}
+
+
+def get_exception_class_name(code: int) -> str:
+    """Get the Python exception class name for an HTTP status code.
+
+    Args:
+        code: HTTP status code (e.g., 404)
+
+    Returns:
+        Python exception class name (e.g., "NotFoundError"), or "Error{code}" as fallback
+
+    Examples:
+        >>> get_exception_class_name(404)
+        'NotFoundError'
+        >>> get_exception_class_name(429)
+        'TooManyRequestsError'
+        >>> get_exception_class_name(999)  # Unknown code
+        'Error999'
+    """
+    # Check if we have a semantic name for this code
+    if code in HTTP_EXCEPTION_NAMES:
+        name = HTTP_EXCEPTION_NAMES[code]
+        # Handle Python keyword conflicts
+        if name == "NotImplementedError":
+            # Avoid conflict with Python's built-in NotImplementedError
+            return "HttpNotImplementedError"
+        return name
+
+    # Fallback to Error{code} for codes we don't have semantic names for
+    return f"Error{code}"

pyopenapi_gen/core/http_transport.py

@@ -0,0 +1,222 @@
+from typing import Any, Protocol
+
+import httpx
+
+from .auth.base import BaseAuth
+from .exceptions import HTTPError
+
+
+class HttpTransport(Protocol):
+    """
+    Defines the interface for an asynchronous HTTP transport layer.
+
+    This protocol allows different HTTP client implementations (like httpx, aiohttp)
+    to be used interchangeably by the generated API client. It requires
+    implementing classes to provide an async `request` method.
+
+    All implementations must:
+    - Provide a fully type-annotated async `request` method.
+    - Return an `httpx.Response` object for all requests.
+    - Be safe for use in async contexts.
+    - STRICT REQUIREMENT: Raise `HTTPError` for all HTTP responses with status codes < 200 or >= 300.
+      This ensures that only successful (2xx) responses are returned to the caller, and all error
+      or informational responses are handled via exceptions. Implementors must not return non-2xx
+      responses directly; instead, they must raise `HTTPError` with the status code and response body.
+      This contract guarantees consistent error handling for all generated clients.
+    """
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        **kwargs: Any,
+    ) -> httpx.Response:
+        """
+        Sends an asynchronous HTTP request.
+
+        Args:
+            method: The HTTP method (e.g., 'GET', 'POST').
+            url: The target URL for the request.
+            **kwargs: Additional keyword arguments for the HTTP client (e.g., headers, params, json, data).
+
+        Returns:
+            httpx.Response: The HTTP response object.
+
+        Raises:
+            HTTPError: For all HTTP responses with status codes < 200 or >= 300. Implementors MUST raise
+                this exception for any non-2xx response, passing the status code and response body.
+            Exception: Implementations may raise exceptions for network errors or invalid responses.
+
+        Protocol Contract:
+            - Only successful (2xx) responses are returned to the caller.
+            - All other responses (including redirects, client errors, and server errors) must result in
+              an HTTPError being raised. This ensures that error handling is consistent and explicit
+              across all generated clients and transport implementations.
+        """
+        raise NotImplementedError()
+
+    async def close(self) -> None:
+        """
+        Closes any resources held by the transport (e.g., HTTP connections).
+
+        All implementations must provide this method. If the transport does not hold resources,
+        this should be a no-op.
+        """
+        raise NotImplementedError()
+
+
+class HttpxTransport:
+    """
+    A concrete implementation of the HttpTransport protocol using the `httpx` library.
+
+    This class provides the default asynchronous HTTP transport mechanism for the
+    generated API client. It wraps an `httpx.AsyncClient` instance to handle
+    request sending, connection pooling, and resource management.
+
+    Optionally supports authentication via any BaseAuth-compatible plugin, including CompositeAuth.
+
+    CONTRACT:
+        - This implementation strictly raises `HTTPError` for all HTTP responses with status codes < 200 or >= 300.
+          Only successful (2xx) responses are returned to the caller. This ensures that all error, informational,
+          and redirect responses are handled via exceptions, providing a consistent error handling model for the
+          generated client code.
+
+    Attributes:
+        _client (httpx.AsyncClient): Configured HTTPX async client for all requests.
+        _auth (BaseAuth | None): Optional authentication plugin for request signing (can be CompositeAuth).
+        _bearer_token (str | None): Optional bearer token for Authorization header.
+        _default_headers (dict[str, str] | None): Default headers to apply to all requests.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        timeout: float | None = None,
+        auth: BaseAuth | None = None,
+        bearer_token: str | None = None,
+        default_headers: dict[str, str] | None = None,
+        verify_ssl: bool = True,
+    ) -> None:
+        """
+        Initializes the HttpxTransport.
+
+        Args:
+            base_url (str): The base URL for all API requests made through this transport.
+            timeout (float | None): The default timeout in seconds for requests. If None, httpx's default is used.
+            auth (BaseAuth | None): Optional authentication plugin for request signing (can be CompositeAuth).
+            bearer_token (str | None): Optional raw bearer token string for Authorization header.
+            default_headers (dict[str, str] | None): Default headers to apply to all requests.
+            verify_ssl (bool): Whether to verify SSL certificates. Defaults to True.
+                Set to False for local development with self-signed certificates.
+
+        Note:
+            If both auth and bearer_token are provided, auth takes precedence.
+        """
+        self._client: httpx.AsyncClient = httpx.AsyncClient(base_url=base_url, timeout=timeout, verify=verify_ssl)
+        self._auth: BaseAuth | None = auth
+        self._bearer_token: str | None = bearer_token
+        self._default_headers: dict[str, str] | None = default_headers
+
+    async def _prepare_headers(
+        self,
+        current_request_kwargs: dict[str, Any],
+    ) -> dict[str, str]:
+        """
+        Prepares headers for an HTTP request, incorporating default headers,
+        request-specific headers, and authentication.
+        """
+        # Initialize headers for the current request
+        prepared_headers: dict[str, str] = {}
+
+        # 1. Apply transport-level default headers
+        if self._default_headers:
+            prepared_headers.update(self._default_headers)
+
+        # 2. Merge headers passed specifically for this request (overriding transport defaults)
+        if "headers" in current_request_kwargs and isinstance(current_request_kwargs["headers"], dict):
+            prepared_headers.update(current_request_kwargs["headers"])
+
+        # 3. Apply authentication plugin or bearer token (which can further modify headers)
+        # We pass a temporary request_args dict containing only the headers to the auth plugin,
+        # as the auth plugin might expect other keys which are not relevant for header preparation.
+        # The auth plugin is expected to modify the 'headers' key in the passed dict.
+        temp_request_args_for_auth = {"headers": prepared_headers.copy()}
+
+        if self._auth is not None:
+            authenticated_args = await self._auth.authenticate_request(temp_request_args_for_auth)
+            # Ensure 'headers' key exists and is a dict after authentication
+            if "headers" in authenticated_args and isinstance(authenticated_args["headers"], dict):
+                prepared_headers = authenticated_args["headers"]
+            else:
+                # Handle cases where auth plugin might not return headers as expected
+                # This could be an error or a specific design of an auth plugin.
+                # For now, we assume it should always return a 'headers' dict.
+                # If not, we retain the headers we had before calling the auth plugin.
+                pass  # Or raise an error, or log a warning.
+        elif self._bearer_token is not None:
+            # If no auth plugin, but bearer token is present, add/overwrite Authorization header.
+            prepared_headers["Authorization"] = f"Bearer {self._bearer_token}"
+
+        return prepared_headers
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        **kwargs: Any,
+    ) -> httpx.Response:
+        """
+        Sends an asynchronous HTTP request using the underlying httpx.AsyncClient.
+
+        Args:
+            method (str): The HTTP method (e.g., 'GET', 'POST').
+            url (str): The target URL path, relative to the `base_url` provided during initialization, or an absolute
+            URL.
+            **kwargs: Additional keyword arguments passed directly to `httpx.AsyncClient.request` (e.g., headers,
+            params, json, data).
+
+        Returns:
+            httpx.Response: The HTTP response object from the server.
+
+        Raises:
+            httpx.HTTPError: For network errors or invalid responses.
+            HTTPError: For non-2xx HTTP responses.
+        """
+        # Prepare request arguments, excluding headers initially
+        request_args: dict[str, Any] = {k: v for k, v in kwargs.items() if k != "headers"}
+
+        # This method handles default headers, request-specific headers, and authentication
+        prepared_headers = await self._prepare_headers(kwargs)
+        request_args["headers"] = prepared_headers
+
+        response = await self._client.request(method, url, **request_args)
+        if response.status_code < 200 or response.status_code >= 300:
+            raise HTTPError(status_code=response.status_code, message=response.text, response=response)
+        return response
+
+    async def close(self) -> None:
+        """
+        Closes the underlying httpx.AsyncClient and releases resources.
+
+        This should be called when the transport is no longer needed, typically
+        when the main API client is being shut down, to ensure proper cleanup
+        of network connections.
+        """
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "HttpxTransport":
+        """
+        Enter the async context manager. Returns self.
+        """
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: object | None,
+    ) -> None:
+        """
+        Exit the async context manager. Calls close().
+        """
+        await self.close()

pyopenapi_gen/core/loader/__init__.py

@@ -0,0 +1,12 @@
+"""Loader package to transform OpenAPI specs into Intermediate Representation.
+
+This package contains the classes and functions to load OpenAPI specifications
+and transform them into the internal IR dataclasses, which are then used for
+code generation.
+"""
+
+from __future__ import annotations
+
+from .loader import SpecLoader, load_ir_from_spec
+
+__all__ = ["SpecLoader", "load_ir_from_spec"]

pyopenapi_gen/core/loader/loader.py

@@ -0,0 +1,174 @@
+"""OpenAPI Spec Loader.
+
+Provides the main SpecLoader class and utilities to transform a validated OpenAPI spec
+into the internal IR dataclasses. This implementation covers a subset of the OpenAPI
+surface, sufficient for the code emitter prototypes.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import warnings
+from typing import Any, List, Mapping, cast
+
+try:
+    # Use the newer validate() API if available to avoid deprecation warnings
+    from openapi_spec_validator import validate as validate_spec
+except ImportError:
+    try:
+        from openapi_spec_validator import validate_spec  # type: ignore
+    except ImportError:  # pragma: no cover – optional in early bootstrapping
+        validate_spec = None  # type: ignore[assignment]
+
+from pyopenapi_gen import IRSpec
+from pyopenapi_gen.core.loader.operations import parse_operations
+from pyopenapi_gen.core.loader.schemas import build_schemas, extract_inline_enums
+
+__all__ = ["SpecLoader", "load_ir_from_spec"]
+
+logger = logging.getLogger(__name__)
+
+# Check for cycle detection debug flags in environment
+MAX_CYCLES = int(os.environ.get("PYOPENAPI_MAX_CYCLES", "0"))
+
+
+class SpecLoader:
+    """Transforms a validated OpenAPI spec into IR dataclasses.
+
+    This class follows the Design by Contract principles and ensures that
+    all operations maintain proper invariants and verify their inputs/outputs.
+    """
+
+    def __init__(self, spec: Mapping[str, Any]):
+        """Initialize the spec loader with an OpenAPI spec.
+
+        Contracts:
+            Preconditions:
+                - spec is a valid OpenAPI spec mapping
+                - spec contains required OpenAPI fields
+            Postconditions:
+                - Instance is ready to load IR from the spec
+        """
+        if not isinstance(spec, Mapping):
+            raise ValueError("spec must be a Mapping")
+        if "openapi" not in spec:
+            raise ValueError("Missing 'openapi' field in the specification")
+        if "paths" not in spec:
+            raise ValueError("Missing 'paths' section in the specification")
+
+        self.spec = spec
+        self.info = spec.get("info", {})
+        self.title = self.info.get("title", "API Client")
+        self.version = self.info.get("version", "0.0.0")
+        self.description = self.info.get("description")
+        self.raw_components = spec.get("components", {})
+        self.raw_schemas = self.raw_components.get("schemas", {})
+        self.raw_parameters = self.raw_components.get("parameters", {})
+        self.raw_responses = self.raw_components.get("responses", {})
+        self.raw_request_bodies = self.raw_components.get("requestBodies", {})
+        self.paths = spec["paths"]
+        self.servers = [s.get("url") for s in spec.get("servers", []) if "url" in s]
+
+    def validate(self) -> List[str]:
+        """Validate the OpenAPI spec but continue on errors.
+
+        Contracts:
+            Postconditions:
+                - Returns a list of validation warnings
+                - The spec is validated using openapi-spec-validator if available
+        """
+        warnings_list = []
+
+        if validate_spec is not None:
+            try:
+                from typing import Hashable
+
+                validate_spec(cast(Mapping[Hashable, Any], self.spec))
+            except Exception as e:
+                warning_msg = f"OpenAPI spec validation error: {e}"
+                # Always collect the message
+                warnings_list.append(warning_msg)
+
+                # Heuristic: if this error originates from jsonschema or
+                # openapi_spec_validator, prefer logging over global warnings
+                # to avoid noisy test output while still surfacing the issue.
+                origin_module = getattr(e.__class__, "__module__", "")
+                if (
+                    isinstance(e, RecursionError)
+                    or origin_module.startswith("jsonschema")
+                    or origin_module.startswith("openapi_spec_validator")
+                ):
+                    logger.warning(warning_msg)
+                else:
+                    # Preserve explicit warning behavior for unexpected failures
+                    warnings.warn(warning_msg, UserWarning)
+
+        return warnings_list
+
+    def load_ir(self) -> IRSpec:
+        """Transform the spec into an IRSpec object.
+
+        Contracts:
+            Postconditions:
+                - Returns a fully populated IRSpec object
+                - All schemas are properly processed and named
+                - All operations are properly parsed and linked to schemas
+        """
+        # First validate the spec
+        self.validate()
+
+        # Build schemas and create context
+        context = build_schemas(self.raw_schemas, self.raw_components)
+
+        # Parse operations
+        operations = parse_operations(
+            self.paths,
+            self.raw_parameters,
+            self.raw_responses,
+            self.raw_request_bodies,
+            context,
+        )
+
+        # Extract inline enums and add them to the schemas map
+        schemas_dict = extract_inline_enums(context.parsed_schemas)
+
+        # Emit collected warnings after all parsing is done
+        for warning_msg in context.collected_warnings:
+            warnings.warn(warning_msg, UserWarning)
+
+        # Create and return the IR spec
+        ir_spec = IRSpec(
+            title=self.title,
+            version=self.version,
+            description=self.description,
+            schemas=schemas_dict,
+            operations=operations,
+            servers=self.servers,
+        )
+
+        # Post-condition check
+        if ir_spec.schemas != schemas_dict:
+            raise RuntimeError("Schemas mismatch in IRSpec")
+        if ir_spec.operations != operations:
+            raise RuntimeError("Operations mismatch in IRSpec")
+
+        return ir_spec
+
+
+def load_ir_from_spec(spec: Mapping[str, Any]) -> IRSpec:
+    """Orchestrate the transformation of a spec dict into IRSpec.
+
+    This is a convenience function that creates a SpecLoader and calls load_ir().
+
+    Contracts:
+        Preconditions:
+            - spec is a valid OpenAPI spec mapping
+        Postconditions:
+            - Returns a fully populated IRSpec object
+    """
+    if not isinstance(spec, Mapping):
+        raise ValueError("spec must be a Mapping")
+
+    loader = SpecLoader(spec)
+    return loader.load_ir()

pyopenapi_gen/core/loader/operations/__init__.py

@@ -0,0 +1,12 @@
+"""Operation parsing utilities.
+
+Functions to extract and transform operations from raw OpenAPI specifications.
+"""
+
+from __future__ import annotations
+
+from .parser import parse_operations
+from .post_processor import post_process_operation
+from .request_body import parse_request_body
+
+__all__ = ["parse_operations", "post_process_operation", "parse_request_body"]