Get Started

This page provides a short tutorial about the necessary features of this library and introduces the most important aspects to you. Let’s get started!

Let’s start with a quick example on how to use this library:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import shitcord

client = shitcord.Client(SomeConfig())


@client.on('message')
async def on_message(message):
    if 'owo' in str(message).lower():
        await message.respond("What's This?")


client.start()

In the following we will introduce some concepts of the library that will be very useful for you.

Blocking

Let’s say you want to implement some feature that requires a special lib. And this library doesn’t support async/await syntax. This would cause your bot to block.

In asynchronous programming a blocking call is essentially any line that are not await`ed. When a line blocks, it stops the entire rest of the bot from functioning, including commands and even functions that keep the bot alive. Ideally speaking, blocking affects performance and even stability of your bot. A common example for blocking is the usage of ``time.sleep()` instead of await trio.sleep().

But don’t worry. I’ve got something nice for you. It is called trio.run_sync_in_worker_thread!

Let’s have a look at an image processing example with PIL to get a closer understanding of this method.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
import shitcord

import meme
import trio
from PIL import Image

client = shitcord.Client(SomeConfig())


# In most cases, blocking doesn't even affect you.
# But for processes that are computationally expensive or heavy such as PIL
# should be executed using run_sync_in_worker_thread to avoid blocking.
# However, don't excessively use this for small shit.
def my_blocking_stuff():
    with Image.open("my_image.jpg") as image:
        deepfried_image = meme.deepfry(image)
        deepfried_image.save("my_meme.png")

    return 'Finished.'


@client.on('message')
async def on_message(message):
    if str(message).startswith('!wot'):
        # Demonstrating the power of run_sync_in_worker_thread
        result = await trio.run_sync_in_worker_thread(my_blocking_stuff)
        await message.respond(result)  # Sends 'Finished.'


client.start()

shitcord.sync

Note

shitcord.sync is experimental and may cause unexpected issues.

There might be cases where you want to use Shitcord without depending on async/await syntax. For this case, we’ve got your back with shitcord.sync.

This module wraps all classes of this library so you can use them entirely without async/await. All you have to do is quite simple:

import shitcord.sync as sync

...

Warning

It is recommended to not mix up import shitcord and import shitcord.sync as shitcord in your bot. It is preferred to stick with one of them in your entire bot.

The RESTShit Interface

Let me introduce you to RESTShit! This is our way of performing requests to the Discord REST API. Ideally speaking, this is a terminal between what should be done and how it should be done.