Skip to content

Update docs for new FeatureAttribute behaviour #1365

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Dec 13, 2024
Merged

Update docs for new FeatureAttribute behaviour #1365

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1183c10
Update docs for new FeatureAttribute behaviour
sdb9696 Dec 11, 2024
9c36983
Apply suggestions from code review
sdb9696 Dec 13, 2024
bb3596a
Tweak components of features
sdb9696 Dec 13, 2024
8e74c1e
Merge branch 'master' into docs/mod_feat
sdb9696 Dec 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions docs/source/featureattributes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Comment on lines +12 to +13
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
or {meth}`kasa.Module.get_feature` which will return `None` if not supported.
For example:
< here and example on how to check for the HSV feature above>
Calling these methods on attributes not annotated with a `FeatureAttribute` return type will return an error.

How about?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This snippet is included in the repl rst section for Module so it would look odd having an example that gets repeated.

60 changes: 11 additions & 49 deletions docs/source/reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,13 @@

## Device

% N.B. Credentials clashes with autodoc

```{eval-rst}
.. autoclass:: Device
:members:
:undoc-members:
:exclude-members: Credentials
```


Expand All @@ -28,7 +30,6 @@
.. autoclass:: Credentials
:members:
:undoc-members:
:noindex:
```


Expand Down Expand Up @@ -61,87 +62,47 @@

```{eval-rst}
.. autoclass:: Module
:noindex:
:members:
:inherited-members:
:undoc-members:
```

```{eval-rst}
.. autoclass:: Feature
:noindex:
:members:
:inherited-members:
:undoc-members:
```

```{eval-rst}
.. automodule:: kasa.interfaces
:noindex:
:members:
:inherited-members:
:undoc-members:
```

## 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
Expand Down Expand Up @@ -171,3 +132,4 @@
.. autoclass:: kasa.exceptions.TimeoutError
:members:
:undoc-members:
```
110 changes: 10 additions & 100 deletions docs/source/topics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -137,96 +140,3 @@ The base exception for all library errors is {class}`KasaException <kasa.excepti
- 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
******************************************

.. 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:
:undoc-members:



API documentation for protocols and transports
**********************************************

.. autoclass:: kasa.protocols.BaseProtocol
:members:
:inherited-members:
:undoc-members:

.. autoclass:: kasa.protocols.IotProtocol
:members:
:inherited-members:
:undoc-members:

.. autoclass:: kasa.protocols.SmartProtocol
:members:
:inherited-members:
:undoc-members:

.. autoclass:: kasa.transports.BaseTransport
:members:
:inherited-members:
:undoc-members:

.. autoclass:: kasa.transports.XorTransport
:members:
:inherited-members:
:undoc-members:

.. autoclass:: kasa.transports.KlapTransport
:members:
:inherited-members:
:undoc-members:

.. autoclass:: kasa.transports.KlapTransportV2
:members:
:inherited-members:
:undoc-members:

.. autoclass:: kasa.transports.AesTransport
:members:
:inherited-members:
:undoc-members:

API documentation for errors and exceptions
*******************************************

.. autoclass:: kasa.exceptions.KasaException
:members:
:undoc-members:

.. autoclass:: kasa.exceptions.DeviceError
:members:
:undoc-members:

.. autoclass:: kasa.exceptions.AuthenticationError
:members:
:undoc-members:

.. autoclass:: kasa.exceptions.UnsupportedDeviceError
:members:
:undoc-members:

.. autoclass:: kasa.exceptions.TimeoutError
:members:
:undoc-members:

-->
3 changes: 3 additions & 0 deletions kasa/module.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
Loading