From 59e5073509945ce83282ba6404df283576b61899 Mon Sep 17 00:00:00 2001 From: "Steven B." <51370195+sdb9696@users.noreply.github.com> Date: Fri, 13 Dec 2024 21:23:58 +0000 Subject: [PATCH] Update docs for new FeatureAttribute behaviour (#1365) Co-authored-by: Teemu R. --- docs/source/featureattributes.md | 13 ++++ docs/source/reference.md | 64 ++++-------------- docs/source/topics.md | 110 +++---------------------------- kasa/module.py | 3 + 4 files changed, 39 insertions(+), 151 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 00000000..69285ad4 --- /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. +For example: + +```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 f4771ac5..90493c9c 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,64 +81,29 @@ ## Protocols and transports + ```{eval-rst} -.. autoclass:: kasa.protocols.BaseProtocol +.. automodule:: kasa.protocols :members: - :inherited-members: + :imported-members: :undoc-members: + :exclude-members: SmartErrorCode + :no-index: ``` ```{eval-rst} -.. autoclass:: kasa.protocols.IotProtocol +.. automodule:: kasa.transports :members: - :inherited-members: + :imported-members: :undoc-members: + :no-index: ``` -```{eval-rst} -.. autoclass:: kasa.protocols.SmartProtocol - :members: - :inherited-members: - :undoc-members: -``` - -```{eval-rst} -.. autoclass:: kasa.transports.BaseTransport - :members: - :inherited-members: - :undoc-members: -``` - -```{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: -``` - -```{eval-rst} -.. autoclass:: kasa.transports.AesTransport - :members: - :inherited-members: - :undoc-members: -``` ## Errors and exceptions + + ```{eval-rst} .. autoclass:: kasa.exceptions.KasaException :members: @@ -171,3 +132,4 @@ .. autoclass:: kasa.exceptions.TimeoutError :members: :undoc-members: +``` diff --git a/docs/source/topics.md b/docs/source/topics.md index 0dcc60d1..f7d0cdd5 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 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 b86d1521..2ca29307 100644 --- a/kasa/module.py +++ b/kasa/module.py @@ -21,6 +21,9 @@ check for the existence of the module: >>> 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: