pyUSPTO.http_config — pyUSPTO 0.2.3.dev1+g2c5d89b38.d20251125 documentation

# Source code for pyUSPTO.http_config

    """
    http_config - HTTP client configuration for USPTO API requests

    This module provides configuration for HTTP transport-level settings including
    timeouts, retries, connection pooling, and custom headers.
    """

    import os
    from dataclasses import dataclass, field
    from typing import Dict, List, Optional

    @dataclass
    class HTTPConfig:
        """HTTP client configuration for request handling.

        This class separates transport-level HTTP concerns from API-level
        configuration, allowing fine-grained control over request behavior.

        Attributes:
            timeout: Read timeout in seconds for requests (default: 30.0)
            connect_timeout: Connection establishment timeout in seconds (default: 10.0)
            max_retries: Maximum number of retry attempts (default: 3)
            backoff_factor: Exponential backoff multiplier for retries (default: 1.0)
            retry_status_codes: HTTP status codes that trigger retries
            pool_connections: Number of connection pools to cache (default: 10)
            pool_maxsize: Maximum number of connections per pool (default: 10)
            custom_headers: Additional headers to include in all requests
        """

        # Timeout configuration
        timeout: Optional[float] = 30.0
        connect_timeout: Optional[float] = 10.0

        # Retry configuration
        max_retries: int = 3
        backoff_factor: float = 1.0
        retry_status_codes: List[int] = field(
            default_factory=lambda: [429, 500, 502, 503, 504]
        )

        # Connection pooling
        pool_connections: int = 10
        pool_maxsize: int = 10

        # Custom headers (User-Agent, tracking, etc.)
        custom_headers: Optional[Dict[str, str]] = None

        @classmethod
        def from_env(cls) -> "HTTPConfig":
            """Create HTTPConfig from environment variables.

            Environment variables:
                USPTO_REQUEST_TIMEOUT: Request timeout in seconds
                USPTO_CONNECT_TIMEOUT: Connection timeout in seconds
                USPTO_MAX_RETRIES: Maximum retry attempts
                USPTO_BACKOFF_FACTOR: Retry backoff factor
                USPTO_POOL_CONNECTIONS: Connection pool size
                USPTO_POOL_MAXSIZE: Max connections per pool

            Returns:
                HTTPConfig instance with values from environment or defaults
            """
            return cls(
                timeout=float(os.environ.get("USPTO_REQUEST_TIMEOUT", "30.0")),
                connect_timeout=float(os.environ.get("USPTO_CONNECT_TIMEOUT", "10.0")),
                max_retries=int(os.environ.get("USPTO_MAX_RETRIES", "3")),
                backoff_factor=float(os.environ.get("USPTO_BACKOFF_FACTOR", "1.0")),
                pool_connections=int(os.environ.get("USPTO_POOL_CONNECTIONS", "10")),
                pool_maxsize=int(os.environ.get("USPTO_POOL_MAXSIZE", "10")),
            )

        def get_timeout_tuple(self) -> tuple[Optional[float], Optional[float]]:
            """Get timeout as tuple for requests library.

            Returns:
                Tuple of (connect_timeout, read_timeout) for requests
            """
            return (self.connect_timeout, self.timeout)