API Reference¶
This section is generated directly from package docstrings.
Client¶
Async long-poll client for Events API streams.
Handles URL parsing, retries, rate limiting, and nextUrl continuation. Use as an async context manager and async iterator.
Initialize a client from an Events API URL.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
events_url
|
str
|
Full Events API URL provided by upstream. |
required |
config
|
ClientConfig | None
|
Optional client configuration overrides. |
None
|
rate_limiter
|
AsyncLimiter | None
|
Optional shared limiter for multiple clients. |
None
|
close()
async
¶
Close the HTTP session and reset poll state.
Safe to call multiple times. Called automatically by context exit. After close(), the instance cannot be reopened.
Router¶
Dispatch events to registered async handlers.
Wildcard handlers run before type-specific handlers. Exceptions raised by handlers are logged and do not stop dispatch of remaining handlers.
Initialize an empty handler registry.
dispatch(event)
async
¶
Dispatch an event to matching handlers.
Executes wildcard handlers first, then type-specific handlers, in registration order. Handler exceptions are caught, logged, and do not propagate or prevent other handlers from executing.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
event
|
Event
|
Event instance to dispatch to registered handlers. |
required |
Note
Handlers run sequentially. A slow handler will delay all subsequent ones for that event.
on(event_type)
¶
Register a handler for one event type.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
event_type
|
EventType
|
Event category to associate with the handler. |
required |
Returns:
| Type | Description |
|---|---|
Callable[[HandlerFunc], HandlerFunc]
|
Decorator that registers the handler and returns it unchanged. |
on_any(func=None)
¶
on_any(
func: None = None,
) -> Callable[[HandlerFunc], HandlerFunc]
on_any(func: HandlerFunc) -> HandlerFunc
Register a handler for all event types.
Supports both @router.on_any and @router.on_any().
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
func
|
HandlerFunc | None
|
Optional handler when used as |
None
|
Returns:
| Type | Description |
|---|---|
Callable[[HandlerFunc], HandlerFunc] | HandlerFunc
|
Registered handler when |
Configuration¶
Bases: BaseModel
Immutable settings for EventClient.
Controls long-poll timeout, retry backoff, and strict validation mode.
retry_attempts = Field(default=25, ge=1)
class-attribute
instance-attribute
¶
Total attempts including the initial request (must be >= 1).
retry_backoff = Field(default=1.0, ge=0)
class-attribute
instance-attribute
¶
Initial retry delay in seconds.
retry_factor = Field(default=2.0, gt=0)
class-attribute
instance-attribute
¶
Backoff multiplier applied after each retry.
retry_max_delay = Field(default=300.0, ge=0)
class-attribute
instance-attribute
¶
Maximum delay between retries in seconds.
strict_validation = False
class-attribute
instance-attribute
¶
Raise on invalid events vs. skip and log.
timeout = Field(default=10, gt=0)
class-attribute
instance-attribute
¶
Server long-poll timeout in seconds.
validate_delays()
¶
Validate retry delay bounds.
Returns:
| Type | Description |
|---|---|
Self
|
Validated configuration instance. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If retry_max_delay is smaller than retry_backoff. |
Events¶
Bases: BaseEventModel
Top-level event container.
Typed convenience accessors parse nested payload fields on demand and return None for missing or invalid values.
Warning
String fields in payload data are untrusted user input.
broadcaster
property
¶
Broadcaster username, or None if missing or invalid.
data = Field(default_factory=dict, alias='object')
class-attribute
instance-attribute
¶
Event data payload.
id
instance-attribute
¶
Unique identifier for the event.
media
property
¶
Media purchase data if present and valid (MEDIA_PURCHASE only).
message
property
¶
Message data if present and valid.
room_subject
property
¶
Room subject if present and valid (ROOM_SUBJECT_CHANGE only).
tip
property
¶
Tip data if present and valid (TIP events only).
type = Field(alias='method')
class-attribute
instance-attribute
¶
Type of the event.
user
property
¶
User data if present and valid.
model_post_init(context)
¶
Parse and cache all typed sub-models after field initialisation.
Called once by Pydantic during __init__ and model_validate.
Bases: str, Enum
Event type values emitted by the API.
BROADCAST_START = 'broadcastStart'
class-attribute
instance-attribute
¶
Broadcaster has started streaming.
BROADCAST_STOP = 'broadcastStop'
class-attribute
instance-attribute
¶
Broadcaster has stopped streaming.
CHAT_MESSAGE = 'chatMessage'
class-attribute
instance-attribute
¶
Chat message has been sent.
FANCLUB_JOIN = 'fanclubJoin'
class-attribute
instance-attribute
¶
User has joined the fan club.
FOLLOW = 'follow'
class-attribute
instance-attribute
¶
User has followed the broadcaster.
MEDIA_PURCHASE = 'mediaPurchase'
class-attribute
instance-attribute
¶
User has purchased media.
PRIVATE_MESSAGE = 'privateMessage'
class-attribute
instance-attribute
¶
Private message has been sent.
ROOM_SUBJECT_CHANGE = 'roomSubjectChange'
class-attribute
instance-attribute
¶
Room subject or title has changed.
TIP = 'tip'
class-attribute
instance-attribute
¶
User has sent a tip.
UNFOLLOW = 'unfollow'
class-attribute
instance-attribute
¶
User has unfollowed the broadcaster.
USER_ENTER = 'userEnter'
class-attribute
instance-attribute
¶
User has entered the room.
USER_LEAVE = 'userLeave'
class-attribute
instance-attribute
¶
User has left the room.
Bases: BaseEventModel
Payload for chatMessage and privateMessage events.
bg_color = None
class-attribute
instance-attribute
¶
Background color of the message.
color = None
class-attribute
instance-attribute
¶
Text color of the message.
font = None
class-attribute
instance-attribute
¶
Font style of the message.
from_user = None
class-attribute
instance-attribute
¶
Username of the sender.
is_private
property
¶
True if this is a private message.
message
instance-attribute
¶
Content of the message.
orig = None
class-attribute
instance-attribute
¶
Original message content.
to_user = None
class-attribute
instance-attribute
¶
Username of the recipient.
Bases: BaseEventModel
Payload for roomSubjectChange events.
subject
instance-attribute
¶
The room subject or title.
Bases: BaseEventModel
User metadata attached to an event.
color_group = None
class-attribute
instance-attribute
¶
User name-color group.
Known values: "o" (owner), "m" (moderator), "f" (fanclub),
"l" (dark purple), "p" (light purple), "tr" (dark blue),
"t" (light blue), "g" (grey).
fc_auto_renew = False
class-attribute
instance-attribute
¶
Whether the user's fanclub membership is a recurring subscription.
gender = None
class-attribute
instance-attribute
¶
User gender code.
Known values: "m" (male), "f" (female), "c" (couple),
"t" (trans).
has_darkmode = False
class-attribute
instance-attribute
¶
Whether the user has dark mode enabled.
has_tokens = False
class-attribute
instance-attribute
¶
Whether the user has at least 1 token.
in_fanclub = False
class-attribute
instance-attribute
¶
Whether the user is in the fan club.
in_private_show = False
class-attribute
instance-attribute
¶
Whether the user is in the broadcaster's private show.
is_broadcasting = False
class-attribute
instance-attribute
¶
Whether the user is currently broadcasting.
is_follower = False
class-attribute
instance-attribute
¶
Whether the user is a follower.
is_mod = False
class-attribute
instance-attribute
¶
Whether the user is a moderator.
is_owner = False
class-attribute
instance-attribute
¶
Whether the user is the room owner.
is_silenced = False
class-attribute
instance-attribute
¶
Whether the user is silenced.
is_spying = False
class-attribute
instance-attribute
¶
Whether the user is spying on a private show.
language = None
class-attribute
instance-attribute
¶
User's preferred language.
Known values: "de" (German), "en" (English), "es" (Spanish),
"fr" (French), "it" (Italian), "ja" (Japanese),
"ko" (Korean), "pl" (Polish), "pt" (Portuguese),
"ru" (Russian), "zh" (Chinese).
recent_tips = None
class-attribute
instance-attribute
¶
Recent tipping activity bucket.
Possible values: "none", "few", "some", "lots", "tons".
Note
The string value "none" is truthy. Compare explicitly with recent_tips is None versus recent_tips == "none".
subgender = None
class-attribute
instance-attribute
¶
Subgender code when gender is "t".
Possible values: "tf", "tm", "tn". None when not provided.
username
instance-attribute
¶
Display name of the user.
Exceptions¶
Bases: Exception
Base exception for client and API failures.
Carries optional HTTP status and response text details when available.
Initialize error with message and optional HTTP details.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
Human-readable description of the failure. |
required |
status_code
|
int | None
|
Optional HTTP status code returned by the API. |
None
|
response_text
|
str | None
|
Optional raw response body. Truncated to 200 characters to reduce PII exposure in structured exception loggers and error-reporting tools. |
None
|
Bases: EventsError
Authentication failure.
Raised for invalid credentials and malformed authentication URL components.