opensourcemirror
/
liquidctl
mirror of https://github.com/liquidctl/liquidctl.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

readme: simplify and improve comments in API example

This commit is contained in:
Jonas Malaco 2022-10-21 03:18:32 -03:00
parent ed0ade657f
commit 113a954f29
2 changed files with 52 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
README.md
View File

@ -536,49 +536,44 @@ The APIs are documented, and this documentation can be accessed through
`pydoc`, or directly read from the source files.
```python
from liquidctl import find_liquidctl_devices
from liquidctl import find_liquidctl_devices
first = True
# Find all connected and supported devices.
devices = find_liquidctl_devices()
# find all connected and supported devices
devices = find_liquidctl_devices()
for dev in devices:
for dev in devices:
# Connect to the device. In this example we use a context manager, but
# the connection can also be manually managed. The context manager
# automatically calls `disconnect`; when managing the connection
# manually, `disconnect` must eventually be called, even if an
# exception is raised.
with dev.connect():
print(f'{dev.description} at {dev.bus}:{dev.address}:')
# connect to the device (here a context manager is used, but the
# connection can also be manually managed)
with dev.connect():
print(f'{dev.description} at {dev.bus}:{dev.address}:')
# Devices should be initialized after every boot. In this example
# we assume that this has not been done before.
print('- initialize')
init_status = dev.initialize()
# devices should be initialized after every boot (here we assume
# this has not been done before)
init_status = dev.initialize()
# Print all data returned by `initialize`.
if init_status:
for key, value, unit in init_status:
print(f'- {key}: {value} {unit}')
# print all data returned by initialize()
if init_status:
for key, value, unit in init_status:
print(f'{key}: {value} {unit}')
# Get regular status information from the device.
status = dev.get_status()
# get regular status information from the device
status = dev.get_status()
# Print all data returned by `get_status`.
print('- get status')
for key, value, unit in status:
print(f'- {key}: {value} {unit}')
# print all data returned by get_status()
for key, value, unit in status:
print(f'{key}: {value} {unit}')
# for a particular device, set the pump LEDs to red
if 'Kraken' in dev.description:
print('setting pump to radical red')
radical_red = [0xff, 0x35, 0x5e]
dev.set_color(channel='pump', mode='fixed', colors=[radical_red])
# the context manager took care of automatically calling disconnect();
# when manually managing the connection, disconnect() must be called at
# some point even if an exception is raised
if first:
first = False
print() # add a blank line between each device
# For a particular device, set the pump LEDs to red.
if 'Kraken' in dev.description:
print('- set pump to radical red')
radical_red = [0xff, 0x35, 0x5e]
dev.set_color(channel='pump', mode='fixed', colors=[radical_red])
```
More examples can be found in the scripts in [`extra/`](extra/).

46
tests/test_api.py
View File

@ -25,52 +25,50 @@ def test_entering_the_runtime_context_does_not_call_connect():
def test_modified_readme_example(capsys):
from liquidctl import find_liquidctl_devices
first = True
# find all connected and supported devices on pseudo bus 'virtual'
devices = find_liquidctl_devices(bus='virtual')
# Find all connected and supported devices.
devices = find_liquidctl_devices(bus='virtual') # readme: remove `bus` argument
for dev in devices:
# connect to the device (here a context manager is used, but the
# connection can also be manually managed)
# Connect to the device. In this example we use a context manager, but
# the connection can also be manually managed. The context manager
# automatically calls `disconnect`; when managing the connection
# manually, `disconnect` must eventually be called, even if an
# exception is raised.
with dev.connect():
print(f'{dev.description} at {dev.bus}:{dev.address}:')
# devices should be initialized after every boot (here we assume
# this has not been done before)
# Devices should be initialized after every boot. In this example
# we assume that this has not been done before.
print('- initialize')
init_status = dev.initialize()
# print all data returned by initialize()
# Print all data returned by `initialize`.
if init_status:
for key, value, unit in init_status:
print(f'{key}: {value} {unit}')
print(f'- {key}: {value} {unit}')
# get regular status information from the device
# Get regular status information from the device.
status = dev.get_status()
# print all data returned by get_status()
# Print all data returned by `get_status`.
print('- get status')
for key, value, unit in status:
print(f'{key}: {value} {unit}')
print(f'- {key}: {value} {unit}')
# for a particular device, set the pump LEDs to red
if 'Virtual Bus Device' in dev.description:
print('setting pump to radical red')
# For a particular device, set the pump LEDs to red.
if 'Virtual Bus Device' in dev.description: # readme: replace with 'Kraken'
print('- set pump to radical red')
radical_red = [0xff, 0x35, 0x5e]
dev.set_color(channel='pump', mode='fixed', colors=[radical_red])
# the context manager took care of automatically calling disconnect();
# when manually managing the connection, disconnect() must be called at
# some point even if an exception is raised
if first:
first = False
print() # add a blank line between each device
# end of modified example; check that it more or less did what it should
out, _ = capsys.readouterr()
assert 'Virtual Bus Device (experimental) at virtual:virtual_address:' in out
assert 'initialize' in out
assert 'Firmware version: 3.14.16' in out
assert 'get status' in out
assert 'Temperature: 30.4 °C' in out
assert 'setting pump to radical red' in out
assert 'set pump to radical red' in out