Internals API Reference#

Warning

This is probably not what you are looking for! This is for the internals of Nextcord and for people who want to write custom implementations of some of our modules

class nextcord.core.http.Bucket(route)#

A simple and fast ratelimiting implementation for HTTP

Warning

This is not multiprocess safe.

Note

This is a async context manager.

Parameters:

route (Route) –

limit: int | None#

How many requests fit in a bucket

property remaining: int | None#

How many requests are remaining.

reset_at: float | None#

When the Bucket fills up again. (UTC time)

class nextcord.core.http.HTTPClient(state, *, max_retries=5)#

A http client to interact with the Discord REST API.

Parameters:

  • state (State) – The current state of the bot

  • max_retries (int) – How many times we will attempt to retry after a unexpected failure (server error or ratelimit issue)

async close()#

Close the client. This should clean up all resources the HTTPClient has created. Should only be called once.

Return type:

None

async get_gateway_bot()#

Gets gateway url and connection information

Note

Documentation

Return type:

ClientResponse

async request(route, *, headers=None, **kwargs)#

Send a request to discord. This automatically handles ratelimits.

New in version 3.0.

Parameters:

  • route (RouteProtocol) – Metadata about the route you are executing

  • headers (Optional[dict[str, str]]) – Request headers. This will add a bot token if availible

  • kwargs (Any) – Keyword only arguments passed to ClientSession.request

Return type:

ClientResponse

async ws_connect(url)#

Connect to a websocket!

Note

Aiohttp has a default timeout, we recommend disabling this as its already handled by GatewayProtocol

Parameters:

url (str) – The URL of the websocket to connect to

Return type:

ClientWebSocketResponse

class nextcord.core.http.Route(method, path, *, use_webhook_global=False, **parameters)#

Metadata about a Discord API route

Parameters:

  • method (str) – The HTTP method for this route

  • path (str) – The API path

  • use_webhook_global (bool) – If this route uses the webhook global LINK MISSING

  • parameters (Any) – Parameters to format path with. You can include guild_id, channel_id, webhook_id or webhook_token to specify ratelimit parameters.

property bucket: str#

The ratelimit bucket this is under

method: str#

The HTTP method for this route

path: str#

The route to be requested from discord

unformatted_path#

The unformatted path

use_webhook_global: bool#

If this route uses the webhook global LINK MISSING

class nextcord.core.gateway.Gateway(state, shard_count=None)#

A fast and simple GatewayProtocol implementation

Parameters:

  • state (State) – The current state of the bot

  • shard_count (Optional[int]) – The current shard count. If this is not None it is expected for it to error instead of changing shard count

async close()#

Close all connections and cleanup. This should only be called once

Return type:

None

async connect()#

Connect to the gateway

Return type:

None

event_dispatcher: Dispatcher#

A dispatcher for events dispatched through the dispatch opcode. This will be dispatched by ShardProtocol

get_identify_ratelimiter(shard_id)#

Get the ratelimiter the shard should use while connecting

Parameters:

shard_id (int) – The shard id of the connecting shard.

Return type:

TimesPer

raw_dispatcher: Dispatcher#

A dispatcher from raw shard data. This will be dispatched by ShardProtocol

shard_count: int | None#

The current shard count

shards: list[ShardProtocol]#

The currently active shards

should_reconnect(shard)#

Called on ShardProtocol disconnect to check if it should auto reconnect. This is used for scaling up shards to stop the old ones from connecting and wasting identifies.

Parameters:

shard (ShardProtocol) – The shard asking if it should reconnect

Return type:

bool

class nextcord.core.gateway.Shard(state, shard_id)#
Parameters:

  • state (State) –

  • shard_id (int) –

async close(code=1000)#

Closes the connection to the gateway

Note

This should only be run once

Parameters:

code (int) – Which code to send to discord when closing. A non 1000 code will allow you to resume later.

Return type:

None

async connect()#

Connect to the gateway

Note

This is allowed to run forever

Return type:

None

event_dispatcher: Dispatcher#

A dispatcher that gets all events dispatched via the dispatch opcode from the gateway. This should only dispatch the data

opcode_dispatcher: Dispatcher#

A dispatcher that will dispatched everything that the gateway sends us.

ready: Event#

A event set when the shard has identified or resumed

async send(data)#

Send a raw message directly to the gateway. Generally this should not be used externally as gateway version might differ.

Parameters:

data (dict[str, Any]) – The raw data to send

Return type:

None

shard_id: int#

The shards ID. This is provided by GatewayProtocol.

Protocols#

class nextcord.core.protocols.http.BucketProtocol(*args, **kwargs)#

