Quickstart

Installing

Install the latest release from PyPI:

python -m pip install mctiers

Creating a Client

The client is asynchronous and should usually be used as an async context manager. This opens and closes the underlying aiohttp session for you.

import asyncio
import mctiers


async def main() -> None:
    async with mctiers.Client() as client:
        gamemodes = await client.list_gamemodes()
        print(gamemodes.keys())


asyncio.run(main())

Fetching Rankings

async with mctiers.Client() as client:
    players = await client.fetch_overall_rankings(count=10)

    for player in players:
        print(player.name, player.points)

Fetching a Player

async with mctiers.Client() as client:
    player = await client.fetch_player_profile_by_name(
        "ItzRealMe",
        badges=True,
        tests=True,
    )

    print(player.name)
    print(player.points)
    print(player.badges)

Rate Limits and Retries

The HTTP layer automatically retries temporary failures in the same spirit as discord.py’s request loop:

• 429 responses are retried after retry_after, Retry-After, or X-RateLimit-Reset-After when available.

• 500, 502, 504, and 524 responses are retried with backoff.

• Connection reset errors are retried when safe.

You can tune this behavior when constructing the client:

client = mctiers.Client(
    max_retries=5,
    max_ratelimit_timeout=30.0,
)

Proxy Support

client = mctiers.Client(
    proxy_url="http://127.0.0.1:8080",
)

proxy_auth accepts aiohttp.BasicAuth.