Metadata-Version: 2.4
Name: pychallonge
Version: 3.0.0
Summary: Lightweight Python wrapper for the Challonge API
Project-URL: Homepage, https://github.com/ZEDGR/pychallonge
Author-email: ZEDGR <georlema@gmail.com>
License: Copyright (c) 2011, Russ Amos
        Copyright (c) 2024, George Lemanis
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
            Redistributions of source code must retain the above copyright notice, this
            list of conditions and the following disclaimer.
        
            Redistributions in binary form must reproduce the above copyright notice,
            this list of conditions and the following disclaimer in the documentation
            and/or other materials provided with the distribution.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
        ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
        LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
        CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
        SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
        INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
        CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
        ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
        THE POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE
Keywords: api,challonge,tournaments
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Requires-Dist: httpx>=0.28.1
Requires-Dist: iso8601>=2.1.0
Requires-Dist: tzlocal>=5.3.1
Description-Content-Type: text/markdown

# pychallonge

Lightweight Python wrapper for the [Challonge API](http://api.challonge.com/v1).
The pychallonge module was created by [Russ Amos](https://github.com/russ-) and maintained by [George Lemanis](https://github.com/ZEDGR)

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

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

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

### Async

```python
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:

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

See [challonge.com](http://api.challonge.com/v1) 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:

```python
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)
```
