API Reference

Clients

Mixed

class toppy.Client(client: ClientProtocol, **options)

A class designed to handle Discord Bot List, DiscordBotsGG, and/or Top.gg

Parameters

• client (ClientProtocol) – The Discord Bot instance. Any Client derived from discord.Client or any other fork’s Client. It must fit the ClientProtocol.

• dbl_token (str) – The authorization token for Discord Bot List.

• dbgg_token (str) – The authentication token for DiscordBotsGG

• topgg_token (str) – The authorization token for Top.gg.

• interval (Optional[float]) – The interval in seconds to auto-post the stats. Defaults to 600.

• post_shard_count (bool) – Decides whether to post the shard count along with the server count. Defaults to False.

• start_on_ready (bool) – Whether to start the auto post task when the bot is ready. If False then it must be manually started with start. Defaults to True.

• session (Optional[aiohttp.ClientSession]) – The session for the HTTP Client.

• versionchanged: (..) – 1.5: client is no longer positional only.

• versionchanged: – 2.0.0: Add support for DiscordBotsGG

start()

Starts the autopost task.

cancel()

Cancels the task of auto posting stats.

property dbl: Optional[DiscordBotListClient]

Access the Client for Discord Bot List.

Return type

Optional[DBLCLient]

property dbgg: Optional[DiscordBotsGGClient]

Access the Client for DiscordBotsGG.

Return type

Optional[DiscordBotsGGClient]

property topgg: Optional[TopGGClient]

Access the Client for Top.gg.

Return type

Optional[TopGGClient]

async post_stats() → None

Post your bots stats to all websites with a token found. All stats are automatically found and posted.

Discord Bot List

class toppy.DiscordBotListClient(client: ClientProtocol, token: str, *, interval: Optional[float] = None, start_on_ready: bool = True, session: Optional[aiohttp.ClientSession] = None)

A Client to access the Discord Bot List API. This includes auto-posting Discord Bot Stats.

https://discordbotlist.com/

Parameters

• client (ClientProtocol) – The Discord Bot instance. Any Client derived from discord.Client or any other fork’s Client.

• token (str) – The token for Discord Bot List.

• interval (Optional[float]) – The interval in seconds to auto-post the stats. Defaults to 600.

• start_on_ready (bool) – Whether to start the auto post task when the bot is ready. If False then it must be manually started with start. Defaults to True.

• session (Optional[aiohttp.ClientSession]) – The session for the HTTP Client.

Changed in version 1.4: Instead of a separate module it is just one file.

Changed in version 1.5: Moved to toppy.client

async post_stats() → None

Post your bots stats to Discord Bot List. All stats are automatically found and posted.

dispatches dbl_post_error with the argument toppy.HTTPException or derived classes or dbl_post_success with no arguments.

cancel() → None

Cancels the task of auto posting stats.

start() → None

Starts the autopost task.

property task: Task

The asyncio.Task object for autopost.

DiscordBotsGG

class toppy.DiscordBotsGGClient(*args, post_shard_count: bool = False, **kwargs)

A Client to access the DiscordBotsGG. This includes auto-posting Discord Bot Stats.

https://discord.bots.gg/

Parameters

• client (ClientProtocol) – The Discord Bot instance. Any Client derived from discord.Client or any other fork’s Client.

• token (str) – The token for DiscordBotsGG. This can be found in the API section.

• interval (Optional[float]) – The interval in seconds to auto-post the stats. Defaults to 600.

• start_on_ready (bool) – Whether to start the auto post task when the bot is ready. If False then it must be manually started with start. Defaults to True.

• session (Optional[aiohttp.ClientSession]) – The session for the HTTP Client.

New in version 2.0.

async search_one_bot(bot_id: int, /) → DiscordBotsGGBot

Search a single bot on DiscordBotsGG.

Parameters

bot_id (int) – The ID to search. Positional only.

Return type

DiscordBotsGGBot

async search_bots(*args, **kwargs) → list[DiscordBotsGGBot]

Search up bots on DiscordBotsGG.

Parameters

• query (Optional[str]:) – Searches for bots that contain the query in their username or short description.

• page (Optional[int]:) – The page to look at.

• limit (Optional[int]:) – The number of results to retrieve. Must be between 1 and 100. Defaults to 50.

• author_id (Optional[int]:) – Retrieves bots by the specified auther/co-owner’s ID.

• author (Optional[str]:) – Retrieves bots by the specified author/co-owner’s username and discriminator. This should not be a User or Member object in your bot library.

• unverified (Optional[bool]:) – Retrieves unapproved bots.

• lib (Optional[str]:) – Retrieves bots written in a specific library.

• sort (Literal['username', 'id', 'guildcount', 'library', 'author']:) – Sorts the results by any of the following keys: username, id, guildcount, library, author.

• order (Optional[Literal['ASC', 'DESC']]:) – Sorts the results in ASC or DESC order.

