signalrgb 0.3.0

A Python client for SignalRGB

🌈 SignalRGB Python Client

A powerful Python client library and CLI for controlling SignalRGB Pro

Features • Installation • Usage • API Reference • Development • Contributing • License

✨ Features

• 📋 List available lighting effects
• 🔍 Get detailed information about specific effects
• 🎨 Apply effects to your devices with ease
• 🖥️ User-friendly command-line interface
• 🐍 Python client library for seamless integration into your projects
• 🔐 Error handling and connection management
• 🔄 Automatic effect caching for improved performance

💻 Installation

You can install the SignalRGB Python Client using pip:

pip install signalrgb

Or if you prefer to use Poetry:

poetry add signalrgb

Prerequisites

• Python 3.12 or higher
• SignalRGB Pro (required for API access)

This library uses the SignalRGB REST API, which is only available in SignalRGB Pro.

🚀 Usage

Command-line Interface

The SignalRGB Python Client comes with an intuitive command-line interface for easy interaction with your SignalRGB setup.

# List all available effects
signalrgb list-effects

# Get details of a specific effect
signalrgb get-effect "Psychedelic Dream"

# Apply an effect
signalrgb apply-effect "Rave Visualizer"

# Get the current effect
signalrgb current-effect

You can also specify a custom host and port:

signalrgb --host hyperia.home --port 16038 list-effects

For a full list of available commands and options, use:

signalrgb --help

Python Library

Integrate the SignalRGB Python Client into your own Python projects with ease:

from signalrgb import SignalRGBClient

# Initialize the client
client = SignalRGBClient(host="hyperia.home", port=16038)

# List all effects
effects = client.get_effects()
for effect in effects:
    print(f"Effect: {effect.attributes.name}")

# Apply an effect
client.apply_effect_by_name("Rain")

# Get current effect
current_effect = client.get_current_effect()
print(f"Current effect: {current_effect.attributes.name}")

Error Handling

The client provides custom exceptions for different types of errors:

from signalrgb import SignalRGBClient, ConnectionError, APIError, EffectNotFoundError

client = SignalRGBClient()

try:
    client.apply_effect_by_name("Non-existent Effect")
except ConnectionError as e:
    print(f"Connection failed: {e}")
except EffectNotFoundError as e:
    print(f"Effect not found: {e}")
except APIError as e:
    print(f"API error occurred: {e}")

📘 API Reference

For detailed information about the available methods and classes, please refer to our API Documentation.

🛠️ Development

To set up the development environment:

1. Clone the repository:

   git clone https://github.com/hyperb1iss/signalrgb-python.git
   cd signalrgb-python
   

2. Install Poetry if you haven't already: pip install poetry
3. Install dependencies: poetry install
4. Activate the virtual environment: poetry shell

To run tests:

pytest

To run linting:

flake8

👥 Contributing

We welcome contributions from the community! Here's how you can help:

1. Fork the repository
2. Create a new branch: git checkout -b feature-branch-name
3. Make your changes and commit them: git commit -m 'Add some feature'
4. Push to the branch: git push origin feature-branch-name
5. Submit a pull request

Please make sure to update tests as appropriate and adhere to the project's coding standards.

📄 License

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

---

📚 Documentation • 🐛 Report Bug • 💡 Request Feature

🙏 Acknowledgements

This project is not officially associated with SignalRGB. It's an independent client library created by the community for the community. Please do not report issues related to this client to the SignalRGB team.

---

Created by Stefanie Jane 🌠

If you find this project helpful, consider buying me a coffee! ☕