Skip to content

docs: modernize docstrings across the repository #1682

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ZeliardM wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs: modernize docstrings across the repository #1682

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 17 additions & 14 deletions docs/tutorial.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@

>>> devices = await Discover.discover(username="[email protected]", password="great_password")
>>> for dev in devices.values():
>>> await dev.update()
>>> print(dev.host)
... await dev.update()
... print(dev.host)
127.0.0.1
127.0.0.2
127.0.0.3
Expand Down Expand Up @@ -56,20 +56,23 @@
>>> light.has_feature("hsv")
True
>>> if light.has_feature("hsv"):
>>> print(light.hsv)
... print(light.hsv)
HSV(hue=0, saturation=100, value=50)

You can test if a module is supported by using `get` to access it.

>>> if effect := dev.modules.get(Module.LightEffect):
>>> print(effect.effect)
>>> print(effect.effect_list)
>>> if effect := dev.modules.get(Module.LightEffect):
>>> await effect.set_effect("Party")
>>> await dev.update()
>>> print(effect.effect)
... print(effect.effect)
... print(effect.effect_list)
Off
['Off', 'Party', 'Relax']

You can then interact with the module:

>>> if effect := dev.modules.get(Module.LightEffect):
... _ = await effect.set_effect("Party")
... await dev.update()
... print(effect.effect)
Party

Individual pieces of functionality are also exposed via features which you can access via :attr:`~kasa.Device.features` and will only be present if they are supported.
Expand All @@ -83,14 +86,14 @@
They are useful if you want write code that dynamically adapts as new features are added to the API.

>>> if auto_update := dev.features.get("auto_update_enabled"):
>>> print(auto_update.value)
... print(auto_update.value)
False
>>> if auto_update:
>>> await auto_update.set_value(True)
>>> await dev.update()
>>> print(auto_update.value)
... _ = await auto_update.set_value(True)
... await dev.update()
... print(auto_update.value)
True
>>> for feat in dev.features.values():
>>> print(f"{feat.name}: {feat.value}")
... print(f"{feat.name}: {feat.value}")
Device ID: 0000000000000000000000000000000000000000\nState: True\nSignal Level: 2\nRSSI: -52\nSSID: #MASKED_SSID#\nReboot: <Action>\nDevice time: 2024-02-23 02:40:15+01:00\nBrightness: 50\nCloud connection: True\nHSV: HSV(hue=0, saturation=100, value=50)\nColor temperature: 2700\nAuto update enabled: True\nUpdate available: None\nCurrent firmware version: 1.1.6 Build 240130 Rel.173828\nAvailable firmware version: None\nCheck latest firmware: <Action>\nLight effect: Party\nLight preset: Light preset 1\nSmooth transition on: 2\nSmooth transition off: 2\nOverheated: False
"""
12 changes: 6 additions & 6 deletions kasa/device.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,10 @@
>>> from kasa import Discover
>>>
>>> dev = await Discover.discover_single(
>>> "127.0.0.2",
>>> username="[email protected]",
>>> password="great_password"
>>> )
... "127.0.0.2",
... username="[email protected]",
... password="great_password"
... )
>>>

Most devices can be turned on and off
Expand Down Expand Up @@ -46,7 +46,7 @@
:ref:`modules <module_target>` that you can access via :attr:`~kasa.Device.modules`:

>>> for module_name in dev.modules:
>>> print(module_name)
... print(module_name)
homekit
Energy
schedule
Expand Down Expand Up @@ -81,7 +81,7 @@
added to the API.

>>> for feature_name in dev.features:
>>> print(feature_name)
... print(feature_name)
state
rssi
on_since
Expand Down
8 changes: 4 additions & 4 deletions kasa/deviceconfig.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,10 @@

>>> from kasa import Discover, Device
>>> device = await Discover.discover_single(
>>> "127.0.0.3",
>>> username="[email protected]",
>>> password="great_password",
>>> )
... "127.0.0.3",
... username="[email protected]",
... password="great_password",
... )
>>> print(device.alias) # Alias is None because update() has not been called
None

Expand Down
14 changes: 7 additions & 7 deletions kasa/discover.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
"""Discover TPLink Smart Home devices.

The main entry point for this library is :func:`Discover.discover()`,
The main entry point for this library is :meth:`Discover.discover()`,
which returns a dictionary of the found devices. The key is the IP address
of the device and the value contains ready-to-use, SmartDevice-derived
device object.

:func:`discover_single()` can be used to initialize a single device given its
:meth:`discover_single()` can be used to initialize a single device given its
IP address. If the :class:`DeviceConfig` of the device is already known,
you can initialize the corresponding device class directly without discovery.
Comment thread
ZeliardM marked this conversation as resolved.

Expand All @@ -27,9 +27,9 @@
You can pass username and password for devices requiring authentication

>>> devices = await Discover.discover(
>>> username="[email protected]",
>>> password="great_password",
>>> )
... username="[email protected]",
... password="great_password",
... )
>>> print(len(devices))
6

Expand Down Expand Up @@ -61,8 +61,8 @@
It is also possible to pass a coroutine to be executed for each found device:

