Adding an API function

---

In this contribute section, it will be explain how to add a function to the API.

If you don't know how to make a pull request (Demand to change the code), you may see this explaination.

1

Research

Before you code a new function for Dispy, you need to know exactly how to do it.

In the documentation of discord, you can find every possible API requests, e.g. Request to create a message. You will need theses informations to continue.

2

Amount

In Dispy, your function can be in multiple place, e.g. to create a message:

• bot.create_message() which need all arguments

• message.reply() which need content and a message object

• channel.send() which need content and a channel object

An API function need to be present on types that has the necessary informations and on the bot object.

3

Where

The API function for the bot object are located in dispy.modules.rest_api.py.

For an object (e.g. Message), they are located in dispy.types and the file which contain the definition of the object. If the object doesn't exist, follow this guide.

4

Introduction

If the object doesn't have the _api = None argument, you need to add it at the end of all the type definition. With this you can call the __request__ object.

You need to import these two thing (if they are not already imported):

from dispy.modules.result import result
import asyncio

5

Create the Function

When creating a function, you need to follow some rules to be sure your pull request will be accepted.

• If the API request return something, it need to has a type object (If it doesn't exist, create it using this guide) or put 'None' if nothing is returned

• It need to be asynchronous.

• It need to be using the internal function of Dispy (result & __request__)

• The line using __request__ need to have the comment # no_traceback at the end.

• Your function need to have a description.

• Your function need to return a result object and it need to be set when the request send a response. Use the damn template x).

Template:

def function(self, argument=None, **kwargs) -> result[<Type>]:
    """
    Description
    """
    future = self._api._loop.create_future()
    
    async def _asynchronous():
        payload = {}
        
        # Your code here!
        
        result = await self._api.__request__('<method>', f'<path>', payload) # no_traceback
        future.set_result(result)
    
    asyncio.run_coroutine_threadsafe(_asynchronous(), self._api._loop)
    return result[<Type>](future,self._api,<Type>)

What's to change in the template

1. There is 3 <Type> to replace with the return type object, you can put 'None'.

2. You need to change <method> to the method used in the API request, e.g. Post, patch, delete.

3. And <path>, you replace by the API path given by the Discord documentation.

Some arguments will need to be passed through run_coroutine_threadsafe.

6

Testing

It is important to test your functions before doing a pull request. Please.

And you're done! Time to open a pull request