Mirrored_Repos/python-kasa
1
0
Fork 0
mirror of https://github.com/python-kasa/python-kasa.git synced 2025-08-04 01:34:12 +00:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Update documentation structure and start migrating to markdown (#934)

Browse Source 
Starts structuring the documentation library usage into Tutorials, Guides, Explanations and Reference.
Continues migrating new docs from rst to markdown.
Extends the test framework discovery mocks to allow easy writing and testing of code examples.
This commit is contained in:
Steven B
2024-06-03 12:14:10 +03:00
committed by GitHub
parent 767156421b
commit 6616d68d42
31 changed files with 619 additions and 324 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/source/conf.py
View File

@@ -37,6 +37,10 @@ extensions = [
"myst_parser",
]
myst_enable_extensions = [
"colon_fence",
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]

24
docs/source/deprecated.md Normal file
View File

@@ -0,0 +1,24 @@
# Deprecated API
```{currentmodule} kasa
```
The page contains the documentation for the deprecated library API that only works with the older kasa devices.
If you want to continue to use the old API for older devices,
you can use the classes in the `iot` module to avoid deprecation warnings.
```py
from kasa.iot import IotDevice, IotBulb, IotPlug, IotDimmer, IotStrip, IotLightStrip
```
```{toctree}
:maxdepth: 2
smartdevice
smartbulb
smartplug
smartdimmer
smartstrip
smartlightstrip
```

62
docs/source/discover.rst
View File

@@ -1,62 +0,0 @@
.. py:module:: kasa.discover
Discovering devices
===================
.. contents:: Contents
:local:
Discovery
*********
Discovery works by sending broadcast UDP packets to two known TP-link discovery ports, 9999 and 20002.
Port 9999 is used for legacy devices that do not use strong encryption and 20002 is for newer devices that use different
levels of encryption.
If a device uses port 20002 for discovery you will obtain some basic information from the device via discovery, but you
will need to await :func:`Device.update() <kasa.SmartDevice.update()>` to get full device information.
Credentials will most likely be required for port 20002 devices although if the device has never been connected to the tplink
cloud it may work without credentials.
To query or update the device requires authentication via :class:`Credentials <kasa.Credentials>` and if this is invalid or not provided it
will raise an :class:`AuthenticationException <kasa.AuthenticationException>`.
If discovery encounters an unsupported device when calling via :meth:`Discover.discover_single() <kasa.Discover.discover_single>`
it will raise a :class:`UnsupportedDeviceException <kasa.UnsupportedDeviceException>`.
If discovery encounters a device when calling :meth:`Discover.discover() <kasa.Discover.discover>`,
you can provide a callback to the ``on_unsupported`` parameter
to handle these.
Example:
.. code-block:: python
import asyncio
from kasa import Discover, Credentials
async def main():
device = await Discover.discover_single(
"127.0.0.1",
credentials=Credentials("myusername", "mypassword"),
discovery_timeout=10
)
await device.update() # Request the update
print(device.alias) # Print out the alias
devices = await Discover.discover(
credentials=Credentials("myusername", "mypassword"),
discovery_timeout=10
)
for ip, device in devices.items():
await device.update()
print(device.alias)
if __name__ == "__main__":
asyncio.run(main())
API documentation
*****************
.. autoclass:: kasa.Discover
:members:
:undoc-members:

42
docs/source/guides.md Normal file
View File

