API Reference¶

The following section outlines the API of dblstatistics.com

Bots¶

class dblstats.objects.bot.Bot(certified: bool, owners: List[int], deleted: bool, id: str, name: str, default_avatar: str, avatar: str, short_description: str, library: str, prefix: str, website: str, approved_at: datetime.datetime, monthly_votes: int, server_count: int, total_votes: int, shard_count: int, monthly_votes_rank: int, server_count_rank: int, total_votes_rank: int, shard_count_rank: int, updated_at: datetime.datetime)¶

The object that represents a bot in Top.gg This is based on the :class BotBase: object.

Parameters

certified – Whether or not the bot is certified on Top.gg
deleted – Whether or not the bot has been removed from Top.gg
id – The bot its user id
name – The bot its username
default_avatar – The default assigned avatar that has been given to the bot (Decided by discriminator)
avatar – The bot avatar url
short_description – A short text that describes the bot
library – The library that the bot uses
prefix – The default bot prefix
website – The website that is associated with the bot
approved_at – The datetime from when the bot got added to Top.gg

class dblstats.objects.bot.BotBase(owners: List[int], monthly_votes: int, server_count: int, total_votes: int, shard_count: int, monthly_votes_rank: int, server_count_rank: int, total_votes_rank: int, shard_count_rank: int, updated_at: datetime.datetime)¶

A bot helper function that contains the basic bot values

Parameters

owners – A collection of the bot owner(s) their discord IDs
monthly_votes – The amount of votes that the bot has received this month
server_count – The amount of servers the bot is in (self reported)
total_votes – The total amount of votes that the bot has
shard_count – The amount of shards that the bot is running on (self reported)
monthly_votes_rank – The position that the bot is in relative to the other bots registered on Top.gg qua votes from this month
server_count_rank – The position that the bot is in relative to the other bots registered on Top.gg qua servers
total_votes_rank – The position that the bot is in relative to the other bots registered on Top.gg qua votes
shard_count_rank – The position that the bot is in relative to the other bots registered on Top.gg qua shards
updated_at – The timestamp that this was updated on

class dblstats.objects.bot.BotHistory(id: str, history: List[dblstats.objects.bot.BotBase])¶

An object that contains a collection of BotBase objects. Each item differs one hour with the previous item.

The maximum collection size is 500 This object contains the previous bot data for that bot.

Parameters

id – The bot its id from which the history is shown
history – A collection of BotBase objects that can be used to see the bot its history.

Auctions¶

class dblstats.objects.dblstats_auctions.AuctionCurrent(bot: Dict[str, List[dblstats.objects.dblstats_auctions.AuctionUser]], server: Dict[str, List[dblstats.objects.dblstats_auctions.AuctionUser]])¶

Represents all current betters.

Parameters

bot – A dictionary of which contains a collection of :class AuctionUser: objects which are associated with the tag (as key) in the bot section.
server – A dictionary of which contains a collection of :class AuctionUser: objects which are associated with the tag (as key) in the server section.

class dblstats.objects.dblstats_auctions.AuctionTag(bot: List[str], server: List[str])¶

Represents a dblstats tag object.

Parameters

bot – A collection of tags strings that are linked to bot types.
server – A collection of tags strings that are linked to server types.

class dblstats.objects.dblstats_auctions.AuctionUser(id: str, user_tag: str, avatar: str, default_avatar: str, product: str, tag: str, list: str, amount: int, outbid: bool, timestamp: datetime.datetime, is_fake: bool)¶

Represents a Top.gg auction user.

Parameters

