Mirrored_Repos/python-kasa
1
0
Fork 0
mirror of https://github.com/python-kasa/python-kasa.git synced 2026-02-25 04:09:58 +00:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Add tutorial doctest module and enable top level await (#919)

Browse Source 
Add a tutorial module with examples that can be tested with `doctest`.

In order to simplify the examples they can be run with doctest allowing
top level await statements by adding a fixture to patch the builtins
that xdoctest uses to test code.

---------

Co-authored-by: Teemu R. <tpr@iki.fi>
This commit is contained in:
Steven B
2024-05-16 17:13:44 +01:00
committed by GitHub
parent a2e8d2c4e8
commit 3490a1ef84
17 changed files with 228 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
docs/source/design.rst
View File

@@ -22,13 +22,13 @@ Use :func:`~kasa.Discover.discover` to perform udp-based broadcast discovery on
This will return you a list of device instances based on the discovery replies.
If the device's host is already known, you can use to construct a device instance with
:meth:`~kasa.SmartDevice.connect()`.
:meth:`~kasa.Device.connect()`.
The :meth:`~kasa.SmartDevice.connect()` also enables support for connecting to new
The :meth:`~kasa.Device.connect()` also enables support for connecting to new
KASA SMART protocol and TAPO devices directly using the parameter :class:`~kasa.DeviceConfig`.
Simply serialize the :attr:`~kasa.SmartDevice.config` property via :meth:`~kasa.DeviceConfig.to_dict()`
Simply serialize the :attr:`~kasa.Device.config` property via :meth:`~kasa.DeviceConfig.to_dict()`
and then deserialize it later with :func:`~kasa.DeviceConfig.from_dict()`
and then pass it into :meth:`~kasa.SmartDevice.connect()`.
and then pass it into :meth:`~kasa.Device.connect()`.
.. _update_cycle:
@@ -36,7 +36,7 @@ and then pass it into :meth:`~kasa.SmartDevice.connect()`.
Update Cycle
************
When :meth:`~kasa.SmartDevice.update()` is called,
When :meth:`~kasa.Device.update()` is called,
the library constructs a query to send to the device based on :ref:`supported modules <modules>`.
Internally, each module defines :meth:`~kasa.modules.Module.query()` to describe what they want query during the update.
@@ -45,7 +45,7 @@ All properties defined both in the device class and in the module classes follow
While the properties are designed to provide a nice API to use for common use cases,
you may sometimes want to access the raw, cached data as returned by the device.
This can be done using the :attr:`~kasa.SmartDevice.internal_state` property.
This can be done using the :attr:`~kasa.Device.internal_state` property.
.. _modules:
@@ -53,15 +53,15 @@ This can be done using the :attr:`~kasa.SmartDevice.internal_state` property.
Modules
*******
The functionality provided by all :class:`~kasa.SmartDevice` instances is (mostly) done inside separate modules.
The functionality provided by all :class:`~kasa.Device` instances is (mostly) done inside separate modules.
While the individual device-type specific classes provide an easy access for the most import features,
you can also access individual modules through :attr:`kasa.SmartDevice.modules`.
You can get the list of supported modules for a given device instance using :attr:`~kasa.SmartDevice.supported_modules`.
You can get the list of supported modules for a given device instance using :attr:`~kasa.Device.supported_modules`.
.. note::
If you only need some module-specific information,
you can call the wanted method on the module to avoid using :meth:`~kasa.SmartDevice.update`.
you can call the wanted method on the module to avoid using :meth:`~kasa.Device.update`.
Protocols and Transports
************************
@@ -112,10 +112,22 @@ The base exception for all library errors is :class:`KasaException <kasa.excepti
- If the device fails to respond within a timeout the library raises a :class:`TimeoutError <kasa.exceptions.TimeoutError>`.
- All other failures will raise the base :class:`KasaException <kasa.exceptions.KasaException>` class.
API documentation for modules
*****************************
API documentation for modules and features
******************************************
.. automodule:: kasa.modules
.. autoclass:: kasa.Module
:noindex:
:members:
:inherited-members:
:undoc-members:
.. automodule:: kasa.interfaces
:noindex:
:members:
:inherited-members:
:undoc-members:
.. autoclass:: kasa.Feature
:noindex:
:members:
:inherited-members: