This pull request adds support for handling and prevention of ratelimits.

• [x] Delaying requests on hitting 429s
• [x] Global ratelimit handling
• [x] Delay requests when a ratelimit bucket is exhausted.
• [x] Use X-Ratelimit-Bucket (ratelimit key, as referred in code) for precise handling of ratelimits between routes that share same ratelimit.
• [x] ~~Add hooks for ratelimits.~~
• [x] Extensive testing.

The current problem is that in order to perform simple HTTP operations, the instance of relevant Discord model is required. When the model is obtainable from cache, there are no problems but when the model isn't available in cache, It leads to issues of making more than one API call in order to fetch the resource and perform the wanted operation on it.

For example to edit a message that is not in cache, the current solution is:

message = await channel.fetch_message(123) # first API call
await message.edit(**kwargs) # second API call

This has an impact on bots who don't have specific intents enabled and in larger bots, this can impact ratelimits of the bot.

For this purpose, there should be "raw" HTTP methods that allow you to make direct API calls to specific endpoints without fetching the relevant resource first. Taking the same example as above, The raw HTTP methods would allow the message editing in a single API call:

await client.rest.edit_message(channel_id=123, **kwargs)

Preferred Solution

The current preferred solution is to expose the existing "internal" RESTClient class to the users. However as it is right now, it takes raw payloads for JSON body and returns raw response. We would have to refactor this class to be more user friendly in order to implement this feature.

This pull request reworks the library documentation to be more easy to navigate and consistent.

Following major changes have been made so far to the documentation and more are currently in progress:

• Restructure the API reference into multiple sections.
• Adds a "Getting Started" page on the documentation that currently mimics the GitHub readme but would contain a detailed intro to getting started with library and Discord bots in general.
• Adds a better and detailed explanation to various features of the library that were left improperly documented.
• Fixes position of various functions and classes in the API reference.
• Moves contribution guidelines to documentation for ease of maintaining

Feedback would be appreciated.

https://github.com/nerdguyahmad/qord/blob/c8398b25773c0ea7b2ea1a1696079dad2834434b/qord/core/rest.py#L55-L56

If you check the above piece of code, you can clearly see that it raises a TypeError error if the session is an instance of aiohttp.ClientSession

Suggested change:

Change line 55 to this:

    if session and not isinstance(session, aiohttp.ClientSession):

During the MESSAGE_UPDATE event, the message data gets overwritten and various values get the value of None or invalid default values. According to Discord documentation, This is because Discord often sends partial message data in MESSAGE_UPDATE event. Library should implement a way of only update the data that is sent by Discord rather than overwriting previously cached data.

The library should provide raw event properties in the event object for the events sent over gateway.

The purpose of this is to allow events to be somewhat independent of client's cache. This will be a workaround for the issue of missing the events that need certain entity to be cached, the most important example is message events that require message instance to be cached by the client.

This feature is a breaking change in the sense that if your bot is missing some gateway intents, some events may dispatch with incomplete data. This would be case for many *_UPDATE and *_DELETE events. In an example of MESSAGE_UPDATE event:

@client.event(GatewayEvent.MESSAGE_UPDATE)
async def on_message_update(event):
  # event.message can be None if message is not cached but 
  # message_id is always present.

  if event.message is None:
    message = await event.channel.fetch_message(event.message_id)
  else:
    message = event.message

  ...

The possibility of encountering an event with incomplete data is high for events like MESSAGE_UPDATE, MESSAGE_DELETE and other events that are dependent on an entity that is often not cached like messages. Whereas for events like GUILD_UPDATE, CHANNEL_CREATE and other events that are dependent on a "persistent" cache will almost never have incomplete data. The documentation would also be updated to properly reflect all possible edge cases related to events in simpler wording.

This design is not yet finalized and there may be more changes.

Currently, In order to modify the behaviour of cache, the only possible way is to write a custom cache handler implementation. However for users who are relying on default cache, this would be an overkill. This is why, A "cache settings" feature should be added that allows you to define specific common options for caching like message cache limit, private channels etc.

A simple concept:

cache_settings = qord.CacheSettings(
  message_limit=...,
  private_channel_limit=...,
)
client = qord.Client(cache_settings=cache_settings)

These settings would be handled and checked by the library internally when caching entities and wouldn't require custom implementations to implement a logic for them.

Options:

These are current options in mind that would be able to be customised.

• message_limit: Number of messages to cache at a time.
• private_channel_limit: Number of private channels to cache at a time.
• cache_message_users: Whether to cache user entities from message creates until the message is cached.

Feedback on what options should be added would be appreciated.