>>> async def print_dev_info(dev):
>>> await dev.update()
>>> print(f"Discovered {dev.alias} (model: {dev.model})")
... await dev.update()
... print(f"Discovered {dev.alias} (model: {dev.model})")
>>>
>>> devices = await Discover.discover(on_discovered=print_dev_info, credentials=creds)
Discovered Bedroom Power Strip (model: KP303)
Expand Down
12 changes: 6 additions & 6 deletions kasa/feature.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,10 @@
>>> from kasa import Discover, Module
>>>
>>> dev = await Discover.discover_single(
>>> "127.0.0.3",
>>> username="[email protected]",
>>> password="great_password"
>>> )
... "127.0.0.3",
... username="[email protected]",
... password="great_password"
... )
>>> await dev.update()
>>> print(dev.alias)
Living Room Bulb
Expand All @@ -18,7 +18,7 @@
to the API:

>>> for feature_id, feature in dev.features.items():
>>> print(f"{feature.name} ({feature_id}): {feature.value}")
... print(f"{feature.name} ({feature_id}): {feature.value}")
Device ID (device_id): 0000000000000000000000000000000000000000
State (state): True
Signal Level (signal_level): 2
Expand All @@ -44,7 +44,7 @@
To see whether a device supports a feature, check for the existence of it:

>>> if feature := dev.features.get("brightness"):
>>> print(feature.value)
... print(feature.value)
100

You can update the value of a feature
Expand Down
12 changes: 6 additions & 6 deletions kasa/interfaces/childsetup.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,10 @@
>>> from kasa import Discover, Module, LightState
>>>
>>> dev = await Discover.discover_single(
>>> "127.0.0.6",
>>> username="[email protected]",
>>> password="great_password"
>>> )
... "127.0.0.6",
... username="[email protected]",
... password="great_password"
... )
>>> await dev.update()
>>> print(dev.alias)
Tapo Hub
Expand All @@ -27,7 +27,7 @@
'device_model': 'S200B', 'name': 'I01BU0tFRF9OQU1FIw===='}]

>>> for child in dev.children:
>>> print(f"{child.device_id} - {child.model}")
... print(f"{child.device_id} - {child.model}")
SCRUBBED_CHILD_DEVICE_ID_1 - T310
SCRUBBED_CHILD_DEVICE_ID_2 - T315
SCRUBBED_CHILD_DEVICE_ID_3 - T110
Expand All @@ -38,7 +38,7 @@

>>> await childsetup.unpair("SCRUBBED_CHILD_DEVICE_ID_4")
>>> for child in dev.children:
>>> print(f"{child.device_id} - {child.model}")
... print(f"{child.device_id} - {child.model}")
SCRUBBED_CHILD_DEVICE_ID_1 - T310
SCRUBBED_CHILD_DEVICE_ID_2 - T315
SCRUBBED_CHILD_DEVICE_ID_3 - T110
Expand Down
10 changes: 5 additions & 5 deletions kasa/interfaces/light.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,10 @@
>>> from kasa import Discover, Module
>>>
>>> dev = await Discover.discover_single(
>>> "127.0.0.3",
>>> username="[email protected]",
>>> password="great_password"
>>> )
... "127.0.0.3",
... username="[email protected]",
... password="great_password"
... )
>>> await dev.update()
>>> print(dev.alias)
Living Room Bulb
Expand Down Expand Up @@ -44,7 +44,7 @@
Bulbs supporting color temperature can be queried for the supported range:

>>> if color_temp_feature := light.get_feature("color_temp"):
>>> print(f"{color_temp_feature.minimum_value}, {color_temp_feature.maximum_value}")
... print(f"{color_temp_feature.minimum_value}, {color_temp_feature.maximum_value}")
2500, 6500
>>> await light.set_color_temp(3000)
>>> await dev.update()
Expand Down
12 changes: 6 additions & 6 deletions kasa/interfaces/lighteffect.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,10 @@
>>> from kasa import Discover, Module, LightState
>>>
>>> dev = await Discover.discover_single(
>>> "127.0.0.3",
>>> username="[email protected]",
>>> password="great_password"
>>> )
... "127.0.0.3",
... username="[email protected]",
... password="great_password"
... )
>>> await dev.update()
>>> print(dev.alias)
Living Room Bulb
Expand All @@ -32,8 +32,8 @@
If the device supports it you can set custom effects:

>>> if light_effect.has_custom_effects:
>>> effect_list = { "brightness", 50 }
>>> await light_effect.set_custom_effect(effect_list)
... effect_list = {"brightness": 50}
... await light_effect.set_custom_effect(effect_list)
>>> light_effect.has_custom_effects # The device in this examples does not support \
custom effects
False
Expand Down
12 changes: 6 additions & 6 deletions kasa/interfaces/lightpreset.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,10 @@
>>> from kasa import Discover, Module, LightState
>>>
>>> dev = await Discover.discover_single(
>>> "127.0.0.3",
>>> username="[email protected]",
>>> password="great_password"
>>> )
... "127.0.0.3",
... username="[email protected]",
... password="great_password"
... )
>>> await dev.update()
>>> print(dev.alias)
Living Room Bulb
Expand Down Expand Up @@ -48,9 +48,9 @@
You can save a new preset state if the device supports it:

>>> if light_preset.has_save_preset:
>>> new_preset_state = LightState(light_on=True, brightness=75, hue=0,\
... new_preset_state = LightState(light_on=True, brightness=75, hue=0,\
saturation=100, color_temp=2700, transition=None)
Comment thread
ZeliardM marked this conversation as resolved.
>>> await light_preset.save_preset("Light preset 1", new_preset_state)
... await light_preset.save_preset("Light preset 1", new_preset_state)
>>> await dev.update()
>>> light_preset.preset # Saving updates the preset state for the preset, it does not \
set the preset
Expand Down
Loading
Loading