pyopenapi-gen 0.8.3__py3-none-any.whl

pyopenapi_gen/core/auth/plugins.py

@@ -0,0 +1,89 @@
+from typing import Any, Awaitable, Callable, Dict, Optional
+
+from .base import BaseAuth
+
+
+class BearerAuth(BaseAuth):
+    """Authentication plugin for Bearer tokens."""
+
+    def __init__(self, token: str) -> None:
+        self.token = token
+
+    async def authenticate_request(self, request_args: Dict[str, Any]) -> Dict[str, Any]:
+        # Ensure headers dict exists
+        headers = dict(request_args.get("headers", {}))
+        headers["Authorization"] = f"Bearer {self.token}"
+        request_args["headers"] = headers
+        return request_args
+
+
+class HeadersAuth(BaseAuth):
+    """Authentication plugin for arbitrary headers."""
+
+    def __init__(self, headers: Dict[str, str]) -> None:
+        self.headers = headers
+
+    async def authenticate_request(self, request_args: Dict[str, Any]) -> Dict[str, Any]:
+        # Merge custom headers
+        hdrs = dict(request_args.get("headers", {}))
+        hdrs.update(self.headers)
+        request_args["headers"] = hdrs
+        return request_args
+
+
+class ApiKeyAuth(BaseAuth):
+    """Authentication plugin for API keys (header, query, or cookie)."""
+
+    def __init__(self, key: str, location: str = "header", name: str = "X-API-Key") -> None:
+        """
+        Args:
+            key: The API key value.
+            location: Where to add the key ("header", "query", or "cookie").
+            name: The name of the header/query/cookie parameter.
+        """
+        self.key = key
+        self.location = location
+        self.name = name
+
+    async def authenticate_request(self, request_args: Dict[str, Any]) -> Dict[str, Any]:
+        if self.location == "header":
+            headers = dict(request_args.get("headers", {}))
+            headers[self.name] = self.key
+            request_args["headers"] = headers
+        elif self.location == "query":
+            params = dict(request_args.get("params", {}))
+            params[self.name] = self.key
+            request_args["params"] = params
+        elif self.location == "cookie":
+            cookies = dict(request_args.get("cookies", {}))
+            cookies[self.name] = self.key
+            request_args["cookies"] = cookies
+        else:
+            raise ValueError(f"Invalid API key location: {self.location}")
+        return request_args
+
+
+class OAuth2Auth(BaseAuth):
+    """Authentication plugin for OAuth2 Bearer tokens, with optional auto-refresh."""
+
+    def __init__(self, access_token: str, refresh_callback: Optional[Callable[[str], Awaitable[str]]] = None) -> None:
+        """
+        Args:
+            access_token: The OAuth2 access token.
+            refresh_callback: Optional async function to refresh the token. If provided, will be called
+            if token is expired.
+        """
+        self.access_token = access_token
+        self.refresh_callback = refresh_callback
+
+    async def authenticate_request(self, request_args: Dict[str, Any]) -> Dict[str, Any]:
+        # In a real implementation, check expiry and refresh if needed
+        if self.refresh_callback is not None:
+            # Optionally refresh token (user must implement expiry logic)
+            new_token = await self.refresh_callback(self.access_token)
+            if new_token and new_token != self.access_token:
+                self.access_token = new_token
+        headers = dict(request_args.get("headers", {}))
+        headers["Authorization"] = f"Bearer {self.access_token}"
+        request_args["headers"] = headers
+        return request_args

pyopenapi_gen/core/exceptions.py

