Skip to content

Commit 12aa188

Browse files
hyperb1isshyperb1iss
committed
📝 Update documentation for async API support
Update docs to reflect new asynchronous client functionality Comprehensively overhaul documentation to document the new async API: - Add AsyncSignalRGBClient reference to client API docs - Update models documentation with new response types - Create detailed async_usage.md guide with examples - Modernize UI with emojis and better section organization - Add Home Assistant integration examples - Update code samples with both sync and async patterns - Improve installation instructions for async requirements - Update CLI documentation with new commands This documentation update complements the recent async API addition, providing clear guidance for both synchronous and asynchronous usage patterns.
1 parent 36d7327 commit 12aa188

File tree

9 files changed

+599
-259
lines changed

9 files changed

+599
-259
lines changed

‎docs/api/client.md‎

Lines changed: 51 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# SignalRGB Client API Reference
22

3-
This page provides detailed API documentation for the `SignalRGBClient` class, which is the main interface for interacting with the SignalRGB API.
3+
This page provides detailed API documentation for both the synchronous `SignalRGBClient` class and the asynchronous `AsyncSignalRGBClient` class, which are the main interfaces for interacting with the SignalRGB API.
44

55
## SignalRGBClient
66

@@ -9,33 +9,40 @@ This page provides detailed API documentation for the `SignalRGBClient` class, w
99
show_root_heading: true
1010
show_source: true
1111

12+
## AsyncSignalRGBClient
13+
14+
::: signalrgb.async_client.AsyncSignalRGBClient
15+
options:
16+
show_root_heading: true
17+
show_source: true
18+
1219
## Exceptions
1320

1421
The SignalRGB client defines several custom exceptions for error handling:
1522

16-
::: signalrgb.client.SignalRGBException
23+
::: signalrgb.exceptions.SignalRGBException
1724
options:
1825
show_root_heading: true
1926
show_source: true
2027

21-
::: signalrgb.client.ConnectionError
28+
::: signalrgb.exceptions.ConnectionError
2229
options:
2330
show_root_heading: true
2431
show_source: true
2532

26-
::: signalrgb.client.APIError
33+
::: signalrgb.exceptions.APIError
2734
options:
2835
show_root_heading: true
2936
show_source: true
3037

31-
::: signalrgb.client.NotFoundError
38+
::: signalrgb.exceptions.NotFoundError
3239
options:
3340
show_root_heading: true
3441
show_source: true
3542

36-
## Usage Example
43+
## Usage Examples
3744

38-
Here's a basic example of how to use the SignalRGBClient:
45+
### Synchronous Client Example
3946

4047
```python
4148
from signalrgb import SignalRGBClient
@@ -54,6 +61,42 @@ client.apply_effect_by_name("Rainbow Wave")
5461
# Get current effect
5562
current_effect = client.get_current_effect()
5663
print(f"Current effect: {current_effect.attributes.name}")
64+
65+
# Adjust brightness
66+
client.brightness = 75
67+
print(f"Brightness set to: {client.brightness}")
68+
```
69+
70+
### Asynchronous Client Example
71+
72+
```python
73+
import asyncio
74+
from signalrgb import AsyncSignalRGBClient
75+
76+
async def main():
77+
# Initialize the client using a context manager
78+
async with AsyncSignalRGBClient(host="localhost", port=16038) as client:
79+
# Get all effects
80+
effects = await client.get_effects()
81+
for effect in effects:
82+
print(f"Effect: {effect.attributes.name}")
83+
84+
# Apply an effect
85+
await client.apply_effect_by_name("Rainbow Wave")
86+
87+
# Get current effect
88+
current_effect = await client.get_current_effect()
89+
print(f"Current effect: {current_effect.attributes.name}")
90+
91+
# Adjust brightness
92+
await client.set_brightness(75)
93+
brightness = await client.get_brightness()
94+
print(f"Brightness set to: {brightness}")
95+
96+
# Run the async example
97+
asyncio.run(main())
5798
```
5899

59-
For more detailed usage examples, please refer to the [Python Library Usage](../usage/library.md) guide.
100+
For more detailed usage examples, please refer to:
101+
- [Python Library Usage](../usage/library.md) for the synchronous client
102+
- [Asynchronous Library Usage](../async_usage.md) for the async client

‎docs/api/models.md‎

Lines changed: 127 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -2,63 +2,159 @@
22

33
This page provides detailed API documentation for the data models used in the SignalRGB Python client. These models represent various data structures used in the SignalRGB API, including effects, responses, and error information.
44

5-
## Attributes
5+
## 🔍 Core Models
6+
7+
### Attributes
68

79
::: signalrgb.model.Attributes
810
options:
911
show_root_heading: true
1012
show_source: true
1113

12-
## Links
14+
### Links
1315

1416
::: signalrgb.model.Links
1517
options:
1618
show_root_heading: true
1719
show_source: true
1820

19-
## Effect
21+
### Effect
2022

2123
::: signalrgb.model.Effect
2224
options:
2325
show_root_heading: true
2426
show_source: true
2527

26-
## EffectList
28+
### EffectList
2729

