reflectapi-runtime 0.1.0__py3-none-any.whl

reflectapi_runtime/exceptions.py

@@ -0,0 +1,120 @@
+"""Exception hierarchy for ReflectAPI Python clients."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx  # noqa: TC002
+
+from .response import TransportMetadata  # noqa: TC001
+
+
+class ApiError(Exception):
+    """Base class for all API-related errors.
+
+    Always contains transport metadata when available, providing access to
+    status codes, headers, timing, and the raw response.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        metadata: TransportMetadata | None = None,
+        cause: Exception | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.metadata = metadata
+        self.cause = cause
+
+    @property
+    def status_code(self) -> int | None:
+        """HTTP status code if available."""
+        return self.metadata.status_code if self.metadata else None
+
+    def __repr__(self) -> str:
+        parts = [f"message={self.args[0]!r}"]
+        if self.metadata:
+            parts.append(f"status_code={self.metadata.status_code}")
+        if self.cause:
+            parts.append(f"cause={self.cause!r}")
+        return f"{self.__class__.__name__}({', '.join(parts)})"
+
+
+class NetworkError(ApiError):
+    """Network-level errors (connection failures, DNS resolution, etc.)."""
+
+    @classmethod
+    def from_httpx_error(cls, error: httpx.RequestError) -> NetworkError:
+        """Create a NetworkError from an httpx RequestError."""
+        return cls(
+            f"Network error: {error}",
+            cause=error,
+        )
+
+
+class TimeoutError(NetworkError):
+    """Request timeout errors."""
+
+    @classmethod
+    def from_httpx_timeout(cls, error: httpx.TimeoutException) -> TimeoutError:
+        """Create a TimeoutError from an httpx TimeoutException."""
+        return cls(
+            f"Request timed out: {error}",
+            cause=error,
+        )
+
+
+class ApplicationError(ApiError):
+    """Application-level errors (4xx and 5xx HTTP responses).
+
+    These represent errors returned by the API server, as opposed to
+    network or client-side validation errors.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        metadata: TransportMetadata,
+        error_data: Any | None = None,
+    ) -> None:
+        super().__init__(message, metadata=metadata)
+        self.error_data = error_data
+
+    @property
+    def status_code(self) -> int:
+        """Get the HTTP status code from metadata."""
+        return self.metadata.status_code if self.metadata else 0
+
+    @classmethod
+    def from_response(
+        cls,
+        response: httpx.Response,
+        metadata: TransportMetadata,
+        error_data: Any | None = None,
+    ) -> ApplicationError:
+        """Create an ApplicationError from an HTTP response."""
+        message = f"API error {response.status_code}: {response.reason_phrase}"
+        if error_data:
+            message += f" - {error_data}"
+
+        return cls(
+            message,
+            metadata=metadata,
+            error_data=error_data,
+        )
+
+
+class ValidationError(ApiError):
+    """Client-side validation errors (malformed requests, invalid data, etc.)."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        validation_errors: list[Any] | None = None,
+        cause: Exception | None = None,
+    ) -> None:
+        super().__init__(message, cause=cause)
+        self.validation_errors = validation_errors or []

reflectapi_runtime/hypothesis_strategies.py

