Skip to content

Client

Jump to bottom
eek#7574 edited this page Mar 22, 2021 · 15 revisions

warning: This documentation was last updated for top.py version 1.0.1 and MAY be out of date.

Models

Bot

attribute name attribute type default value
id int
username str
discriminator str
avatar_url str None
default_avatar str
avatar str avatar_url or default_avatar
prefix str
short_description str
long_description str None
tags List[str] []
website str None
support str None
github str None
owners List[int] []
featured_guilds List[int] []
invite str

user(state = none)

Returns a discord.User object from self.id.

Unless you constructed this yourself (don't), it's usually safe to leave state blank. If for whatever reason you need to provide a state, make sure it has a get_user attribute.

Returns discord.User

User

attribute name attribute type default value
id int
username str
discriminator str
avatar_url str None
default_avatar str
avatar str avatar_url or default_avatar
bio str None
banner_url str None
socials WeakRef
colour Colour
color alias for self.colour
supporter bool False
site_mod bool False
site_admin bool False
certified bool False

user(state = none)

Returns a discord.User object from self.id.

Unless you constructed this yourself (don't), it's usually safe to leave state blank. If for whatever reason you need to provide a state, make sure it has a get_user attribute.

Returns discord.User

SimpleUser

attribute name attribute type default value
id int
username str
discriminator str #0000
avatar str

BotStats

attribute name attribute type default value
server_count int 0
shards Dict[int, int]
shard_count int 0
reliable bool

Note: the reliable attribute is True when the length of shards is that of shard_count, and the sum of shards values is the same as server_count

Functions

async fetch_bot(bot_id: int, *, fail_if_ratelimited: bool = False)

Fetches a bot from top.gg

  • bot_id: The bot's client ID
  • fail_if_ratelimited: Whether to raise an error if we get ratelimited or just wait an hour

Returns: A bot model

async fetch_bots(limit: int = 50, offset: int = 0, search: dict = None, sort: str = None, fail_if_ratelimited: bool = True)

Fetches up to <limit> bots. It's best you read top.gg's docs on this one.

  • limit: Up to this many bots will be fetched. Maximum of 500.
  • offset: just read top.gg's docs for this one
  • search: Search options (e.g. {"library": "discord.py"})
  • sort: gg's docs don't explain much to be honest
  • fail_if_ratelimited: Whether to raise an error if we get ratelimited or just wait an hour

Returns: A list of bot objects.

async bulk_fetch_bots(limit: int = 500, *args)

Similar to fetch_bots, except allows for requesting more than 500. 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)
...

async fetch_votes(fail_if_ratelimited: bool = True)

Fetches the most recent 1,000 voters for the current bot.

  • fail_if_ratelimited: if True, will raise Ratelimited instead of waiting the ratelimit out.

Returns: A list of SimpleUsers

async upvote_check(user_id: int, fail_if_ratelimited: bool = True)

Checks if the user <user_id> has voted or not.

Warning!

In a later update, user_id will be replaced with user, and will take a discord.User over int.

Returns: True if the user has voted, otherwise False.

async get_stats(bot_id: int)

Gets public stats on a bot (i.e. guild count, shard count)

Warning!

In a later update, bot_id will be replaced with bot, and will take a discord.User over int.

Returns: BotStats

async post_stats(stats: dict = None)

Posts public stats to your top.gg page.

  • stats: if provided, will be automatically generated. It's best you do this.

Returns: int - the number of servers posted.

Clone this wiki locally