# 🟣 OxideTwitch

**OxideTwitch** is a specialized Twitch API client built on the [OxideHTTP](https://git.miwory.dev/OxideHTTP/OxideHTTP) core. It combines the speed of Rust with an easy-to-use Pythonic interface, specifically tuned for the rigors of the Twitch Developer ecosystem.

---

## 🔥 Why OxideTwitch?

Twitch's API has strict rate limits and requires constant token management. OxideTwitch handles the heavy lifting for you:

* **⚡ Oxide Core:** Uses `pyreqwest` (Rust) for underlying HTTP calls.
* **🛡️ Distributed Rate Limiting:** Uses your OxideHTTP Redis integration to ensure your bot never hits a `429 Too Many Requests` even across multiple instances.
* **💾 Intelligent Caching:** Automatically caches common lookups (like User IDs or Stream Status) to save your API quota.
* **🏗️ Type-Safe Models:** Fully validated responses using Pydantic models.

---

## 📦 Installation

Ensure you have your Gitea index configured in `uv`, then run:

```bash
uv add oxidetwitch

```

---

## 🛠 Quick Start

### Basic User Lookup

OxideTwitch automatically handles the `base_url` and header injection for you.

```python
import asyncio
from oxidetwitch.api import TwitchAPIClient

async def main():
    async with TwitchAPIClient(
        client_id="your_id",
        client_secret="your_client_secret",
        redirect_uri="https://example.com",
        redis_url="redis://localhost:6379",
    ) as twitch:
        # Get user data (automatically cached if configured)
        users = await twitch.get_users(access_token="access_token", login="Miwowy")
        user = users.data[0]
        print(f"User ID: {user.id} | Description: {user.description}")

asyncio.run(main())

```

### Handling Streams with Rate Limiting

If you are polling 100+ streams, OxideTwitch spaces out the requests using the **GCRA algorithm** to keep your token healthy.

```python
async def poll_streams(channels):
    async with TwitchAPIClient(...) as twitch:
        # These will be executed as fast as the rate limiter allows
        tasks = [twitch.get_streams(..., user_login=name) for name in channels]
        streams = await asyncio.gather(*tasks)

```

---

## ⚙️ Advanced: Using with `uv` and Gitea

Since **OxideTwitch** depends on **OxideHTTP**, ensure your `pyproject.toml` is configured to find both in your private registry:

```toml
[[tool.uv.index]]
name = "OxideTwitch"
url = "https://git.miwory.dev/api/packages/OxideHTTP/pypi/simple"

```

---