Miwory
da232d7461
All checks were successful
Build And Publish Package / publish (push) Successful in 50s
82 lines
2.4 KiB
Markdown
82 lines
2.4 KiB
Markdown
# 🟣 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 TwitchClient(
|
|
client_id="your_id",
|
|
client_secret="your_client_secret",
|
|
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 TwitchClient(...) as twitch:
|
|
# These will be executed as fast as the rate limiter allows
|
|
tasks = [twitch.get_stream(user_login=name) for name in channels]
|
|
streams = await asyncio.gather(*tasks)
|
|
return [s for s in streams if s.is_live]
|
|
|
|
```
|
|
|
|
---
|
|
|
|
## ⚙️ 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"
|
|
|
|
```
|
|
|
|
---
|