pychallonge

Lightweight Python wrapper for the Challonge API. The pychallonge module was created by Russ Amos and maintained by George Lemanis

Python version support

• 3.10 or later

Installation

The pychallonge package is available on PyPI and you can install it through your favorite package manager:

pip install pychallonge

Usage

from challonge import Client

# Create a client with your Challonge API credentials.
client = Client(user="your_challonge_username", api_key="your_api_key")

# Retrieve a tournament by its id (or its url).
tournament = client.tournaments.show(3272)

# Tournaments, matches, and participants are returned as typed dataclasses.
print(tournament.id)          # 3272
print(tournament.name)        # My Awesome Tournament
print(tournament.started_at)  # None

# Retrieve the participants for a given tournament.
participants = client.participants.index(tournament.id)
print(len(participants))  # 13

# Mutations (POST/PUT) return the updated resource directly.
tournament = client.tournaments.start(tournament.id)
print(tournament.started_at)  # 2011-07-31 16:16:02-04:00

# Close the client when done, or use it as a context manager.
client.close()

Context manager

with Client(user="your_challonge_username", api_key="your_api_key") as client:
    tournament = client.tournaments.show(3272)

Async

from challonge import AsyncClient

async with AsyncClient(user="your_challonge_username", api_key="your_api_key") as client:
    tournament = await client.tournaments.show(3272)
    participants = await client.participants.index(tournament.id)

Timezone

By default datetime fields are normalised to your machine's local timezone. Pass a timezone string to override:

client = Client(user="your_challonge_username", api_key="your_api_key", timezone="UTC")

See challonge.com for full API documentation.

API Issues

The Challonge API has some issues with the attachments endpoints. When uploading an attachment with a file (asset), the API returns a 500 internal server error. This issue has been reported to Challonge.

The check-in undo endpoint has unexpected behaviour: the checked_in field in the API response remains True even after a successful undo. The participant is correctly marked as not checked in on the website.

Running the tests

Tests make real API calls and require a Challonge account. Set CHALLONGE_USER and CHALLONGE_KEY in your environment before running.

$ git clone https://github.com/ZEDGR/pychallonge
$ cd pychallonge
$ CHALLONGE_USER=my_user CHALLONGE_KEY=my_api_key uv run pytest tests.py -v

Note that several tournaments are created and destroyed over the course of the tests. If any test fails mid-run, orphaned tournaments can be cleaned up as follows:

from challonge import Client

with Client(user="my_user", api_key="my_api_key") as client:
    for t in client.tournaments.index():
        if t.name.startswith("pychal"):
            client.tournaments.destroy(t.id)