Aoba Discord Bot DocumentationRelease 0.1.13

Douglas Carvalho

Aug 16, 2021

Contents:

1 Aoba Discord Bot 11.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.2 Credits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

2 Installation 32.1 Add to your server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32.2 Host instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

3 Usage 53.1 Discord Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53.2 Command-line interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53.3 Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

4 aoba_discord_bot 74.1 aoba_discord_bot package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

5 Contributing 115.1 Types of Contributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115.2 Get Started! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125.3 Pull Request Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135.4 Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135.5 Deploying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

6 History 156.1 0.1.13 (2021-08-15) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

7 Indices and tables 17

Python Module Index 19

Index 21

i

ii

CHAPTER 1

Aoba Discord Bot

Aoba is an open-source Discord bot made with Python, providing admin, osu! and anime functionalities.

Please be aware that until version 1.0.0 is released the bot should not be considered stable. It’s still very early indevelopment and could have bugs that would cause problems to your server.

• Free software: MIT license

• Documentation: https://aoba-discord-bot.readthedocs.io.

1.1 Features

Aoba has the following modules/commands:

• Admin: ban, unban, custom_cmd, kick, prefix, purge

• BotAdmin: announce, servers, shutdown, status

• Osu: beatmaps_backup, score_pp

1

Aoba Discord Bot Documentation, Release 0.1.13

• User: escape_markdown, help

1.2 Credits

This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.

2 Chapter 1. Aoba Discord Bot

CHAPTER 2

Installation

2.1 Add to your server

Click here to add our instance of Aoba to your server.

2.2 Host instance

2.2.1 Stable release

To install Aoba Discord Bot, run this command in your terminal:

$ pip install aoba_discord_bot

This is the preferred method to install Aoba Discord Bot, as it will always install the most recent stable release.

If you don’t have pip installed, this Python installation guide can guide you through the process. The installationrequires Python 3.6, 3.7, 3.8 or 3.9.

2.2.2 From source

The sources for Aoba Discord Bot can be downloaded from the Github repo.

You can either clone the public repository:

$ git clone git://github.com/douglascdev/aoba_discord_bot

Or download the tarball:

$ curl -OJL https://github.com/douglascdev/aoba_discord_bot/tarball/master

Once you have a copy of the source, you can install it with:

3

Aoba Discord Bot Documentation, Release 0.1.13

$ python setup.py install

4 Chapter 2. Installation

CHAPTER 3

Usage

3.1 Discord Commands

The bot’s commands are separated in groups.

• Admin

• Bot Admin

• Osu

• User

3.2 Command-line interface

Running an instance requires you to create a bot account to obtain a token. After following the Installation. you’ll beable to use the command-line interface:

$ aoba_discord_bot --helpUsage: aoba_discord_bot [OPTIONS]

Console script for aoba_discord_bot.

Options:--db TEXT Path for SQLite database file--token TEXT Discord API token--osu_client_id TEXT OAuth client Id for the osu! Cog--osu_client_secret TEXT OAuth client secret for the osu! Cog--help Show this message and exit.

To run an instance, pass the token as an argument to the command-line interface:

$ aoba_discord_bot --token <YOUR_TOKEN>

5

Aoba Discord Bot Documentation, Release 0.1.13

The other arguments are optional.

3.3 Modules

To use Aoba Discord Bot in a project:

import aoba_discord_bot

6 Chapter 3. Usage

CHAPTER 4

aoba_discord_bot

4.1 aoba_discord_bot package

4.1.1 Subpackages

aoba_discord_bot.cogs package

Subpackages

Admin

Submodules

aoba_discord_bot.cogs.admin.admin_cog module

class aoba_discord_bot.cogs.admin.admin_cog.Admin(bot: discord.ext.commands.bot.Bot,db_session:sqlalchemy.orm.session.Session)

Bases: discord.ext.commands.cog.Cog

Category of commands for administrative tasks like managing commands and banning users.

ban = <discord.ext.commands.core.Command object>

custom_cmd = <discord.ext.commands.core.Group object>

del_command = <discord.ext.commands.core.Command object>

kick = <discord.ext.commands.core.Command object>

new_command = <discord.ext.commands.core.Command object>

prefix = <discord.ext.commands.core.Command object>

purge = <discord.ext.commands.core.Command object>

