tessl/pypi-http3

A next generation HTTP client for Python 3 with HTTP/2 support, async/await capabilities, and requests-compatible API.

—

Pending

Overview

Eval results

Files

Configuration

Name: tessl/pypi-http3
Author: tessl

Flexible configuration classes for customizing HTTP3 client behavior including timeouts, SSL settings, connection pool limits, and other operational parameters. These configuration objects provide fine-grained control over client behavior and can be used with both synchronous and asynchronous clients.

Capabilities

Timeout Configuration

Controls various timeout aspects of HTTP requests and connections.

class TimeoutConfig:
    def __init__(self, timeout=None, *, connect_timeout=None, read_timeout=None, write_timeout=None):
        """
        Configure timeouts for HTTP operations.

        Parameters:
        - timeout (float or TimeoutConfig, optional): Overall timeout for all operations
        - connect_timeout (float, optional): Timeout for connection establishment
        - read_timeout (float, optional): Timeout for reading response data
        - write_timeout (float, optional): Timeout for sending request data

        Note: If timeout is provided, individual timeout parameters are ignored.
        """

    @property
    def connect_timeout(self) -> float:
        """Timeout for connection establishment in seconds."""

    @property
    def read_timeout(self) -> float:
        """Timeout for reading response data in seconds."""

    @property
    def write_timeout(self) -> float:
        """Timeout for sending request data in seconds."""

Usage Example:

import http3

# Simple timeout (applies to all operations)
timeout = http3.TimeoutConfig(timeout=30.0)

# Granular timeout control
timeout = http3.TimeoutConfig(
    connect_timeout=5.0,   # 5 seconds to establish connection
    read_timeout=30.0,     # 30 seconds to read response
    write_timeout=10.0     # 10 seconds to send request
)

# Use with client
client = http3.Client(timeout=timeout)

# Or use tuple shorthand for (connect, read, write)
client = http3.Client(timeout=(5.0, 30.0, 10.0))

SSL Configuration

Manages SSL/TLS settings for secure connections.

class SSLConfig:
    def __init__(self, *, cert=None, verify=True):
        """
        Configure SSL/TLS settings.

        Parameters:
        - cert (CertTypes, optional): Client certificate for mutual TLS
        - verify (VerifyTypes): SSL certificate verification setting
        """

    @property
    def cert(self) -> CertTypes:
        """Client certificate configuration."""

    @property
    def verify(self) -> VerifyTypes:
        """SSL verification setting."""

    def with_overrides(self, cert=None, verify=None):
        """
        Create a new SSLConfig with modified settings.

        Parameters:
        - cert (CertTypes, optional): Override certificate setting
        - verify (VerifyTypes, optional): Override verification setting

        Returns:
        SSLConfig: New configuration instance
        """

    async def load_ssl_context(self):
        """
        Load and return the SSL context for this configuration.

        Returns:
        ssl.SSLContext: Configured SSL context
        """

Usage Example:

import http3

# Default SSL (verify certificates)
ssl_config = http3.SSLConfig()

# Disable SSL verification (not recommended for production)
ssl_config = http3.SSLConfig(verify=False)

# Custom CA bundle
ssl_config = http3.SSLConfig(verify='/path/to/ca-bundle.crt')

# Client certificate authentication
ssl_config = http3.SSLConfig(
    cert='/path/to/client-cert.pem',
    verify=True
)

# Client certificate with separate key file
ssl_config = http3.SSLConfig(
    cert=('/path/to/cert.pem', '/path/to/key.pem'),
    verify=True
)

# Use with client
client = http3.Client(verify=ssl_config.verify, cert=ssl_config.cert)

Connection Pool Limits

Controls connection pooling behavior for optimal resource usage and performance.

class PoolLimits:
    def __init__(self, *, soft_limit=None, hard_limit=None, pool_timeout=None):
        """
        Configure connection pool limits.

        Parameters:
        - soft_limit (int, optional): Preferred maximum connections per host
        - hard_limit (int, optional): Absolute maximum connections per host
        - pool_timeout (float, optional): Timeout waiting for connection from pool
        """

    @property
    def soft_limit(self) -> int:
        """Preferred maximum connections per host."""

    @property
    def hard_limit(self) -> int:
        """Absolute maximum connections per host."""

    @property
    def pool_timeout(self) -> float:
        """Timeout in seconds for acquiring connection from pool."""

Usage Example:

import http3

