From 1183c10c6bd539d1bf235cf06614b8695c87ed6d Mon Sep 17 00:00:00 2001 From: Steven B <51370195+sdb9696@users.noreply.github.com> Date: Wed, 11 Dec 2024 18:10:43 +0000 Subject: [PATCH 1/3] Update docs for new FeatureAttribute behaviour --- docs/source/featureattributes.md | 13 ++++ docs/source/reference.md | 60 ++++------------- docs/source/topics.md | 110 +++---------------------------- kasa/module.py | 3 + 4 files changed, 37 insertions(+), 149 deletions(-) create mode 100644 docs/source/featureattributes.md diff --git a/docs/source/featureattributes.md b/docs/source/featureattributes.md new file mode 100644 index 000000000..a2b9b4e2c --- /dev/null +++ b/docs/source/featureattributes.md @@ -0,0 +1,13 @@ +Some modules have attributes that may not be supported by the device. +These attributes will be annotated with a `FeatureAttribute` return type. +i.e. + +```py + @property + def hsv(self) -> Annotated[HSV, FeatureAttribute()]: + """Return the current HSV state of the bulb.""" +``` + +You can test whether a `FeatureAttribute` is supported by the device with {meth}`kasa.Module.has_feature` +or {meth}`kasa.Module.get_feature` which will return `None` if not supported. +Calling these methods on attributes not annotated with a `FeatureAttribute` return type will return an error. diff --git a/docs/source/reference.md b/docs/source/reference.md index f4771ac5d..90493c9c2 100644 --- a/docs/source/reference.md +++ b/docs/source/reference.md @@ -13,11 +13,13 @@ ## Device +% N.B. Credentials clashes with autodoc ```{eval-rst} .. autoclass:: Device :members: :undoc-members: + :exclude-members: Credentials ``` @@ -28,7 +30,6 @@ .. autoclass:: Credentials :members: :undoc-members: - :noindex: ``` @@ -61,15 +62,11 @@ ```{eval-rst} .. autoclass:: Module - :noindex: :members: - :inherited-members: - :undoc-members: ``` ```{eval-rst} .. autoclass:: Feature - :noindex: :members: :inherited-members: :undoc-members: @@ -77,7 +74,6 @@ ```{eval-rst} .. automodule:: kasa.interfaces - :noindex: :members: :inherited-members: :undoc-members: @@ -85,63 +81,28 @@ ## Protocols and transports -```{eval-rst} -.. autoclass:: kasa.protocols.BaseProtocol - :members: - :inherited-members: - :undoc-members: -``` - -```{eval-rst} -.. autoclass:: kasa.protocols.IotProtocol - :members: - :inherited-members: - :undoc-members: -``` ```{eval-rst} -.. autoclass:: kasa.protocols.SmartProtocol +.. automodule:: kasa.protocols :members: - :inherited-members: + :imported-members: :undoc-members: + :exclude-members: SmartErrorCode + :no-index: ``` ```{eval-rst} -.. autoclass:: kasa.transports.BaseTransport +.. automodule:: kasa.transports :members: - :inherited-members: + :imported-members: :undoc-members: + :no-index: ``` -```{eval-rst} -.. autoclass:: kasa.transports.XorTransport - :members: - :inherited-members: - :undoc-members: -``` -```{eval-rst} -.. autoclass:: kasa.transports.KlapTransport - :members: - :inherited-members: - :undoc-members: -``` - -```{eval-rst} -.. autoclass:: kasa.transports.KlapTransportV2 - :members: - :inherited-members: - :undoc-members: -``` +## Errors and exceptions -```{eval-rst} -.. autoclass:: kasa.transports.AesTransport - :members: - :inherited-members: - :undoc-members: -``` -## Errors and exceptions ```{eval-rst} .. autoclass:: kasa.exceptions.KasaException @@ -171,3 +132,4 @@ .. autoclass:: kasa.exceptions.TimeoutError :members: :undoc-members: +``` diff --git a/docs/source/topics.md b/docs/source/topics.md index 0dcc60d19..ea229bbd8 100644 --- a/docs/source/topics.md +++ b/docs/source/topics.md @@ -80,14 +80,17 @@ This can be done using the {attr}`~kasa.Device.internal_state` property. ## Modules and Features 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.Device.modules`. -You can get the list of supported modules for a given device instance using {attr}`~kasa.Device.supported_modules`. +While the device class provides easy access for most device related attributes, +for components of functionality like `light` and `camera` you can access the module through {attr}`kasa.Device.modules`. +The module names are handily available as constants on {class}`~kasa.Module` and will return type aware values from the collection. -```{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`. -``` +Features represent individual pieces of functionality within a module like brightness, hsv and temperature within a light module. +They allow for instrospection and can be accessed through {attr}`kasa.Device.features`. +Attributes can be accessed via a `Feature` or a module attribute depending on the use case. +Modules tend to provide richer functionality but using the features does not require an understanding of the module api. + +:::{include} featureattributes.md +::: (topics-protocols-and-transports)= ## Protocols and Transports @@ -137,96 +140,3 @@ The base exception for all library errors is {class}`KasaException `. - If the device fails to respond within a timeout the library raises a {class}`TimeoutError `. - All other failures will raise the base {class}`KasaException ` class. - - diff --git a/kasa/module.py b/kasa/module.py index 2b2e65f93..6a4eeb9b1 100644 --- a/kasa/module.py +++ b/kasa/module.py @@ -21,6 +21,9 @@ >>> print(light.brightness) 100 +.. include:: ../featureattributes.md + :parser: myst_parser.sphinx_ + To see whether a device supports specific functionality, you can check whether the module has that feature: From 9c36983b9d218608c78c6b085510e56f931a60c3 Mon Sep 17 00:00:00 2001 From: "Steven B." <51370195+sdb9696@users.noreply.github.com> Date: Fri, 13 Dec 2024 14:44:19 +0000 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Teemu R. --- docs/source/featureattributes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/featureattributes.md b/docs/source/featureattributes.md index a2b9b4e2c..69285ad46 100644 --- a/docs/source/featureattributes.md +++ b/docs/source/featureattributes.md @@ -1,6 +1,6 @@ Some modules have attributes that may not be supported by the device. These attributes will be annotated with a `FeatureAttribute` return type. -i.e. +For example: ```py @property From bb3596a4392e4ea2569fdf4ef60338b8c0fec32b Mon Sep 17 00:00:00 2001 From: Steven B <51370195+sdb9696@users.noreply.github.com> Date: Fri, 13 Dec 2024 14:48:22 +0000 Subject: [PATCH 3/3] Tweak components of features --- docs/source/topics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/topics.md b/docs/source/topics.md index ea229bbd8..f7d0cdd50 100644 --- a/docs/source/topics.md +++ b/docs/source/topics.md @@ -81,7 +81,7 @@ This can be done using the {attr}`~kasa.Device.internal_state` property. The functionality provided by all {class}`~kasa.Device` instances is (mostly) done inside separate modules. While the device class provides easy access for most device related attributes, -for components of functionality like `light` and `camera` you can access the module through {attr}`kasa.Device.modules`. +for components like `light` and `camera` you can access the module through {attr}`kasa.Device.modules`. The module names are handily available as constants on {class}`~kasa.Module` and will return type aware values from the collection. Features represent individual pieces of functionality within a module like brightness, hsv and temperature within a light module.