API Reference

The following section outlines the API of dblpy.

Client

Note

All of the following functions return their data as a JSON object (except widget generation)!

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

Represents a client connection that connects to discordbots.org. 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.
guild_count()[source]

Gets the guild count from the bot object

post_server_count(shard_count: int = None, shard_no: int = None)[source]

This function is a coroutine.

Posts the server count to discordbots.org

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.
get_server_count(bot_id: int = None)[source]

This function is a coroutine.

Gets a server count from discordbots.org

Parameters:bot_id (int[Optional]) – The bot_id of the bot you want to lookup. Defaults to the Bot provided in Client init
Returns:stats – The server count and shards of a bot. The date object is returned in a datetime.datetime object
Return type:dict
get_upvote_info(**kwargs)[source]

This function is a coroutine.

Gets information about who upvoted a bot from discordbots.org

Note

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

Parameters:
  • **onlyids (bool[Optional]) – Whether to return an array of simple user objects or an array of user ids. Defaults to False
  • **days (int[Optional]) – Limits the votes to ones done within the amount of days you specify. Defaults to 31
Returns:

votes – Info about who upvoted your bot.

Return type:

dict

get_bot_info(bot_id: int = None)[source]

This function is a coroutine.

Gets information about a bot from discordbots.org

Parameters:bot_id (int[Optional]) – The bot_id of the bot you want to lookup.
Returns:bot info – Information on the bot you looked up. https://discordbots.org/api/docs#bots
Return type:dict
get_bots(limit: int = 50, offset: int = 0)[source]

This function is a coroutine.

Gets information about listed bots on discordbots.org

Parameters:
  • limit (int[Optional]) – The number of results you wish to lookup. Defaults to 50.
  • offset (int[Optional]) – The page number to search. Defaults to 0.
Returns:

bots – Returns info on the bots on DBL. https://discordbots.org/api/docs#bots

Return type:

dict

get_user_info(user_id: int)[source]

This function is a coroutine.

Gets information about a user on discordbots.org

Parameters:user_id (int) – The user_id of the user you wish to lookup.
Returns:user_data – Info about the user. https://discordbots.org/api/docs#users
Return type:dict
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) – The bot_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. server count) of the statistics.
  • highlight (str) – The hex color code of the data boxes.
Returns:

URL of the widget

Return type:

str

get_widget_large(bot_id: int = None)[source]

This function is a coroutine.

Generates the default large widget.

Parameters:bot_id (int) – The bot_id of the bot you wish to make a widget for.
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) – The bot_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_widget_small(bot_id: int = None)[source]

This function is a coroutine.

Generates the default small widget.

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

This function is a coroutine. Closes all connections.

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.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

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

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

int – The close code of the websocket.

reason

str – The reason provided for the closure.