7

Aoba Discord Bot Documentation, Release 0.1.13

unban = <discord.ext.commands.core.Command object>

Module contents

Bot Admin

Submodules

aoba_discord_bot.cogs.bot_admin.bot_admin_cog module

class aoba_discord_bot.cogs.bot_admin.bot_admin_cog.BotAdmin(bot: dis-cord.ext.commands.bot.Bot,db_session:sqlalchemy.orm.session.Session)

Bases: discord.ext.commands.cog.Cog

announce = <discord.ext.commands.core.Command object>

get_guilds = <discord.ext.commands.core.Command object>

shutdown = <discord.ext.commands.core.Command object>

status = <discord.ext.commands.core.Command object>

Module contents

Osu

Submodules

aoba_discord_bot.cogs.osu.osu_api_cog module

class aoba_discord_bot.cogs.osu.osu_api_cog.Osu(client_id: int, client_secret: str)Bases: discord.ext.commands.cog.Cog

API_BASE_URL = 'https://osu.ppy.sh/api/v2/'

API_OAUTH_URL = 'https://osu.ppy.sh/oauth/token'

beatmaps_backup = <discord.ext.commands.core.Command object>

score_pp = <discord.ext.commands.core.Command object>

Module contents

User

Submodules

8 Chapter 4. aoba_discord_bot

Aoba Discord Bot Documentation, Release 0.1.13

aoba_discord_bot.cogs.user.user_cog module

class aoba_discord_bot.cogs.user.user_cog.AobaHelp(**options)Bases: discord.ext.commands.help.DefaultHelpCommand

add_indented_commands(commands, *, heading, max_size=None)Indents a list of commands after the specified heading.

The formatting is added to the paginator.

The default implementation is the command name indented by indent spaces, padded to max_sizefollowed by the command’s Command.short_doc and then shortened to fit into the width.

commands: Sequence[Command] A list of commands to indent for output.

heading: str The heading to add to the output. This is only added if the list of commands is greater than0.

max_size: Optional[int] The max size to use for the gap between indents. If unspecified, callsget_max_size() on the commands parameter.

shorten_text(text)str: Shortens text to fit into the width.

class aoba_discord_bot.cogs.user.user_cog.User(bot: discord.ext.commands.bot.Bot)Bases: discord.ext.commands.cog.Cog

cog_unload()A special method that is called when the cog gets removed.

This function cannot be a coroutine. It must be a regular function.

Subclasses must replace this if they want special unloading behaviour.

escape_markdown = <discord.ext.commands.core.Command object>

Module contents

Module contents

4.1.2 Submodules

4.1.3 aoba_discord_bot.aoba_checks module

aoba_discord_bot.aoba_checks.author_is_admin(ctx: dis-cord.ext.commands.context.Context)→ bool

aoba_discord_bot.aoba_checks.author_is_not_bot(ctx: dis-cord.ext.commands.context.Context) →bool

4.1.4 aoba_discord_bot.bot module

Main module.

class aoba_discord_bot.bot.AobaDiscordBot(aoba_params: dict, **options)Bases: discord.ext.commands.bot.Bot

4.1. aoba_discord_bot package 9

Aoba Discord Bot Documentation, Release 0.1.13

4.1.5 aoba_discord_bot.cli module

Console script for aoba_discord_bot.

4.1.6 aoba_discord_bot.db_models module

class aoba_discord_bot.db_models.AobaCommand(**kwargs)Bases: sqlalchemy.orm.decl_api.Base

Custom commands added by server admins

guild

guild_id

id

name

text

class aoba_discord_bot.db_models.AobaGuild(**kwargs)Bases: sqlalchemy.orm.decl_api.Base

command_prefix

commands

guild_id

4.1.7 aoba_discord_bot.formatting module

aoba_discord_bot.formatting.mention_author(ctx: discord.ext.commands.context.Context)→ str

4.1.8 Module contents

Top-level package for Aoba Discord Bot.

10 Chapter 4. aoba_discord_bot

CHAPTER 5

Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

5.1 Types of Contributions

5.1.1 Report Bugs

Report bugs at https://github.com/douglascdev/aoba_discord_bot/issues.

If you are reporting a bug, please include:

• Your operating system name and version.

• Any details about your local setup that might be helpful in troubleshooting.

