Update docs with more howto examples (#968)

Co-authored-by: Teemu R. <tpr@iki.fi>

kasa/interfaces/light.py

@@ -1,4 +1,64 @@
-"""Module for Device base class."""
+"""Interact with a TPLink Light.
+
+>>> from kasa import Discover, Module
+>>>
+>>> dev = await Discover.discover_single(
+>>>     "127.0.0.3",
+>>>     username="user@example.com",
+>>>     password="great_password"
+>>> )
+>>> await dev.update()
+>>> print(dev.alias)
+Living Room Bulb
+
+Lights, like any other supported devices, can be turned on and off:
+
+>>> print(dev.is_on)
+>>> await dev.turn_on()
+>>> await dev.update()
+>>> print(dev.is_on)
+True
+
+Get the light module to interact:
+
+>>> light = dev.modules[Module.Light]
+
+You can use the ``is_``-prefixed properties to check for supported features:
+
+>>> light.is_dimmable
+True
+>>> light.is_color
+True
+>>> light.is_variable_color_temp
+True
+
+All known bulbs support changing the brightness:
+
+>>> light.brightness
+100
+>>> await light.set_brightness(50)
+>>> await dev.update()
+>>> light.brightness
+50
+
+Bulbs supporting color temperature can be queried for the supported range:
+
+>>> light.valid_temperature_range
+ColorTempRange(min=2500, max=6500)
+>>> await light.set_color_temp(3000)
+>>> await dev.update()
+>>> light.color_temp
+3000
+
+Color bulbs can be adjusted by passing hue, saturation and value:
+
+>>> await light.set_hsv(180, 100, 80)
+>>> await dev.update()
+>>> light.hsv
+HSV(hue=180, saturation=100, value=80)
+
+
+"""
 
 from __future__ import annotations
 

kasa/interfaces/lighteffect.py

@@ -1,4 +1,44 @@
-"""Module for base light effect module."""
+"""Interact with a TPLink Light Effect.
+
+>>> from kasa import Discover, Module, LightState
+>>>
+>>> dev = await Discover.discover_single(
+>>>     "127.0.0.3",
+>>>     username="user@example.com",
+>>>     password="great_password"
+>>> )
+>>> await dev.update()
+>>> print(dev.alias)
+Living Room Bulb
+
+Light effects are accessed via the LightPreset module. To list available presets
+
+>>> if dev.modules[Module.Light].has_effects:
+>>>     light_effect = dev.modules[Module.LightEffect]
+>>> light_effect.effect_list
+['Off', 'Party', 'Relax']
+
+To view the currently selected effect:
+
+>>> light_effect.effect
+Off
+
+To activate a light effect:
+
+>>> await light_effect.set_effect("Party")
+>>> await dev.update()
+>>> light_effect.effect
+Party
+
+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)
+>>> light_effect.has_custom_effects  # The device in this examples does not support \
+custom effects
+False
+"""
 
 from __future__ import annotations
 

kasa/interfaces/lightpreset.py

@@ -1,4 +1,72 @@
-"""Module for LightPreset base class."""
+"""Interact with TPLink Light Presets.
+
+>>> from kasa import Discover, Module, LightState
+>>>
+>>> dev = await Discover.discover_single(
+>>>     "127.0.0.3",
+>>>     username="user@example.com",
+>>>     password="great_password"
+>>> )
+>>> await dev.update()
+>>> print(dev.alias)
+Living Room Bulb
+
+Light presets are accessed via the LightPreset module. To list available presets
+
+>>> light_preset = dev.modules[Module.LightPreset]
+>>> light_preset.preset_list
+['Not set', 'Light preset 1', 'Light preset 2', 'Light preset 3',\
+ 'Light preset 4', 'Light preset 5', 'Light preset 6', 'Light preset 7']
+
+To view the currently selected preset:
+
+>>> light_preset.preset
+Not set
+
+To view the actual light state for the presets:
+
+>>> len(light_preset.preset_states_list)
+7
+
+>>> light_preset.preset_states_list[0]
+LightState(light_on=None, brightness=50, hue=0,\
+ saturation=100, color_temp=2700, transition=None)
+
+To set a preset as active:
+
+>>> dev.modules[Module.Light].state  # This is only needed to show the example working
+LightState(light_on=True, brightness=100, hue=0,\
+ saturation=100, color_temp=2700, transition=None)
+>>> await light_preset.set_preset("Light preset 1")
+>>> await dev.update()
+>>> light_preset.preset
+Light preset 1
+>>> dev.modules[Module.Light].state  # This is only needed to show the example working
+LightState(light_on=True, brightness=50, hue=0,\
+ saturation=100, color_temp=2700, transition=None)
+
+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,\
+ saturation=100, color_temp=2700, transition=None)
+>>>     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
+Not set
+>>> light_preset.preset_states_list[0]
+LightState(light_on=None, brightness=75, hue=0,\
+ saturation=100, color_temp=2700, transition=None)
+
+If you manually set the light state to a preset state it will show that preset as \
+    active:
+
+>>> await dev.modules[Module.Light].set_brightness(75)
+>>> await dev.update()
+>>> light_preset.preset
+Light preset 1
+"""
 
 from __future__ import annotations