diff --git a/.flake8 b/.flake8 index c584b928..d4e8f681 100644 --- a/.flake8 +++ b/.flake8 @@ -2,6 +2,7 @@ exclude = .git,.tox,__pycache__,kasa/tests/newfakes.py,kasa/tests/test_fixtures.py max-line-length = 88 per-file-ignores = - kasa/tests/*.py:D100,D101,D102,D103,D104 + kasa/tests/*.py:D100,D101,D102,D103,D104,F401 + docs/source/conf.py:D100,D103 ignore = D105, D107, E203, E501, W503 max-complexity = 18 diff --git a/README.md b/README.md index b3399dc9..724fa673 100644 --- a/README.md +++ b/README.md @@ -37,30 +37,10 @@ This project is a maintainer-made fork of [pyHS100](https://github.com/GadgetRea **Contributions (be it adding missing features, fixing bugs or improving documentation) are more than welcome, feel free to submit pull requests! See below for instructions for setting up a development environment.** -# Usage -The package is shipped with a console tool named kasa, please refer to ```kasa --help``` for detailed usage. -The device to which the commands are sent is chosen by `KASA_HOST` environment variable or passing `--host
` as an option. -To see what is being sent to and received from the device, specify option `--debug`. - -To avoid discovering the devices when executing commands its type can be passed by specifying either `--plug` or `--bulb`, -if no type is given its type will be discovered automatically with a small delay. -Some commands (such as reading energy meter values and setting color of bulbs) additional parameters are required, -which you can find by adding `--help` after the command, e.g. `kasa emeter --help` or `kasa hsv --help`. - -If no command is given, the `state` command will be executed to query the device state. - -## Initial Setup - -You can provision your device without any extra apps by using the `kasa wifi` command: -1. If the device is unprovisioned, connect to its open network -2. Use `kasa discover` (or check the routes) to locate the IP address of the device (likely 192.168.0.1) -3. Scan for available networks using `kasa wifi scan` -4. Join/change the network using `kasa wifi join` command, see `--help` for details. ## Discovering devices The devices can be discovered either by using `kasa discover` or by calling `kasa` without any parameters. -In both cases supported devices are discovered from the same broadcast domain, and their current state will be queried and printed out. ``` $ kasa @@ -108,112 +88,7 @@ The commands are straightforward, so feel free to check `--help` for instruction # Library usage -The property accesses use the data obtained before by awaiting `update()`. -The values are cached until the next update call. In practice this means that property accesses do no I/O and are dependent, while I/O producing methods need to be awaited. - -Methods changing the state of the device do not invalidate the cache (i.e., there is no implicit `update()`). -You can assume that the operation has succeeded if no exception is raised. -These methods will return the device response, which can be useful for some use cases. - -Errors are raised as `SmartDeviceException` instances for the library user to handle. - -## Discovering devices - -`Discover.discover()` can be used to discover supported devices in the local network. -The return value is a dictionary keyed with the IP address and the value holds a ready-to-use instance of the detected device type. - -Example: -```python -import asyncio -from kasa import Discover - -devices = asyncio.run(Discover.discover()) -for addr, dev in devices.items(): - asyncio.run(dev.update()) - print(f"{addr} >> {dev}") -``` -``` -$ python example.py - -``` - -## Querying basic information - -```python -import asyncio -from kasa import SmartPlug -from pprint import pformat as pf - -plug = SmartPlug("192.168.XXX.XXX") -asyncio.run(plug.update()) -print("Hardware: %s" % pf(plug.hw_info)) -print("Full sysinfo: %s" % pf(plug.sys_info)) -``` - -The rest of the examples assume that you have initialized an instance. - -## State & switching - -Devices can be turned on and off by either calling appropriate methods on the device object. - -```python -print("Current state: %s" % plug.is_on) -await plug.turn_off() -await plug.turn_on() -``` - -## Getting emeter status (if applicable) -The `update()` call will automatically fetch the following emeter information: -* Current consumption (accessed through `emeter_realtime` property) -* Today's consumption (`emeter_today`) -* This month's consumption (`emeter_this_month`) - -You can also request this information separately: - -```python -print("Current consumption: %s" % await plug.get_emeter_realtime()) -print("Per day: %s" % await plug.get_emeter_daily(year=2016, month=12)) -print("Per month: %s" % await plug.get_emeter_monthly(year=2016)) -``` - -## Bulb and dimmer-specific APIs - -The bulb API is likewise straightforward, so please refer to its API documentation. -Information about supported features can be queried by using properties prefixed with `is_`, e.g. `is_dimmable`. - -### Setting the brightness - -```python -import asyncio -from kasa import SmartBulb - -bulb = SmartBulb("192.168.1.123") -asyncio.run(bulb.update()) - -if bulb.is_dimmable: - asyncio.run(bulb.set_brightness(100)) - asyncio.run(bulb.update()) - print(bulb.brightness) -``` - -### Setting the color temperature -```python -if bulb.is_variable_color_temp: - await bulb.set_color_temp(3000) - await bulb.update() - print(bulb.color_temp) -``` - -### Setting the color - -Hue is given in degrees (0-360) and saturation and value in percentage. - -```python -if bulb.is_color: - await bulb.set_hsv(180, 100, 100) # set to cyan - await bulb.update() - print(bulb.hsv) -``` +You can find several code examples in [the API documentation](broken link). ## Contributing diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d0c3cbf1 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..6247f7e2 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/_static/copybutton.js b/docs/source/_static/copybutton.js new file mode 100644 index 00000000..a8e45151 --- /dev/null +++ b/docs/source/_static/copybutton.js @@ -0,0 +1,65 @@ +// Copyright 2014 PSF. Licensed under the PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2 +// File originates from the cpython source found in Doc/tools/sphinxext/static/copybutton.js + +$(document).ready(function() { + /* Add a [>>>] button on the top-right corner of code samples to hide + * the >>> and ... prompts and the output and thus make the code + * copyable. */ + var div = $('.highlight-python .highlight,' + + '.highlight-default .highlight,' + + '.highlight-python3 .highlight') + var pre = div.find('pre'); + + // get the styles from the current theme + pre.parent().parent().css('position', 'relative'); + var hide_text = 'Hide the prompts and output'; + var show_text = 'Show the prompts and output'; + var border_width = pre.css('border-top-width'); + var border_style = pre.css('border-top-style'); + var border_color = pre.css('border-top-color'); + var button_styles = { + 'cursor':'pointer', 'position': 'absolute', 'top': '0', 'right': '0', + 'border-color': border_color, 'border-style': border_style, + 'border-width': border_width, 'color': border_color, 'text-size': '75%', + 'font-family': 'monospace', 'padding-left': '0.2em', 'padding-right': '0.2em', + 'border-radius': '0 3px 0 0' + } + + // create and add the button to all the code blocks that contain >>> + div.each(function(index) { + var jthis = $(this); + if (jthis.find('.gp').length > 0) { + var button = $('>>>'); + button.css(button_styles) + button.attr('title', hide_text); + button.data('hidden', 'false'); + jthis.prepend(button); + } + // tracebacks (.gt) contain bare text elements that need to be + // wrapped in a span to work with .nextUntil() (see later) + jthis.find('pre:has(.gt)').contents().filter(function() { + return ((this.nodeType == 3) && (this.data.trim().length > 0)); + }).wrap(''); + }); + + // define the behavior of the button when it's clicked + $('.copybutton').click(function(e){ + e.preventDefault(); + var button = $(this); + if (button.data('hidden') === 'false') { + // hide the code output + button.parent().find('.go, .gp, .gt').hide(); + button.next('pre').find('.gt').nextUntil('.gp, .go').css('visibility', 'hidden'); + button.css('text-decoration', 'line-through'); + button.attr('title', show_text); + button.data('hidden', 'true'); + } else { + // show the code output + button.parent().find('.go, .gp, .gt').show(); + button.next('pre').find('.gt').nextUntil('.gp, .go').css('visibility', 'visible'); + button.css('text-decoration', 'none'); + button.attr('title', hide_text); + button.data('hidden', 'false'); + } + }); +}); diff --git a/docs/source/cli.rst b/docs/source/cli.rst new file mode 100644 index 00000000..0d1989db --- /dev/null +++ b/docs/source/cli.rst @@ -0,0 +1,28 @@ +Command-line usage +================== + +The package is shipped with a console tool named kasa, please refer to ``kasa --help`` for detailed usage. +The device to which the commands are sent is chosen by `KASA_HOST` environment variable or passing ``--host
`` as an option. +To see what is being sent to and received from the device, specify option ``--debug``. + +To avoid discovering the devices when executing commands its type can be passed by specifying either ``--plug`` or ``--bulb``, +if no type is given its type will be discovered automatically with a small delay. +Some commands (such as reading energy meter values and setting color of bulbs) additional parameters are required, +which you can find by adding ``--help`` after the command, e.g. ``kasa emeter --help`` or ``kasa hsv --help``. + +If no command is given, the ``state`` command will be executed to query the device state. + +Provisioning +~~~~~~~~~~~~ + +You can provision your device without any extra apps by using the ``kasa wifi`` command: + +1. If the device is unprovisioned, connect to its open network +2. Use ``kasa discover`` (or check the routes) to locate the IP address of the device (likely 192.168.0.1) +3. Scan for available networks using ``kasa wifi scan`` +4. Join/change the network using ``kasa wifi join`` command, see ``--help`` for details. + +``kasa --help`` +~~~~~~~~~~~~~~~ + +.. program-output:: kasa --help diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..7e718402 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,70 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = "python-kasa" +copyright = "2020, python-kasa developers" +author = "python-kasa developers" + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.coverage", + "sphinx.ext.viewcode", + "sphinxcontrib.programoutput", +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] # type: ignore + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "sphinx_rtd_theme" + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ["_static"] + + +def setup(app): + # add copybutton to hide the >>> prompts, see https://github.com/readthedocs/sphinx_rtd_theme/issues/167 + app.add_js_file("copybutton.js") + + # see https://github.com/readthedocs/recommonmark/issues/191#issuecomment-622369992 + from m2r import MdInclude + + app.add_config_value("no_underscore_emphasis", False, "env") + app.add_config_value("m2r_parse_relative_links", False, "env") + app.add_config_value("m2r_anonymous_references", False, "env") + app.add_config_value("m2r_disable_inline_math", False, "env") + app.add_directive("mdinclude", MdInclude) diff --git a/docs/source/discover.rst b/docs/source/discover.rst new file mode 100644 index 00000000..f47f50d7 --- /dev/null +++ b/docs/source/discover.rst @@ -0,0 +1,17 @@ +Discovering devices +=================== + +.. code-block:: + + import asyncio + from kasa import Discover + + devices = asyncio.run(Discover.discover()) + for addr, dev in devices.items(): + asyncio.run(dev.update()) + print(f"{addr} >> {dev}") + + +.. autoclass:: kasa.Discover + :members: + :undoc-members: diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..7d59f5f4 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,17 @@ +python-kasa documentation +========================= + +.. mdinclude:: ../../README.md + +.. toctree:: + :maxdepth: 2 + + + Home + cli + discover + smartdevice + smartbulb + smartplug + smartdimmer + smartstrip diff --git a/docs/source/smartbulb.rst b/docs/source/smartbulb.rst new file mode 100644 index 00000000..76f66224 --- /dev/null +++ b/docs/source/smartbulb.rst @@ -0,0 +1,6 @@ +Bulbs +=========== + +.. autoclass:: kasa.SmartBulb + :members: + :undoc-members: diff --git a/docs/source/smartdevice.rst b/docs/source/smartdevice.rst new file mode 100644 index 00000000..f2ab6ff3 --- /dev/null +++ b/docs/source/smartdevice.rst @@ -0,0 +1,18 @@ +Common API +====================== + +The basic functionalities of all supported devices are accessible using the common :class:`SmartDevice` base class. + +The property accesses use the data obtained before by awaiting :func:`update()`. +The values are cached until the next update call. In practice this means that property accesses do no I/O and are dependent, while I/O producing methods need to be awaited. + +Methods changing the state of the device do not invalidate the cache (i.e., there is no implicit `update()`). +You can assume that the operation has succeeded if no exception is raised. +These methods will return the device response, which can be useful for some use cases. + +Errors are raised as :class:`SmartDeviceException` instances for the library user to handle. + + +.. autoclass:: kasa.SmartDevice + :members: + :undoc-members: diff --git a/docs/source/smartdimmer.rst b/docs/source/smartdimmer.rst new file mode 100644 index 00000000..f55d571c --- /dev/null +++ b/docs/source/smartdimmer.rst @@ -0,0 +1,6 @@ +Dimmers +======= + +.. autoclass:: kasa.SmartDimmer + :members: + :undoc-members: diff --git a/docs/source/smartplug.rst b/docs/source/smartplug.rst new file mode 100644 index 00000000..75b342cb --- /dev/null +++ b/docs/source/smartplug.rst @@ -0,0 +1,6 @@ +Plugs +===== + +.. autoclass:: kasa.SmartPlug + :members: + :undoc-members: diff --git a/docs/source/smartstrip.rst b/docs/source/smartstrip.rst new file mode 100644 index 00000000..b6c9ff90 --- /dev/null +++ b/docs/source/smartstrip.rst @@ -0,0 +1,6 @@ +Smart strips +============ + +.. autoclass:: kasa.SmartStrip + :members: + :undoc-members: diff --git a/kasa/discover.py b/kasa/discover.py index ef7f4d4c..ba5d702b 100755 --- a/kasa/discover.py +++ b/kasa/discover.py @@ -21,7 +21,7 @@ OnDiscoveredCallable = Callable[[SmartDevice], Awaitable[None]] class _DiscoverProtocol(asyncio.DatagramProtocol): """Implementation of the discovery protocol handler. - This is internal class, use :func:Discover.discover: instead. + This is internal class, use :func:`Discover.discover`: instead. """ discovered_devices: Dict[str, SmartDevice] @@ -72,6 +72,7 @@ class _DiscoverProtocol(asyncio.DatagramProtocol): device_class = Discover._get_device_class(info) device = device_class(ip) + asyncio.ensure_future(device.update()) self.discovered_devices[ip] = device self.discovered_devices_raw[ip] = info @@ -93,16 +94,36 @@ class _DiscoverProtocol(asyncio.DatagramProtocol): class Discover: """Discover TPLink Smart Home devices. - The main entry point for this library is Discover.discover(), + The main entry point for this library is :func:`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. - discover_single() can be used to initialize a single device given its + :func:`discover_single()` can be used to initialize a single device given its IP address. If the type of the device and its IP address is already known, you can initialize the corresponding device class directly without this. The protocol uses UDP broadcast datagrams on port 9999 for discovery. + + Examples: + Discovery returns a list of discovered devices: + + >>> import asyncio + >>> found_devices = asyncio.run(Discover.discover()) + >>> [dev.alias for dev in found_devices] + ['TP-LINK_Power Strip_CF69'] + + Discovery can also be targeted to a specific broadcast address instead of the 255.255.255.255: + + >>> asyncio.run(Discover.discover(target="192.168.8.255")) + + It is also possible to pass a coroutine to be executed for each found device: + + >>> async def print_alias(dev): + >>> print(f"Discovered {dev.alias}") + >>> devices = asyncio.run(Discover.discover(on_discovered=print_alias)) + + """ DISCOVERY_PORT = 9999 @@ -130,12 +151,13 @@ class Discover: to detect available supported devices in the local network, and waits for given timeout for answers from devices. - If given, `on_discovered` coroutine will get passed with the SmartDevice as parameter. - The results of the discovery can be accessed either via `discovered_devices` (SmartDevice-derived) or - `discovered_devices_raw` (JSON objects). + If given, `on_discovered` coroutine will get passed with the :class:`SmartDevice`-derived object as parameter. + + The results of the discovery are returned either as a list of :class:`SmartDevice`-derived objects + or as raw response dictionaries objects (if `return_raw` is True). :param target: The target broadcast address (e.g. 192.168.xxx.255). - :param on_discovered: + :param on_discovered: coroutine to execute on discovery :param timeout: How long to wait for responses, defaults to 5 :param discovery_packets: Number of discovery packets are broadcasted. :param return_raw: True to return JSON objects instead of Devices. @@ -180,7 +202,9 @@ class Discover: device_class = Discover._get_device_class(info) if device_class is not None: - return device_class(host) + dev = device_class(host) + await dev.update() + return dev raise SmartDeviceException("Unable to discover device, received: %s" % info) diff --git a/kasa/smartbulb.py b/kasa/smartbulb.py index a06dcf11..97aac8a9 100644 --- a/kasa/smartbulb.py +++ b/kasa/smartbulb.py @@ -23,53 +23,69 @@ TPLINK_KELVIN = { class SmartBulb(SmartDevice): """Representation of a TP-Link Smart Bulb. - Usage example: - ```python - p = SmartBulb("192.168.1.105") - await p.update() + To initialize, you have to await :func:`update()` at least once. + This will allow accessing the properties using the exposed properties. - # print the devices alias - print(p.alias) + All changes to the device are done using awaitable methods, + which will not change the cached values, but you must await :func:`update()` separately. - # change state of bulb - await p.turn_on() - await p.update() - assert p.is_on - await p.turn_off() - - # query and print current state of plug - print(p.state_information) - - # check whether the bulb supports color changes - if p.is_color: - print("we got color!") - # set the color to an HSV tuple - await p.set_hsv(180, 100, 100) - await p.update() - # get the current HSV value - print(p.hsv) - - # check whether the bulb supports setting color temperature - if p.is_variable_color_temp: - # set the color temperature in Kelvin - await p.set_color_temp(3000) - await p.update() - - # get the current color temperature - print(p.color_temp) - - # check whether the bulb is dimmable - if p.is_dimmable: - # set the bulb to 50% brightness - await p.set_brightness(50) - await p.update() - - # check the current brightness - print(p.brightness) - ``` - - Errors reported by the device are raised as SmartDeviceExceptions, + Errors reported by the device are raised as :class:`SmartDeviceException`s, and should be handled by the user of the library. + + Examples: + >>> import asyncio + >>> bulb = SmartBulb("127.0.0.1") + >>> asyncio.run(bulb.update()) + >>> print(bulb.alias) + KL130 office bulb + + Bulbs, like any other supported devices, can be turned on and off: + + >>> asyncio.run(bulb.turn_off()) + >>> asyncio.run(bulb.turn_on()) + >>> asyncio.run(bulb.update()) + >>> print(bulb.is_on) + True + + You can use the is_-prefixed properties to check for supported features + >>> bulb.is_dimmable + True + >>> bulb.is_color + True + >>> bulb.is_variable_color_temp + True + + All known bulbs support changing the brightness: + + >>> bulb.brightness + 30 + >>> asyncio.run(bulb.set_brightness(50)) + >>> asyncio.run(bulb.update()) + >>> bulb.brightness + 50 + + Bulbs supporting color temperature can be queried to know which range is accepted: + + >>> bulb.valid_temperature_range + (2500, 9000) + >>> asyncio.run(bulb.set_color_temp(3000)) + >>> asyncio.run(bulb.update()) + >>> bulb.color_temp + 3000 + + Color bulbs can be adjusted by passing hue, saturation and value: + + >>> asyncio.run(bulb.set_hsv(180, 100, 80)) + >>> asyncio.run(bulb.update()) + >>> bulb.hsv + (180, 100, 80) + + If you don't want to use the default transitions, you can pass `transition` in milliseconds. + This applies to all transitions (turn_on, turn_off, set_hsv, set_color_temp, set_brightness). + The following changes the brightness over a period of 10 seconds: + + >>> asyncio.run(bulb.set_brightness(100, transition=10_000)) + """ LIGHT_SERVICE = "smartlife.iot.smartbulb.lightingservice" diff --git a/kasa/smartdevice.py b/kasa/smartdevice.py index 0ed263b4..304dd265 100755 --- a/kasa/smartdevice.py +++ b/kasa/smartdevice.py @@ -118,7 +118,98 @@ def requires_update(f): class SmartDevice: - """Base class for all supported device types.""" + """Base class for all supported device types. + + You don't usually want to construct this class which implements the shared common interfaces. + The recommended way is to either use the discovery functionality, or construct one of the subclasses: + + * :class:`SmartPlug` + * :class:`SmartBulb` + * :class:`SmartStrip` + * :class:`SmartDimmer` + + To initialize, you have to await :func:`update()` at least once. + This will allow accessing the properties using the exposed properties. + + All changes to the device are done using awaitable methods, + which will not change the cached values, but you must await update() separately. + + Errors reported by the device are raised as SmartDeviceExceptions, + and should be handled by the user of the library. + + Examples: + >>> import asyncio + >>> dev = SmartDevice("127.0.0.1") + >>> asyncio.run(dev.update()) + + All devices provide several informational properties: + + >>> dev.alias + Kitchen + >>> dev.model + HS110(EU) + >>> dev.rssi + -71 + >>> dev.mac + 50:C7:BF:01:F8:CD + + Some information can also be changed programatically: + + >>> asyncio.run(dev.set_alias("new alias")) + >>> asyncio.run(dev.set_mac("01:23:45:67:89:ab")) + >>> asyncio.run(dev.update()) + >>> dev.alias + new alias + >>> dev.mac + 01:23:45:67:89:ab + + When initialized using discovery or using a subclass, you can check the type of the device: + + >>> dev.is_bulb + False + >>> dev.is_strip + False + >>> dev.is_plug + True + + You can also get the hardware and software as a dict, or access the full device response: + + >>> dev.hw_info + {'sw_ver': '1.2.5 Build 171213 Rel.101523', + 'hw_ver': '1.0', + 'mac': '01:23:45:67:89:ab', + 'type': 'IOT.SMARTPLUGSWITCH', + 'hwId': '45E29DA8382494D2E82688B52A0B2EB5', + 'fwId': '00000000000000000000000000000000', + 'oemId': '3D341ECE302C0642C99E31CE2430544B', + 'dev_name': 'Wi-Fi Smart Plug With Energy Monitoring'} + >>> dev.sys_info + + All devices can be turned on and off: + + >>> asyncio.run(dev.turn_off()) + >>> asyncio.run(dev.turn_on()) + >>> asyncio.run(dev.update()) + >>> dev.is_on + True + + Some devices provide energy consumption meter, and regular update will already fetch some information: + + >>> dev.has_emeter + True + >>> dev.emeter_realtime + {'current': 0.015342, 'err_code': 0, 'power': 0.983971, 'total': 32.448, 'voltage': 235.595234} + >>> dev.emeter_today + >>> dev.emeter_this_month + + You can also query the historical data (note that these needs to be awaited), keyed with month/day: + + >>> asyncio.run(dev.get_emeter_monthly(year=2016)) + {11: 1.089, 12: 1.582} + >>> asyncio.run(dev.get_emeter_daily(year=2016, month=11)) + {24: 0.026, 25: 0.109} + + """ def __init__(self, host: str) -> None: """Create a new SmartDevice instance. @@ -382,6 +473,9 @@ class SmartDevice: @requires_update def emeter_today(self) -> Optional[float]: """Return today's energy consumption in kWh.""" + if not self.has_emeter: + raise SmartDeviceException("Device has no emeter") + raw_data = self._last_update[self.emeter_type]["get_daystat"]["day_list"] data = self._emeter_convert_emeter_data(raw_data) today = datetime.now().day @@ -395,6 +489,9 @@ class SmartDevice: @requires_update def emeter_this_month(self) -> Optional[float]: """Return this month's energy consumption in kWh.""" + if not self.has_emeter: + raise SmartDeviceException("Device has no emeter") + raw_data = self._last_update[self.emeter_type]["get_monthstat"]["month_list"] data = self._emeter_convert_emeter_data(raw_data) current_month = datetime.now().month @@ -485,7 +582,7 @@ class SmartDevice: response = EmeterStatus(await self.get_emeter_realtime()) return response["power"] - async def reboot(self, delay=1) -> None: + async def reboot(self, delay: int = 1) -> None: """Reboot the device. Note that giving a delay of zero causes this to block, diff --git a/kasa/smartdimmer.py b/kasa/smartdimmer.py index 780ac433..743fcd1e 100644 --- a/kasa/smartdimmer.py +++ b/kasa/smartdimmer.py @@ -9,18 +9,30 @@ class SmartDimmer(SmartPlug): """Representation of a TP-Link Smart Dimmer. Dimmers work similarly to plugs, but provide also support for - adjusting the brightness. This class extends SmartPlug interface. + adjusting the brightness. This class extends :class:`SmartPlug` interface. - Example: - ``` - dimmer = SmartDimmer("192.168.1.105") - await dimmer.turn_on() - print("Current brightness: %s" % dimmer.brightness) + To initialize, you have to await :func:`update()` at least once. + This will allow accessing the properties using the exposed properties. - await dimmer.set_brightness(100) - ``` + All changes to the device are done using awaitable methods, + which will not change the cached values, but you must await :func:`update()` separately. - Refer to SmartPlug for the full API. + Errors reported by the device are raised as :class:`SmartDeviceException`s, + and should be handled by the user of the library. + + Examples: + >>> import asyncio + >>> dimmer = SmartDimmer("192.168.1.105") + >>> asyncio.run(dimmer.turn_on()) + >>> dimmer.brightness + 25 + + >>> asyncio.run(dimmer.set_brightness(50)) + >>> asyncio.run(dimmer.update()) + >>> dimmer.brightness + 50 + + Refer to :class:`SmartPlug` for the full API. """ DIMMER_SERVICE = "smartlife.iot.dimmer" diff --git a/kasa/smartplug.py b/kasa/smartplug.py index 55904eb8..e3583d10 100644 --- a/kasa/smartplug.py +++ b/kasa/smartplug.py @@ -10,24 +10,30 @@ _LOGGER = logging.getLogger(__name__) class SmartPlug(SmartDevice): """Representation of a TP-Link Smart Switch. - Usage example: - ```python - p = SmartPlug("192.168.1.105") + To initialize, you have to await :func:`update()` at least once. + This will allow accessing the properties using the exposed properties. - # print the devices alias - print(p.alias) + All changes to the device are done using awaitable methods, + which will not change the cached values, but you must await :func:`update()` separately. - # change state of plug - await p.turn_on() - assert p.is_on is True - await p.turn_off() - - # print current state of plug - print(p.state_information) - ``` - - Errors reported by the device are raised as SmartDeviceExceptions, + Errors reported by the device are raised as :class:`SmartDeviceException`s, and should be handled by the user of the library. + + Examples: + >>> import asyncio + >>> plug = SmartPlug("127.0.0.1") + >>> asyncio.run(plug.update()) + >>> plug.alias + Kitchen + + Setting the LED state: + + >>> asyncio.run(plug.set_led(True)) + >>> asyncio.run(plug.update()) + >>> plug.led + True + + For more examples, see the :class:`SmartDevice` class. """ def __init__(self, host: str) -> None: diff --git a/kasa/smartstrip.py b/kasa/smartstrip.py index e5c3a1af..f2234abd 100755 --- a/kasa/smartstrip.py +++ b/kasa/smartstrip.py @@ -18,28 +18,52 @@ _LOGGER = logging.getLogger(__name__) class SmartStrip(SmartDevice): """Representation of a TP-Link Smart Power Strip. - Usage example when used as library: - ```python - p = SmartStrip("192.168.1.105") + A strip consists of the parent device and its children. + All methods of the parent act on all children, while the child devices + share the common API with the :class:`SmartPlug` class. - # query the state of the strip - await p.update() - print(p.is_on) + To initialize, you have to await :func:`update()` at least once. + This will allow accessing the properties using the exposed properties. - # change state of all outlets - await p.turn_on() - await p.turn_off() + All changes to the device are done using awaitable methods, + which will not change the cached values, but you must await :func:`update()` separately. - # individual outlets are accessible through plugs variable - for plug in p.plugs: - print(f"{p}: {p.is_on}") - - # change state of a single outlet - await p.plugs[0].turn_on() - ``` - - Errors reported by the device are raised as SmartDeviceExceptions, + Errors reported by the device are raised as :class:`SmartDeviceException`s, and should be handled by the user of the library. + + Examples: + >>> import asyncio + >>> strip = SmartStrip("127.0.0.1") + >>> asyncio.run(strip.update()) + >>> strip.alias + TP-LINK_Power Strip_CF69 + + All methods act on the whole strip: + + >>> for plug in strip.children: + >>> print(f"{plug.alias}: {plug.is_on}") + Plug 1: True + Plug 2: False + Plug 3: False + >>> strip.is_on + True + >>> asyncio.run(strip.turn_off()) + + Accessing individual plugs can be done using the `children` property: + + >>> len(strip.children) + 3 + >>> for plug in strip.children: + >>> print(f"{plug.alias}: {plug.is_on}") + Plug 1: False + Plug 2: False + Plug 3: False + >>> asyncio.run(strip.children[1].turn_on()) + >>> asyncio.run(strip.update()) + >>> strip.is_on + True + + For more examples, see the :class:`SmartDevice` class. """ def __init__(self, host: str) -> None: @@ -212,7 +236,7 @@ class SmartStripPlug(SmartPlug): def is_on(self) -> bool: """Return whether device is on.""" info = self._get_child_info() - return info["state"] + return bool(info["state"]) @property # type: ignore @requires_update diff --git a/kasa/tests/conftest.py b/kasa/tests/conftest.py index f2b4c178..f530b5db 100644 --- a/kasa/tests/conftest.py +++ b/kasa/tests/conftest.py @@ -3,6 +3,7 @@ import glob import json import os from os.path import basename +from pathlib import Path, PurePath from unittest.mock import MagicMock import pytest # type: ignore # see https://github.com/pytest-dev/pytest/issues/3342 @@ -100,6 +101,38 @@ async def handle_turn_on(dev, turn_on): pytestmark = pytest.mark.asyncio +def device_for_file(model): + for d in STRIPS: + if d in model: + return SmartStrip + for d in PLUGS: + if d in model: + return SmartPlug + for d in BULBS: + if d in model: + return SmartBulb + for d in DIMMERS: + if d in model: + return SmartDimmer + + raise Exception("Unable to find type for %s", model) + + +def get_device_for_file(file): + # if the wanted file is not an absolute path, prepend the fixtures directory + p = Path(file) + if not p.is_absolute(): + p = Path(__file__).parent / "fixtures" / file + + with open(p) as f: + sysinfo = json.load(f) + model = basename(file) + p = device_for_file(model)(host="123.123.123.123") + p.protocol = FakeTransportProtocol(sysinfo) + asyncio.run(p.update()) + return p + + @pytest.fixture(params=SUPPORTED_DEVICES) def dev(request): """Device fixture. @@ -117,29 +150,7 @@ def dev(request): return d raise Exception("Unable to find type for %s" % ip) - def device_for_file(model): - for d in STRIPS: - if d in model: - return SmartStrip - for d in PLUGS: - if d in model: - return SmartPlug - for d in BULBS: - if d in model: - return SmartBulb - for d in DIMMERS: - if d in model: - return SmartDimmer - - raise Exception("Unable to find type for %s", model) - - with open(file) as f: - sysinfo = json.load(f) - model = basename(file) - p = device_for_file(model)(host="123.123.123.123") - p.protocol = FakeTransportProtocol(sysinfo) - asyncio.run(p.update()) - yield p + return get_device_for_file(file) def pytest_addoption(parser): diff --git a/kasa/tests/fixtures/KL130(US)_1.0.json b/kasa/tests/fixtures/KL130(US)_1.0.json index 49c16ec5..b07044a6 100644 --- a/kasa/tests/fixtures/KL130(US)_1.0.json +++ b/kasa/tests/fixtures/KL130(US)_1.0.json @@ -27,7 +27,7 @@ "system": { "get_sysinfo": { "active_mode": "none", - "alias": "Nick office tplink", + "alias": "KL130 office bulb", "ctrl_protocols": { "name": "Linkie", "version": "1.0" @@ -45,7 +45,7 @@ "is_factory": false, "is_variable_color_temp": 1, "light_state": { - "brightness": 0, + "brightness": 30, "color_temp": 0, "hue": 15, "mode": "normal", diff --git a/kasa/tests/newfakes.py b/kasa/tests/newfakes.py index 2f2be2ef..16ea1d4c 100644 --- a/kasa/tests/newfakes.py +++ b/kasa/tests/newfakes.py @@ -240,42 +240,41 @@ emeter_commands = { } -def error(target, cmd="no-command", msg="default msg"): - return {target: {cmd: {"err_code": -1323, "msg": msg}}} +def error(msg="default msg"): + return {"err_code": -1323, "msg": msg} -def success(target, cmd, res): +def success(res): if res: res.update({"err_code": 0}) else: res = {"err_code": 0} - return {target: {cmd: res}} + return res class FakeTransportProtocol(TPLinkSmartHomeProtocol): def __init__(self, info): self.discovery_data = info proto = FakeTransportProtocol.baseproto + for target in info: # print("target %s" % target) for cmd in info[target]: # print("initializing tgt %s cmd %s" % (target, cmd)) proto[target][cmd] = info[target][cmd] - # if we have emeter support, check for it + # if we have emeter support, we need to add the missing pieces for module in ["emeter", "smartlife.iot.common.emeter"]: - if module not in info: - # TODO required for old tests - continue - if "get_realtime" in info[module]: - get_realtime_res = info[module]["get_realtime"] - # TODO remove when removing old tests - if callable(get_realtime_res): - get_realtime_res = get_realtime_res() - if ( - "err_code" not in get_realtime_res - or not get_realtime_res["err_code"] - ): - proto[module] = emeter_commands[module] + for etype in ["get_realtime", "get_daystat", "get_monthstat"]: + if etype in info[module]: # if the fixture has the data, use it + # print("got %s %s from fixture: %s" % (module, etype, info[module][etype])) + proto[module][etype] = info[module][etype] + else: # otherwise fall back to the static one + dummy_data = emeter_commands[module][etype] + # print("got %s %s from dummy: %s" % (module, etype, dummy_data)) + proto[module][etype] = dummy_data + + # print("initialized: %s" % proto[module]) + self.proto = proto def set_alias(self, x, child_ids=[]): @@ -309,7 +308,7 @@ class FakeTransportProtocol(TPLinkSmartHomeProtocol): def set_mac(self, x, *args): _LOGGER.debug("Setting mac to %s", x) - self.proto["system"]["get_sysinfo"]["mac"] = x + self.proto["system"]["get_sysinfo"]["mac"] = x["mac"] def set_hs220_brightness(self, x, *args): _LOGGER.debug("Setting brightness to %s", x) @@ -345,9 +344,10 @@ class FakeTransportProtocol(TPLinkSmartHomeProtocol): if not light_state["on_off"] and "on_off" not in x: light_state = light_state["dft_on_state"] - _LOGGER.debug("Current state: %s", light_state) + _LOGGER.debug("Old state: %s", light_state) for key in x: light_state[key] = x[key] + _LOGGER.debug("New state: %s", light_state) def light_state(self, x, *args): light_state = self.proto["system"]["get_sysinfo"]["light_state"] @@ -417,26 +417,39 @@ class FakeTransportProtocol(TPLinkSmartHomeProtocol): except KeyError: child_ids = [] - target = next(iter(request)) - if target not in proto.keys(): - return error(target, msg="target not found") + def get_response_for_module(target): - cmd = next(iter(request[target])) - if cmd not in proto[target].keys(): - return error(target, cmd, msg="command not found") + if target not in proto.keys(): + return error(msg="target not found") - params = request[target][cmd] - _LOGGER.debug(f"Going to execute {target}.{cmd} (params: {params}).. ") + def get_response_for_command(cmd): + if cmd not in proto[target].keys(): + return error(msg=f"command {cmd} not found") - if callable(proto[target][cmd]): - res = proto[target][cmd](self, params, child_ids) - _LOGGER.debug("[callable] %s.%s: %s", target, cmd, res) - # verify that change didn't break schema, requires refactoring.. - # TestSmartPlug.sysinfo_schema(self.proto["system"]["get_sysinfo"]) - return success(target, cmd, res) - elif isinstance(proto[target][cmd], dict): - res = proto[target][cmd] - _LOGGER.debug("[static] %s.%s: %s", target, cmd, res) - return success(target, cmd, res) - else: - raise NotImplementedError(f"target {target} cmd {cmd}") + params = request[target][cmd] + _LOGGER.debug(f"Going to execute {target}.{cmd} (params: {params}).. ") + + if callable(proto[target][cmd]): + res = proto[target][cmd](self, params, child_ids) + _LOGGER.debug("[callable] %s.%s: %s", target, cmd, res) + return success(res) + elif isinstance(proto[target][cmd], dict): + res = proto[target][cmd] + _LOGGER.debug("[static] %s.%s: %s", target, cmd, res) + return success(res) + else: + raise NotImplementedError(f"target {target} cmd {cmd}") + + from collections import defaultdict + + cmd_responses = defaultdict(dict) + for cmd in request[target]: + cmd_responses[target][cmd] = get_response_for_command(cmd) + + return cmd_responses + + response = {} + for target in request: + response.update(get_response_for_module(target)) + + return response diff --git a/kasa/tests/test_bulb.py b/kasa/tests/test_bulb.py index b84558b1..b8d3ab3c 100644 --- a/kasa/tests/test_bulb.py +++ b/kasa/tests/test_bulb.py @@ -10,6 +10,7 @@ from .conftest import ( non_color_bulb, non_dimmable, non_variable_temp, + pytestmark, turn_on, variable_temp, ) diff --git a/kasa/tests/test_cli.py b/kasa/tests/test_cli.py index dd174608..1b94d489 100644 --- a/kasa/tests/test_cli.py +++ b/kasa/tests/test_cli.py @@ -1,12 +1,9 @@ -import pytest from asyncclick.testing import CliRunner from kasa import SmartDevice from kasa.cli import alias, brightness, emeter, raw_command, state, sysinfo -from .conftest import handle_turn_on, turn_on - -pytestmark = pytest.mark.asyncio +from .conftest import handle_turn_on, pytestmark, turn_on async def test_sysinfo(dev): diff --git a/kasa/tests/test_dimmer.py b/kasa/tests/test_dimmer.py index b5e98b78..96a1021a 100644 --- a/kasa/tests/test_dimmer.py +++ b/kasa/tests/test_dimmer.py @@ -2,7 +2,7 @@ import pytest from kasa import SmartDimmer -from .conftest import dimmer, handle_turn_on, turn_on +from .conftest import dimmer, handle_turn_on, pytestmark, turn_on @dimmer diff --git a/kasa/tests/test_discovery.py b/kasa/tests/test_discovery.py index 45121d1d..10de7b99 100644 --- a/kasa/tests/test_discovery.py +++ b/kasa/tests/test_discovery.py @@ -3,10 +3,7 @@ import pytest # type: ignore # https://github.com/pytest-dev/pytest/issues/3342 from kasa import DeviceType, Discover, SmartDevice, SmartDeviceException -from .conftest import bulb, dimmer, plug, strip - -# to avoid adding this for each async function separately -pytestmark = pytest.mark.asyncio +from .conftest import bulb, dimmer, plug, pytestmark, strip @plug diff --git a/kasa/tests/test_emeter.py b/kasa/tests/test_emeter.py index ecdb4241..5cdd5067 100644 --- a/kasa/tests/test_emeter.py +++ b/kasa/tests/test_emeter.py @@ -2,7 +2,7 @@ import pytest from kasa import SmartDeviceException -from .conftest import has_emeter, no_emeter +from .conftest import has_emeter, no_emeter, pytestmark from .newfakes import CURRENT_CONSUMPTION_SCHEMA diff --git a/kasa/tests/test_plug.py b/kasa/tests/test_plug.py index d9f11825..a301095e 100644 --- a/kasa/tests/test_plug.py +++ b/kasa/tests/test_plug.py @@ -1,6 +1,6 @@ from kasa import DeviceType -from .conftest import plug +from .conftest import plug, pytestmark from .newfakes import PLUG_SCHEMA diff --git a/kasa/tests/test_protocol.py b/kasa/tests/test_protocol.py index 0a8291e1..51c01d49 100644 --- a/kasa/tests/test_protocol.py +++ b/kasa/tests/test_protocol.py @@ -4,6 +4,7 @@ import pytest from ..exceptions import SmartDeviceException from ..protocol import TPLinkSmartHomeProtocol +from .conftest import pytestmark @pytest.mark.parametrize("retry_count", [1, 3, 5]) diff --git a/kasa/tests/test_readme_examples.py b/kasa/tests/test_readme_examples.py new file mode 100644 index 00000000..204a923e --- /dev/null +++ b/kasa/tests/test_readme_examples.py @@ -0,0 +1,65 @@ +import sys + +import pytest + +import xdoctest +from kasa.tests.conftest import get_device_for_file + + +def test_bulb_examples(mocker): + """Use KL130 (bulb with all features) to test the doctests.""" + p = get_device_for_file("KL130(US)_1.0.json") + mocker.patch("kasa.smartbulb.SmartBulb", return_value=p) + mocker.patch("kasa.smartbulb.SmartBulb.update") + res = xdoctest.doctest_module("kasa.smartbulb", "all") + assert not res["failed"] + + +def test_smartdevice_examples(mocker): + """Use HS110 for emeter examples.""" + p = get_device_for_file("HS110(EU)_1.0_real.json") + mocker.patch("kasa.smartdevice.SmartDevice", return_value=p) + mocker.patch("kasa.smartdevice.SmartDevice.update") + res = xdoctest.doctest_module("kasa.smartdevice", "all") + assert not res["failed"] + + +def test_plug_examples(mocker): + """Test plug examples.""" + p = get_device_for_file("HS110(EU)_1.0_real.json") + mocker.patch("kasa.smartplug.SmartPlug", return_value=p) + mocker.patch("kasa.smartplug.SmartPlug.update") + res = xdoctest.doctest_module("kasa.smartplug", "all") + assert not res["failed"] + + +def test_strip_examples(mocker): + """Test strip examples.""" + p = get_device_for_file("KP303(UK)_1.0.json") + mocker.patch("kasa.smartstrip.SmartStrip", return_value=p) + mocker.patch("kasa.smartstrip.SmartStrip.update") + res = xdoctest.doctest_module("kasa.smartstrip", "all") + assert not res["failed"] + + +def test_dimmer_examples(mocker): + """Test dimmer examples.""" + p = get_device_for_file("HS220(US)_1.0_real.json") + mocker.patch("kasa.smartdimmer.SmartDimmer", return_value=p) + mocker.patch("kasa.smartdimmer.SmartDimmer.update") + res = xdoctest.doctest_module("kasa.smartdimmer", "all") + assert not res["failed"] + + +@pytest.mark.skipif( + sys.version_info < (3, 8), reason="3.7 handles asyncio.run differently" +) +def test_discovery_examples(mocker): + """Test discovery examples.""" + p = get_device_for_file("KP303(UK)_1.0.json") + + # This succeeds on python 3.8 but fails on 3.7 + # ValueError: a coroutine was expected, got [