171 lines
3.1 KiB
Markdown
171 lines
3.1 KiB
Markdown
# Twitch Client (Async)
|
|
|
|
An internal **async Twitch API client** built on top of **AioHTTPX**, providing typed access to the Twitch **Helix API** and **OAuth2** endpoints with built-in rate limiting and optional caching.
|
|
|
|
---
|
|
|
|
## What it provides
|
|
|
|
* `TwitchAPIClient` — async client for Twitch **Helix API**
|
|
* `TwitchAuthClient` — async client for Twitch **OAuth2**
|
|
* Built on **AioHTTPX** (aiohttp transport, Redis rate limiting & caching)
|
|
* Strongly typed responses using **Pydantic models**
|
|
* Automatic request parameter cleanup (`None` values removed)
|
|
|
|
---
|
|
|
|
## Installation (internal)
|
|
|
|
Configure your private package index, then:
|
|
|
|
```bash
|
|
pip install twitchclient
|
|
```
|
|
|
|
---
|
|
|
|
## Authentication
|
|
|
|
### OAuth helper client
|
|
|
|
```python
|
|
from twitchclient.auth import TwitchAuthClient
|
|
from twitchclient import scopes
|
|
|
|
auth = TwitchAuthClient(
|
|
client_id="CLIENT_ID",
|
|
client_secret="CLIENT_SECRET",
|
|
redirect_uri="https://your.app/callback",
|
|
)
|
|
|
|
url = await auth.create_authorization_code_grant_flow_url(
|
|
scope=[scopes.USER_READ_EMAIL, scopes.CHAT_READ],
|
|
)
|
|
```
|
|
|
|
### App access token
|
|
|
|
```python
|
|
token = await auth.app_access_token()
|
|
print(token.access_token)
|
|
```
|
|
|
|
### User access token
|
|
|
|
```python
|
|
token = await auth.user_access_token(code="AUTH_CODE")
|
|
```
|
|
|
|
---
|
|
|
|
## API Client
|
|
|
|
```python
|
|
from twitchclient.api import TwitchAPIClient
|
|
|
|
client = TwitchAPIClient(
|
|
client_id="CLIENT_ID",
|
|
client_secret="CLIENT_SECRET",
|
|
redirect_uri="https://your.app/callback",
|
|
redis_url="redis://localhost:6379", # optional
|
|
)
|
|
```
|
|
|
|
* Base URL: `https://api.twitch.tv/helix`
|
|
* `Client-Id` header is set automatically
|
|
* Rate limit defaults to **700 req/min** when Redis is enabled
|
|
|
|
---
|
|
|
|
## Example usage
|
|
|
|
### Get channel information
|
|
|
|
```python
|
|
channels = await client.get_channel_information(
|
|
access_token=token.access_token,
|
|
broadcaster_id=123456,
|
|
)
|
|
```
|
|
|
|
### Start a commercial
|
|
|
|
```python
|
|
await client.start_commercial(
|
|
access_token=token.access_token,
|
|
broadcaster_id=123456,
|
|
)
|
|
```
|
|
|
|
### Cached request
|
|
|
|
Caching is controlled via the `X-Cache-TTL` header:
|
|
|
|
```python
|
|
streams = await client.get_streams(
|
|
access_token=token.access_token,
|
|
game_id=509658,
|
|
cache_time=30,
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
## Rate limiting & caching
|
|
|
|
* **Redis-backed**
|
|
* Shared key: `twitch`
|
|
* Enabled automatically when `redis_url` is provided
|
|
* Cache TTL is per-request (`X-Cache-TTL` header)
|
|
|
|
Implementation is inherited from **AioHTTPX transports** .
|
|
|
|
---
|
|
|
|
## Errors
|
|
|
|
All API methods raise typed exceptions:
|
|
|
|
* `ClientError(status_code, message)`
|
|
* `InternalError(status_code, message)`
|
|
|
|
Defined in schema module .
|
|
|
|
---
|
|
|
|
## Scopes
|
|
|
|
OAuth scopes are defined as constants and typed literals:
|
|
|
|
```python
|
|
from twitchclient import scopes
|
|
|
|
scopes.CHANNEL_READ_SUBSCRIPTIONS
|
|
scopes.CHAT_READ
|
|
```
|
|
|
|
See `scopes.py` for the full list .
|
|
|
|
---
|
|
|
|
## Typed responses
|
|
|
|
All successful responses return **Pydantic models**, e.g.:
|
|
|
|
* `ChannelsInformation`
|
|
* `Streams`
|
|
* `Users`
|
|
* `EventsubSubscriptions`
|
|
|
|
Models live in `schema.py` .
|
|
|
|
---
|
|
|
|
## Notes & limitations
|
|
|
|
* Async-only (no sync client)
|
|
* Internal API, no stability guarantees
|
|
* Some endpoints still marked TODO (e.g. Guest Star)
|
|
|
|
---
|