Return type

list[DiscordBotsGGBot]

async post_stats() → None

Post your bots stats to DiscordBotsGG. All stats are automatically found and posted.

dispatches dbgg_post_error with the argument toppy.HTTPException or derived classes or dbgg_post_success with no arguments.

cancel() → None

Cancels the task of auto posting stats.

start() → None

Starts the autopost task.

property task: Task

The asyncio.Task object for autopost.

Top.gg

class toppy.TopGGClient(*args, post_shard_count: bool = False, **kwargs)

A Client to access the Top.gg API. This includes auto-posting Discord Bot Stats and accessing data about other Discord Bots on Top.gg.

https://top.gg/

Parameters

• client (ClientProtocol) – The Discord Bot instance. Any Client derived from discord.Client or any other fork’s Client.

• token (str) – The token found in the Webhooks tab of the bots owner only section.

• interval (Optional[float]) – The interval in seconds to auto-post the stats. Defaults to 600.

• post_shard_count (bool) – Decides whether to post the shard count along with the server count. Defaults to False.

• start_on_ready (bool:) – Whether to start the auto post task when the bot is ready. If False then it must be manually started with start. Defaults to True.

• session (Optional[aiohttp.ClientSession]) – The session for the HTTP Client.

Changed in version 1.4: Instead of a separate module it is just one file.

Changed in version 1.5: Moved to toppy.client

async search_bots(query: str, *, limit: Optional[int] = None, offset: Optional[int] = None) → list[TopGGBot]

Search up bots on Top.gg.

Parameters

• query (str) – The query to use when searching.

• limit (Optional[int]) – The limit of Bot to return. Keyword only.

• offset (Optional[int]) – The amount of bots to skip in the results. Keyword only.

Return type

list[TopGGBot]

async search_one_bot(bot_id: int, /) → TopGGBot

Search a single bot on Top.gg.

Parameters

bot_id (int) – The ID to search. Positional only.

Return type

TopGGBot

async last_1000_votes(bot_id: Optional[int] = None, /) → AsyncGenerator[TopGGUser, None]

Get the last 1000 votes of a bot on Top.gg.

Parameters

bot_id (Optional[int]) – The ID of the bot. Defaults to the Bot initialized with. Positional only.

Yields

TopGGUser

Example

async for user in topgg.last_1000_votes():
    ...

async check_if_voted(bot_id: Optional[int], user_id: int) → bool

Check if a user has voted on a bot.

Parameters

• bot_id (Optional[int]) – The ID of the bot. Defaults to the Bot initialized with.

• user_id (int) – The ID of the user.

Return type

bool

async post_stats() → None

Post your bots stats to Top.gg. All stats are automatically found and posted.

dispatches topgg_post_error with the argument toppy.HTTPException or derived classes or topgg_post_success with no arguments.

cancel() → None

Cancels the task of auto posting stats.

start() → None

Starts the autopost task.

property task: Task

The asyncio.Task object for autopost.

Cog

Use load_extension(‘toppy.cog’) to load the cog.

ToppyCog

class toppy.cog.ToppyCog(*args: Any, **kwargs: Any)

A cog to make it simple to use this library.

New in version 1.2.

Raises

toppy.NoTokenSet –

async post_error(error: HTTPException)

This listener will print on_topgg_post_error and on_dbl_post_error to the console.

async cog_command_error(ctx: Context, error: CommandError)

Catches all errors in this cog raised by is_owner

async post(ctx: Context)

A command to post your stats.

[p]post

The is_owner check is used.

async interval(ctx: Context, interval: float)

A command to change the interval of the autopost.

[p]interval <interval>

site: float

The interval to change to. If we are using Client then both Discord Bot List and Top.gg intervals will be changed.

The is_owner() check is used.

Useful Utilities

async toppy.utils.run_web_application(application: web.Application, site_class: Type[web.BaseSite] = <class 'aiohttp.web_runner.TCPSite'>, connect_db: Optional[AbstractDatabase] = None, **kwargs) → web.BaseSite

Run the webhook server created in create_webhook_server

Parameters

• application (aiohttp.web.Application) – The application to run.

• site_class (aiohttp.web.BaseSite) – The site for the application. Must have all methods from aiohttp.web.BaseSite. Defaults to web.TCPSite

• connect_db (Optional[AbstractDatabase]) – Pass in an instance that fits the AbstractDatabase protocol. This will automatically connect it.

• **kwargs – The kwargs to pass into site_class.

Return type

The instance of the site class passed into site_class.

Models

These models represent objects on relavent websites.

DiscordBotsGG

class toppy.models.DiscordBotsGGBot(data: dict)

A class that represents a bot on DiscordBotsGG, not on discord.

New in version 2.0.

property id: int

The id of the bot.

property name: str

The username of the bot.

property discriminator: int

