Intro to the Polympics API wrapper¶

Creating a client¶

The first thing you need to do to use the API is create an API client. There are 3 types of client:

Unauthenticated
App-authenticated
User-authenticated

Creating an unauthenticated client is very simple:

client = UnauthenticatedClient()

However, if you want to do anything other than read-only operations, you’ll need to authenticate. To use app credentials, see the following example:

credentials = Credentials('A3', 'YOUR-TOKEN-HERE')
client = AppClient(credentials)

Creating a user-authenticated client is very similar:

credentials = Credentials('S3', 'YOUR-TOKEN-HERE')
client = UserClient(credentials)

Note

All three clients take an additional parameter, base_url. This is the location at which the API is hosted, for example http://127.0.0.1:8000 or https://api.polytopia.fun.

Getting an account¶

You can get an account by Discord ID using get_account. For example:

account = await client.get_account(12345678901234)
print(account.name)
print(account.permissions)
print(account.team.name)

Getting a team¶

You can get a team by ID using get_team. For example:

team = await client.get_team(31)
print(team.name)
print(team.member_count)

Getting an award¶

You can get an award by ID using the get_award method. For example:

award = await client.get_award(42)
print(award.title, award.image_url)
for awardee in award.awardees:
    # awardee is an Account object.
    print(awardee.name)

Listing all accounts¶

You can list all accounts using list_accounts. For example:

async for account in client.list_accounts():
    print(account.name)

You can also get results a page at a time:

accounts = client.list_accounts()
for account in await accounts.get_page(0):
    print(account.name)

You can use the search and team parameters to narrow down results.

print(f'Members from team {team.name} with "bob" in their name:')
async for account in client.list_accounts('bob', team=team):
    print(account.name)

Listing all teams¶

You can list all teams using list_teams. For example:

async for team in client.list_teams():
    print(team.name)

This supports the same pagination system as list_accounts, as well as the search parameter:

teams = client.list_teams(search='foo')
print([team.name for team in await teams.get_page(0)])

Checking if signups are open¶

Call check_signups on any client to check if signups are open:

if await client.check_signups():
    print('Signups are open.')
else:
    print('Signups are closed.)

New users will not be allowed to register when signups are closed.

Creating an account¶

Registering a user is a simple call to create_account:

team = await client.get_team(5)
account = await client.create_account(
    id=1234567,
    name='Artemis',
    discriminator='8472',
    avatar_url='https://picsum.photos/200',
    team=team
)
assert account.name == 'Artemis'
assert account.team.id == 5

Note

This requires an AppClient or UserClient with the manage_account_details permission.

You can also chose the permissions to grant the user:

account = await client.create_account(
    id=1234567,
    name='Artemis',
    discriminator='8472',
    team=team,
    permissions=Permissions(
        manage_teams=True, manage_account_details=True
    )
)

Note

In order to grant permissions to a user:

You must be authenticated.
You cannot grant permissions you do not have.
You cannot grant authenticate_users, since that’s not a permission users can have.
You cannot grant permissions unless you have the manage_permissions permission, except as stated below:
You can grant the manage_own_team permission to other members of your own team (as long as you also have manage_own_team).

Editing an account¶

Editing a user’s account can be done with update_account:

account = await client.get_account(41129492792313)
account = await client.update_account(
   account, name='Artemis', discriminator='1231'
)
assert account.name == 'Artemis'

Note

This requires an AppClient or UserClient with the manage_account_details permission.

You can similarly update a user’s team:

account = await client.update_account(account, team=team)

Note

This requires an AppClient or UserClient with the manage_account_teams permission, or a UserClient authenticated with the given account.

Or you can remove a user from a team, using the NO_TEAM constant:

account = await client.update_account(account, team=polympics.NO_TEAM)

Note

This requires permissions as explained above for adding a user to a team, with the addition that you can remove a user from a team if you are a member of that team and have the manage_own_team permission.

You can also update user permissions with the grant_permissions and revoke_permissions args, subject to the rules outlined in “Creating an account”.

Example:

account = await client.update_account(
    account, grant_permissions=Permissions(manage_own_team=True),
    revoke_permissions=Permissions(manage_teams=True)
)

Using the discord_token parameter, you can update a user’s name, discriminator and avatar URL to match Discord. This requires no permissions, since user tokens can be authenticated with Discord.

Example:

account = await client.update_account(account, discord_token=token)

Deleting an account¶

You can delete a user’s account with the delete_account method:

account = await client.get_account(124214913289)
await client.delete_account(account)

Note

This requires an AppClient or UserClient with the manage_account_details permission, or just a UserClient associated with the given account.

Creating a team¶

You can create a team using the create_team method. It accepts one parameter, name, for the team’s name:

team = await client.create_team('Gods of Olympus')
assert team.name == 'Gods of Olympus'

Note

This requires an AppClient or UserClient with the manage_teams permission.

Editing a team¶

You can edit a team using the update_team method. It accepts the same name parameter as create_team:

team = await client.get_team(13)
team = await client.update_team(team, name='Cool Kidz')
assert team.name == 'Cool Kidz'

Note

This requires an AppClient or UserClient with the manage_teams permission, or just a UserClient with the manage_own_team permission who is a member of the given team.

Deleting a team¶

You can delete a team with the delete_team method. It accepts a single argument, the team to delete:

team = await client.get_team(28)
await client.delete_team(team)

Note

This requires an AppClient or UserClient with the manage_teams permission, or just a UserClient with the manage_own_team permission who is a member of the given team.