# Default pool limits
pool_limits = http3.PoolLimits()

# Custom pool configuration
pool_limits = http3.PoolLimits(
    soft_limit=10,      # Prefer max 10 connections per host
    hard_limit=50,      # Never exceed 50 connections per host
    pool_timeout=5.0    # Wait max 5 seconds for available connection
)

# Use with client
client = http3.Client(pool_limits=pool_limits)

Default Configuration Values

HTTP3 provides sensible defaults for all configuration options:

# Default timeout configuration
DEFAULT_TIMEOUT_CONFIG = TimeoutConfig(timeout=5.0)

# Default SSL configuration
DEFAULT_SSL_CONFIG = SSLConfig(cert=None, verify=True)

# Default pool limits
DEFAULT_POOL_LIMITS = PoolLimits(soft_limit=10, hard_limit=100, pool_timeout=5.0)

# Default maximum redirects
DEFAULT_MAX_REDIRECTS = 20

# Default CA bundle path
DEFAULT_CA_BUNDLE_PATH: str  # Path to system CA bundle

# Default user agent string
USER_AGENT: str  # "python-http3/0.6.7"

Type Aliases

Configuration-related type aliases for flexible input handling:

# Certificate types
CertTypes = Union[str, Tuple[str, str]]

# SSL verification types
VerifyTypes = Union[str, bool]

# Timeout types
TimeoutTypes = Union[float, Tuple[float, float, float], TimeoutConfig]

Advanced Configuration

Custom Cipher Configuration

HTTP3 uses secure cipher suites by default:

DEFAULT_CIPHERS: str  # Secure cipher suite string

Protocol Configuration

class Protocol(str, Enum):
    HTTP_11 = "HTTP/1.1"
    HTTP_2 = "HTTP/2"

Concurrency Backend

Configure the async backend for HTTP3:

class AsyncioBackend:
    """Default asyncio-based concurrency backend."""
    
    async def connect(self, hostname, port, ssl_context, timeout):
        """Establish connection to host."""
    
    def get_semaphore(self, limits):
        """Get semaphore for connection limiting."""
    
    async def run_in_threadpool(self, func, *args, **kwargs):
        """Run function in thread pool."""

Usage Examples

Complete Client Configuration

import http3

# Comprehensive client configuration
client = http3.Client(
    # Authentication
    auth=('username', 'password'),
    
    # SSL settings
    verify=True,
    cert=('/path/to/cert.pem', '/path/to/key.pem'),
    
    # Timeout configuration
    timeout=http3.TimeoutConfig(
        connect_timeout=5.0,
        read_timeout=30.0,
        write_timeout=10.0
    ),
    
    # Connection pool limits
    pool_limits=http3.PoolLimits(
        soft_limit=20,
        hard_limit=100,
        pool_timeout=5.0
    ),
    
    # Redirect behavior
    max_redirects=10,
    
    # Base URL for relative requests
    base_url='https://api.example.com/v1',
    
    # Default cookies
    cookies={'session': 'abc123'}
)

Environment-Based Configuration

import os
import http3

# Configuration from environment variables
def create_client():
    timeout = float(os.getenv('HTTP_TIMEOUT', '30.0'))
    verify_ssl = os.getenv('VERIFY_SSL', 'true').lower() == 'true'
    ca_bundle = os.getenv('CA_BUNDLE_PATH')
    
    return http3.Client(
        timeout=timeout,
        verify=ca_bundle if ca_bundle else verify_ssl,
        pool_limits=http3.PoolLimits(
            soft_limit=int(os.getenv('POOL_SOFT_LIMIT', '10')),
            hard_limit=int(os.getenv('POOL_HARD_LIMIT', '100'))
        )
    )

client = create_client()

Configuration Validation

import http3

def validate_config():
    try:
        # Test SSL configuration
        ssl_config = http3.SSLConfig(verify=True)
        ssl_context = await ssl_config.load_ssl_context()
        
        # Test timeout configuration
        timeout = http3.TimeoutConfig(
            connect_timeout=5.0,
            read_timeout=30.0,
            write_timeout=10.0
        )
        
        # Create client with validation
        client = http3.Client(
            timeout=timeout,
            verify=ssl_config.verify,
            pool_limits=http3.PoolLimits(soft_limit=10, hard_limit=50)
        )
        
        return client
        
    except Exception as e:
        print(f"Configuration error: {e}")
        return None

Install with Tessl CLI