The discriminator of the bot.

property avatar: str

The avatar url of the bot’s avatar.

property co_owners: list[int]

Snowflakes of the co-owners of the bot.

property prefix: str

The prefix of the bot.

property help_command: str

The text to invoke the help command for the bot.

property library_name: str

The library the bot is made with.

property website: str

The website url of the bot.

property support_invite: Optional[str]

The support server invite code of the bot.

property bot_invite: str

The custom bot invite url of the bot.

property short_description: str

The short description of the bot.

property long_description: Optional[str]

The long description of the bot. Can contain HTML and/or Markdown.

property open_source: Optional[str]

A url to the code repository of the bot.

property guild_count: Optional[int]

The amount of guilds the bot has according to posted stats.

property shard_count: Optional[int]

The amount of shards the bot has according to posted stats.

property verified: bool

Whether the bot has been verified yet.

property online: bool

Whether the bot is online.

property in_guild: bool

Whether the bot is in the DiscordBotsGG guild.

property owner: DiscordBotsGGOwner

The owner of the bot.

property status: str

The current status of the bot.

class toppy.models.DiscordBotsGGOwner(username: str, discriminator: int, id: int)

A class that represents an owner of a bot on DiscordBotsGG.

Changed in version 2.0.1: user_id renamed to id.

Top.gg

class toppy.models.TopGGBot(data: dict)

A class that represents a bot on Top.gg, not on discord.

Changed in version 2.0: Renamed to TopGGBot

property id: int

The id of the bot.

property name: str

The username of the bot.

property discriminator: int

The discriminator of the bot.

property avatar: str

The avatar hash of the bot’s avatar.

property prefix: str

The prefix of the bot.

property short_description: str

The short description of the bot.

property long_description: str

The long description of the bot. Can contain HTML and/or Markdown.

property tags: list[str]

The tags of the bot.

property website: Optional[str]

The website url of the bot.

property support: Optional[str]

The support server invite code of the bot.

property github: Optional[str]

The link to the github repo of the bot.

property owners: list[int]

Snowflakes of the owners of the bot. First one in the list is the main owner.

property featured_guilds: list[int]

Snowflakes of the guilds featured on the bot page.

property invite: Optional[str]

The custom bot invite url of the bot.

property date_of_approval: datetime

The date when the bot was approved.

property guild_count: Optional[int]

The amount of guilds the bot has according to posted stats..

property shard_count: Optional[int]

The amount of shards the bot has according to posted stats..

property certified: bool

The certified status of the bot.

property vanity: Optional[str]

The vanity url of the bot.

property upvotes: int

The amount of upvotes the bot has

property monthly_upvotes: int

The amount of upvotes the bot has this month.

class toppy.models.TopGGUser(data: dict)

A class that represents a user from a vote on Top.gg, not any other Top.gg user. It will be initialized automatically. Not manually.

Changed in version 2.0: Renamed to TopGGUser

property name: str

The username of the user.

property id: int

The username of the user.

property avatar: str

The avatar hash of the user’s avatar

Event Reference

on_dbl_post_success()

Called with a successful post of stats to Discord Bot List has been made.

on_dbl_post_error(error)

Called when an HTTP exception occursed during a post of stats to Discord Bot List.

Parameters

error (toppy.HTTPException) – The exception that occured.

on_dbgg_post_success()

Called with a successful post of stats to DiscordBotsGG has been made.

on_dbgg_post_error(error)

Called when an HTTP exception occursed during a post of stats to DiscordBotsGG.

Parameters

error (toppy.HTTPException) – The exception that occured.

on_topgg_post_success()

Called with a successful post of stats to Top.gg has been made.

on_topgg_post_error(error)

Called when an HTTP exception occursed during a post of stats to Top.gg.

Parameters

error (toppy.HTTPException) – The exception that occured.

Exceptions

HTTP Exceptions

class toppy.HTTPException(resp: Optional[ClientResponse] = None, message: Optional[str] = None)

The base HTTP exception class.

class toppy.BadRequest(resp: Optional[ClientResponse] = None, message: Optional[str] = None)

Status 400.

class toppy.Unauthorized(resp: Optional[ClientResponse] = None, message: Optional[str] = None)

Status 401.

class toppy.Forbidden(resp: Optional[ClientResponse] = None, message: Optional[str] = None)

Status 403.

class toppy.RateLimited(retry_after: Optional[int] = None, resp: Optional[ClientResponse] = None)

Status 429.

retry_after

The amount of seconds you can retry in.

Type

Optional[int]

Missing Extra Requirements

class toppy.MissingExtraRequire(require: str)

If a user is missing extra requirements

Client Not Ready

class toppy.ClientNotReady

The bot is not ready and does not have an application ID set so no ID could be found

No Token Set

class toppy.NoTokenSet

An exception if the bot is missing bot vars to use the cog.