@@ -0,0 +1,275 @@
+"""Hypothesis strategies for generated Pydantic models.
+
+This module provides utilities to automatically generate Hypothesis strategies
+for ReflectAPI-generated Pydantic models, enabling property-based testing.
+"""
+
+from __future__ import annotations
+
+import datetime
+import uuid
+from typing import Any, Union, get_args, get_origin
+
+try:
+    import hypothesis
+    from hypothesis import strategies as st
+    HAS_HYPOTHESIS = True
+except ImportError:
+    HAS_HYPOTHESIS = False
+
+from pydantic import BaseModel
+
+from .option import ReflectapiOption, Undefined
+
+if HAS_HYPOTHESIS:
+
+    def strategy_for_option(inner_strategy: st.SearchStrategy) -> st.SearchStrategy:
+        """Create a strategy for ReflectapiOption types.
+
+        Args:
+            inner_strategy: Strategy for the inner type T in Option<T>.
+
+        Returns:
+            Strategy that produces ReflectapiOption instances with undefined, None, or values.
+        """
+        return st.one_of(
+            st.just(ReflectapiOption(Undefined)),  # Undefined case
+            st.just(ReflectapiOption(None)),       # None case
+            inner_strategy.map(ReflectapiOption),  # Some(value) case
+        )
+
+
+    def strategy_for_type(type_hint: type) -> st.SearchStrategy:
+        """Generate a Hypothesis strategy for a given type hint.
+
+        This function maps Python types to appropriate Hypothesis strategies,
+        with special handling for ReflectAPI types.
+
+        Args:
+            type_hint: The type to generate a strategy for.
+
+        Returns:
+            Hypothesis strategy for the given type.
+        """
+        # Handle basic types
+        if type_hint is str:
+            return st.text()
+        elif type_hint is int:
+            return st.integers()
+        elif type_hint is float:
+            return st.floats(allow_nan=False, allow_infinity=False)
+        elif type_hint is bool:
+            return st.booleans()
+        elif type_hint is bytes:
+            return st.binary()
+        elif type_hint is datetime.datetime:
+            return st.datetimes()
+        elif type_hint is datetime.date:
+            return st.dates()
+        elif type_hint is uuid.UUID:
+            return st.uuids()
+
+        # Handle ReflectapiOption specifically
+        if hasattr(type_hint, '__origin__') and type_hint.__origin__ is ReflectapiOption:
+            inner_type = get_args(type_hint)[0] if get_args(type_hint) else Any
+            inner_strategy = strategy_for_type(inner_type)
+            return strategy_for_option(inner_strategy)
+
+        # Handle generic types
+        origin = get_origin(type_hint)
+        args = get_args(type_hint)
+
+        if origin is Union:
+            # Handle Optional[T] (Union[T, None]) and other unions
+            if len(args) == 2 and type(None) in args:
+                # Optional type
+                non_none_type = args[0] if args[1] is type(None) else args[1]
+                return st.one_of(st.none(), strategy_for_type(non_none_type))
+            else:
+                # General union
+                return st.one_of(*[strategy_for_type(arg) for arg in args])
+
+        elif origin is list:
+            inner_type = args[0] if args else Any
+            return st.lists(strategy_for_type(inner_type), max_size=10)
+
+        elif origin is dict:
+            key_type = args[0] if len(args) > 0 else str
+            value_type = args[1] if len(args) > 1 else Any
+            return st.dictionaries(
+                strategy_for_type(key_type),
+                strategy_for_type(value_type),
+                max_size=10
+            )
+
+        elif origin is tuple:
+            if args:
+                return st.tuples(*[strategy_for_type(arg) for arg in args])
+            else:
+                return st.tuples()
+
+        # Handle Pydantic models
+        if isinstance(type_hint, type) and issubclass(type_hint, BaseModel):
+            return strategy_for_pydantic_model(type_hint)
+
+        # Fallback for unknown types
+        return st.none()
+
+
+    def strategy_for_pydantic_model(model_class: type[BaseModel]) -> st.SearchStrategy:
+        """Generate a Hypothesis strategy for a Pydantic model.
+
+        This creates a strategy that generates valid instances of the given
+        Pydantic model class, respecting field types and constraints.
+
+        Args:
+            model_class: The Pydantic model class to generate strategies for.
+
+        Returns:
+            Strategy that produces instances of the model class.
+        """
+        field_strategies = {}
+
+        # Handle Pydantic models
+        if hasattr(model_class, 'model_fields'):
+            for field_name, field_info in model_class.model_fields.items():
+                field_type = field_info.annotation
+                field_strategies[field_name] = strategy_for_type(field_type)
+        else:
+            raise ValueError(f"Unsupported Pydantic model: {model_class}. Only Pydantic V2 models are supported.")
+
+        # Create a strategy that builds the model
+        return st.builds(model_class, **field_strategies)
+
+
+    def register_custom_strategy(type_hint: type, strategy: st.SearchStrategy) -> None:
+        """Register a custom strategy for a specific type.
+
+        This allows users to override the default strategy generation
+        for specific types or add support for custom types.
+
+        Args:
+            type_hint: The type to register a strategy for.
+            strategy: The Hypothesis strategy to use for this type.
+        """
+        if not hasattr(register_custom_strategy, '_custom_strategies'):
+            register_custom_strategy._custom_strategies = {}
+        register_custom_strategy._custom_strategies[type_hint] = strategy
+
+
+    def get_custom_strategy(type_hint: type) -> st.SearchStrategy | None:
+        """Get a custom strategy for a type, if registered.
+
+        Args:
+            type_hint: The type to look up.
+
+        Returns:
+            Custom strategy if registered, None otherwise.
+        """
+        if hasattr(register_custom_strategy, '_custom_strategies'):
+            return register_custom_strategy._custom_strategies.get(type_hint)
+        return None
+
+
+    def enhanced_strategy_for_type(type_hint: type) -> st.SearchStrategy:
+        """Enhanced strategy generation with custom strategy support.
+
+        This is the main entry point that checks for custom strategies
+        before falling back to the default generation logic.
+
+        Args:
+            type_hint: The type to generate a strategy for.
+
+        Returns:
+            Hypothesis strategy for the given type.
+        """
+        # Check for custom strategies first
+        custom_strategy = get_custom_strategy(type_hint)
+        if custom_strategy is not None:
+            return custom_strategy
+
+        # Fall back to default logic
+        return strategy_for_type(type_hint)
+
+
+    # Convenience function for common patterns
+    def api_model_strategy(
+        model_class: type[BaseModel],
+        **field_overrides: st.SearchStrategy
+    ) -> st.SearchStrategy:
+        """Create a strategy for an API model with field overrides.
+
+        This is useful when you want to use the default strategy for most fields
+        but customize specific fields for testing scenarios.
+
+        Args:
+            model_class: The Pydantic model class.
+            **field_overrides: Custom strategies for specific fields.
+
+        Returns:
+            Strategy for the model with custom field strategies applied.
+
+        Example:
+            ```python
+            # Override the 'id' field to use positive integers
+            strategy = api_model_strategy(
+                UserModel,
+                id=st.integers(min_value=1),
+                email=st.emails()
+            )
+            ```
+        """
+        field_strategies = {}
+
+        # Get default strategies for all fields
+        if hasattr(model_class, 'model_fields'):
+            # Pydantic models
+            for field_name, field_info in model_class.model_fields.items():
+                if field_name in field_overrides:
+                    field_strategies[field_name] = field_overrides[field_name]
+                else:
+                    field_strategies[field_name] = enhanced_strategy_for_type(field_info.annotation)
+        else:
+            raise ValueError(f"Unsupported Pydantic model: {model_class}. Only Pydantic V2 models are supported.")
+
+        return st.builds(model_class, **field_strategies)
+
+
+else:
+    # Hypothesis not available - provide stub implementations
+
+    def strategy_for_option(inner_strategy):
+        """Stub implementation when Hypothesis is not available."""
+        raise ImportError("Hypothesis is required for strategy generation")
+
+    def strategy_for_type(type_hint):
+        """Stub implementation when Hypothesis is not available."""
+        raise ImportError("Hypothesis is required for strategy generation")
+
+    def strategy_for_pydantic_model(model_class):
+        """Stub implementation when Hypothesis is not available."""
+        raise ImportError("Hypothesis is required for strategy generation")
+
+    def register_custom_strategy(type_hint, strategy):
+        """Stub implementation when Hypothesis is not available."""
+        raise ImportError("Hypothesis is required for strategy generation")
+
+    def enhanced_strategy_for_type(type_hint):
+        """Stub implementation when Hypothesis is not available."""
+        raise ImportError("Hypothesis is required for strategy generation")
+
+    def api_model_strategy(model_class, **field_overrides):
+        """Stub implementation when Hypothesis is not available."""
+        raise ImportError("Hypothesis is required for strategy generation")
+
+
+# Export the main functions
+__all__ = [
+    'HAS_HYPOTHESIS',
+    'strategy_for_option',
+    'strategy_for_type',
+    'strategy_for_pydantic_model',
+    'enhanced_strategy_for_type',
+    'register_custom_strategy',
+    'api_model_strategy',
+]