• Detailed steps to reproduce the bug.

5.1.2 Fix Bugs

Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wantsto implement it.

5.1.3 Implement Features

Look through the GitHub issues for features. Anything tagged with “enhancement” and “help wanted” is open towhoever wants to implement it.

11

Aoba Discord Bot Documentation, Release 0.1.13

5.1.4 Write Documentation

Aoba Discord Bot could always use more documentation, whether as part of the official Aoba Discord Bot docs, indocstrings, or even on the web in blog posts, articles, and such.

5.1.5 Submit Feedback

The best way to send feedback is to file an issue at https://github.com/douglascdev/aoba_discord_bot/issues.

If you are proposing a feature:

• Explain in detail how it would work.

• Keep the scope as narrow as possible, to make it easier to implement.

• Remember that this is a volunteer-driven project, and that contributions are welcome :)

5.2 Get Started!

Ready to contribute? Here’s how to set up aoba_discord_bot for local development.

1. Fork the aoba_discord_bot repo on GitHub.

2. Clone your fork locally:

$ git clone git@github.com:your_name_here/aoba_discord_bot.git

3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set upyour fork for local development:

$ mkvirtualenv aoba_discord_bot$ cd aoba_discord_bot/$ python setup.py develop

4. Create a branch for local development:

$ git checkout -b name-of-your-bugfix-or-feature

Now you can make your changes locally.

5. When you’re done making changes, check that your changes pass flake8 and the tests, including testing otherPython versions with tox:

$ flake8 aoba_discord_bot tests$ python setup.py test or pytest$ tox

To get flake8 and tox, just pip install them into your virtualenv.

6. Commit your changes and push your branch to GitHub:

$ git add .$ git commit -m "Your detailed description of your changes."$ git push origin name-of-your-bugfix-or-feature

7. Submit a pull request through the GitHub website.

12 Chapter 5. Contributing

Aoba Discord Bot Documentation, Release 0.1.13

5.3 Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

1. The pull request should include tests.

2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a functionwith a docstring, and add the feature to the list in README.rst.

3. The pull request should work for Python 3.5, 3.6, 3.7 and 3.8, and for PyPy. Check https://travis-ci.com/douglascdev/aoba_discord_bot/pull_requests and make sure that the tests pass for all supported Python versions.

5.4 Tips

To run a subset of tests:

$ pytest tests.test_aoba_discord_bot

5.5 Deploying

A reminder for the maintainers on how to deploy. Make sure all your changes are committed (including an entry inHISTORY.rst). Then run:

$ bump2version patch # possible: major / minor / patch$ git push$ git push --tags

Travis will then deploy to PyPI if tests pass.

5.3. Pull Request Guidelines 13

Aoba Discord Bot Documentation, Release 0.1.13

14 Chapter 5. Contributing

CHAPTER 6

History

6.1 0.1.13 (2021-08-15)

• Release on PyPI.

15

Aoba Discord Bot Documentation, Release 0.1.13

16 Chapter 6. History

CHAPTER 7

Indices and tables

• genindex

• modindex

• search

17

Aoba Discord Bot Documentation, Release 0.1.13

18 Chapter 7. Indices and tables

Python Module Index

aaoba_discord_bot, 10aoba_discord_bot.aoba_checks, 9aoba_discord_bot.bot, 9aoba_discord_bot.cli, 10aoba_discord_bot.cogs, 9aoba_discord_bot.cogs.admin, 8aoba_discord_bot.cogs.admin.admin_cog,

7aoba_discord_bot.cogs.bot_admin, 8aoba_discord_bot.cogs.bot_admin.bot_admin_cog,

8aoba_discord_bot.cogs.osu, 8aoba_discord_bot.cogs.osu.osu_api_cog,

8aoba_discord_bot.cogs.user, 9aoba_discord_bot.cogs.user.user_cog, 9aoba_discord_bot.db_models, 10aoba_discord_bot.formatting, 10

19

Aoba Discord Bot Documentation, Release 0.1.13

20 Python Module Index

Index

Aadd_indented_commands()

(aoba_discord_bot.cogs.user.user_cog.AobaHelpmethod), 9

Admin (class in aoba_discord_bot.cogs.admin.admin_cog),7

