Pincer Core Module

Dispatching

GatewayDispatch

Attributes

• data
• event_name
• op
• seq

Methods

• clsGatewayDispatch.from_string

class GatewayDispatch

Bases: object

Represents a websocket message.

op

The discord opcode which represents what the message means.

Type

int

data

The event data that has been sent/received.

Type

Optional[Union[int, Dict[str, Any]]]

seq

The sequence number of a message, which can be used for resuming sessions and heartbeats.

Type

Optional[int]

event_name

The event name for the payload.

Type

Optional[str]

classmethod from_string(payload)

Parses a given payload from a string format and returns a GatewayDispatch.

Parameters

payload (str) – The payload to parse.

Returns

The new class.

Return type

GatewayDispatch

Gateway

Gateway

Methods

• defappend_handlers
• asyncevent_loop
• asynchandle_data
• asynchandle_heartbeat
• asynchandle_heartbeat_req
• asynchandle_invalid_session
• asynchandle_reconnect
• asyncidentify_and_handle_hello
• asyncinit_session
• asyncsend
• defsend_next_heartbeat
• defset_session_id
• defstart_heartbeat
• asyncstart_loop

class Gateway

Bases: object

The Gateway handles all interactions with the Discord Websocket API. This also contains the main event loop, and handles the heartbeat.

Running the Gateway will create a connection with the Discord Websocket API on behalf of the provided token.

