Welcome to BoticordPy’s documentation!

This is a documentation for simple python module to work with the boticord api.

Quickstart

Installation

Enter one of these commands to install the library:

pip install boticordpy

python3 -m pip install boticordpy

Or just clone the repo: https://github.com/grey-cat-1908/boticordpy

Examples

Without Using Cogs System

Post bot stats when bot is ready.

from discord.ext import commands

from boticordpy import BoticordClient

bot = commands.Bot(command_prefix="!")
boticord = BoticordClient(bot, "your-boticord-token")


@bot.event
async def on_ready():
    stats = {"servers": len(bot.guilds), "shards": bot.shard_count, "users": len(bot.users)}
    await boticord.Bots.postStats(stats)


bot.run("your-bot-token")

Using Cogs System

Cog with automatically stats post (every 15 minutes) + bot’s owner command that can be used to post stats.

from discord.ext import commands

from boticordpy import BoticordClient


class BoticordCog(commands.Cog):
    def __init__(self, bot):
        self.bot = bot
        self.boticord = BoticordClient(self.bot, "your-boticord-token")
        self.boticord.start_loop()

    @commands.command(name="boticord-update")
    @commands.is_owner()
    async def boticord_update(self, ctx):
        """
            This commands can be used by owner to post stats to boticord
        """
        stats = {"servers": len(self.bot.guilds), "shards": 0, "users": len(self.bot.users)}
        await self.boticord.Bots.postStats(stats)


def setup(bot):
    bot.add_cog(BoticordCog(bot))

Main

This class is used to make it much easier to use the Boticord API.

BoticordClient

class boticordpy.BoticordClient(bot, token=None, **kwargs)

This class is used to make it much easier to use the Boticord API.

Parameters

bot (commands.Bot | commands.AutoShardedBot) – The discord.py Bot instance
token (str) – boticord api key

Bots

modules.bots.Bots with all arguments filled.

Type: modules.bots.Bots

Servers

modules.servers.Servers with all arguments filled.

Type: modules.servers.Servers

Users

modules.users.Users with all arguments filled.

Type: modules.users.Users

event(event_name: str)

A decorator that registers an event to listen to. You can find all the events on Event Reference page.

:param event_name str: boticord event name

start_loop(sleep_time: Optional[int] = None) → None

Can be used to post stats automatically.

Parameters: sleep_time (int) – stats posting interval - can be not specified or None (default interval - 15 minutes)

Modules

This page describes all the modules of boticordpy.

Bots

class boticordpy.modules.Bots(bot, **kwargs)

Class with methods to work with Boticord API Bots.

Parameters: bot (commands.Bot | commands.AutoShardedBot) – The discord.py Bot instance

async getBotComments(botID: int)

Returns comments of the discord bot with the given ID.

Parameters: botID (int) – Discord Bot’s ID

async getBotInfo(botID: int)

Returns information about discord bot with the given ID.

Parameters: botID (int) – Discord Bot’s ID

async postStats(stats: dict)

Post stats to Boticord API.

Parameters: stats (dict) – A dictionary of {guilds: int, shards: int, users: int}

Servers

class boticordpy.modules.Servers(bot, **kwargs)

Class with methods to work with Boticord API Servers.

Parameters: bot (commands.Bot | commands.AutoShardedBot) – The discord.py Bot instance

async getServerComments(serverID: int)

Returns comments of the discord server with the given ID.

Parameters: serverID (int) – Discord Server’s ID

async getServerInfo(serverID: int)

Returns information about discord server with the given ID.

Parameters: serverID (int) – Discord Server’s ID

async postServerStats(message: discord.message.Message, custom_stats: Optional[dict] = None)

Post server stats to Boticord API.

Parameters

message (discord.Message) – Message object of used command.
custom_stats (dict) – Dict with custom server stats. (Optional)

Users

class boticordpy.modules.Users(**kwargs)

Class with methods to work with Boticord API Users.

async getUserBots(userID: int)

Returns bots of discord user with the given ID.

Parameters: userID (int) – Discord User’s ID

async getUserComments(userID: int)

Returns comments of discord user with the given ID.

Parameters: userID (int) – Discord User’s ID

async getUserInfo(userID: int)

Returns information about discord user with the given ID.

Parameters: userID (int) – Discord User’s ID

BoticordWebhook

class boticordpy.BoticordWebhook(bot: Union[discord.ext.commands.bot.Bot, discord.ext.commands.bot.AutoShardedBot], boticord_client: boticordpy.client.BoticordClient)

This class is used as a manager for the Boticord webhook.

:param bot commands.Bot | commands.AutoShardedBot: The discord.py Bot instance

bot_webhook(route: str = '/bot', hook_key: str = '') → boticordpy.webhook.BoticordWebhook

This method may be used to configure the route of boticord bot’s webhook.

:param route str: Bot’s webhook route. Must start with /. Defaults - /bot. :param hook_key str: Webhook authorization key.

Returns
Return type: BoticordWebhook

async close() → None: Stops the webhook.

run(port: int)

Runs the webhook.

Parameters: port – The port to run the webhook on.

Reference

Event Reference

Example of event creation:

from discord.ext import commands

from boticordpy import BoticordWebhook, BoticordClient

bot = commands.Bot(command_prefix="!")
boticord = BoticordClient(bot, "boticord-api-token")

boticord_webhook = BoticordWebhook(bot, boticord).bot_webhook("/bot", "X-Hook-Key")
boticord_webhook.run(5000)


@boticord.event("edit_bot_comment")
async def on_boticord_comment_edit(data):
    print(data)

You can name the function whatever you want, but the decorator must always specify an existing event as an argument.

Warning

All the events must be a coroutine. If they aren’t, then you might get unexpected errors. In order to turn a function into a coroutine they must be async def functions.

Here you can find some information about events:

Boticord Events	Returns Type
new_bot_comment	types.Comment
edit_bot_comment	types.EditedComment
delete_bot_comment	types.Comment
new_bot_bump	types.BotVote
new_server_comment	Raw Data
edit_server_comment	Raw Data
delete_server_comment	Raw Data

You can find more events in Boticord Documentation.

Types

class boticordpy.types.BotVote(raw_data)

Model that represents information about bot’s vote.

raw_data

Raw data from the Boticord API.

Type: dict

user_id

ID of user, who voted.

Type: int

at

Voting date.

Type: datetime.datetime

class boticordpy.types.Comment(raw_data)

Model that represents information about a comment.

raw_data

Raw data from the Boticord API.

Type: dict

user_id

ID of comment author.

Type: int

comment

Comment.

Type: str

at

The comment creation time.

Type: datetime.datetime

class boticordpy.types.CommentData(raw_data)

Model that represents edited comment text data.

old

Old comment text.

Type: str or None

new

New comment text.

Type: str or None

class boticordpy.types.EditedComment(raw_data)

Model that represents information about edited comment. It is inherited from Comment