cb_events.models

Data models for Chaturbate Events API.

This module defines Pydantic models for deserializing and validating events from the Chaturbate Events API. All models are immutable (frozen) and use camelCase aliases to match the API’s JSON format.

Model Hierarchy:

BaseEventModel: Base class with shared configuration. Event: Main event container with type and nested data. User: User information attached to events. Message: Chat or private message content. Tip: Tip transaction details. Media: Media purchase information. RoomSubject: Room subject/title changes.

Example

Accessing nested event data:

event = Event.model_validate(api_response)
if event.type == EventType.TIP and event.tip:
    print(f"Received {event.tip.tokens} tokens")
if event.user:
    print(f"From: {event.user.username}")

Attributes

logger

Logger for the cb_events.models module.

Classes

BaseEventModel	Base model for all event-related data structures.
Event	Event from the Chaturbate Events API.
EventType	Event types from the Chaturbate Events API.
Media	Media purchase transaction details.
Message	Chat or private message content.
RoomSubject	Room subject or title information.
Tip	Tip transaction details.
User	User information attached to events.

Module Contents

class cb_events.models.BaseEventModel(/, **data: Any)

Bases: pydantic.BaseModel

Base model for all event-related data structures.

Provides shared Pydantic configuration for JSON deserialization with camelCase to snake_case conversion and immutability.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class cb_events.models.Event(/, **data: Any)

Bases: BaseEventModel

Event from the Chaturbate Events API.

The main event container that wraps all event types. Use the typed properties to access nested data safely—they return None if data is missing or invalid for the event type.

Example

Safe access to nested data:

if event.type == EventType.TIP:
    if tip := event.tip:
        print(f"Tip: {tip.tokens} tokens")
    if user := event.user:
        print(f"From: {user.username}")

Note

Failures to parse nested model data are logged as a warning and return None. Scalar convenience accessors, such as broadcaster, return None quietly when the value is missing or invalid.

Warning

All string fields in event data (e.g. message.message, user.username, tip.message) originate from untrusted user input and are not sanitized by this library. Escape or validate them before use in HTML, SQL, or shell contexts.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

property broadcaster: str | None

Broadcaster username, or None if missing or invalid.

data: dict[str, object] = None

Event data payload.

id: str

Unique identifier for the event.

property media: Media | None

Media purchase data if present and valid (MEDIA_PURCHASE only).

property message: Message | None

Message data if present and valid.

property room_subject: RoomSubject | None

Room subject if present and valid (ROOM_SUBJECT_CHANGE only).

property tip: Tip | None

Tip data if present and valid (TIP events only).

type: EventType = None

Type of the event.

property user: User | None

User data if present and valid.

class cb_events.models.EventType

Bases: str, enum.Enum

Event types from the Chaturbate Events API.

Each member represents a distinct event category that can be received from the API. Use with Router.on() to register type-specific handlers.

Example

Filtering events by type:

@router.on(EventType.TIP)
async def handle_tip(event: Event) -> None:
    print(f"Tip received: {event.tip.tokens}")

Initialize self. See help(type(self)) for accurate signature.

BROADCAST_START = 'broadcastStart'

Broadcaster has started streaming.

BROADCAST_STOP = 'broadcastStop'

Broadcaster has stopped streaming.

CHAT_MESSAGE = 'chatMessage'

Chat message has been sent.

FANCLUB_JOIN = 'fanclubJoin'

User has joined the fan club.

FOLLOW = 'follow'

User has followed the broadcaster.

MEDIA_PURCHASE = 'mediaPurchase'

User has purchased media.

PRIVATE_MESSAGE = 'privateMessage'

Private message has been sent.

ROOM_SUBJECT_CHANGE = 'roomSubjectChange'

Room subject or title has changed.

TIP = 'tip'

User has sent a tip.

UNFOLLOW = 'unfollow'

User has unfollowed the broadcaster.

USER_ENTER = 'userEnter'

User has entered the room.

USER_LEAVE = 'userLeave'

User has left the room.

class cb_events.models.Media(/, **data: Any)

Bases: BaseEventModel

Media purchase transaction details.

Contains information about a media purchase event.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

id: str

Identifier of the purchased media.

name: str

Name of the purchased media.

tokens: int

Number of tokens spent on the media purchase.

type: Literal['video', 'photos']

Type of the purchased media.

class cb_events.models.Message(/, **data: Any)

Bases: BaseEventModel

Chat or private message content.

Represents message data from chatMessage and privateMessage events.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

bg_color: str | None = None

Background color of the message.

color: str | None = None

Text color of the message.

font: str | None = None

Font style of the message.

from_user: str | None = None

Username of the sender.

property is_private: bool

True if this is a private message.

message: str

Content of the message.

orig: str | None = None

Original message content.

to_user: str | None = None

Username of the recipient.

class cb_events.models.RoomSubject(/, **data: Any)

Bases: BaseEventModel

Room subject or title information.

Contains the updated room subject from roomSubjectChange events.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

subject: str

The room subject or title.

class cb_events.models.Tip(/, **data: Any)

Bases: BaseEventModel

Tip transaction details.

Contains information about a tip event including the amount and optional message.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

is_anon: bool = False

Whether the tip is anonymous.

message: str | None = None

Optional message attached to the tip.

tokens: int

Number of tokens tipped.

class cb_events.models.User(/, **data: Any)

Bases: BaseEventModel

User information attached to events.

Contains details about the user who triggered the event, including display name, membership status, and various flags.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

color_group: str | None = None

Color group of the user.

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: bool = False

Whether the user’s fanclub membership is a recurring subscription.

gender: str | None = None

Gender of the user.

Known values: "m" (male), "f" (female), "c" (couple), "t" (trans).

has_darkmode: bool = False

Whether the user has dark mode enabled.

has_tokens: bool = False

Whether the user has at least 1 token.

in_fanclub: bool = False

Whether the user is in the fan club.

in_private_show: bool = False

Whether the user is in the broadcaster’s private show.

is_broadcasting: bool = False

Whether the user is currently broadcasting.

is_follower: bool = False

Whether the user is a follower.

is_mod: bool = False

Whether the user is a moderator.

is_owner: bool = False

Whether the user is the room owner.

is_silenced: bool = False

Whether the user is silenced.

is_spying: bool = False

Whether the user is spying on a private show.

language: str | None = None

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: Literal['none', 'few', 'some', 'lots', 'tons'] | None = None

How much the user has tipped recently.

Possible values: "none" (no recent tips, no tokens — grey username), "few" (few or no recent tips, has tokens — light blue), "some" (some recent tips — dark blue), "lots" (lots — purple), "tons" (tons — dark purple).

Note

The value "none" is truthy. Compare explicitly with recent_tips is None (field absent) versus recent_tips == "none" (present but no tips).

subgender: Literal['tf', 'tm', 'tn'] | None = None

Subgender of the user (only set when gender is "t" / trans).

Possible values: "tf" (transfemme), "tm" (transmasc), "tn" (non-binary). None when the user is not trans.

username: str

Display name of the user.

cb_events.models.logger

Logger for the cb_events.models module.