Skip to content

http_client

Centralized HTTP client service for Tux bot.

This module provides a shared httpx.AsyncClient instance with connection pooling, proper timeout configuration, and error handling for all HTTP requests across the bot.

Lifecycle Management

The HTTP client follows a singleton pattern with lazy initialization:

  1. Initialization: Module-level http_client instance is created on import
  2. Connection: AsyncClient is created on first use (lazy initialization)
  3. Reuse: All subsequent requests use the same pooled client
  4. Cleanup: Bot calls http_client.close() during shutdown
Usage Examples

from tux.services.http_client import http_client

GET request

response = await http_client.get("https://api.example.com/data") data = response.json()

POST request with JSON

response = await http_client.post("https://api.example.com/submit", json={"key": "value"})

Custom timeout

response = await http_client.get("https://slow-api.example.com", timeout=60.0)

Configuration

The client is pre-configured with: - Connection pooling (max 100 connections, 20 keepalive) - HTTP/2 support enabled - Automatic redirect following - Custom User-Agent header with bot version - Timeout settings (10s connect, 30s read, 10s write, 5s pool)

Thread Safety

The client uses an asyncio.Lock for thread-safe lazy initialization. Multiple coroutines can safely call methods concurrently.

Classes:

  • HTTPClient –

    Centralized HTTP client service with connection pooling and proper configuration.

Classes

HTTPClient

Python
HTTPClient()

Centralized HTTP client service with connection pooling and proper configuration.

This class manages a shared httpx.AsyncClient instance with lazy initialization, ensuring efficient connection reuse across all bot HTTP operations.

Attributes:

  • _client (AsyncClient | None) –

    The underlying HTTP client instance (None until first use)

  • _lock (Lock) –

    Thread-safe initialization lock

Notes

Use the module-level http_client singleton instead of creating instances directly.

Initialize the HTTP client service.

The actual httpx.AsyncClient is not created until first use, following lazy initialization pattern for efficiency.

Methods:

  • get_client –

    Get or create the HTTP client instance.

  • close –

    Close the HTTP client and cleanup resources.

  • get –

    Make a GET request.

  • post –

    Make a POST request.

  • put –

    Make a PUT request.

  • delete –

    Make a DELETE request.

  • request –

    Make a request with the specified HTTP method.

Functions

get_client async
Python
get_client() -> AsyncClient

Get or create the HTTP client instance.

Uses double-checked locking pattern for thread-safe lazy initialization. The client is created once on first call and reused for all subsequent requests.

Returns:

  • AsyncClient –

    The configured HTTP client instance with connection pooling.

Notes

This method is automatically called by all request methods (get, post, etc.). You typically don't need to call this directly.

_create_client
Python
_create_client() -> AsyncClient

Create a new HTTP client with optimal configuration.

Configuration includes: - Connection pooling (100 max connections, 20 keepalive) - HTTP/2 support for performance - Automatic redirect following - Custom User-Agent with bot version - Comprehensive timeout settings

Returns:

  • AsyncClient –

    Configured HTTP client instance ready for use.

close async
Python
close() -> None

Close the HTTP client and cleanup resources.

This method should be called during bot shutdown to properly close all connections and release resources.

Notes

Called automatically by the bot's shutdown process in bot._close_connections(). After calling close(), the client will be recreated on next use (lazy init).

get async
Python
get(url: str, **kwargs: Any) -> Response

Make a GET request.

Parameters:

  • url (str) –

    The URL to request.

  • **kwargs (Any, default: {} ) –

    Additional arguments passed to httpx.AsyncClient.get() (e.g., params, headers, timeout, etc.)

Returns:

  • Response –

    The HTTP response.

Examples:

Python Console Session
>>> response = await http_client.get("https://api.github.com/repos/allthingslinux/tux")
>>> data = response.json()
post async
Python
post(url: str, **kwargs: Any) -> Response

Make a POST request.

Parameters:

  • url (str) –

    The URL to request.

  • **kwargs (Any, default: {} ) –

    Additional arguments passed to httpx.AsyncClient.post() (e.g., json, data, headers, timeout, etc.)

Returns:

  • Response –

    The HTTP response.

Examples:

Python Console Session
>>> response = await http_client.post("https://api.example.com/submit", json={"message": "hello"})
put async
Python
put(url: str, **kwargs: Any) -> Response

Make a PUT request.

Parameters:

  • url (str) –

    The URL to request.

  • **kwargs (Any, default: {} ) –

    Additional arguments passed to httpx.AsyncClient.put()

Returns:

  • Response –

    The HTTP response.

delete async
Python
delete(url: str, **kwargs: Any) -> Response

Make a DELETE request.

Parameters:

  • url (str) –

    The URL to request.

  • **kwargs (Any, default: {} ) –

    Additional arguments passed to httpx.AsyncClient.delete()

Returns:

  • Response –

    The HTTP response.

request async
Python
request(method: str, url: str, **kwargs: Any) -> Response

Make a request with the specified HTTP method.

Parameters:

  • method (str) –

    The HTTP method to use (GET, POST, PUT, DELETE, PATCH, etc.).

  • url (str) –

    The URL to request.

  • **kwargs (Any, default: {} ) –

    Additional arguments passed to httpx.AsyncClient.request()

Returns:

  • Response –

    The HTTP response.

Examples:

Python Console Session
>>> response = await http_client.request("PATCH", "https://api.example.com/update")

Functions