Welcome to Shitcord’s documentation!

Shitcord is a feature-rich, easy to use Discord API Library which is built on top of trio. However, you can either use it with an async/await syntax or completely without.

Introduction

Thanks for your interest in this project! Shitcord is a library that aids with creating applications that utilize the Discord API. Let’s have a look at a small introduction to the library.

Prerequisites

Shitcord works with Python 3.5.2+. Support for lower versions isn’t supported due to a dependency (asks) that doesn’t support any Python versions lower than Python 3.5.2.

Shitcord’s dependencies

At this point, we want to say thanks to the developers of a few awesome libraries that Shitcord requires to work.

trio

Once upon a time, people thought that asyncio is total bullshit. Then they attempted to create a better asynchronous I/O framework without all the mistakes asyncio made. And trio is the result. It’s a great concurrency framework and is the core of Shitcord. Definitely check it out here.

asks

asks is an awesome but messy HTTP library that was built to be similar to the requests library. It is used for performing HTTP requests to the Discord REST API and parsing the responses. Check it out here.

trio-websocket

trio-websocket is a library that implements the WebSocket protocol handling I/O using trio. It is used for connecting and interacting with the Discord Gateway. it is a great library striving for safety, correctness and ergonomics and is based on wsproto. Check out the project here.

Installation

As this library is still WIP, it isn’t published on PyPI yet. So you can install the most recent version from GitHub:

# Windows:
py -3 -m pip install -U git+https://github.com/itsVale/Shitcord@async#egg=shitcord

# Linux & macOS:
python3 -m pip install -U git+https://github.com/itsVale/Shitcord@async#egg=shitcord

This is the preferred way of installing Shitcord. If you want to use other installation methods, please don’t expect support for the installation of this library.

Warning

If you’re using Python 3.6+ on macOS, please make sure to run the Install certificates.command located in the Python folder inside your Applications directory. This is important, because Python 3.6+ comes with its own bundled version of OpenSSL because Apple only provides deprecated binaries. Without this step, you’re most likely getting an SSLError whenever you try to run your bot.

Basic Usage

As the following documentation is incomplete and the library due to WIP may be changed dramatically at any time, we don’t provide a usage example yet. Also, it is not very user-friendly yet, so better stay patient unless you are willing to read the source code.

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()

Support

If you need help with this library or have a question about how its usage, you could either create an issue on GitHub or, and this is the most preferred way, you join the official support server.

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:

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.

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.

Event Reference

Coming soon!

API Reference

A full documentation of Shitcord’s public API.

Note

Shitcord is still a WIP, so don’t expect too much. And also, some of the models might be incomplete or just haven’t been documented yet. If you find such a case in the source code, feel free to create a pull request that adds documentation as it is really appreciated.

Version Info

There are two main ways to retrieve the version of Shitcord.

shitcord.version_info

A named tuple similar to sys.version_info.

Just like in sys.version_info, the valid values for releaselevel are ‘alpha’, ‘beta’, ‘candidate’ and ‘final’.

shitcord.__version__

A string representation of the version, e.g. '0.0.2-beta0'.

Shitcord comes with an intuitive client that combines Gateway and REST API functionality in a simple, easy to use interface.

ClientConfig

Client

HTTP

Shitcord’s HTTP interface that is used for making requests to the REST API, parsing responses and handling rate limits is documented in the following. There might be cases where you want to make your own requests instead of using the library’s interface. E.g. when new API endpoints were published that aren’t implemented yet. Or cases where you need a raw response. The full HTTP interface is documented in the following. However, don’t use this if you aren’t 100% sure you know what you are doing! The implemented interface is way more user-friendly and safe to use.

CooldownBucket

Limiter

HTTP

API

Gateway

Discord uses gateways for real-time communication with clients over WebSocket connections. These will be documented in the following. There are two gateway implementations, one for voice and the other for regular data like event dispatches.

Shitcord has a full implementation of the Discord Gateway which basically represents the core of Shitcord’s internal logic.

JSONEncoder

ETFEncoder

WebSocketClient

DiscordWebSocketClient

Models

Shitcord’s models either are implementations of objects that the Discord API uses, or helpers that make it easier to interact with some concepts of the API.

Don’t create objects of them manually. There is always a way to retrieve them from Shitcord.

Snowflake

PartialChannel

TextChannel

DMChannel

VoiceChannel

GroupDMChannel

CategoryChannel

Colour

Embed

EmbedThumbnail

EmbedVideo

EmbedImage

EmbedProvider

EmbedAuthor

EmbedFooter

EmbedField

Emoji

PartialEmoji

Activity

ActivityType

Presence

StatusType

Guild

PartialGuild

Invite

Member

Message

Permissions

Role

User

VoiceRegion

VoiceState

Webhook

Utils

Shitcord uses a couple of utils that are helpers for the API implementation. But some of them might also be useful for developers using this library as they might want to add functionality or use existing utils like the event emitter for their own project. These utils are fully documented in the following section.

EventEmitter

Exceptions

The following exceptions are thrown by Shitcord.

ShitRequestFailed

This exception receives its own section because this one is a bit different from the others. Errors like

shitcord.http.errors.ShitRequestFailed: Your shit ('GET', '/users/01234') failed with code 10013 (HTTP code 404): Unknown User

are quite special. They look a bit cryptic, but they are easy to understand.

First of all, you need to know that Shitcord only raises one error for any HTTP request failure: ShitRequestFailed. And because of that, this one contains all necessary information.

They contain a JSON code and an HTTP response code as well as the bucket the request was made to. The bucket represents the endpoint of the Discord API + the used HTTP method. The JSON and the HTTP code can be looked up here.

This is the recommended way to look up the codes you received for you to know why the request failed.

Indices and tables

• Index
• Module Index
• Search Page