2830
::: signalrgb.model.EffectList
2931
options:
3032
show_root_heading: true
3133
show_source: true
3234

33-
## Error
35+
## 🛠️ State Models
36+
37+
### CurrentState
38+
39+
::: signalrgb.model.CurrentState
40+
options:
41+
show_root_heading: true
42+
show_source: true
43+
44+
### CurrentStateHolder
45+
46+
::: signalrgb.model.CurrentStateHolder
47+
options:
48+
show_root_heading: true
49+
show_source: true
50+
51+
## 📐 Layout Models
52+
53+
### Layout
54+
55+
::: signalrgb.model.Layout
56+
options:
57+
show_root_heading: true
58+
show_source: true
59+
60+
### LayoutList
61+
62+
::: signalrgb.model.LayoutList
63+
options:
64+
show_root_heading: true
65+
show_source: true
66+
67+
### CurrentLayoutHolder
68+
69+
::: signalrgb.model.CurrentLayoutHolder
70+
options:
71+
show_root_heading: true
72+
show_source: true
73+
74+
## 💾 Preset Models
75+
76+
### EffectPreset
77+
78+
::: signalrgb.model.EffectPreset
79+
options:
80+
show_root_heading: true
81+
show_source: true
82+
83+
### EffectPresetList
84+
85+
::: signalrgb.model.EffectPresetList
86+
options:
87+
show_root_heading: true
88+
show_source: true
89+
90+
## ⚠️ Error Models
91+
92+
### Error
3493

3594
::: signalrgb.model.Error
3695
options:
3796
show_root_heading: true
3897
show_source: true
3998

40-
## SignalRGBResponse
99+
## 🔄 Response Models
100+
101+
### SignalRGBResponse
41102

42103
::: signalrgb.model.SignalRGBResponse
43104
options:
44105
show_root_heading: true
45106
show_source: true
46107

47-
## EffectDetailsResponse
108+
### EffectDetailsResponse
48109

49110
::: signalrgb.model.EffectDetailsResponse
50111
options:
51112
show_root_heading: true
52113
show_source: true
53114

54-
## EffectListResponse
115+
### EffectListResponse
55116

56117
::: signalrgb.model.EffectListResponse
57118
options:
58119
show_root_heading: true
59120
show_source: true
60121

61-
## Usage Example
122+
### CurrentStateResponse
123+
124+
::: signalrgb.model.CurrentStateResponse
125+
options:
126+
show_root_heading: true
127+
show_source: true
128+
129+
### LayoutListResponse
130+
131+
::: signalrgb.model.LayoutListResponse
132+
options:
133+
show_root_heading: true
134+
show_source: true
135+
136+
### CurrentLayoutResponse
137+
138+
::: signalrgb.model.CurrentLayoutResponse
139+
options:
140+
show_root_heading: true
141+
show_source: true
142+
143+
### EffectPresetListResponse
144+
145+
::: signalrgb.model.EffectPresetListResponse
146+
options:
147+
show_root_heading: true
148+
show_source: true
149+
150+
### EffectPresetResponse
151+
152+
::: signalrgb.model.EffectPresetResponse
153+
options:
154+
show_root_heading: true
155+
show_source: true
156+
157+
## 💡 Usage Example
62158

63159
Here's a basic example of how to work with these models:
64160

@@ -77,17 +173,27 @@ print(f"Effect name: {effect.attributes.name}")
77173
print(f"Effect description: {effect.attributes.description}")
78174
print(f"Effect uses audio: {effect.attributes.uses_audio}")
79175

80-
# Create a new effect (note: this is just an example, you can't actually create new effects via the API)
81-
new_effect = Effect(
82-
id="custom_effect_1",
83-
type="lighting",
84-
links=Links(apply="/api/v1/effects/custom_effect_1/apply"),
85-
attributes=Attributes(
86-
name="My Custom Effect",
87-
description="A custom lighting effect",
88-
uses_audio=True
89-
)
90-
)
176+
# Extract parameters
177+
parameters = effect.attributes.parameters
178+
for param_name, param_data in parameters.items():
179+
print(f"Parameter: {param_name}")
180+
print(f" Type: {param_data.get('type', 'Unknown')}")
181+
print(f" Value: {param_data.get('value')}")
182+
183+
# Working with async client
184+
import asyncio
185+
from signalrgb import AsyncSignalRGBClient
186+
187+
async def get_effect_info():
188+
async with AsyncSignalRGBClient() as client:
189+
effect = await client.get_effect_by_name("Rainbow Wave")
190+
return effect.attributes.name, effect.id
191+
192+
# Run the async code
193+
name, effect_id = asyncio.run(get_effect_info())
194+
print(f"Got effect: {name} with ID: {effect_id}")
91195
```
92196

93-
For more detailed usage examples, please refer to the [Python Library Usage](../usage/library.md) guide.
197+
For more detailed usage examples, please refer to:
198+
- [Python Library Usage](../usage/library.md) for the synchronous client
199+
- [Asynchronous Library Usage](../async_usage.md) for the async client

0 commit comments

Comments
 (0)