Skip to content

HTTP

Internal API

These classes are for internal use only.

Users should interact with Client and other public API classes instead.

HTTPClient

Handles all HTTP communication with Discord's API including rate-limiting by bucket and globally, async request handling, multipart/form-data file uploads, and error handling/retries.

token = token instance-attribute

The bot's token.

_logger = logger instance-attribute

Logger instance to log events.

session: aiohttp.ClientSession = None instance-attribute

Client session instance.

global_reset = 0 instance-attribute

Global rete limit cooldown if a global rate limit is active.

global_lock: asyncio.Lock = None instance-attribute

Lock on queues to avoid race conditions.

pending_queue: asyncio.Queue = None instance-attribute

Queue for requests not yet assigned to bucket.

pending_worker: asyncio.Task = None instance-attribute

Task processing for the pending queue.

endpoint_to_bucket: dict[str, str] = {} instance-attribute

Maps endpoints to rate-limit buckets

bucket_queues: dict[str, RouteQueue] = {} instance-attribute

Maps endpoints to RouteQueue objects.

_sentinel = object() instance-attribute

Sentinel to terminate session.

base_url = 'https://discord.com/api/v10' instance-attribute

Base URL for discord's API requests.

start_session async

Initializes aiohttp session, queues, locks, and starting pending worker.

request async

Enqueues request WRT rate-limit buckets.

Parameters:

  • method (str) –

    HTTP method (e.g., POST, GET, DELETE, PATCH, etc.)

  • endpoint (str) –

    Discord endpoint (e.g., /channels/123/messages)

  • data (dict, default: None ) –

    relevant data

  • files (list[str], default: None ) –

    relevant files

Returns:

  • Future –

    future with response

_pending_worker async

Processes requests from global pending queue.

_route_worker async

Processes request from specific rate-limit bucket.

Parameters:

  • bucket (str) –

    endpoint

_process_request async

Core request execution. Handles headers, payload, files, retries, and bucket assignment.

Parameters:

Raises:

_handle_response async

Resolves future with parsed JSON/text response.

Parameters:

  • item (RequestItem) –

    request data to handle

  • resp (ClientResponse) –

    response for item

_check_global_limit async

Waits if the global rate-limit is in effect.

close_session async

Gracefully shuts down all workes and closes aiohttp session.

RouteQueue

Represents a queue of requests for a single rate-limit bucket. Manages task worker that processes requests for that bucket.

queue = asyncio.Queue() instance-attribute

Queue holding RequestItem for this bucket.

worker = None instance-attribute

Process for executing request for this bucket.

RequestItem dataclass

Data container representing an HTTP request to Discord's API. Used internally by HTTPClient for queuing and processing requests.

method: str instance-attribute

HTTP method (e.g., GET, POST, DELETE, PUT, PATCH)

url: str instance-attribute

Fully qualifying URL for this request.

endpoint: str instance-attribute

Endpoint of the URL for this request.

data: dict | None instance-attribute

Relevant data for this request.

files: list | None instance-attribute

Relevant files for this request.

future: asyncio.Future instance-attribute

Track the result of this request.