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: bot_types, *, 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.

Attributes:
bot: Union[discord.Client, discord.ext.commands.Bot]

The bot that this instance is running under. Can be any instance of bot, not just the ones listed.

token: str

The token you use for top.gg’s API

property session: Optional[ClientSession]

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: Union[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: Optional[dict] = None, sort: Optional[str] = None) → BotSearchResults

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
async bulk_fetch_bots(limit: int = 500, *args) → dict

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.

Returns

The results of your search (up to limit results)

Return type

toppy.models.BotSearchResults

Raises
async fetch_votes() → List[SimpleUser]

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: Union[User, Member, Object]) → bool

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

bool

Raises
async get_stats(bot: Union[User, Member, Object]) → BotStats

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
async post_stats(force_shard_count: bool = False) → int

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

int

Raises
async is_weekend() → bool

Returns True or False, depending on if it’s a “weekend”.

If it’s a weekend, votes count as double.

Return type

py:bool:

Raises

toppy.errors.ToppyError – Either the server sent an invalid response, or an unexpected response code was given.

async fetch_user(user: Union[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().