Low Level API

ACord exposes its lower level API, just in case you need to use it. We also allow you to customise the functionality of the library very easily, so be awair of what your doing. So lets start simple.

Core [HTTP Control]

So lets dive into customising the HTTP side of ACord.

Signals

Signals are files which contain OPCodes and Status Codes. They are used by ACord to monitor and identify changes or issues raised by discord.

For example acord.core.signals.gateway, contains all the stuff ACord may use for tracking states and commands sent by discord. If we receive, OPCode 0, we know is a DISPATCH event. So we will also dispatch the event through to the higher level API.

Now with errors, it works exactly the same way. If the WebSocket closes with 4004, we know that AUTH_FAILED. So we will raise it so the user can correct their mistake.

ABC

The ABC file contains all the bits of information ACord uses to interact with the REST API. You can change the API Version, API Url and so on.

import acord.core.abc as core_abc

core_abc.API_VERSION = 9

# Continue with your code as usually

This file also contains the Route object and buildURL function. They can be used to make routes and URLs for the REST API. Which can then be used by ACord to make requests to that route with the desired method.

Decoders

Nothing special goes on in here, just some helper functions to process gateway messages and HTTP responses.

The decompressResponse helps in decompressing the zlib-compressed message. And, decodeResponse is a higher level function which can decode both string and bytes.

ETF is currently not supported, but will be in future versions.

Tip

You can change these functions by overwriting them like this:

import acord.core.decoders as dec
import json

dec.JSON = json.loads

Heartbeats

Heartbeats are used by ACord to keep WebSocket connections alive. Now this is pretty much useless unless you wanna build your own heartbeater.

Heartbeat ABC Class

class acord.core.heartbeat.KeepAlive(group=None, target=None, name=None, args=(), kwargs=None, *, daemon=None)

Represents a keep alive handler.

Danger

If you are not overwriting KeepAlive.run(), you will need to provide the following attrs.

_ended

Whether heartbeating has ended

Type

bool

_interval

Time to wait between heartbeats, in seconds.

Type

int

abstract ack()

Called when server responds with an ACK to our heartbeat

abstract get_payload()

Gets heartbeat payload

run()

Default .run function, calls KeepAlive.send_heartbeat() every n seconds.

Note

Once ended, .join is called within this function

abstract send_heartbeat()

Sends a heartbeat

Implementations

You will need to use the KeepAlive ABC, which has the following methods you need to provide:

• send_heartbeat(self) -> Sends heartbeat through the WebSocket

• get_payload(self) -> Returns a payload for the heartbeat

• ack(self) -> Called when the WebSocket ACKs our heartbeat

And the following attrs which is used by .run(self) func. You won’t need this if you overwrite this function.

• _ended: bool : Whether the client has stopped heartbeating

• _interval: int : Time in seconds to wait for till next heartbeat

Hint

Take a peak at the default implementations of the heartbeat system, it may or may not help but will surely guide you along the way.

Note

As of version 0.2.3a0, users will need to overwrite the imported class name, in the same way as decoders.

HTTPClient

Now the fun class, this class is responsible for making HTTP Request to the REST API.

Hint

You can already access this through Client.http, or any model which has the conn attr.

HTTPClient Class

class acord.core.http.HTTPClient(client: typing.Any, *, token: typing.Optional[str] = None, connecter: typing.Optional[aiohttp.connector.BaseConnector] = None, loop: asyncio.events.AbstractEventLoop = <_UnixSelectorEventLoop running=False closed=False debug=False>, ratelimiter: acord.core.ratelimiter.HTTPRatelimiter = DefaultHTTPRatelimiter(max_requests=(10000, 600), cache={}, awaiting_requests=[], global_lock=None, locked_until=None, current_requests=0))

Base HTTPClient for interacting with the REST API.

Parameters

• client (Client) – Client class is attached to

• token (str) – Bot token to be used for authorizing requests

• connector (BaseConnector) – Connector be used when creating session

• loop (asyncio.AbstractEventLoop) – Loop to be used

• ratelimiter (HTTPRatelimiter) – A ratelimiter for client to use.

client

Client attached to this HTTPClient

Type

Client

token

Token to be used for making HTTP Requests.

Type

str

connection

A connector class to be used with the session

Type

BaseConnector

ratelimiter

Ratelimiter being used by this HTTPClient

Type

DefaultHTTPRatelimiter

user_agent

Default user agent to be sent with all requests.

Note

This user agent is unique to this class, different HTTPClients may have different user agents.

Type

str

async fetch_gateway() → dict

This function is a coroutine.

Fetches the bot gateway, returns a dict with gateway connection info

async login(*, token: Optional[str] = None, **kwds) → dict

This function is a coroutine.

Creates a session for client to use, returns user data of client on completation

Parameters

• token (str) – Token to overwrite HTTPClient.token, becomes default token if token was not provided previously.

• **kwds –

  Any additional kwargs to be passed through ClientSession.

  Warning

  You may not include connector and loop kwargs.

async logout()

This function is a coroutine.

Logs client out from session

async request(route: acord.core.abc.Route, data: Optional[Union[dict, aiohttp.formdata.FormData, Any]] = None, headers: dict = {}, **kwds) → aiohttp.client_reqrep.ClientResponse

This function is a coroutine.

Sends a request to the desired route.

Parameters

• route (Route) – Route to send request to

• data (Union[dict, FormData, Any]) – Data to be sent with request

• headers (dict) – Headers to send with request

• **kwds – Additional kwargs to be passed through request()

Making Requests

Once you have got your HTTP class, you can do many things. One of which is make requests.

In this example we will simply leave a guild.

Note

We recommend to use Guild.leave().

from acord.core.abc import Route

GUILD_ID = Snowflake(..., )  # Actual guild id here
client = ...    # Your HTTPClient object

async with client as conn:
    async with conn.request(
        Route("DELETE", path=f"/users/@me/guilds/{GUILD_ID}"),
    ) as request:
        if request.status == 204:
            print("Left the guild! :D")

This is an advantage to any user who like having this control, it can also allow you to have access to API Routes before ACord has added them!

Ratelimiters

Ratelimiters will be covered later, which will be available soon.