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
.
-
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: Returns: bots – Returns info on bots that match the search query on Top.gg.
Return type:
-
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 eitherpng
andsvg
. Defaults topng
;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 typebool
;colors
: a dictionary consisting of a parameter as a key and HEX color as value.color
will be appended to the key in casekey.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:
-
dsl_webhook
(route: str, auth_key: str)[source]¶ Helper method that configures a route that listens to server votes.
Parameters:
-
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 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
-
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