Client API Reference¶

class topgg.client.DBLClient(token: str, *, default_bot_id: Optional[int] = None, session: Optional[aiohttp.client.ClientSession] = None)[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.

Keyword Arguments

default_bot_id (typing.Optional [ int ]) – The default bot_id. You can override this by passing it when calling a method.
session (aiohttp.ClientSession) – An aiohttp session to use for requests to the API.

autopost() → topgg.autopost.AutoPoster[source]¶

Returns a helper instance for auto-posting.

Note

The second time you call this method, it’ll return the same instance as the one returned from the first call.

Returns: An instance of AutoPoster.
Return type: AutoPoster

async close() → None[source]¶: Closes all connections.

generate_widget(*, options: topgg.types.WidgetOptions) → str[source]¶

Generates a Top.gg widget from the provided WidgetOptions object.

Keyword Arguments

options (WidgetOptions) – A WidgetOptions object containing widget parameters.

Returns

Generated widget URL.

Return type

str

Raises

ClientException – If bot_id or default_bot_id is unset.
TypeError – If options passed is not of type WidgetOptions.

async get_bot_info(bot_id: Optional[int] = None) → topgg.types.BotData[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: Information on the bot you looked up. Returned data can be found here.
Return type: BotData
Raises: ClientException – If neither bot_id or default_bot_id was set.

async get_bot_votes() → List[topgg.types.BriefUserData][source]¶

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 who voted for your bot.
Return type: list [ BriefUserData ]
Raises: ClientException – If default_bot_id isn’t provided when constructing the client.

async get_bots(limit: int = 50, offset: int = 0, sort: Optional[str] = None, search: Optional[Dict[str, Any]] = None, fields: Optional[List[str]] = None) → topgg.types.DataDict[str, Any][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 [ str, typing.Any ]) – The search data.
fields (list [ str ]) – Fields to output.

Returns

Info on bots that match the search query on Top.gg.

Return type

DataDict

get_data(type_: Any, default: Optional[Any] = None) → Any¶: Gets the injected data.

async get_guild_count(bot_id: Optional[int] = None) → topgg.types.BotStatsData[source]¶

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: The guild count and shards of a bot on Top.gg.
Return type: BotStatsData
Raises: ClientException – If neither bot_id or default_bot_id was set.

async get_user_info(user_id: int) → topgg.types.UserData[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: Information about a Top.gg user.
Return type: UserData

async get_user_vote(user_id: int) → bool[source]¶

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

Parameters: user_id (int) – ID of the user.
Returns: Info about the user’s vote.
Return type: bool
Raises: ClientException – If default_bot_id isn’t provided when constructing the client.

async get_weekend_status() → bool[source]¶

Gets weekend status from Top.gg.

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

async post_guild_count(stats: topgg.types.StatsWrapper) → None[source]¶

async post_guild_count(*, guild_count: Union[int, List[int]], shard_count: Optional[int] = 'None', shard_id: Optional[int] = 'None') → None

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

Warning

You can’t provide both args and kwargs at once.

Parameters

stats (StatsWrapper) – An instance of StatsWrapper containing guild_count, shard_count, and shard_id.

Keyword Arguments

guild_count (typing.Optional [typing.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 (typing.Optional [ int ]) – The total number of shards.
shard_id (typing.Optional [ int ]) – The index of the current shard. Top.gg uses 0 based indexing for shards.

Raises

TypeError – If no argument is provided.

set_data(data_: Any, *, override: bool = False) → topgg.data.DataContainerT¶

Sets data to be available in your functions.

Parameters

data_ (typing.Any) – The data to be injected.
override (bool) – Whether or not to override another instance that already exists.

Raises

TopGGException – If override is False and another instance of the same type exists.