announce (aoba_discord_bot.cogs.bot_admin.bot_admin_cog.BotAdminattribute), 8

aoba_discord_bot (module), 10aoba_discord_bot.aoba_checks (module), 9aoba_discord_bot.bot (module), 9aoba_discord_bot.cli (module), 10aoba_discord_bot.cogs (module), 9aoba_discord_bot.cogs.admin (module), 8aoba_discord_bot.cogs.admin.admin_cog

(module), 7aoba_discord_bot.cogs.bot_admin (module),

8aoba_discord_bot.cogs.bot_admin.bot_admin_cog

(module), 8aoba_discord_bot.cogs.osu (module), 8aoba_discord_bot.cogs.osu.osu_api_cog

(module), 8aoba_discord_bot.cogs.user (module), 9aoba_discord_bot.cogs.user.user_cog

(module), 9aoba_discord_bot.db_models (module), 10aoba_discord_bot.formatting (module), 10AobaCommand (class in aoba_discord_bot.db_models),

10AobaDiscordBot (class in aoba_discord_bot.bot), 9AobaGuild (class in aoba_discord_bot.db_models), 10AobaHelp (class in aoba_discord_bot.cogs.user.user_cog),

9API_BASE_URL (aoba_discord_bot.cogs.osu.osu_api_cog.Osu

attribute), 8API_OAUTH_URL (aoba_discord_bot.cogs.osu.osu_api_cog.Osu

attribute), 8author_is_admin() (in module

aoba_discord_bot.aoba_checks), 9author_is_not_bot() (in module

aoba_discord_bot.aoba_checks), 9

Bban (aoba_discord_bot.cogs.admin.admin_cog.Admin

attribute), 7beatmaps_backup (aoba_discord_bot.cogs.osu.osu_api_cog.Osu

attribute), 8BotAdmin (class in aoba_discord_bot.cogs.bot_admin.bot_admin_cog),

8

Ccog_unload() (aoba_discord_bot.cogs.user.user_cog.User

method), 9command_prefix (aoba_discord_bot.db_models.AobaGuild

attribute), 10commands (aoba_discord_bot.db_models.AobaGuild

attribute), 10custom_cmd (aoba_discord_bot.cogs.admin.admin_cog.Admin

attribute), 7

Ddel_command (aoba_discord_bot.cogs.admin.admin_cog.Admin

attribute), 7

Eescape_markdown (aoba_discord_bot.cogs.user.user_cog.User

attribute), 9

Gget_guilds (aoba_discord_bot.cogs.bot_admin.bot_admin_cog.BotAdmin

attribute), 8guild (aoba_discord_bot.db_models.AobaCommand

attribute), 10guild_id (aoba_discord_bot.db_models.AobaCommand

attribute), 10guild_id (aoba_discord_bot.db_models.AobaGuild

attribute), 10

21

Aoba Discord Bot Documentation, Release 0.1.13

Iid (aoba_discord_bot.db_models.AobaCommand

attribute), 10

Kkick (aoba_discord_bot.cogs.admin.admin_cog.Admin

attribute), 7

Mmention_author() (in module

aoba_discord_bot.formatting), 10

Nname (aoba_discord_bot.db_models.AobaCommand at-

tribute), 10new_command (aoba_discord_bot.cogs.admin.admin_cog.Admin

attribute), 7

OOsu (class in aoba_discord_bot.cogs.osu.osu_api_cog),

8

Pprefix (aoba_discord_bot.cogs.admin.admin_cog.Admin

attribute), 7purge (aoba_discord_bot.cogs.admin.admin_cog.Admin

attribute), 7

Sscore_pp (aoba_discord_bot.cogs.osu.osu_api_cog.Osu

attribute), 8shorten_text() (aoba_discord_bot.cogs.user.user_cog.AobaHelp

method), 9shutdown (aoba_discord_bot.cogs.bot_admin.bot_admin_cog.BotAdmin

attribute), 8status (aoba_discord_bot.cogs.bot_admin.bot_admin_cog.BotAdmin

attribute), 8

Ttext (aoba_discord_bot.db_models.AobaCommand at-

tribute), 10

Uunban (aoba_discord_bot.cogs.admin.admin_cog.Admin

attribute), 8User (class in aoba_discord_bot.cogs.user.user_cog), 9

22 Index