Quickstart
==========

Installing
----------

Install the latest release from PyPI:

.. code-block:: bash

   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.

.. code-block:: python

   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
-----------------

.. code-block:: python

   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
-----------------

.. code-block:: python

   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:

.. code-block:: python

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

Proxy Support
-------------

.. code-block:: python

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

``proxy_auth`` accepts :class:`aiohttp.BasicAuth`.