reflectapi_runtime/middleware.py

@@ -0,0 +1,254 @@
+"""Middleware system for ReflectAPI Python clients."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import random
+from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Callable
+from typing import Union
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+# Type aliases for handlers in the middleware chain
+AsyncNextHandler = Callable[[httpx.Request], Awaitable[httpx.Response]]
+SyncNextHandler = Callable[[httpx.Request], httpx.Response]
+NextHandler = Union[AsyncNextHandler, SyncNextHandler]
+
+
+class AsyncMiddleware(ABC):
+    """Base class for asynchronous client middleware.
+
+    Middleware can intercept and transform requests and responses,
+    enabling cross-cutting concerns like caching, logging, retry logic, etc.
+    """
+
+    @abstractmethod
+    async def handle(
+        self, request: httpx.Request, next_call: AsyncNextHandler
+    ) -> httpx.Response:
+        """Handle a request and return a response.
+
+        Args:
+            request: The HTTP request to process
+            next_call: Async callable to continue the middleware chain
+
+        Returns:
+            The HTTP response (possibly modified)
+        """
+        pass
+
+
+class SyncMiddleware(ABC):
+    """Base class for synchronous client middleware.
+
+    Middleware can intercept and transform requests and responses,
+    enabling cross-cutting concerns like caching, logging, retry logic, etc.
+    """
+
+    @abstractmethod
+    def handle(
+        self, request: httpx.Request, next_call: SyncNextHandler
+    ) -> httpx.Response:
+        """Handle a request and return a response.
+
+        Args:
+            request: The HTTP request to process
+            next_call: Callable to continue the middleware chain
+
+        Returns:
+            The HTTP response (possibly modified)
+        """
+        pass
+
+
+class AsyncLoggingMiddleware(AsyncMiddleware):
+    """Async middleware that logs request and response information."""
+
+    def __init__(self, logger_name: str = "reflectapi.client") -> None:
+        self.logger = logging.getLogger(logger_name)
+
+    async def handle(
+        self, request: httpx.Request, next_call: AsyncNextHandler
+    ) -> httpx.Response:
+        """Log request and response details."""
+        self.logger.debug(
+            "Making request",
+            extra={
+                "method": request.method,
+                "url": str(request.url),
+                "headers": dict(request.headers),
+            },
+        )
+
+        response = await next_call(request)
+
+        self.logger.debug(
+            "Received response",
+            extra={
+                "status_code": response.status_code,
+                "headers": dict(response.headers),
+                "url": str(request.url),
+            },
+        )
+
+        return response
+
+
+class SyncLoggingMiddleware(SyncMiddleware):
+    """Sync middleware that logs request and response information."""
+
+    def __init__(self, logger_name: str = "reflectapi.client") -> None:
+        self.logger = logging.getLogger(logger_name)
+
+    def handle(
+        self, request: httpx.Request, next_call: SyncNextHandler
+    ) -> httpx.Response:
+        """Log request and response details."""
+        self.logger.debug(
+            "Making request",
+            extra={
+                "method": request.method,
+                "url": str(request.url),
+                "headers": dict(request.headers),
+            },
+        )
+
+        response = next_call(request)
+
+        self.logger.debug(
+            "Received response",
+            extra={
+                "status_code": response.status_code,
+                "headers": dict(response.headers),
+                "url": str(request.url),
+            },
+        )
+
+        return response
+
+
+class RetryMiddleware(AsyncMiddleware):
+    """Middleware that retries requests on transient failures with exponential backoff and jitter."""
+
+    # Methods that are safe to retry automatically on network failures
+    IDEMPOTENT_METHODS = frozenset({"GET", "HEAD", "OPTIONS", "PUT", "DELETE", "TRACE"})
+
+    def __init__(
+        self,
+        max_retries: int = 3,
+        retry_status_codes: set[int] | None = None,
+        backoff_factor: float = 0.5,  # Start with a shorter backoff
+    ) -> None:
+        self.max_retries = max_retries
+        self.retry_status_codes = retry_status_codes or {429, 502, 503, 504}
+        self.backoff_factor = backoff_factor
+
+    async def handle(
+        self, request: httpx.Request, next_call: AsyncNextHandler
+    ) -> httpx.Response:
+        """Retry requests on transient failures."""
+        last_exception = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = await next_call(request)
+
+                if attempt == self.max_retries or response.status_code not in self.retry_status_codes:
+                    return response
+
+                # If we are going to retry, store the response as the last exception
+                last_exception = response
+
+            except httpx.RequestError as e:
+                last_exception = e
+                # Do not retry non-idempotent methods on network errors
+                if request.method not in self.IDEMPOTENT_METHODS or attempt == self.max_retries:
+                    raise
+
+            # Backoff with Jitter (AWS-recommended approach)
+            # Cap the backoff at 30 seconds and add jitter for better distribution
+            temp = min(self.backoff_factor * (2 ** attempt), 30.0)  # Cap backoff
+            sleep_duration = temp / 2 + random.uniform(0, temp / 2)
+
+            logger.debug(
+                f"Retrying request to {request.url} after {sleep_duration:.2f}s (attempt {attempt + 1}/{self.max_retries})"
+            )
+            await asyncio.sleep(sleep_duration)
+
+        # This part should be unreachable, but linters might complain.
+        # It's better to re-raise the last known exception.
+        if isinstance(last_exception, httpx.Response):
+            return last_exception
+        raise last_exception from None
+
+
+class AsyncMiddlewareChain:
+    """Manages a chain of async middleware for processing requests."""
+
+    def __init__(self, middleware: list[AsyncMiddleware]) -> None:
+        self.middleware = middleware
+
+    async def execute(
+        self,
+        request: httpx.Request,
+        transport: httpx.AsyncClient,
+    ) -> httpx.Response:
+        """Execute the middleware chain with the given request."""
+
+        async def create_handler(
+            middleware_list: list[AsyncMiddleware], index: int
+        ) -> AsyncNextHandler:
+            """Create a handler for the middleware at the given index."""
+
+            async def handler(req: httpx.Request) -> httpx.Response:
+                if index >= len(middleware_list):
+                    # End of chain - make the actual HTTP request
+                    return await transport.send(req)
+
+                # Process through next middleware
+                next_handler = await create_handler(middleware_list, index + 1)
+                return await middleware_list[index].handle(req, next_handler)
+
+            return handler
+
+        handler = await create_handler(self.middleware, 0)
+        return await handler(request)
+
+
+class SyncMiddlewareChain:
+    """Manages a chain of sync middleware for processing requests."""
+
+    def __init__(self, middleware: list[SyncMiddleware]) -> None:
+        self.middleware = middleware
+
+    def execute(
+        self,
+        request: httpx.Request,
+        transport: httpx.Client,
+    ) -> httpx.Response:
+        """Execute the middleware chain with the given request."""
+
+        def create_handler(
+            middleware_list: list[SyncMiddleware], index: int
+        ) -> SyncNextHandler:
+            """Create a handler for the middleware at the given index."""
+
+            def handler(req: httpx.Request) -> httpx.Response:
+                if index >= len(middleware_list):
+                    # End of chain - make the actual HTTP request
+                    return transport.send(req)
+
+                # Process through next middleware
+                next_handler = create_handler(middleware_list, index + 1)
+                return middleware_list[index].handle(req, next_handler)
+
+            return handler
+
+        handler = create_handler(self.middleware, 0)
+        return handler(request)
+
+