From d18770a3eed5c7ee2ac2466ace1fcc37f61647cc Mon Sep 17 00:00:00 2001 From: MountainGod2 Date: Fri, 1 Nov 2024 13:43:31 -0600 Subject: [PATCH] docs: Update Chaturbate Poller description and features in README.md --- README.md | 60 +++++++++++++++++++++++++------------------------------ 1 file changed, 27 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index b2b2b90c..d5c868ea 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,25 @@ # Chaturbate Poller -**Chaturbate Poller** is a Python library for interacting with the Chaturbate API. It allows you to poll events asynchronously, handle various event types, and optionally store event data in InfluxDB for further analysis or monitoring. +**Chaturbate Poller** is a Python library and CLI for polling events from the Chaturbate API. It provides asynchronous event handling, logging, and optional integration with InfluxDB to store event data for analysis. [![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/) [![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/) [![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) -[![Workflow Status](https://img.shields.io/github/actions/workflow/status/MountainGod2/chaturbate_poller/ci-cd-build.yml?branch=main&link=https%3A%2F%2Fgithub.com%2FMountainGod2%2Fchaturbate_poller%2Factions%2Fworkflows%2Fci-cd-build.yml)](https://github.com/MountainGod2/chaturbate_poller/actions/workflows/ci-cd-build.yml/) +[![Workflow Status](https://img.shields.io/github/actions/workflow/status/MountainGod2/chaturbate_poller/docker-build.yml?branch=main&link=https%3A%2F%2Fgithub.com%2FMountainGod2%2Fchaturbate_poller%2Factions%2Fworkflows%2Fdocker-build.yml)](https://github.com/MountainGod2/chaturbate_poller/actions/workflows/docker-build.yml/) [![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) [![Python Version](https://img.shields.io/pypi/pyversions/chaturbate-poller?link=https%3A%2F%2Fwww.python.org%2Fdownloads%2F)](https://www.python.org/downloads/) [![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/) ## Features -- **Event Polling**: Fetch events from the Chaturbate API using Python's asyncio. -- **Error Handling**: Includes retry logic for basic error handling during polling. -- **Optional Logging**: Configurable logging to keep track of polling activity. -- **InfluxDB Support**: Optionally store events in InfluxDB if data storage is required. +- **Event Polling**: Efficiently poll events from Chaturbate’s API. +- **Error Handling**: Includes backoff and retry mechanisms. +- **Logging**: Console and JSON file logging for structured insights. +- **Optional InfluxDB Storage**: Store events in InfluxDB for analysis or monitoring. ## Installation -Make sure you have Python 3.11 or later installed, then install the package: +Ensure Python 3.11 or later is installed, then install via pip: ```bash pip install chaturbate-poller @@ -27,7 +27,7 @@ pip install chaturbate-poller ## Configuration -To get started, create a `.env` file in the root of your project directory. This file will store your API credentials and (if applicable) InfluxDB connection details: +Create a `.env` file in your project’s root directory for API and InfluxDB credentials: ```text CB_USERNAME="your_chaturbate_username" @@ -36,34 +36,31 @@ INFLUXDB_URL="http://influxdb:8086" INFLUXDB_TOKEN="your_influxdb_token" INFLUXDB_ORG="chaturbate-poller" INFLUXDB_BUCKET="your_bucket" -USE_DATABASE="true" # Enable if you plan to use InfluxDB +USE_DATABASE="false" # Set to `true` if InfluxDB is used ``` > [!NOTE] -> To create an API token, click here: [https://chaturbate.com/statsapi/authtoken/](https://chaturbate.com/statsapi/authtoken/) - -> [!IMPORTANT] -> Ensure you have the "**Events API**" permission selected before generating +> [Generate an API token here](https://chaturbate.com/statsapi/authtoken/) with the "Events API" permission enabled. ## Usage -### Command-Line Tool +### CLI -You run Chaturbate Poller directly from the command line: +Start the poller from the command line: ```bash -python -m chaturbate_poller --username --token +python -m chaturbate_poller start --username --token ``` -For more options: +For additional options: ```bash python -m chaturbate_poller --help ``` -### Docker Usage +### Docker -To run Chaturbate Poller in a Docker container: +Run Chaturbate Poller in Docker: ```bash docker pull ghcr.io/mountaingod2/chaturbate_poller:latest @@ -76,13 +73,12 @@ docker run \ ghcr.io/mountaingod2/chaturbate_poller:latest --verbose --testbed ``` -### Library Example +### Library Usage -You can also import it into your programs. Here’s a simple example of how to fetch events in a loop using the library asynchronously: +To use Chaturbate Poller as a library, here's a sample script to fetch events in a loop: ```python import asyncio - from chaturbate_poller import ChaturbateClient async def main(): @@ -91,9 +87,7 @@ async def main(): while True: response = await client.fetch_events(url) for event in response.events: - - # Do something with the received events - print(event.dict()) + print(event.dict()) # Process each event url = response.next_url @@ -101,15 +95,17 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## Development Setup +## Development 1. Clone the repository: + ```bash git clone https://github.com/MountainGod2/chaturbate_poller.git cd chaturbate_poller ``` -2. Install dependencies using [uv](https://docs.astral.sh/uv/): +2. Set up the environment and dependencies using [uv](https://docs.astral.sh/uv/): + ```bash uv venv .venv uv pip install -e . @@ -117,14 +113,12 @@ if __name__ == "__main__": ## Contributing -Contributions are welcome! If you'd like to contribute: +Contributions are welcome! To contribute: 1. Fork the repository. -2. Create a new feature branch. -3. Submit a pull request. - -Please ensure that any changes pass tests and follow coding guidelines. +2. Create a feature branch. +3. Submit a pull request, ensuring tests and coding standards are met. ## License -This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more information. +This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.