API Reference

This page will describe top.py’s client class and it’s attributes.

Note

Like discord.py, we use python’s in-built logging module. Most things are logged via the debug level, and only certain events are logged via warnings. You’re not missing much if you don’t set it up.

Version

You can get a version from toppy.__version__

Client

class toppy.TopGG(bot: DiscordClient, *, token: str, autopost: bool = True)

The client class for the top.gg API.

This class handles everything for the top.gg API, APART FROM voting webhooks - Those are handled by the server class.

property session: ClientSession | None

Returns the current top.py client session.

Warning

You must have at least called one function before using this variable, as the connection is not created on class initialization.

Returns:

The current aiohttp client session

Return type:

aiohttp.ClientSession

property vote_url: str

Just gives you a link to your bot’s vote page.

Return type:

str

property invite_url: str

Just gives you a link to your bot’s invite page.

autopost

A background task helper that abstracts the loop and reconnection logic for you.

The main interface to create this is through loop().

async fetch_bot(bot: User | Member | Object) → Bot

Fetches a bot from top.gg

Parameters:

bot (Union[discord.User, discord.Member]) – The bot’s user to fetch

Returns:

The retrieved bot

Return type:

toppy.models.Bot

Raises:
async fetch_bots(limit: int = 50, offset: int = 0, search: dict = None, sort: str = None) → BotSearchResult

Fetches up to limit bots from top.gg

Parameters:

  • limit (int) – How many bots to fetch.

  • offset (int) – How many bots to “skip” (pagination)

  • search (Optional[dict]) – Search pairs (e.g. {“library”: “discord.py”})

  • sort (Optional[str]) – What field to sort by. Prefix with dash to reverse results.

Returns:

The results of your search (up to limit results)

Return type:

toppy.models.BotSearchResults

Raises:
bulk_fetch_bots(limit: int = 500, offset: int = 0, search: dict = None, sort: str = None) → BulkFetchBotsIterator

Similar to fetch_bots, except allows for requesting more than 500 bots at once.

Warning

This function is not guaranteed to return exactly limit.

Keep in mind that it returns up to limit

Danger

Since this function sends multiple requests, it can take a long time.

Furthermore, sending a bulk request for more than thirty thousand (30,000) bots will cause you to be ratelimited.

This is equivalent to:

batch_one = await TopGG.fetch_bots(500)
batch_two = await TopGG.fetch_bots(500, offset=500)
batch_three = await TopGG.fetch_bots(500, offset=1000)
Parameters:

  • limit (int) – How many bots to fetch.

  • offset (int) – How many bots to “skip” (pagination)

  • search (Optional[dict]) – Search pairs (e.g. {“library”: “discord.py”})

  • sort (Optional[str]) – What field to sort by. Prefix with dash to reverse results.

Raises:
async fetch_votes() → List[VoteResult]

Fetches the last 1000 voters for your bot.

Returns:

A list of up to 1000 SimpleUser objects who have voted for your bot in the past (any time period).

Return type:

list [toppy.models.SimpleUser]

Raises:
async upvote_check(user: User | Member | Object) → IndividualUserVoteResult

Checks to see if the provided user has voted for your bot in the pas 12 hours.

Parameters:

user – The user to fetch upvote for.

Returns:

True if the has user voted in the past 12 hours, False if not

Return type:

IndividualUserVoteResult

Raises:
async get_stats(bot: User | Member | Object) → BotStatsResult

Fetches the server & shard count for a bot.

NOTE: this does NOT fetch votes. Use the fetch_bot function for that.

Returns:

Basic statistics on the specified bot.

Return type:

toppy.models.BotStats

Raises:

was given.

async post_stats(force_shard_count: bool = False) → BotStatsPayload

Posts your bot’s current statistics to top.gg

Parameters:

force_shard_count (bool) – If true, always include shard data, even when it would normally be excluded

Returns:

an integer of how many servers got posted.

Return type:

BotStatsResult

Raises:
async fetch_user(user: User | Member | Object) → User

Fetches a user’s profile from top.gg.

Parameters:

user – Union[discord.User, discord.Member] - Who’s top.gg profile to fetch.

Raises:
Returns toppy.models.User:

The fetched user’s profile

Client Event Reference

_Note: all events must be async._

toppy.on_guild_post(stats: dict)

Event dispatched whenever toppy.client.TopGG.post_stats() is called.

stats is a dictionary with the keys server_count (int), shards (list), and shard_count (int)

Parameters:

stats – dict - Aforementioned stats dictionary

toppy.on_toppy_request(*, url: str, method: Literal['GET', 'POST'])

Event dispatched whenever the internal function toppy.client.TopGG._request() is used.

URL is the request URL, and method is the method used on the URL.

Warning

This function is called on EVERY request, and as such should only really be used to find out why you’re being ratelimited (if that is happening). The only other use case is to see where your requests are going.

Parameters:

  • url – str - The URL the request was sent to

  • method – str - The method used to request.

on_toppy_stat_autopost(result):

Event dispatched whenever the internal autopost task succeeds.

Note

This function takes the exact same argument as on_guild_post().