aoba discord bot documentation
TRANSCRIPT
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 [email protected]: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