Metadata-Version: 2.4
Name: festivalapi
Version: 0.2.0
Summary: Python client for the Festival API — film festival data for developers
Author-email: Festival API <hello@festivalapi.com>
License-Expression: MIT
Project-URL: Homepage, https://festivalapi.com
Project-URL: Documentation, https://festivalapi.com/docs
Project-URL: Repository, https://github.com/rv888/festivalapi_com
Project-URL: Issues, https://github.com/rv888/festivalapi_com/issues
Keywords: film-festival,festival,submissions,film,api
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# Festival API — Python Client

Client library for the [Festival API](https://festivalapi.com).

```bash
pip install festivalapi
```

## Usage

```python
from festivalapi import FestivalAPI

client = FestivalAPI("fda_your_api_key")

# Search festivals
festivals = client.festivals.list(category="short_film")

# Get festival detail
festival = client.festivals.get(1)

# Get festival roster
roster = client.festivals.roster(1)

# Get scored festivals
scored = client.festivals.scored(min_score=70)

# List categories (no auth required)
categories = client.categories()

# Health check (no auth)
client.health()
```

## API Key

Sign up at [festivalapi.com](https://festivalapi.com) to get your API key. You can also set the `FESTIVALAPI_KEY` environment variable.

## Error Handling

```python
from festivalapi import FestivalAPI, NotFoundError, InsufficientCreditsError

client = FestivalAPI("fda_your_api_key")

try:
    festival = client.festivals.get(999999)
except NotFoundError:
    print("Festival not found")
except InsufficientCreditsError as e:
    print(f"Need more credits: {e}")
```

## Requirements

- Python 3.9+
- Zero dependencies (uses only stdlib `urllib`)

## License

MIT