@@ -0,0 +1,25 @@
+from typing import Optional
+
+import httpx
+
+
+class HTTPError(Exception):
+    """Base HTTP error with status code and message."""
+
+    def __init__(self, status_code: int, message: str, response: Optional[httpx.Response] = 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_transport.py

@@ -0,0 +1,219 @@
+from typing import Any, Dict, Optional, 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 (Optional[BaseAuth]): Optional authentication plugin for request signing (can be CompositeAuth).
+        _bearer_token (Optional[str]): Optional bearer token for Authorization header.
+        _default_headers (Optional[Dict[str, str]]): Default headers to apply to all requests.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        timeout: Optional[float] = None,
+        auth: Optional[BaseAuth] = None,
+        bearer_token: Optional[str] = None,
+        default_headers: Optional[Dict[str, str]] = None,
+    ) -> None:
+        """
+        Initializes the HttpxTransport.
+
+        Args:
+            base_url (str): The base URL for all API requests made through this transport.
+            timeout (Optional[float]): The default timeout in seconds for requests. If None, httpx's default is used.
+            auth (Optional[BaseAuth]): Optional authentication plugin for request signing (can be CompositeAuth).
+            bearer_token (Optional[str]): Optional raw bearer token string for Authorization header.
+            default_headers (Optional[Dict[str, str]]): Default headers to apply to all requests.
+
+        Note:
+            If both auth and bearer_token are provided, auth takes precedence.
+        """
+        self._client: httpx.AsyncClient = httpx.AsyncClient(base_url=base_url, timeout=timeout)
+        self._auth: Optional[BaseAuth] = auth
+        self._bearer_token: Optional[str] = bearer_token
+        self._default_headers: Optional[Dict[str, str]] = 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,158 @@
+"""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}"
+                warnings_list.append(warning_msg)
+                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
+        assert ir_spec.schemas == schemas_dict, "Schemas mismatch in IRSpec"
+        assert ir_spec.operations == operations, "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"]

pyopenapi_gen/core/loader/operations/parser.py

@@ -0,0 +1,155 @@
+"""Operation parsers for OpenAPI IR transformation.
+
+Provides the main parse_operations function to transform OpenAPI paths into IR operations.
+"""
+
+from __future__ import annotations
+
+import logging
+import warnings
+from typing import Any, List, Mapping, Optional, cast
+
+from pyopenapi_gen import HTTPMethod, IROperation, IRParameter, IRRequestBody, IRResponse
+from pyopenapi_gen.core.loader.operations.post_processor import post_process_operation
+from pyopenapi_gen.core.loader.operations.request_body import parse_request_body
+from pyopenapi_gen.core.loader.parameters import parse_parameter, resolve_parameter_node_if_ref
+from pyopenapi_gen.core.loader.responses import parse_response
+from pyopenapi_gen.core.parsing.context import ParsingContext
+from pyopenapi_gen.core.utils import NameSanitizer
+
+logger = logging.getLogger(__name__)
+
+
+def parse_operations(
+    paths: Mapping[str, Any],
+    raw_parameters: Mapping[str, Any],
+    raw_responses: Mapping[str, Any],
+    raw_request_bodies: Mapping[str, Any],
+    context: ParsingContext,
+) -> List[IROperation]:
+    """Iterate paths to build IROperation list.
+
+    Contracts:
+        Preconditions:
+            - paths is a valid paths object from OpenAPI spec
+            - raw_parameters, raw_responses, raw_request_bodies are component mappings
+            - context is properly initialized with schemas
+        Postconditions:
+            - Returns a list of IROperation objects
+            - All operations have correct path, method, parameters, responses, etc.
+            - All referenced schemas are properly stored in context
+    """
+    assert isinstance(paths, Mapping), "paths must be a Mapping"
+    assert isinstance(raw_parameters, Mapping), "raw_parameters must be a Mapping"
+    assert isinstance(raw_responses, Mapping), "raw_responses must be a Mapping"
+    assert isinstance(raw_request_bodies, Mapping), "raw_request_bodies must be a Mapping"
+    assert isinstance(context, ParsingContext), "context must be a ParsingContext"
+
+    ops: List[IROperation] = []
+
+    for path, item in paths.items():
+        if not isinstance(item, Mapping):
+            continue
+        entry = cast(Mapping[str, Any], item)
+
+        base_params_nodes = cast(List[Mapping[str, Any]], entry.get("parameters", []))
+
+        for method, on in entry.items():
+            try:
+                if method in {
+                    "parameters",
+                    "summary",
+                    "description",
+                    "servers",
+                    "$ref",
+                }:
+                    continue
+                mu = method.upper()
+                if mu not in HTTPMethod.__members__:
+                    continue
+
+                node_op = cast(Mapping[str, Any], on)
+
+                # Get operation_id for this specific operation
+                if "operationId" in node_op:
+                    operation_id = node_op["operationId"]
+                else:
+                    operation_id = NameSanitizer.sanitize_method_name(f"{mu}_{path}".strip("/"))
+
+                # Parse base parameters (path-level) with operation_id context
+                base_params: List[IRParameter] = []
+                for p_node_data_raw in base_params_nodes:
+                    resolved_p_node_data = resolve_parameter_node_if_ref(p_node_data_raw, context)
+                    base_params.append(
+                        parse_parameter(resolved_p_node_data, context, operation_id_for_promo=operation_id)
+                    )
+
+                # Parse operation-specific parameters
+                params: List[IRParameter] = list(base_params)  # Start with copies of path-level params
+                for p_param_node_raw in cast(List[Mapping[str, Any]], node_op.get("parameters", [])):
+                    resolved_p_param_node = resolve_parameter_node_if_ref(p_param_node_raw, context)
+                    params.append(parse_parameter(resolved_p_param_node, context, operation_id_for_promo=operation_id))
+
+                # Parse request body
+                rb: Optional[IRRequestBody] = None
+                if "requestBody" in node_op:
+                    rb = parse_request_body(
+                        cast(Mapping[str, Any], node_op["requestBody"]),
+                        raw_request_bodies,
+                        context,
+                        operation_id,
+                    )
+
+                # Parse responses
+                resps: List[IRResponse] = []
+                for sc, rn_node in cast(Mapping[str, Any], node_op.get("responses", {})).items():
+                    if (
+                        isinstance(rn_node, Mapping)
+                        and "$ref" in rn_node
+                        and isinstance(rn_node.get("$ref"), str)
+                        and rn_node["$ref"].startswith("#/components/responses/")
+                    ):
+                        ref_name = rn_node["$ref"].split("/")[-1]
+                        resp_node_resolved = raw_responses.get(ref_name, {}) or rn_node
+                    elif (
+                        isinstance(rn_node, Mapping)
+                        and "$ref" in rn_node
+                        and isinstance(rn_node.get("$ref"), str)
+                        and rn_node["$ref"].startswith("#/components/schemas/")
+                    ):
+                        # Handle direct schema references in responses
+                        # Convert schema reference to a response with content
+                        resp_node_resolved = {
+                            "description": f"Response with {rn_node['$ref'].split('/')[-1]} schema",
+                            "content": {"application/json": {"schema": {"$ref": rn_node["$ref"]}}},
+                        }
+                    else:
+                        resp_node_resolved = rn_node
+                    resps.append(parse_response(sc, resp_node_resolved, context, operation_id_for_promo=operation_id))
+
+                op = IROperation(
+                    operation_id=operation_id,
+                    method=HTTPMethod[mu],
+                    path=path,
+                    summary=node_op.get("summary"),
+                    description=node_op.get("description"),
+                    parameters=params,
+                    request_body=rb,
+                    responses=resps,
+                    tags=list(node_op.get("tags", [])),
+                )
+            except Exception as e:
+                warnings.warn(
+                    f"Skipping operation parsing for {method.upper()} {path}: {e}",
+                    UserWarning,
+                )
+                continue
+            else:
+                # Post-process the parsed operation to fill in schema names
+                post_process_operation(op, context)
+                ops.append(op)
+
+    # Post-condition check
+    assert all(isinstance(op, IROperation) for op in ops), "All items must be IROperation objects"
+
+    return ops