allow async with to be used with a ButtplugClient object

.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Run tests
+        run: uv run pytest tests/ -v
+
+      - name: Run mypy
+        run: uv run mypy src/buttplug/
+
+      - name: Run ruff check
+        run: uv run ruff check src/buttplug/
+
+      - name: Run ruff format check
+        run: uv run ruff format --check src/buttplug/

CHANGELOG.md

@@ -1,3 +1,16 @@
+# 0.3.0 (2022-08-06)
+
+## Breaking Changes
+
+- device_removed_handlers now correctly receive the removed ButtplugClientDevice rather than its integer id.
+
+# 0.2.1 (2021-12-12)
+
+## Bug Fixes
+
+- Change print statements to logging calls so we don't interrupt other libraries.
+- Update to websockets 10 for security issues.
+
 # 0.2.0 (2020-05-10)
 
 ## Bug Fixes

README.md

@@ -1,77 +1,148 @@
-# DEPRECATION WARNING
-
-This project will be deprecated and archived in the coming weeks/months, with
-the Python implementation of buttplug moving to an FFI layer on top of
-buttplug-rs. Bugs are currently being triaged from this library to
-buttplug-rs-ffi.
-
-The new project will be at
-
-[https://github.com/buttplugio/buttplug-rs-ffi/](https://github.com/buttplugio/buttplug-rs-ffi/)
-
-The API will change, though minimally (mostly connection in methods), and we
-will most likely still distribute the pypi package under the same name
-("buttplug").
-
-You may continue to use this repo for the time being, just wanted everyone to be
-aware of the changes happening in the near future.
-
 # buttplug-py
 
 [![PyPi version](https://img.shields.io/pypi/v/buttplug)](http://pypi.org/project/buttplug)
 [![Python version](https://img.shields.io/pypi/pyversions/buttplug)](http://pypi.org/project/buttplug)
 
 [![Patreon donate button](https://img.shields.io/badge/patreon-donate-yellow.svg)](https://www.patreon.com/qdot)
-[![Discourse Forum](https://img.shields.io/badge/discourse-forum-blue.svg)](https://metafetish.club)
 [![Discord](https://img.shields.io/discord/353303527587708932.svg?logo=discord)](https://discord.buttplug.io)
 [![Twitter](https://img.shields.io/twitter/follow/buttplugio.svg?style=social&logo=twitter)](https://twitter.com/buttplugio)
 
-Buttplug-py is a python implementation of the Core and Client portions
-of the Buttplug Sex Toy Control Protocol. It allows users to write
-applications that can connect to Buttplug Servers, such as the
-[Intiface Desktop
-Application](https://github.com/intiface/intiface-desktop) or Intiface
-[C# CLI](https://github.com/intiface/intiface-cli-csharp) or [Node
-CLI](https://github.com/intiface/intiface-cli-node).
+Python client library for the [Buttplug](https://buttplug.io) Intimate Hardware Control Protocol (v4).
 
-A python-based Buttplug server is certainly possible, and may happen
-in the future. For the moment, we are mostly trying to make it easier
-for people to write Buttplug applications in python that can access
-the already existing server implementations.
+## Installation
 
-For more information on the Buttplug project, check out the project
-website at [https://buttplug.io](https://buttplug.io).
+```bash
+pip install buttplug
+```
 
-## Table Of Contents
+Or with [uv](https://github.com/astral-sh/uv):
 
-- [Support The Project](#support-the-project)
-- [Documentation](#documentation)
-- [Examples](#examples)
-- [License](#license)
+```bash
+uv add buttplug
+```
 
-## Support The Project
+## Quick Start
 
-If you find this project helpful, you can [support us via
-Patreon](http://patreon.com/qdot)! Every donation helps us afford more
-hardware to reverse, document, and write code for!
+1. **Install and start [Intiface Central](https://intiface.com/central/)** - This is the server that connects to your devices.
 
-## Documentation
+2. **Connect and control devices:**
+
+```python
+import asyncio
+from buttplug import ButtplugClient, DeviceOutputCommand, OutputType
+
+async def main():
+    # Create a client
+    client = ButtplugClient("My App")
+
+    # Connect to Intiface Central (default address)
+    await client.connect("ws://127.0.0.1:12345")
+
+    # Scan for devices
+    await client.start_scanning()
+    await asyncio.sleep(5)  # Wait for devices to be found
+    await client.stop_scanning()
+
+    # Control devices
+    for device in client.devices.values():
+        print(f"Found: {device.name}")
+
+        if device.has_output(OutputType.VIBRATE):
+            await device.run_output(DeviceOutputCommand(OutputType.VIBRATE, 0.5))
+            await asyncio.sleep(2)
+            await device.stop()
+
+    await client.disconnect()
+
+asyncio.run(main())
+```
+
+## Features
+
+- **Simple API**: Unified `run_output()` method for all output types
+- **Full Protocol Support**: Implements Buttplug protocol v4
+- **Type Hints**: Full typing support for IDE autocomplete and type checking
+- **Async/Await**: Modern Python async API
+- **Event Callbacks**: Get notified when devices connect/disconnect
 
-Library and API Documentation for buttplug-py is available at
+## Device Control
 
-https://buttplug-py.docs.buttplug.io
+```python
+from buttplug import DeviceOutputCommand, OutputType
 
-Other recommended reading includes
+# Check device capabilities and send commands
+if device.has_output(OutputType.VIBRATE):
+    await device.run_output(DeviceOutputCommand(OutputType.VIBRATE, 0.75))
 
-- [The Buttplug Protocol Spec](https://buttplug-spec.docs.buttplug.io)
-- [The Buttplug Developer Guide](https://buttplug-developer-guide.docs.buttplug.io)
+if device.has_output(OutputType.ROTATE):
+    await device.run_output(DeviceOutputCommand(OutputType.ROTATE, 0.5))
+
+if device.has_output(OutputType.POSITION_WITH_DURATION):
+    await device.run_output(
+        DeviceOutputCommand(OutputType.POSITION_WITH_DURATION, 1.0, duration=500)
+    )
+
+# Read sensors
+if device.has_input(InputType.BATTERY):
+    battery = await device.battery()
+    print(f"Battery: {battery * 100:.0f}%")
+
+# Stop device
+await device.stop()
+```
+
+## Event Handling
+
+```python
+# Set up callbacks before connecting
+client.on_device_added = lambda d: print(f"Connected: {d.name}")
+client.on_device_removed = lambda d: print(f"Disconnected: {d.name}")
+client.on_scanning_finished = lambda: print("Scan complete")
+client.on_server_disconnect = lambda: print("Server disconnected!")
+
+# Async callbacks are also supported
+async def on_device_added(device):
+    if device.has_output(OutputType.VIBRATE):
+        await device.run_output(DeviceOutputCommand(OutputType.VIBRATE, 0.25))
+
+client.on_device_added = on_device_added
+```
 
 ## Examples
 
-Example code is available in the examples/ directory. Examples are
-heavily commented to hopefully make usage of the library clearer.
+See the [examples/](examples/) directory for more detailed examples:
+
+- `application.py` - Complete application workflow
+- `connection.py` - Connecting to a server
+- `device_control.py` - Vibrate, rotate, and position commands
+- `device_enumeration.py` - Discovering devices
+- `device_info.py` - Inspecting device features
+- `sensors.py` - Battery and signal strength
+- `errors.py` - Error handling
+
+To run examples from within the repo:
+
+```bash
+uv sync
+uv run python examples/application.py
+```
+
+## Requirements
+
+- Python 3.10+
+- [Intiface Central](https://intiface.com/central/) or another Buttplug server
+
+## Documentation
+
+- [Buttplug Developer Guide](https://docs.buttplug.io)
+- [Protocol Specification](https://docs.buttplug.io/docs/spec)
+
+## Support
+
+- [Discord](https://discord.buttplug.io) - Community chat and support
+- [GitHub Issues](https://github.com/buttplugio/buttplug-py/issues) - Bug reports and feature requests
+- [Patreon](https://patreon.com/qdot) / [GitHub Sponsors](https://github.com/sponsors/qdot) - Support development
 
 ## License
 
-Buttplug is BSD 3-Clause licensed. More information is available in
-the LICENSE file.
+BSD 3-Clause. See [LICENSE](LICENSE) for details.