Ratelimiting for HTTP!

You have to implement a async with context manager that waits when it runs out. Limit remaining and reset_at will be automatically set by HTTPClient.

Note

Ratelimiting should be implemented as specified

Parameters:

route (RouteProtocol) – The route this is for

limit: int | None#

How many requests a bucket holds

remaining: int | None#

How many is remaining.

reset_at: float | None#

When the bucket resets

class nextcord.core.protocols.http.HTTPClientProtocol(*args, **kwargs)#

A http client to interact with the Discord REST API. This should handle ratelimits.

state: State

A bot state

token: Optional[str]

The bot token if present.

async close()#

Close the client. This should clean up all resources the HTTPClient has created. Should only be called once.

Return type:

None

async get_gateway_bot()#

Gets gateway url and connection information

Note

Documentation

Return type:

ClientResponse

async request(route, **kwargs)#

Send a HTTP request to the discord API

This should use TypeSheet.http_bucket to ratelimit.

route: RouteProtocol

The metadata for this API route

kwargs:

Keyword only arguments passed to ClientSession.request

Parameters:
Return type:

ClientResponse

async ws_connect(url)#

Connect to a websocket!

Note

Aiohttp has a default timeout, we recommend disabling this as its already handled by GatewayProtocol

Parameters:

url (str) – The URL of the websocket to connect to

Return type:

ClientWebSocketResponse

class nextcord.core.protocols.http.RouteProtocol(*args, **kwargs)#

Metadata about a Discord API route

Parameters:

  • method (str) – The HTTP method for this route

  • path (str) – The API path

  • use_webhook_global (bool) – If this route uses the webhook global LINK MISSING

  • parameters – Parameters to format path with. You can include guild_id, channel_id, webhook_id or webhook_token to specify ratelimit parameters.

bucket: str#

The ratelimit bucket this is under

method: str#

The HTTP method

path: str#

The route to be requested from discord

use_webhook_global: bool#

If this route uses the webhook global LINK MISSING

class nextcord.core.gateway.protocols.GatewayProtocol(*args, **kwargs)#

The connector the gateway and shard manager. You are responsible for scaling up/down shards and distributing requests (such as member chunking)

Note

Documentation can be found here

Parameters:

  • state (State) – The current state of the bot

  • shard_count (Optional[int]) – The current shard count. If this is not None it is expected for it to error instead of changing shard count

async close()#

Close all connections and cleanup. This should only be called once

Return type:

None

async connect()#

Connect to the gateway.

Return type:

None

event_dispatcher: Dispatcher#

A dispatcher for events dispatched through the dispatch opcode. This will be dispatched by ShardProtocol

get_identify_ratelimiter(shard_id)#

Get the ratelimiter the shard should use while connecting

Parameters:

shard_id (int) – The shard id of the connecting shard.

Return type:

TimesPer

raw_dispatcher: Dispatcher#

A dispatcher from raw shard data. This will be dispatched by ShardProtocol

async send(data, *, shard_id=0)#

Sends a raw message to the gateway. Generally this should not be used often as gateway version might differ.

Parameters:

  • data (dict[str, Any]) – The raw data to send to discord

  • shard_id (int) – Which shard id to send on. This defaults to shard 0

Return type:

None

shard_count: int | None#

The active shard count. None if not set yet.

should_reconnect(shard)#

Called on ShardProtocol disconnect to check if it should auto reconnect. This can be used for stopping shards reconnecting temporarily while you are rescaling or similar

Parameters:

shard (ShardProtocol) – The shard asking if it should reconnect

Return type:

bool

class nextcord.core.gateway.protocols.ShardProtocol(*args, **kwargs)#

A gateway shard spawned by GatewayProtocol

Parameters:

  • state (State) – The current bot state

  • shard_id (int) – The shard_id you provide to discord in the identify payload when connecting.

async close()#

Closes the connection to the gateway

Note

This should only be run once

Parameters:

code (int) – Which code to send to discord when closing. A non 1000 code will allow you to resume later.

Return type:

None

async connect()#

Connect to the gateway

Note

This is allowed to run forever

Return type:

None

event_dispatcher: Dispatcher#

A dispatcher that gets all events dispatched via the dispatch opcode from the gateway. This should only dispatch the data

opcode_dispatcher: Dispatcher#

A dispatcher that will dispatched everything that the gateway sends us.

ready: Event#

A event set when the shard has identified or resumed

async send(data)#

Send a raw message directly to the gateway. Generally this should not be used externally as gateway version might differ.

Parameters:

data (dict[str, Any]) – The raw data to send

Return type:

None

shard_id: int#

The shards ID. This is provided by GatewayProtocol.