{"id":22845267,"url":"https://github.com/mountaingod2/chaturbate_poller","last_synced_at":"2025-04-28T16:44:24.125Z","repository":{"id":230777967,"uuid":"780153014","full_name":"MountainGod2/chaturbate_poller","owner":"MountainGod2","description":"Python package for fetching and processing events from the Chaturbate Events API.","archived":false,"fork":false,"pushed_at":"2025-04-21T11:03:04.000Z","size":9075,"stargazers_count":5,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-04-21T11:43:47.944Z","etag":null,"topics":["api-client","chaturbate","chaturbate-api","chaturbate-apps","longpoll","python3"],"latest_commit_sha":null,"homepage":"https://chaturbate-poller.readthedocs.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MountainGod2.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-03-31T20:58:21.000Z","updated_at":"2025-04-21T10:57:48.000Z","dependencies_parsed_at":"2024-04-15T16:28:09.205Z","dependency_job_id":"e69dd67c-5afa-4efc-9964-83e4f6d2f26c","html_url":"https://github.com/MountainGod2/chaturbate_poller","commit_stats":null,"previous_names":["mountaingod2/chaturbate_poller"],"tags_count":251,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MountainGod2%2Fchaturbate_poller","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MountainGod2%2Fchaturbate_poller/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MountainGod2%2Fchaturbate_poller/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MountainGod2%2Fchaturbate_poller/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MountainGod2","download_url":"https://codeload.github.com/MountainGod2/chaturbate_poller/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251347898,"owners_count":21575176,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-client","chaturbate","chaturbate-api","chaturbate-apps","longpoll","python3"],"created_at":"2024-12-13T03:16:36.932Z","updated_at":"2025-04-28T16:44:24.120Z","avatar_url":"https://github.com/MountainGod2.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Chaturbate Poller\n\n[![Read the Docs](https://img.shields.io/readthedocs/chaturbate-poller?link=https%3A%2F%2Fchaturbate-poller.readthedocs.io%2Fen%2Fstable%2F)](https://chaturbate-poller.readthedocs.io/en/stable/)\n[![Codecov Coverage](https://img.shields.io/codecov/c/github/MountainGod2/chaturbate_poller/main?link=https%3A%2F%2Fapp.codecov.io%2Fgh%2FMountainGod2%2Fchaturbate_poller)](https://app.codecov.io/gh/MountainGod2/chaturbate_poller/)\n[![CodeFactor Grade](https://img.shields.io/codefactor/grade/github/MountainGod2/chaturbate_poller?link=https%3A%2F%2Fwww.codefactor.io%2Frepository%2Fgithub%2Fmountaingod2%2Fchaturbate_poller)](https://www.codefactor.io/repository/github/mountaingod2/chaturbate_poller)\n[![Workflow Status](https://img.shields.io/github/actions/workflow/status/MountainGod2/chaturbate_poller/cd.yml?branch=main\u0026link=https%3A%2F%2Fgithub.com%2FMountainGod2%2Fchaturbate_poller%2Factions%2Fworkflows%2Fcd.yml)](https://github.com/MountainGod2/chaturbate_poller/actions/workflows/cd.yml/)\n[![License](https://img.shields.io/pypi/l/chaturbate-poller?link=https%3A%2F%2Fgithub.com%2FMountainGod2%2Fchaturbate_poller)](https://github.com/MountainGod2/chaturbate_poller?tab=MIT-1-ov-file)\n\n[![Python Version](https://img.shields.io/pypi/pyversions/chaturbate-poller?link=https%3A%2F%2Fwww.python.org%2Fdownloads%2F)](https://www.python.org/downloads/)\n[![PyPI Version](https://img.shields.io/pypi/v/chaturbate-poller?link=https%3A%2F%2Fpypi.org%2Fproject%2Fchaturbate-poller%2F)](https://pypi.org/project/chaturbate-poller/)\n[![Docker Image Version](https://img.shields.io/docker/v/mountaingod2/chaturbate_poller?sort=semver\u0026label=docker\u0026link=https%3A%2F%2Fhub.docker.com%2Fr%2Fmountaingod2%2Fchaturbate_poller)](https://hub.docker.com/r/mountaingod2/chaturbate_poller)\n[![Docker Image Size](https://img.shields.io/docker/image-size/mountaingod2/chaturbate_poller?sort=semver\u0026arch=amd64\u0026link=https%3A%2F%2Fhub.docker.com%2Fr%2Fmountaingod2%2Fchaturbate_poller%2Ftags)](https://hub.docker.com/r/mountaingod2/chaturbate_poller)\n\n\u003c/div\u003e\n\nPython library and CLI tool for interacting with the Chaturbate Events API. Monitor and analyze chat activity, tips, room status changes, and other events in real-time with support for structured logging, automated error handling, and optional InfluxDB integration.\n\n## Features\n\n- **Real-time Event Tracking**\n  - Monitor chat messages, tips, room status changes, and other events\n  - Configurable polling intervals with automatic rate limiting\n  - Support for both production and testbed environments\n\n- **Robust Error Handling**\n  - Automatic retries with exponential backoff for transient errors\n  - Detailed error classification and reporting\n  - Connection recovery after network interruptions\n\n- **Comprehensive Logging**\n  - Structured JSON logs for machine parsing\n  - Console-friendly output with rich formatting\n  - Configurable verbosity levels for debugging\n\n- **Data Persistence \u0026 Analytics**\n  - Optional InfluxDB integration for time-series storage\n  - Pre-configured sample queries for common analytics use cases\n  - Efficient data retention policies for long-term storage\n\n## Installation\n\nHere are a few ways to install the package:\n\n### Using uv (Recommended)\n\nInstall with [uv](https://github.com/astral-sh/uv):\n\n```bash\nuv pip install chaturbate-poller\n```\n\n### Using pip\n\nMake sure you have Python 3.12+ installed:\n\n```bash\n# Create and activate virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate\n\n# Install the package\npip install chaturbate-poller\n```\n\n### Using uvx (CLI tool isolation)\n\nRun the CLI without installing it in your Python environment:\n\n```bash\nuvx chaturbate_poller start\n```\n\n### Environment Configuration (Optional)\n\nCreate a `.env` file with your credentials:\n\n```ini\n# Required for API access\nCB_USERNAME=\"your_chaturbate_username\"\nCB_TOKEN=\"your_chaturbate_token\"\n\n# Optional: InfluxDB settings (if using --database flag)\nINFLUXDB_URL=\"http://influxdb:8086\"\nINFLUXDB_TOKEN=\"your_influxdb_token\"\nINFLUXDB_ORG=\"chaturbate-poller\"\nINFLUXDB_BUCKET=\"my-bucket\"\nUSE_DATABASE=\"false\"  # Set to \"true\" to enable InfluxDB integration\n```\n\n**API Token:** You'll need to generate your token at [chaturbate.com/statsapi/authtoken/](https://chaturbate.com/statsapi/authtoken/) with \"Events API\" permission enabled.\n\n## Quick Start\n\n```bash\n# With uv\nuv run chaturbate_poller start --username your_username --token your_token\n\n# Using testbed mode (for development/testing)\nuv run chaturbate_poller start --testbed --verbose\n\n# With pip installation\npython -m chaturbate_poller start --username your_username --token your_token\n```\n\n## Usage\n\n### CLI Usage\n\n```bash\nchaturbate_poller start [OPTIONS]\n```\n\n#### Common Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--username TEXT` | Your Chaturbate username | From `.env` file |\n| `--token TEXT` | Your API token | From `.env` file |\n| `--timeout FLOAT` | API request timeout in seconds | 10.0 |\n| `--database / --no-database` | Enable InfluxDB integration | Disabled |\n| `--testbed / --no-testbed` | Use testbed environment | Disabled |\n| `--verbose / --no-verbose` | Enable detailed logging | Disabled |\n| `--help` | Show help message and exit | |\n\nFor a complete list of the available CLI options:\n\n```bash\nchaturbate_poller --help\n```\n\n### Docker\n\nRun the poller in a container with all dependencies included:\n\n```bash\n# Pull the latest image\ndocker pull ghcr.io/mountaingod2/chaturbate_poller:latest\n\n# Run with environment variables\ndocker run -d \\\n  --name chaturbate-poller \\\n  -e CB_USERNAME=\"your_chaturbate_username\" \\\n  -e CB_TOKEN=\"your_chaturbate_token\" \\\n  -v /path/to/host/logs:/app/logs \\\n  ghcr.io/mountaingod2/chaturbate_poller:latest --verbose\n```\n\nIf you do not specify the `-v /path/to/host/logs:/app/logs` option, logs will still be written to `/app/logs` inside the container, but they will not persist after the container is removed.\n\n### Docker Compose\n\nFor a complete setup including InfluxDB for data persistence:\n\n1. **Clone the configuration:**\n\n   ```bash\n   # Copy the example environment file\n   cp .env.example .env\n\n   # Edit with your credentials\n   nano .env\n   ```\n\n2. **Launch the services:**\n\n   ```bash\n   docker-compose up -d\n   ```\n\n3. **Pass additional arguments**:\n\n   ```bash\n   POLLER_ARGS=\"--verbose --testbed\" docker-compose up -d\n   ```\n\n4. **Access InfluxDB** at [http://localhost:8086](http://localhost:8086)\n\n## InfluxDB Integration\n\nWhen enabled with the `--database` flag, events are stored in InfluxDB for analytics and visualization.\n\n### Sample Queries\n\nHere are some useful InfluxDB Flux queries to analyze your Chaturbate data:\n\n```text\n// Event count by type (last 24 hours)\nfrom(bucket: \"events\")\n  |\u003e range(start: -24h)\n  |\u003e filter(fn: (r) =\u003e r._measurement == \"chaturbate_events\")\n  |\u003e filter(fn: (r) =\u003e r._field == \"method\")\n  |\u003e group(columns: [\"_value\"])\n  |\u003e count()\n  |\u003e sort(columns: [\"_value\"], desc: true)\n\n// Total tips received (last 7 days)\nfrom(bucket: \"events\")\n  |\u003e range(start: -7d)\n  |\u003e filter(fn: (r) =\u003e r._measurement == \"chaturbate_events\")\n  |\u003e filter(fn: (r) =\u003e r.method == \"tip\")\n  |\u003e filter(fn: (r) =\u003e r._field == \"object.tip.tokens\")\n  |\u003e sum()\n\n// Top chatters by message count (last 24 hours)\nfrom(bucket: \"events\")\n  |\u003e range(start: -24h)\n  |\u003e filter(fn: (r) =\u003e r._measurement == \"chaturbate_events\")\n  |\u003e filter(fn: (r) =\u003e r.method == \"chatMessage\")\n  |\u003e filter(fn: (r) =\u003e r._field == \"object.user.username\")\n  |\u003e group(columns: [\"_value\"])\n  |\u003e count()\n  |\u003e sort(columns: [\"_value\"], desc: true)\n  |\u003e limit(n: 10)\n```\n\nFor more examples, check out the `/config/chaturbate_poller/influxdb_queries.flux` file.\n\n## Programmatic Usage\n\nYou can integrate the library into your own Python applications:\n\n### Basic Example\n\n```python\nimport asyncio\nfrom chaturbate_poller import ChaturbateClient\n\nasync def main():\n    async with ChaturbateClient(\"your_username\", \"your_token\") as client:\n        url = None\n        while True:\n            response = await client.fetch_events(url)\n            for event in response.events:\n                # Process each event\n                print(f\"Event type: {event.method}\")\n                print(event.model_dump_json(indent=2))\n\n            # Use the next URL for pagination\n            url = response.next_url\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\n### Custom Event Handlers\n\n```python\nimport asyncio\nfrom chaturbate_poller import ChaturbateClient\nfrom chaturbate_poller.models import TipEvent, ChatMessageEvent\n\nasync def handle_tip(event: TipEvent) -\u003e None:\n    \"\"\"Process tip events with custom logic.\"\"\"\n    username = event.object.user.username\n    amount = event.object.tip.tokens\n    print(f\"Received {amount} tokens from {username}!\")\n\n    # Trigger special actions based on tip amount\n    if amount \u003e= 100:\n        await send_special_thanks(username)\n\nasync def handle_chat(event: ChatMessageEvent) -\u003e None:\n    \"\"\"Process chat message events.\"\"\"\n    username = event.object.user.username\n    message = event.object.message\n    print(f\"{username}: {message}\")\n\nasync def main():\n    # Register handlers for specific event types\n    handlers = {\n        \"tip\": handle_tip,\n        \"chatMessage\": handle_chat,\n    }\n\n    # Create client with custom handlers\n    async with ChaturbateClient(\n        \"your_username\",\n        \"your_token\",\n        event_handlers=handlers\n    ) as client:\n        # Start polling with automatic handler dispatch\n        await client.poll_events()\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\n### With InfluxDB Integration\n\n```python\nimport asyncio\nfrom chaturbate_poller import ChaturbateClient, InfluxDBWriter\n\nasync def main():\n    # Configure InfluxDB writer\n    influx = InfluxDBWriter(\n        url=\"http://localhost:8086\",\n        token=\"your_influxdb_token\",\n        org=\"your_org\",\n        bucket=\"events\"\n    )\n\n    # Create client with database integration\n    async with ChaturbateClient(\n        \"your_username\",\n        \"your_token\",\n        database_writer=influx\n    ) as client:\n        await client.poll_events()\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\n## Development\n\n### Setup Development Environment\n\n1. **Clone the repository:**\n\n   ```bash\n   git clone https://github.com/MountainGod2/chaturbate_poller.git\n   cd chaturbate_poller\n   ```\n\n2. **Install dependencies:**\n\n   ```bash\n   # Using uv (recommended)\n   uv sync --all-extras\n\n   # Or using pip\n   pip install -e \".[dev,docs]\"\n   ```\n\n3. **Set up pre-commit hooks:**\n\n   ```bash\n   pre-commit install\n   ```\n\n### Running Tests\n\n```bash\n# Run all tests\nuv run pytest\n```\n\n## Documentation\n\n### Building Docs Locally\n\n```bash\n# Install documentation dependencies\nuv sync --extra=docs\n\n# Build HTML documentation\nuv run sphinx-build -b html docs docs/_build/html\n```\n\nThen open `docs/_build/html/index.html` in your browser.\n\n### Online Documentation\n\nVisit the [documentation](https://chaturbate-poller.readthedocs.io/) for Jupyter notebook example and API reference.\n\n## Changelog\n\nView the complete [CHANGELOG.md](CHANGELOG.md) for version history and updates.\n\n## Contributing\n\nContributions are welcome! Here's how to get started:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes with appropriate tests\n4. Run linting and tests (`pre-commit run --all-files`)\n5. Commit your changes (`git commit -m 'Add amazing feature'`)\n6. Push to your branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\nFor more details, please read the [Contributing Guidelines](CONTRIBUTING.md).\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmountaingod2%2Fchaturbate_poller","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmountaingod2%2Fchaturbate_poller","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmountaingod2%2Fchaturbate_poller/lists"}