Configuration¶

OxideHTTP uses OxideHTTPConfig to configure the HTTP client. Configuration is divided into smaller dataclasses, allowing you to customize connection handling, security, requests, compression, and logging independently.

All configuration sections have sensible defaults, so you only need to specify the options you want to change.

Basic Configuration¶

Create an OxideHTTPConfig instance and pass it to OxideHTTP:

from datetime import timedelta

from oxidehttp import OxideHTTP
from oxidehttp.config import ConnectionConfig, OxideHTTPConfig, RequestConfig

config = OxideHTTPConfig(
    base_url='https://api.example.com',
    connection=ConnectionConfig(
        timeout=timedelta(seconds=15), max_connections=100
    ),
    request=RequestConfig(user_agent='MyApplication/1.0'),
)

async with OxideHTTP(config) as client:
    response = await client.get('/users')

Configuration objects are frozen and use slots. Configure them when creating the client rather than modifying their attributes afterward.

OxideHTTPConfig¶

The top-level configuration object.

Option	Type	Default	Description
`base_url`	`str \\| None`	`None`	Base URL used by the client.
`headers`	`Headers \\| None`	`None`	Default headers applied to requests.
`connection`	`ConnectionConfig`	`ConnectionConfig()`	Connection and runtime settings.
`security`	`SecurityConfig`	`SecurityConfig()`	Security settings.
`request`	`RequestConfig`	`RequestConfig()`	Request defaults and middleware.
`compression`	`CompressionConfig`	`CompressionConfig()`	Supported response compression formats.
`logging`	`LoggingConfig`	`LoggingConfig()`	Client logging settings.

Base URL¶

Set base_url when requests share the same API origin:

config = OxideHTTPConfig(base_url='https://api.example.com/v1')

You can then use relative paths when making requests:

async with OxideHTTP(config) as client:
    response = await client.get('/users')

Default Headers¶

Use headers to configure headers shared by requests:

config = OxideHTTPConfig(
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Accept': 'application/json',
    }
)

Request-specific headers can also be supplied when calling an HTTP method.

ConnectionConfig¶

Controls connection-related settings and runtime behavior.

Option	Type	Default	Description
`timeout`	`timedelta \\| None`	`None`	Connection/request timeout setting.
`max_connections`	`int \\| None`	`None`	Maximum number of connections.
`runtime_multithreaded`	`bool`	`True`	Enables the multithreaded runtime.
`proxies`	`Mapping[ProxyType, str]`	`{}`	Proxy URLs mapped to their proxy types.

When provided, timeout and max_connections must be greater than zero.

Timeout¶

Use timedelta to specify the timeout:

from datetime import timedelta

from oxidehttp.config import ConnectionConfig

connection = ConnectionConfig(timeout=timedelta(seconds=10))

Leaving the timeout as None uses the underlying client's default behavior.

Maximum Connections¶

Limit the number of connections:

connection = ConnectionConfig(max_connections=100)

The default of None leaves the connection limit to the underlying client.

Runtime¶

The multithreaded runtime is enabled by default:

connection = ConnectionConfig(runtime_multithreaded=True)

Set it to False to disable the multithreaded runtime:

connection = ConnectionConfig(runtime_multithreaded=False)

Proxies¶

Configure proxies using a mapping of ProxyType values to proxy URLs:

from oxidehttp.config import ConnectionConfig

connection = ConnectionConfig(
    proxies={
        # Add the proxy types and URLs required by your application.
    }
)

Refer to the ProxyType API reference for the supported proxy types.

SecurityConfig¶

Controls TLS certificate verification.

Option	Type	Default	Description
`verify_ssl`	`bool`	`True`	Enables SSL certificate verification.

Certificate verification is enabled by default:

from oxidehttp.config import SecurityConfig

security = SecurityConfig(verify_ssl=True)

You can disable verification when working with a development server or a controlled environment:

security = SecurityConfig(verify_ssl=False)

Warning: Disabling certificate verification makes HTTPS connections vulnerable to man-in-the-middle attacks. Do not disable it in production.

RequestConfig¶

Controls default request behavior.

Option	Type	Default	Description
`user_agent`	`str \\| None`	`DEFAULT_USER_AGENT`	Default User-Agent value.
`middlewares`	`Sequence[Middleware]`	`()`	Middleware applied to requests.

User-Agent¶

OxideHTTP uses its package version in the default User-Agent:

oxidehttp/<version>

Override it when integrating with an API that expects a custom User-Agent:

from oxidehttp.config import RequestConfig

request = RequestConfig(user_agent='MyApplication/1.0')

Set it to None if you do not want to configure a default User-Agent:

request = RequestConfig(user_agent=None)

Default Middleware¶

Middleware can be configured globally:

from oxidehttp.config import RequestConfig

request = RequestConfig(
    middlewares=(
        # Middleware instances
    )
)

You can also supply middleware for an individual request. See Middleware for details.

CompressionConfig¶

Controls which response compression formats are enabled.

All supported formats are enabled by default.

Option	Type	Default	Description
`gzip`	`bool`	`True`	Enables gzip compression.
`brotli`	`bool`	`True`	Enables Brotli compression.
`zstd`	`bool`	`True`	Enables Zstandard compression.
`deflate`	`bool`	`True`	Enables deflate compression.

For example, disable Brotli and Zstandard:

from oxidehttp.config import CompressionConfig

compression = CompressionConfig(
    gzip=True, brotli=False, zstd=False, deflate=True
)

LoggingConfig¶

Controls logging produced by the client.

Logging is disabled by default.

Option	Type	Default	Description
`enabled`	`bool`	`False`	Enables client logging.
`logger`	`Logger \\| None`	`None`	Logger instance used by the client.
`log_requests`	`bool`	`True`	Enables request logging.
`log_streams`	`bool`	`True`	Enables stream logging.
`log_sse_reconnects`	`bool`	`True`	Enables SSE reconnection logging.

Enable Logging¶

Enable logging with the default logger behavior:

from oxidehttp.config import LoggingConfig

logging = LoggingConfig(enabled=True)

Custom Logger¶

Provide your own logger instance:

from loguru import logger

from oxidehttp.config import LoggingConfig

logging = LoggingConfig(enabled=True, logger=logger)

Select Logged Events¶

You can independently control which events are logged:

logging = LoggingConfig(
    enabled=True, log_requests=True, log_streams=False, log_sse_reconnects=True
)

The individual event options default to True, but have no effect while logging is disabled.

Complete Example¶

The following example combines the available configuration sections:

from datetime import timedelta

from loguru import logger

from oxidehttp import OxideHTTP
from oxidehttp.config import (
    CompressionConfig,
    ConnectionConfig,
    LoggingConfig,
    OxideHTTPConfig,
    RequestConfig,
    SecurityConfig,
)

config = OxideHTTPConfig(
    base_url='https://api.example.com/v1',
    headers={'Accept': 'application/json'},
    connection=ConnectionConfig(
        timeout=timedelta(seconds=15),
        max_connections=100,
        runtime_multithreaded=True,
    ),
    security=SecurityConfig(verify_ssl=True),
    request=RequestConfig(user_agent='MyApplication/1.0'),
    compression=CompressionConfig(
        gzip=True, brotli=True, zstd=True, deflate=True
    ),
    logging=LoggingConfig(
        enabled=True,
        logger=logger,
        log_requests=True,
        log_streams=True,
        log_sse_reconnects=True,
    ),
)

async with OxideHTTP(config) as client:
    response = await client.get('/users')
    print(response.status_code)