This token must be a bot token. (Which can be found on https://discord.com/developers/applications/)

Parameters

• token (str.) – The token for this bot

• intents (Intents) – The intents to use. More information can be found at https://discord.com/developers/docs/topics/gateway#gateway-intents.

• url (str) – The gateway url.

• shard (int) – The ID of the shard to run.

• num_shards (int) – Number used to route traffic to the current. This should usually be the total number of shards that will be run. More information at https://discord.com/developers/docs/topics/gateway#sharding.

append_handlers(handlers)

The Client that uses the handler can append their own methods. The gateway will run those methods when the specified opcode is received.

await event_loop()

This function is a coroutine. Handles receiving messages and decompressing them if needed

await handle_data(data)

This function is a coroutine. Method is run when a payload is received from the gateway. The message is expected to already have been decompressed. Handling the opcode is forked to the background, so they aren’t blocking.

await handle_heartbeat(payload)

This function is a coroutine. Opcode 11 - Heartbeat Track that the heartbeat has been received using shared state (Rustaceans would be very mad)

await handle_heartbeat_req(payload)

This function is a coroutine. Opcode 1 - Instantly send a heartbeat.

await handle_invalid_session(payload)

This function is a coroutine. Opcode 9 - Invalid connection Attempt to relog. This is probably because the session was already invalidated when we tried to reconnect.

await handle_reconnect(payload)

This function is a coroutine. Opcode 7 - Reconnect and resume immediately.

await identify_and_handle_hello(payload)

This function is a coroutine. Opcode 10 - Hello there general kenobi Runs when we connect to the gateway for the first time and every time after. If the client thinks it should reconnect, the opcode 6 resume payload is sent instead of the opcode 2 hello payload. A new session is only started after a reconnect if pcode 9 is received.

Successful reconnects are handled in the resumed middleware.

await init_session()

This function is a coroutine. Crates the ClientSession. ALWAYS run this function right after initializing a Gateway.

await send(payload)

This function is a coroutine. Send a string object to the payload. Most of this method is just logging, the last line is the only one that matters for functionality.

send_next_heartbeat()

It is expected to always be waiting for a heartbeat. By canceling that task, a heartbeat can be sent.

set_session_id(_id)

Session id is private for consistency

start_heartbeat()

Starts the heartbeat if it is not already running.

await start_loop()

This function is a coroutine. Instantiate the dispatcher, this will create a connection to the Discord websocket API on behalf of the client whose token has been passed.

GatewayInfo

class GatewayInfo

Bases: pincer.utils.api_object.APIObject

Gateway info returned from the gateway/bot endpoint

Http

HTTPClient

Attributes

• max_tts
• url

Methods

• asyncclose
• asyncdelete
• asyncget
• asynchead
• asyncoptions
• asyncpatch
• asyncpost
• asyncput

class HTTPClient

Bases: object

Interacts with Discord API through HTTP protocol

Parameters

• object. (Instantiate a new HttpApi) –

• token – Discord API token

• Arguments (Keyword) –

• version – The discord API version. See https://discord.com/developers/docs/reference#api-versioning.

• ttl – Max amount of attempts after error code 5xx

url

f"https://discord.com/api/v{version}" “Base url for all HTTP requests”

Type

str

max_tts

Max amount of attempts after error code 5xx

Type

int

await close()

This function is a coroutine.

Closes the aiohttp session

await delete(route, headers=None)

This function is a coroutine.

Sends a delete request to a Discord REST endpoint.

Parameters

• route (str) – The Discord REST endpoint to send a delete request to.

• headers (Optional[Dict[str, Any]]) – The request headers.

  Default: None

Returns

The response from discord.

Return type

Optional[Dict]

await get(route, params=None)

This function is a coroutine.

Sends a get request to a Discord REST endpoint.

Parameters

• route (str) – The Discord REST endpoint to send a get request to.

• params (Optional[Dict]) – The query parameters to add to the request.

  Default: None

Returns

The response from discord.

Return type

Optional[Dict]

await head(route)

This function is a coroutine.

Sends a head request to a Discord REST endpoint.

Parameters

route (str) – The Discord REST endpoint to send a head request to.

Returns

The response from discord.

Return type

Optional[Dict]

await options(route)

This function is a coroutine.

Sends an options request to a Discord REST endpoint.

Parameters

route (str) – The Discord REST endpoint to send an options request to.

Returns

The response from discord.

Return type

Optional[Dict]

await patch(route, data=None, content_type='application/json', headers=None)

This function is a coroutine.

Sends a patch request to a Discord REST endpoint.

Parameters

• route (str) – The Discord REST endpoint to send a patch request to.

• data (Dict) – The update data for the patch request.

• content_type (str) – Body content type.

  Default: application/json

• headers (Optional[Dict[str, Any]]) – The request headers.

Returns

JSON response from the discord API.

Return type

Optional[Dict]

await post(route, data=None, content_type='application/json', headers=None)

This function is a coroutine.

Sends a post request to a Discord REST endpoint

Parameters

• route (str) – The Discord REST endpoint to send a patch request to.

• data (Dict) – The update data for the patch request.

• content_type (str) – Body content type.

  Default: application/json

• headers (Optional[Dict[str, Any]]) – The request headers.

Returns

JSON response from the discord API.

Return type

Optional[Dict]

await put(route, data=None, content_type='application/json', headers=None)

This function is a coroutine.

Sends a put request to a Discord REST endpoint

Parameters

• route (str) – The Discord REST endpoint to send a patch request to.

• data (Dict) – The update data for the patch request.

• content_type (str) – Body content type.

  Default: application/json

• headers (Optional[Dict[str, Any]]) – The request headers.

Returns

JSON response from the discord API.

Return type

Optional[Dict]

Rate Limiting

Bucket

class Bucket

Bases: object

Represents a rate limit bucket

limit

The number of requests that can be made.

Type

int

remaining

The number of remaining requests that can be made.

Type

int

reset

Epoch time at which rate limit resets.

Type

float

reset_after

Total time in seconds until rate limit resets.

Type

float

time_cached

Time since epoch when this bucket was last saved.

Type

float

RateLimiter

Attributes

• buckets

Methods

• defsave_response_bucket
• asyncwait_until_not_ratelimited

class RateLimiter

Bases: object

Prevents user rate limits .. attribute:: bucket_map

Maps endpoints and methods to a rate limit bucket

type

Dict[Tuple[str, HttpCallable], str]

buckets

Dictionary of buckets

Type

Dict[str, Bucket]

save_response_bucket(endpoint, method, header)

Parameters

• endpoint (str) – The endpoint

• method (HttpCallable) – The method used on the endpoint (E.g. Get, Post, Patch)

• header (aiohttp.typedefs.CIMultiDictProxy) – The headers from the response

await wait_until_not_ratelimited(endpoint, method)

This function is a coroutine. Waits until the response no longer needs to be blocked to prevent a 429 response because of user rate limits.

Parameters

• endpoint (str) – The endpoint

• method (HttpCallable) – The method used on the endpoint (E.g. Get, Post, Patch)