Metadata-Version: 2.4
Name: festivalapi
Version: 0.2.2
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("fes_your_api_key")

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

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

# Get festival roster (past winners / screened films)
roster = client.festivals.roster(1)

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

# List available category codes (requires auth)
categories = client.categories()
for cat in categories["results"]:
    print(f'{cat["category"]} ({cat["count"]})')

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

## Categories

Call `client.categories()` to get all available category codes. Returns:

```python
{
  "count": 158,
  "results": [
    {"category": "short_film", "count": 60},
    {"category": "feature", "count": 55},
    {"category": "documentary", "count": 31},
    {"category": "animation", "count": 14},
    {"category": "horror", "count": 12},
    {"category": "experimental", "count": 10},
    {"category": "ai", "count": 10},
    {"category": "music_video", "count": 14},
    {"category": "web_series", "count": 9},
    {"category": "comedy", "count": 5},
    {"category": "sci_fi", "count": 5},
    {"category": "student", "count": 5},
    {"category": "lgbtq", "count": 3},
    {"category": "vr_360", "count": 2},
    ...
  ]
}
```

Common filters: `short_film`, `feature`, `documentary`, `animation`, `horror`, `sci_fi`, `comedy`, `experimental`, `music_video`, `ai`, `web_series`, `student`, `lgbtq`, `vr_360`.

Use the `category` field (lowercase) as the filter value — e.g. `client.festivals.list(category="horror")`.

## API Key

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

## Error Handling

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

client = FestivalAPI("fes_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
