API Reference

The following section outlines the API of topggpy.

Client

class topgg.DBLClient(bot: discord.client.Client, token: str, autopost: bool = False, **kwargs)[source]

Represents a client connection that connects to Top.gg. This class is used to interact with the Top.gg API.

Parameters:
  • token (str) – Your bot’s Top.gg API Token.
  • bot (discord.Client) – An instance of a discord.py Client object.
  • autopost (Optional[bool]) – Whether to automatically post bot’s guild count every 30 minutes. This will dispatch on_guild_post().
  • **post_shard_count (Optional[bool]) – Whether to post the shard count on autopost. Defaults to False.
  • **session (Optional[aiohttp session]) – An aiohttp session to use for requests to the API.
  • **loop (Optional[event loop]) – An event loop to use for asynchronous operations. Defaults to bot.loop.
close()[source]

This function is a coroutine.

Closes all connections.

generate_widget(options: dict = None) → str[source]

This function is a coroutine.

Generates a Top.gg widget from provided options.

Parameters:options (dict) – A dictionary consisting of options. For further information, see the Widgets section.
Returns:widget – Generated widget URL.
Return type:str
get_bot_info(bot_id: int = None) → dict[source]

This function is a coroutine.

Gets information about a bot from Top.gg.

Parameters:bot_id (int) – ID of the bot to look up. Defaults to the provided Client object.
Returns:bot info – Information on the bot you looked up. Returned data can be found here.
Return type:dict
get_bot_votes() → List[str][source]

This function is a coroutine.

Gets information about last 1000 votes for your bot on Top.gg.

Note

This API endpoint is only available to the bot’s owner.

Returns:users – Users who voted for your bot.
Return type:List[str]
get_bots(limit: int = 50, offset: int = 0, sort: str = None, search: dict = None, fields: list = None) → dict[source]

This function is a coroutine.

Gets information about listed bots on Top.gg.

Parameters:
  • limit (int) – The number of results to look up. Defaults to 50. Max 500 allowed.
  • offset (int) – The amount of bots to skip. Defaults to 0.
  • sort (str) – The field to sort by. Prefix with - to reverse the order.
  • search (dict) – The search data.
  • fields (List[dict]) – Fields to output.
Returns:

bots – Returns info on bots that match the search query on Top.gg.

Return type:

dict

get_guild_count(bot_id: int = None) → dict[source]

This function is a coroutine.

Gets a bot’s guild count and shard info from Top.gg.

Parameters:bot_id (int) – ID of the bot you want to look up. Defaults to the provided Client object.
Returns:stats – The guild count and shards of a bot on Top.gg. The date field is returned in a datetime.datetime object.
Return type:dict
get_user_info(user_id: int) → dict[source]

This function is a coroutine.

Gets information about a user on Top.gg.

Parameters:user_id (int) – ID of the user to look up.
Returns:user data – Info about the user. Returned data can be found in top.gg documentation.
Return type:dict
get_user_vote(user_id: int) → bool[source]

This function is a coroutine.

Gets information about a user’s vote for your bot on Top.gg.

Parameters:user_id (int) – ID of the user.
Returns:vote status – Info about the user’s vote.
Return type:bool
get_weekend_status()[source]

This function is a coroutine.

Gets weekend status from Top.gg.

Returns:weekend status – The boolean value of weekend status.
Return type:bool
guild_count

Gets the guild count from the provided Client object.

post_guild_count(guild_count: Union[int, List[int]] = None, shard_count: int = None, shard_id: int = None)[source]

This function is a coroutine.

Posts your bot’s guild count and shards info to Top.gg.

Parameters:
  • guild_count (Optional[Union[int, List[int]]]) – Number of guilds the bot is in. Applies the number to a shard instead if shards are specified. If not specified, length of provided client’s property .guilds will be posted.
  • shard_count (Optional[int]) – The total number of shards.
  • shard_id (Optional[int]) – The index of the current shard. Top.gg uses 0 based indexing for shards.

Event reference

topgg.on_guild_post()

Called when guild count is posted on top.gg

topgg.on_dbl_vote(data)

Called when someone votes for your bot on top.gg

Parameters:data – The data with vote info returned in dict object

Example:

@bot.event
async def on_dbl_vote(data):
    print(data)

The returned data can be found in Top.gg docs.

Widgets

In topggpy, DBLClient has a DBLClient.generate_widget() method that takes an options dictionary as a parameter.

All available values for each key:
  • bot_id: ID of a bot to generate widget for. Must resolve to an ID of a listed bot when converted to a string;
  • format: must be either png and svg. Defaults to png;
  • type: used for short widgets (``). For large widget, must be an empty string;
  • noavatar: indicates whether to exclude bot avatar from short widgets. Must be of type bool;
  • colors: a dictionary consisting of a parameter as a key and HEX color as value. color will be appended to the key in case key.endswith("color") returns False.

Example:

print(await self.topggpy.generate_widget({
    "id": 270904126974590976,
    format: "svg",
    colors: {
        "username": 0xFFFFFF,
        "top": 0x000000
        }
    }))

Webhooks

Attention

In order for webhooks to work, the port you provide to WebhookManager.run() must be accessible, meaning your firewall must allow incoming requests to it.

Note

WebhookManager exposes the internal webserver instance via the WebhookManager.webserver property as well as helper methods.

class topgg.WebhookManager(bot: discord.client.Client)[source]

This class is used as a manager for the top.gg webhook.

Parameters:bot (discord.Client) – The Client object that will be utilized by this manager’s webhook(s) to emit events.
dbl_webhook(route: str, auth_key: str)[source]

Helper method that configures a route that listens to bot votes.

Parameters:
  • route (str) – The route to use for bot votes.
  • auth_key (str) – The Authorization key that will be used to verify the incoming requests.
dsl_webhook(route: str, auth_key: str)[source]

Helper method that configures a route that listens to server votes.

Parameters:
  • route (str) – The route to use for server votes.
  • auth_key (str) – The Authorization key that will be used to verify the incoming requests.
close()[source]

Stop the webhook.

run(port: int)[source]

Runs the webhook.

Parameters:port (int) – The port to run the webhook on.
webserver

Returns the internal webserver that handles webhook requests.

Returns:The internal webserver if it exists.
Return type:Optional[aiohttp.web.TCPSite]

Exceptions

The following exceptions are thrown by the library.

exception topgg.TopGGException[source]

Base exception class for topggpy.

Ideally speaking, this could be caught to handle any exceptions thrown from this library.

exception topgg.UnauthorizedDetected[source]

Exception that’s thrown when no API Token is provided.

Subclass of TopGGException

exception topgg.ClientException[source]

Exception that’s thrown when an operation in the DBLClient fails.

These are usually for exceptions that happened due to user input.

exception topgg.HTTPException(response, message)[source]

Exception that’s thrown when an HTTP request operation fails.

response

The response of the failed HTTP request.

Type:aiohttp.ClientResponse
text

The text of the error. Could be an empty string.

Type:str
exception topgg.Unauthorized(response, message)[source]

Exception that’s thrown for when status code 401 occurs.

Subclass of HTTPException

exception topgg.Forbidden(response, message)[source]

Exception that’s thrown for when status code 403 occurs.

Subclass of HTTPException

exception topgg.NotFound(response, message)[source]

Exception that’s thrown for when status code 404 occurs.

Subclass of HTTPException

exception topgg.ServerError(response, message)[source]

Exception that’s thrown when Top.gg returns “Server Error” responses (status codes such as 500 and 503).

Subclass of HTTPException