Chaturbate Poller

Python library and CLI tool for polling events from the Chaturbate API featuring asynchronous event handling, structured logging, and optional InfluxDB integration for analytics and monitoring.

Features

Event Polling: Retrieve real-time events from the Chaturbate API.
Error Handling: Built-in retries, exponential backoff, and error classification.
Logging: Supports structured JSON logs and console outputs for better debugging.
Optional InfluxDB Integration: Store and analyze events using InfluxDB.

Installation

Ensure Python 3.12 or later is installed, then install the package via pip:

pip install chaturbate-poller

Environment Configuration (Optional)

Create a .env file in your project’s root directory with the following:

CB_USERNAME="your_chaturbate_username"
CB_TOKEN="your_chaturbate_token"
INFLUXDB_URL="http://influxdb:8086"
INFLUXDB_TOKEN="your_influxdb_token"
INFLUXDB_ORG="chaturbate-poller"
INFLUXDB_BUCKET="my-bucket"
USE_DATABASE="false"  # Set to `true` if InfluxDB is used

💡 Tip: Generate an API token here with “Events API” permission enabled.

Usage

CLI Usage

Start the poller with the following command:

python -m chaturbate_poller start --username <your_username> --token <your_token>

Common CLI Options

--username: Your Chaturbate username. Defaults to .env file value.
--token: Your API token. Defaults to .env file value.
--timeout: Timeout for API requests (default: 10 seconds).
--database: Enable InfluxDB integration. Defaults to disabled.
--testbed: Enable the testbed environment for testing.
--verbose: Enable detailed logging for debugging.

Run python -m chaturbate_poller --help for a complete list of options.

Docker

To run the poller in Docker, pull the image and start the container:

docker pull ghcr.io/mountaingod2/chaturbate_poller:latest
docker run \
  -e CB_USERNAME="your_chaturbate_username" \
  -e CB_TOKEN="your_chaturbate_token" \
  ghcr.io/mountaingod2/chaturbate_poller:latest --verbose --database

Docker Compose

This project includes a Docker Compose configuration for running the Chaturbate Poller with InfluxDB.

Setup

Create a .env file based on the .env.example template:
```
cp .env.example .env
```
Edit the .env file with your credentials and settings.
Start the services:
```
docker-compose up -d
```

Configuration Options

You can pass additional arguments to the poller service in two ways:

Using environment variables:

POLLER_ARGS="--verbose --testbed --database" docker-compose up -d

Using docker-compose run:

docker-compose run --rm chaturbate_poller --verbose --testbed

Accessing InfluxDB

The InfluxDB interface is available at http://localhost:8086 after startup by default.

InfluxDB Integration

When the --database flag is enabled, events are stored in InfluxDB using the line protocol format. This enables powerful analytics and visualization capabilities.

Sample Queries

The following are examples of useful InfluxDB Flux queries for analyzing your Chaturbate data:

// Count events by method in the last 24 hours
from(bucket: "events")
  |> range(start: -24h)
  |> filter(fn: (r) => r._measurement == "chaturbate_events")
  |> filter(fn: (r) => r._field == "method")
  |> group(columns: ["_value"])
  |> count()

// Calculate total tips received in the last 7 days
from(bucket: "events")
  |> range(start: -7d)
  |> filter(fn: (r) => r._measurement == "chaturbate_events")
  |> filter(fn: (r) => r.method == "tip")
  |> filter(fn: (r) => r._field == "object.tip.tokens")
  |> sum()

// Find most active users in the last 24 hours
from(bucket: "events")
  |> range(start: -24h)
  |> filter(fn: (r) => r._measurement == "chaturbate_events")
  |> filter(fn: (r) => r.method == "chatMessage")
  |> filter(fn: (r) => r._field == "object.user.username")
  |> group(columns: ["_value"])
  |> count()
  |> sort(columns: ["_value"], desc: true)
  |> limit(n: 10)

A complete set of example queries can be found in the /config/chaturbate_poller/influxdb_queries.flux file. These queries can be used directly in the InfluxDB UI or imported into Grafana dashboards.

Programmatic Usage

The library can also be used directly in your Python code:

import asyncio
from chaturbate_poller import ChaturbateClient

async def main():
    async with ChaturbateClient("your_username", "your_token", testbed=False) as client:
        url = None
        while True:
            response = await client.fetch_events(url)
            for event in response.events:

                # Do something with the event
                print(event.model_dump())

            url = response.next_url

if __name__ == "__main__":
    asyncio.run(main())

Development

Setup

Clone the repository:

git clone https://github.com/MountainGod2/chaturbate_poller.git
cd chaturbate_poller

Install dependencies using uv:
```
uv sync --all-extras
```

Running Tests

Run tests with pytest:

uv run pytest

Documentation

Build and preview the documentation locally:

uv sync --extra=docs
uv run sphinx-build -b html docs docs/_build/html

Contributing

Contributions are welcome! Here’s how to get started:

Fork the repository.
Create a feature branch.
Submit a pull request, ensuring it includes tests and adheres to the coding standards.

License

This project is licensed under the MIT License. See the LICENSE file for details.