This project has been archived by its maintainers, and is no longer receiving any updates.
Chaturbate Poller
Python library and CLI for monitoring Chaturbate Events API. Real-time event tracking with automatic error handling and optional InfluxDB integration.
Features
- Real-time event monitoring - Chat messages, tips, room status changes, and user interactions
- Robust error handling - Automatic retries with exponential backoff and connection recovery
- Structured data output - Clean event formatting with type-safe models
- Database integration - Optional InfluxDB support for analytics and time-series data
- Flexible configuration - Environment variables, CLI options, or programmatic setup
Installation
Using uv (recommended)
uv pip install chaturbate-poller
Using pip
pip install chaturbate-poller
CLI without installation
uvx chaturbate_poller start
API Token
Generate your API token at https://chaturbate.com/statsapi/authtoken/ with "Events API" permission.
Quick Start
CLI Usage
# Direct credentials
chaturbate_poller start --username your_username --token your_token
# Testbed environment
chaturbate_poller start --testbed --verbose
# Environment configuration
chaturbate_poller start
Environment Configuration
Create a .env file in your project root:
CB_USERNAME="your_chaturbate_username"
CB_TOKEN="your_chaturbate_token"
# Optional InfluxDB configuration
INFLUXDB_URL="http://influxdb:8086"
INFLUXDB_TOKEN="your_influxdb_token"
INFLUXDB_ORG="chaturbate-poller"
INFLUXDB_BUCKET="events"
Usage
CLI Options
chaturbate_poller start [OPTIONS]
Key options:
--username TEXT- Chaturbate username--token TEXT- API token--timeout FLOAT- Request timeout in seconds (default: 10.0)--database- Enable InfluxDB integration--testbed- Use testbed environment--verbose- Enable detailed logging
Docker
docker run -e CB_USERNAME="username" -e CB_TOKEN="token" \
ghcr.io/mountaingod2/chaturbate_poller:latest --verbose
Docker Compose
cp .env.example .env
# Configure credentials in .env
docker-compose up -d
Programmatic Usage
Basic Client
import asyncio
from chaturbate_poller import ChaturbateClient
async def main():
async with ChaturbateClient("username", "token") as client:
url = None
while True:
response = await client.fetch_events(url)
for event in response.events:
print(f"Event: {event.method}")
print(event.model_dump_json(indent=2))
url = response.next_url
asyncio.run(main())
Event Handling
from chaturbate_poller import ChaturbateClient, format_message
async def process_events():
async with ChaturbateClient("username", "token") as client:
url = None
while True:
response = await client.fetch_events(url)
for event in response.events:
if event.method == "tip":
amount = event.object.tip.tokens
user = event.object.user.username
print(f"Tip: {user} -> {amount} tokens")
elif event.method == "chatMessage":
message = format_message(event)
print(f"Chat: {message}")
url = response.next_url
InfluxDB Integration
Enable with --database flag to store events for analytics. See sample queries for data analysis examples.
Development
git clone https://github.com/MountainGod2/chaturbate_poller.git
cd chaturbate_poller
uv sync --all-extras
uv run pytest
Documentation
Contributing
Pull requests welcome. Fork the repository, create a feature branch, add tests, and submit a PR.
License
1 maintainer
Metadata
1 maintainer
Release files for chaturbate-poller 5.1.8
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| chaturbate_poller-5.1.8.tar.gz | 236.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| chaturbate_poller-5.1.8-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 267.8 kB
Release files / chaturbate_poller-5.1.8.tar.gz
| Download URL | chaturbate_poller-5.1.8.tar.gz |
|---|---|
| Size | 236.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
de25552af2a06f6d5dcdb7ee38b862f91ec9cba333d8b05e8ae551c657414baa
|
|
BLAKE2b-256 checksum How to use checksums |
bff33ea36fd8cd7cc803a4e0f18bbde7ea13e06dc53a07630d4669e8837e4404
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 18, 2025.
Transparency logRelease files / chaturbate_poller-5.1.8-py3-none-any.whl
| Download URL | chaturbate_poller-5.1.8-py3-none-any.whl |
|---|---|
| Size | 31.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1e886f9526c59c6ca1847bbd5892c3d60cd989d3e8fbc6fab76054d72c7e0caf
|
|
BLAKE2b-256 checksum How to use checksums |
0ee75495c0756aa29946065bac36fa1a7cf2fad04f413463dedb9305befbb916
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 18, 2025.
Transparency log
