API Reference

The following section outlines the API of dblpy.

Client

class dbl.DBLClient(bot, token, **kwargs)[source]

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

Parameters:
  • token – An API Token
  • bot – An instance of a discord.py Bot or Client object
  • **loop (Optional[event loop]) – The event loop to use for asynchronous operations. Defaults to bot.loop.
  • **session (Optional) – The aiohttp session to use for requests to the API.
  • **autopost (Optional[bool]) – Whether to automatically post bot’s guild count every 30 minutes. This will dispatch on_guild_post().
  • **webhook_auth (Optional) – The string for Authorization you set on the site for verification.
  • **webhook_path (Optional) – The path for the webhook request.
  • **webhook_port (Optional[int]) – The port to run the webhook on. Will activate webhook when set.
guild_count()[source]

Gets the guild count from the Client/Bot object

close()[source]

This function is a coroutine.

Closes all connections.

generate_widget_large(bot_id: int = None, top: str = '2C2F33', mid: str = '23272A', user: str = 'FFFFFF', cert: str = 'FFFFFF', data: str = 'FFFFFF', label: str = '99AAB5', highlight: str = '2C2F33')[source]

This function is a coroutine.

Generates a custom large widget. Do not add # to the color codes (e.g. #FF00FF become FF00FF).

Parameters:
  • bot_id (int) – ID of the bot you wish to make a widget for.
  • top (str) – The hex color code of the top bar.
  • mid (str) – The hex color code of the main section.
  • user (str) – The hex color code of the username text.
  • cert (str) – The hex color code of the certified text (if applicable).
  • data (str) – The hex color code of the statistics (numbers only e.g. 44) of the bot.
  • label (str) – The hex color code of the description (text e.g. guild count) of the statistics.
  • highlight (str) – The hex color code of the data boxes.
Returns:

URL of the widget
Return type:

str
generate_widget_small(bot_id: int = None, avabg: str = '2C2F33', lcol: str = '23272A', rcol: str = '2C2F33', ltxt: str = 'FFFFFF', rtxt: str = 'FFFFFF')[source]

This function is a coroutine.

Generates a custom large widget. Do not add # to the color codes (e.g. #FF00FF become FF00FF).

Parameters:
  • bot_id (int) – ID of the bot you wish to make a widget for.
  • avabg (str) – The hex color code of the background of the avatar (if the avatar has transparency).
  • lcol (str) – The hex color code of the left background color.
  • rcol (str) – The hex color code of the right background color.
  • ltxt (str) – The hex color code of the left text.
  • rtxt (str) – The hex color code of the right text.
Returns:

URL of the widget
Return type:

str
get_bot_info(bot_id: int = None)[source]

This function is a coroutine.

Gets information about a bot from top.gg

Parameters:bot_id (int[Optional]) – ID of the bot you want to lookup.
Returns:bot info – Information on the bot you looked up. https://top.gg/api/docs#bots
Return type:dict
get_bot_upvotes()[source]

This function is a coroutine.

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

Note

This API endpoint is available to the owner of the bot only.

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

This function is a coroutine.

Gets information about listed bots on top.gg

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

bots – Returns info on the bots on DBL. https://top.gg/api/docs#bots
Return type:

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

This function is a coroutine.

Gets a guild count from top.gg

Parameters:bot_id (int[Optional]) – ID of the bot you want to lookup. Defaults to the discord.py Bot/Client provided in Client init.
Returns:stats – The guild count and shards of a bot. The date object is returned in a datetime.datetime object.
Return type:dict
get_user_info(user_id: int)[source]

This function is a coroutine.

Gets information about a user on top.gg

Parameters:user_id (int) – ID of the user you wish to lookup.
Returns:user data – Info about the user. https://top.gg/api/docs#users
Return type:dict
get_user_vote(user_id: int)[source]

This function is a coroutine.

Gets information about the user’s upvote for your bot on top.gg

Parameters:user_id (int) – ID of the user you wish to lookup.
Returns:vote status – Info about the user’s upvote.
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
get_widget_large(bot_id: int = None)[source]

This function is a coroutine.

Generates the default large widget.

Parameters:bot_id (int) – ID of the bot you wish to make a widget for.
Returns:URL of the widget
Return type:str
get_widget_small(bot_id: int = None)[source]

This function is a coroutine.

Generates the default small widget.

Parameters:bot_id (int) – ID of the bot you wish to make a widget for.
Returns:URL of the widget
Return type:str
post_guild_count(shard_count: int = None, shard_no: int = None)[source]

This function is a coroutine.

Posts your bot’s guild count to top.gg

Parameters:
  • shard_count (int[Optional]) – The total number of shards.
  • shard_no (int[Optional]) – The index of the current shard. DBL uses 0 based indexing for shards.

Event reference

dbl.on_guild_post()

Called when guild count is posted on top.gg

dbl.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 data returned can be found here.

dbl.on_dbl_test(data)

Called when someone tests webhook system for your bot on top.gg

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

Example:

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

The data returned can be found here.

Exceptions

The following exceptions are thrown by the library.

exception dbl.DBLException[source]

Base exception class for dblpy

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

exception dbl.UnauthorizedDetected[source]

Exception that’s thrown when no API Token is provided

Subclass of DBLException

exception dbl.ClientException[source]

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

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

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

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

response

The response of the failed HTTP request. This is an instance of aiohttp.ClientResponse.

text

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

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

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

Subclass of HTTPException

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

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

Subclass of HTTPException

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

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

Subclass of HTTPException

exception dbl.InvalidArgument[source]

Exception that’s thrown when an argument to a function is invalid some way (e.g. wrong value or wrong type).

This could be considered the analogous of ValueError and TypeError except derived from ClientException and thus DBLException.

exception dbl.ConnectionClosed(original)[source]

Exception that’s thrown when the gateway connection is closed for reasons that could not be handled internally.

code

The close code of the websocket.

Type:int
reason

The reason provided for the closure.

Type:str