@@ -0,0 +1,42 @@
# How-to Guides
This page contains guides of how to perform common actions using the library.
## Discover devices
```{eval-rst}
.. automodule:: kasa.discover
```
## Connect without discovery
```{eval-rst}
.. automodule:: kasa.deviceconfig
```
## Get Energy Consumption and Usage Statistics
:::{note}
In order to use the helper methods to calculate the statistics correctly, your devices need to have correct time set.
The devices use NTP and public servers from [NTP Pool Project](https://www.ntppool.org/) to synchronize their time.
:::
### Energy Consumption
The availability of energy consumption sensors depend on the device.
While most of the bulbs support it, only specific switches (e.g., HS110) or strips (e.g., HS300) support it.
You can use {attr}`~Device.has_emeter` to check for the availability.
### Usage statistics
You can use {attr}`~Device.on_since` to query for the time the device has been turned on.
Some devices also support reporting the usage statistics on daily or monthly basis.
You can access this information using through the usage module ({class}`kasa.modules.Usage`):
```py
dev = SmartPlug("127.0.0.1")
usage = dev.modules["usage"]
print(f"Minutes on this month: {usage.usage_this_month}")
print(f"Minutes on today: {usage.usage_today}")
```

12
docs/source/index.md Normal file
View File

@@ -0,0 +1,12 @@
```{include} ../../README.md
```
```{toctree}
:maxdepth: 2
Home <self>
cli
library
contribute
SUPPORTED
```

20
docs/source/index.rst
View File

@@ -1,20 +0,0 @@
.. include:: ../../README.md
:parser: myst_parser.sphinx_
.. toctree::
:maxdepth: 2
Home <self>
cli
tutorial
discover
device
design
contribute
smartbulb
smartplug
smartdimmer
smartstrip
smartlightstrip
SUPPORTED

15
docs/source/library.md Normal file
View File

@@ -0,0 +1,15 @@
# Library usage
```{currentmodule} kasa
```
The page contains all information about the library usage:
```{toctree}
:maxdepth: 2
tutorial
guides
topics
reference
deprecated
```

134
docs/source/reference.md Normal file
View File

@@ -0,0 +1,134 @@
# API Reference
```{currentmodule} kasa
```
## Discover
```{eval-rst}
.. autoclass:: kasa.Discover
:members:
```
## Device
```{eval-rst}
.. autoclass:: kasa.Device
:members:
:undoc-members:
```
## Modules and Features
```{eval-rst}
.. autoclass:: kasa.Module
:noindex:
:members:
:inherited-members:
:undoc-members:
```
```{eval-rst}
.. automodule:: kasa.interfaces
:noindex:
:members:
:inherited-members:
:undoc-members:
```
```{eval-rst}
.. autoclass:: kasa.Feature
:noindex:
:members:
:inherited-members:
:undoc-members:
```
## Protocols and transports
```{eval-rst}
.. autoclass:: kasa.protocol.BaseProtocol
:members:
:inherited-members:
:undoc-members:
```
```{eval-rst}
.. autoclass:: kasa.iotprotocol.IotProtocol
:members:
:inherited-members:
:undoc-members:
```
```{eval-rst}
.. autoclass:: kasa.smartprotocol.SmartProtocol
:members:
:inherited-members:
:undoc-members:
```
```{eval-rst}
.. autoclass:: kasa.protocol.BaseTransport
:members:
:inherited-members:
:undoc-members:
```
```{eval-rst}
.. autoclass:: kasa.xortransport.XorTransport
:members:
:inherited-members:
:undoc-members:
```
```{eval-rst}
.. autoclass:: kasa.klaptransport.KlapTransport
:members:
:inherited-members:
:undoc-members:
```
```{eval-rst}
.. autoclass:: kasa.klaptransport.KlapTransportV2
:members:
:inherited-members:
:undoc-members:
```
```{eval-rst}
.. autoclass:: kasa.aestransport.AesTransport
:members:
:inherited-members:
:undoc-members:
```
## Errors and exceptions
```{eval-rst}
.. autoclass:: kasa.exceptions.KasaException
:members:
:undoc-members:
```
```{eval-rst}
.. autoclass:: kasa.exceptions.DeviceError
:members:
:undoc-members:
```
```{eval-rst}
.. autoclass:: kasa.exceptions.AuthenticationError
:members:
:undoc-members:
```
```{eval-rst}
.. autoclass:: kasa.exceptions.UnsupportedDeviceError
:members:
:undoc-members:
```
```{eval-rst}
.. autoclass:: kasa.exceptions.TimeoutError
:members:
:undoc-members:

75
docs/source/device.rst → docs/source/smartdevice.rst
View File

@@ -1,32 +1,32 @@
.. py:module:: kasa
.. py:currentmodule:: kasa
Common API
==========
Base Device
===========
.. contents:: Contents
:local:
Device class
************
SmartDevice class
*****************
The basic functionalities of all supported devices are accessible using the common :class:`Device` base class.
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:`Device.update()`.
The property accesses use the data obtained before by awaiting :func:`SmartDevice.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.
See :ref:`library_design` for more detailed information.
See :ref:`topics-update-cycle` for more detailed information.
.. note::
The device instances share the communication socket in background to optimize I/O accesses.
This means that you need to use the same event loop for subsequent requests.
The library gives a warning ("Detected protocol reuse between different event loop") to hint if you are accessing the device incorrectly.
Methods changing the state of the device do not invalidate the cache (i.e., there is no implicit :func:`Device.update()` call made by the library).
Methods changing the state of the device do not invalidate the cache (i.e., there is no implicit :func:`SmartDevice.update()` call made by the library).
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:`KasaException` instances for the library user to handle.
Errors are raised as :class:`SmartDeviceException` instances for the library user to handle.
Simple example script showing some functionality for legacy devices:
Simple example script showing some functionality:
.. code-block:: python
@@ -45,31 +45,6 @@ Simple example script showing some functionality for legacy devices:
if __name__ == "__main__":
asyncio.run(main())
If you are connecting to a newer KASA or TAPO device you can get the device via discovery or
connect directly with :class:`DeviceConfig`:
.. code-block:: python
import asyncio
from kasa import Discover, Credentials
async def main():
device = await Discover.discover_single(
"127.0.0.1",
credentials=Credentials("myusername", "mypassword"),
discovery_timeout=10
)
config = device.config # DeviceConfig.to_dict() can be used to store for later
# To connect directly later without discovery
later_device = await SmartDevice.connect(config=config)
await later_device.update()
print(later_device.alias) # Print out the alias
If you want to perform updates in a loop, you need to make sure that the device accesses are done in the same event loop:
.. code-block:: python
@@ -92,22 +67,6 @@ Refer to device type specific classes for more examples:
:class:`SmartPlug`, :class:`SmartBulb`, :class:`SmartStrip`,
:class:`SmartDimmer`, :class:`SmartLightStrip`.
DeviceConfig class
******************
The :class:`DeviceConfig` class can be used to initialise devices with parameters to allow them to be connected to without using
discovery.
This is required for newer KASA and TAPO devices that use different protocols for communication and will not respond
on port 9999 but instead use different encryption protocols over http port 80.
Currently there are three known types of encryption for TP-Link devices and two different protocols.
Devices with automatic firmware updates enabled may update to newer versions of the encryption without separate notice,
so discovery can be helpful to determine the correct config.
To connect directly pass a :class:`DeviceConfig` object to :meth:`Device.connect()`.
A :class:`DeviceConfig` can be constucted manually if you know the :attr:`DeviceConfig.connection_type` values for the device or
alternatively the config can be retrieved from :attr:`Device.config` post discovery and then re-used.
Energy Consumption and Usage Statistics
***************************************
@@ -141,16 +100,6 @@ You can access this information using through the usage module (:class:`kasa.mod
API documentation
*****************
.. autoclass:: Device
:members:
:undoc-members:
.. autoclass:: DeviceConfig
:members:
:inherited-members:
:undoc-members:
:member-order: bysource
.. autoclass:: Credentials
.. autoclass:: SmartDevice
:members:
:undoc-members:

142
docs/source/design.rst → docs/source/topics.md
View File

@@ -1,70 +1,96 @@
.. py:module:: kasa.modules
# Topics
.. _library_design:
```{contents} Contents
:local:
```
Library Design & Modules
========================
This page aims to provide some details on the design and internals of this library.
These topics aim to provide some details on the design and internals of this library.
You might be interested in this if you want to improve this library,
or if you are just looking to access some information that is not currently exposed.
.. contents:: Contents
:local:
(topics-initialization)=
## Initialization
.. _initialization:
Initialization
**************
Use :func:`~kasa.Discover.discover` to perform udp-based broadcast discovery on the network.
Use {func}`~kasa.Discover.discover` to perform udp-based broadcast discovery on the network.
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.Device.connect()`.
{meth}`~kasa.Device.connect()`.
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.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.Device.connect()`.
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.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.Device.connect()`.
.. _update_cycle:
(topics-discovery)=
## Discovery
Update Cycle
************
Discovery works by sending broadcast UDP packets to two known TP-link discovery ports, 9999 and 20002.
Port 9999 is used for legacy devices that do not use strong encryption and 20002 is for newer devices that use different
levels of encryption.
If a device uses port 20002 for discovery you will obtain some basic information from the device via discovery, but you
will need to await {func}`Device.update() <kasa.Device.update()>` to get full device information.
Credentials will most likely be required for port 20002 devices although if the device has never been connected to the tplink
cloud it may work without credentials.
When :meth:`~kasa.Device.update()` is called,
To query or update the device requires authentication via {class}`Credentials <kasa.Credentials>` and if this is invalid or not provided it
will raise an {class}`AuthenticationException <kasa.AuthenticationException>`.
If discovery encounters an unsupported device when calling via {meth}`Discover.discover_single() <kasa.Discover.discover_single>`
it will raise a {class}`UnsupportedDeviceException <kasa.UnsupportedDeviceException>`.
If discovery encounters a device when calling {func}`Discover.discover() <kasa.Discover.discover>`,
you can provide a callback to the ``on_unsupported`` parameter
to handle these.
(topics-deviceconfig)=
## DeviceConfig
The {class}`DeviceConfig` class can be used to initialise devices with parameters to allow them to be connected to without using
discovery.
This is required for newer KASA and TAPO devices that use different protocols for communication and will not respond
on port 9999 but instead use different encryption protocols over http port 80.
Currently there are three known types of encryption for TP-Link devices and two different protocols.
Devices with automatic firmware updates enabled may update to newer versions of the encryption without separate notice,
so discovery can be helpful to determine the correct config.
To connect directly pass a {class}`DeviceConfig` object to {meth}`Device.connect()`.
A {class}`DeviceConfig` can be constucted manually if you know the {attr}`DeviceConfig.connection_type` values for the device or
alternatively the config can be retrieved from {attr}`Device.config` post discovery and then re-used.
(topics-update-cycle)=
## Update Cycle
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.
Internally, each module defines {meth}`~kasa.modules.Module.query()` to describe what they want query during the update.
The returned data is cached internally to avoid I/O on property accesses.
All properties defined both in the device class and in the module classes follow this principle.
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.Device.internal_state` property.
This can be done using the {attr}`~kasa.Device.internal_state` property.
.. _modules:
(topics-modules-and-features)=
## Modules and Features
Modules
*******
The functionality provided by all :class:`~kasa.Device` 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.Device.supported_modules`.
you can also access individual modules through {attr}`kasa.Device.modules`.
You can get the list of supported modules for a given device instance using {attr}`~kasa.Device.supported_modules`.
.. note::
```{note}
If you only need some module-specific information,
you can call the wanted method on the module to avoid using {meth}`~kasa.Device.update`.
```
If you only need some module-specific information,
you can call the wanted method on the module to avoid using :meth:`~kasa.Device.update`.
Protocols and Transports
************************
(topics-protocols-and-transports)=
## Protocols and Transports
The library supports two different TP-Link protocols, ``IOT`` and ``SMART``.
``IOT`` is the original Kasa protocol and ``SMART`` is the newer protocol supported by TAPO devices and newer KASA devices.
@@ -90,27 +116,29 @@ In order to support these different configurations the library migrated from a s
to support pluggable transports and protocols.
The classes providing this functionality are:
- :class:`BaseProtocol <kasa.protocol.BaseProtocol>`
- :class:`IotProtocol <kasa.iotprotocol.IotProtocol>`
- :class:`SmartProtocol <kasa.smartprotocol.SmartProtocol>`
- {class}`BaseProtocol <kasa.protocol.BaseProtocol>`
- {class}`IotProtocol <kasa.iotprotocol.IotProtocol>`
- {class}`SmartProtocol <kasa.smartprotocol.SmartProtocol>`
- :class:`BaseTransport <kasa.protocol.BaseTransport>`
- :class:`XorTransport <kasa.xortransport.XorTransport>`
- :class:`AesTransport <kasa.aestransport.AesTransport>`
- :class:`KlapTransport <kasa.klaptransport.KlapTransport>`
- :class:`KlapTransportV2 <kasa.klaptransport.KlapTransportV2>`
- {class}`BaseTransport <kasa.protocol.BaseTransport>`
- {class}`XorTransport <kasa.xortransport.XorTransport>`
- {class}`AesTransport <kasa.aestransport.AesTransport>`
- {class}`KlapTransport <kasa.klaptransport.KlapTransport>`
- {class}`KlapTransportV2 <kasa.klaptransport.KlapTransportV2>`
Errors and Exceptions
*********************
(topics-errors-and-exceptions)=
## Errors and Exceptions
The base exception for all library errors is :class:`KasaException <kasa.exceptions.KasaException>`.
The base exception for all library errors is {class}`KasaException <kasa.exceptions.KasaException>`.
- If the device returns an error the library raises a :class:`DeviceError <kasa.exceptions.DeviceError>` which will usually contain an ``error_code`` with the detail.
- If the device fails to authenticate the library raises an :class:`AuthenticationError <kasa.exceptions.AuthenticationError>` which is derived
from :class:`DeviceError <kasa.exceptions.DeviceError>` and could contain an ``error_code`` depending on the type of failure.
- If the library encounters and unsupported deviceit raises an :class:`UnsupportedDeviceError <kasa.exceptions.UnsupportedDeviceError>`.
- 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.
- If the device returns an error the library raises a {class}`DeviceError <kasa.exceptions.DeviceError>` which will usually contain an ``error_code`` with the detail.
- If the device fails to authenticate the library raises an {class}`AuthenticationError <kasa.exceptions.AuthenticationError>` which is derived
from {class}`DeviceError <kasa.exceptions.DeviceError>` and could contain an ``error_code`` depending on the type of failure.
- If the library encounters and unsupported deviceit raises an {class}`UnsupportedDeviceError <kasa.exceptions.UnsupportedDeviceError>`.
- 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.
<!-- Commenting out this section keeps git seeing the change as a rename.
API documentation for modules and features
******************************************
@@ -200,3 +228,5 @@ API documentation for errors and exceptions
.. autoclass:: kasa.exceptions.TimeoutError
:members:
:undoc-members:
-->

2
docs/source/tutorial.md
View File

@@ -1,4 +1,4 @@
# Tutorial
# Getting started
```{eval-rst}
.. automodule:: tutorial

11
docs/tutorial.py
View File

@@ -13,21 +13,24 @@ Most newer devices require your TP-Link cloud username and password, but this ca
>>> from kasa import Device, Discover, Credentials
:func:`~kasa.Discover.discover` returns a list of devices on your network:
:func:`~kasa.Discover.discover` returns a dict[str,Device] of devices on your network:
>>> devices = await Discover.discover(credentials=Credentials("user@example.com", "great_password"))
>>> for dev in devices:
>>> for dev in devices.values():
>>> await dev.update()
>>> print(dev.host)
127.0.0.1
127.0.0.2
127.0.0.3
127.0.0.4
127.0.0.5
:meth:`~kasa.Discover.discover_single` returns a single device by hostname:
>>> dev = await Discover.discover_single("127.0.0.1", credentials=Credentials("user@example.com", "great_password"))
>>> dev = await Discover.discover_single("127.0.0.3", credentials=Credentials("user@example.com", "great_password"))
>>> await dev.update()
>>> dev.alias
Living Room
Living Room Bulb
>>> dev.model
L530
>>> dev.rssi