Metadata-Version: 2.4
Name: theatrical
Version: 0.1.0
Summary: Python SDK for cinema platform APIs. Type-safe async-first client with authentication, rate limiting, retry logic, and mock mode.
Project-URL: Homepage, https://theatrical.dev
Project-URL: Repository, https://github.com/brunohart/theatrical
Project-URL: Documentation, https://github.com/brunohart/theatrical/tree/main/packages/sdk-py
Project-URL: Changelog, https://github.com/brunohart/theatrical/blob/main/packages/sdk-py/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/brunohart/theatrical/issues
Author: designedbybruno
License-Expression: MIT
License-File: LICENSE
Keywords: api,cinema,ocapi,sdk,ticketing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Requires-Dist: twine>=5.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Theatrical SDK for Python

Type-safe async-first Python client for cinema platform APIs. Part of the [Theatrical](https://github.com/brunohart/theatrical) polyglot SDK.

## Install

```bash
pip install theatrical
```

## Status

**Alpha** — all 8 resource modules implemented with full TS API parity. 332 pytest tests passing. mypy strict clean, ruff clean.

## Requirements

- Python 3.10+
- httpx >= 0.27.0
- pydantic >= 2.0.0

## Quick Start

```python
from theatrical import TheatricalClient, TheatricalConfig, TheatricalEnvironment

async with TheatricalClient(TheatricalConfig(
    api_key="your-api-key",
    environment=TheatricalEnvironment.SANDBOX,
)) as client:
    sessions = await client.sessions.list()
```

## Mock Mode

```python
client = TheatricalClient.create_mock()
# Returns pre-defined NZ cinema fixture data — no API key needed
```

## Singleton Pattern

```python
# At startup:
TheatricalClient.set_global(TheatricalConfig(api_key="key"))

# Anywhere:
client = TheatricalClient.global_instance()
```

## Features

- Async-first design with `httpx` and context manager support
- `pydantic` v2 models with automatic camelCase alias support
- 8 resource modules: sessions, sites, films, orders, loyalty, subscriptions, pricing, F&B
- Typed error hierarchy: `AuthenticationError`, `NotFoundError`, `RateLimitError`, `ValidationError`
- Mock mode with NZ cinema fixture data for offline development
- PEP 561 compliant — ships `py.typed` for downstream type checking
- 332 tests, mypy strict, ruff clean

## Development

```bash
pip install -e ".[dev]"
make check  # runs typecheck, lint, test
```

## Disclaimer

This project is an independent, open-source developer toolkit for cinema platform APIs. It is not affiliated with, endorsed by, or officially connected to Vista Group International Ltd or any of its subsidiaries. All product names, trademarks, and registered trademarks are property of their respective owners.