id – The user their discord id
tag – The user their discord tag (username#discriminator)
avatar – The user their discord avatar url
default_avatar – The user their default discord avatar url (calculated by discriminator)
product – The bot/server name for which the bet is for.
tag – That associated page for the product.
list – The list type for the product, this is either bot or server.
amount – The bet amount in usd.
outbid – If this bet has been outbid.
timestamp – When the bet got submitted.
is_fake – If the bet has been verified as real.

class dblstats.objects.dblstats_auctions.Auctions(fetcher: dblstats.utils.async_fetcher.AsyncFetcher)¶

An object that can fetch the current Top.gg auctions

Parameters: fetcher – The :class AsyncFetcher: object. (Which will fetch the data from the API)
Property tags: Returns a cached :class AuctionTag:.

async get_current() → dblstats.objects.dblstats_auctions.AuctionCurrent ¶

Fetches all current auctions.

Return AuctionCurrent: The latest auctions.

async get_tags() → dblstats.objects.dblstats_auctions.AuctionTag ¶

Fetches the latest tags from the API. This also updates the tags property for this class.

Return AuctionTag: The latest bot and server tags.

Client¶

class dblstats.objects.dblstats_client.Client(token: str)¶

Represents your dblstatistics.com client.

This interacts with the api, so it allows you to fetch data.

Parameters: token – Your secret dblstatistics.com API token.
Property auctions: An :class Auctions: which can be used to fetch all auction related data.

async get_bot(id: Union[int, str]) → dblstats.objects.bot.Bot ¶

Fetch a bot from the dblstatistics website.

Parameters: id – The id of the bot that must be fetched.

async get_bot_history(id: Union[int, str]) → dblstats.objects.bot.BotHistory ¶

Fetch a bot its history from the dblstatistics website.

Parameters: id – The id of the bot that must be fetched.

async get_top_bots(sort_by: dblstats.objects.dblstats_client.Sorter = <Sorter.votes: 'votes'>) → List[dblstats.objects.bot.Bot]¶

Returns a collection of sorted dblstats Bot objects.

Parameters: sort_by – The way the bots should get sorted, default is by votes.

async get_user_bots(id: Union[int, str]) → dblstats.objects.user.UserBots ¶

Returns all bots from a user. (As a UserBots object)

Parameters: id – The user from which the bots should be fetched.

async get_widget(id: Union[str, int], widget: Union[dblstats.objects.dblstats_widgets.Widget, dblstats.objects.dblstats_widgets.RanksWidget]) → _io.BytesIO¶

Returns the bytes equivalent for the widget. If you want to send the widget in a discord message/file use dblstats.Client.get_widget_file instead.

Using this method over the get_widget_file method means that you get full control over the byte object.

Parameters

id – The bot its ID
widget – A widget object which contains the desired configuration.

async get_widget_file(id: Union[str, int], widget: Union[dblstats.objects.dblstats_widgets.Widget, dblstats.objects.dblstats_widgets.RanksWidget], *, name: str = None) → Tuple[discord.file.File, str]¶

An method which makes it easier to send the widget in a discord.py file.

Example usage:

widget = widgets.Widget(widgets.WidgetType.servers)
file, name = await self.dblstats.get_widget_file(str(bot), widget)
await client.send_file(message.channel, fp=file, filename=name)

Parameters

id – The bot its ID
widget – A widget object which contains the desired configuration.
name – (optional) The name you want the file to have. (default is {id}_{type})

class dblstats.objects.dblstats_client.Sorter(value)¶

Attr votes: Sorts by most voted
Attr monthly_votes: Sorts by most voted from this month
Attr servers: Sorts by most servers
Attr shards: Sorts by most shards

User¶

class dblstats.objects.user.UserBase(id: str, tag: str, avatar: str, default_avatar: str)¶

Represents the base of a top.gg user.

Parameters

id – The user their discord id
tag – The user their discord tag (username#discriminator)
avatar – The user their discord avatar url
default_avatar – The user their default discord avatar url (calculated by discriminator)

class dblstats.objects.user.UserBots(user: dblstats.objects.user.UserBase, bots: List[dblstats.objects.bot.Bot])¶

Represents a user with their corresponding bots.

Parameters

user – The user that owns the bots.
bots – A collection of bots that are owned by the user.

Widgets¶

class dblstats.objects.dblstats_widgets.RanksWidget(**kwargs)¶

A dblstatistics.com ranks widget. This represents an object that can be reused and customized. This object inherits WidgetBase. (see in its **kwargs)

Parameters

title_color – (optional) The hex color for the widget title. Default is site provided.
rank_back_color – (optional) The hex color for the rank background in the widget. Default is site provided.
rank_color – (optional) The hex color for the rank in the widget. Default is site provided.
border_color – (optional) The hex color of the widget its border color. Default is site provided.

class dblstats.objects.dblstats_widgets.Widget(widget_type: dblstats.objects.dblstats_widgets.WidgetType, **kwargs)¶

A dblstatistics.com widget. This represents an object that can be reused and customized. This object inherits WidgetBase. (see in its **kwargs)

Parameters

title_font_size – (optional) The fontsize for the widget title. Default is 12.
label_font_size – (optional) The fontsize for the widget labels. Default is 12.
text_color – (optional) The hex color of the widget text. Default is site provided.
line_color – (optional) The hex color of the widget lines (eg graphs ect).

class dblstats.objects.dblstats_widgets.WidgetBase(widget_type: dblstats.objects.dblstats_widgets.WidgetType, **kwargs)¶

The base object for widgets. This gets inherited by the Widget and RanksWidget object.

Parameters

widget_type – The widget type you want it to be.
background_color – (optional) The background color for the widget. Default is site provided.
width – (optional) The width of the widget. Default is 400.
height – (optional) The height of the widget. Default is 150.

class dblstats.objects.dblstats_widgets.WidgetType(value)¶

The allowed types of widgets.

Property servers: The property that you use when you want to fetch the bot its servers widget.
Property total_votes: The property that you use when you want to fetch the bot its total votes widget.
Property monthly_votes: The property that you use when you want to fetch the bot its monthly votes widget.
Property shard_count: The property that you use when you want to fetch the bot its shards widget.
Property ranks: The property that gets used by the RanksWidget object.

Exceptions¶

exception dblstats.objects.exceptions.DBLStatsException¶: The base class for all dblstats exceptions.

exception dblstats.objects.exceptions.InvalidAuthorizationToken¶: The exception that get raised when no or an invalid client token has been provided.

exception dblstats.objects.exceptions.InvalidProperty¶: The exception that gets raised when a property of the right type has been provided but is not allowed in that method or class

exception dblstats.objects.exceptions.InvalidTarget¶: The exception that get raised when the requested target does not exist.

exception dblstats.objects.exceptions.UnknownException¶: Gets raised when the developer didn’t anticipate for something. If this gets raised, please report this to our github: https://github.com/Arthurdw/dblstats/issues

API Reference¶

Version Related Info¶

Bots¶

Auctions¶

Client¶

User¶

Widgets¶

Exceptions¶