8000 Update docs for new FeatureAttribute behaviour (#1365) · python-kasa/python-kasa@59e5073 · GitHub
[go: up one dir, main page]
Skip to content

Commit 59e5073

Browse files
sdb9696rytilahti
sdb9696
and
rytilahti
authored
Update docs for new FeatureAttribute behaviour (#1365)
Co-authored-by: Teemu R. <tpr@iki.fi>
1 parent 2ca6d3e commit 59e5073

File tree

4 files changed

+37
-149
lines changed

4 files changed

+37
-149
lines changed

‎docs/source/featureattributes.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
Some modules have attributes that may not be supported by the device.
2+
These attributes will be annotated with a `FeatureAttribute` return type.
3+
For example:
4+
5+
```py
6+
@property
7+
def hsv(self) -> Annotated[HSV, FeatureAttribute()]:
8+
"""Return the current HSV state of the bulb."""
9+
```
10+
11+
You can test whether a `FeatureAttribute` is supported by the device with {meth}`kasa.Module.has_feature`
12+
or {meth}`kasa.Module.get_feature` which will return `None` if not supported.
13+
Calling these methods on attributes not annotated with a `FeatureAttribute` return type will return an error.

‎docs/source/reference.md

Lines changed: 11 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,13 @@
1313

1414
## Device
1515

16+
% N.B. Credentials clashes with autodoc
1617

1718
```{eval-rst}
1819
.. autoclass:: Device
1920
:members:
2021
:undoc-members:
22+
:exclude-members: Credentials
2123
```
2224

2325

@@ -28,7 +30,6 @@
2830
.. autoclass:: Credentials
2931
:members:
3032
:undoc-members:
31-
:noindex:
3233
```
3334

3435

@@ -61,87 +62,47 @@
6162

6263
```{eval-rst}
6364
.. autoclass:: Module
64-
:noindex:
6565
:members:
66-
:inherited-members:
67-
:undoc-members:
6866
```
6967

7068
```{eval-rst}
7169
.. autoclass:: Feature
72-
:noindex:
7370
:members:
7471
:inherited-members:
7572
:undoc-members:
7673
```
7774

7875
```{eval-rst}
7976
.. automodule:: kasa.interfaces
80-
:noindex:
8177
:members:
8278
:inherited-members:
8379
:undoc-members:
8480
```
8581

8682
## Protocols and transports
8783

88-
```{eval-rst}
89-
.. autoclass:: kasa.protocols.BaseProtocol
90-
:members:
91-
:inherited-members:
92-
:undoc-members:
93-
```
94-
95-
```{eval-rst}
96-
.. autoclass:: kasa.protocols.IotProtocol
97-
:members:
98-
:inherited-members:
99-
:undoc-members:
100-
```
10184

10285
```{eval-rst}
103-
.. autoclass:: kasa.protocols.SmartProtocol
86+
.. automodule:: kasa.protocols
10487
:members:
105-
:inherited-members:
88+
:imported-members:
10689
:undoc-members:
90+
:exclude-members: SmartErrorCode
91+
:no-index:
10792
```
10893

10994
```{eval-rst}
110-
.. autoclass:: kasa.transports.BaseTransport
95+
.. automodule:: kasa.transports
11196
:members:
112-
:inherited-members:
97+
:imported-members:
11398
:undoc-members:
99+
:no-index:
114100
```
115101

116-
```{eval-rst}
117-
.. autoclass:: kasa.transports.XorTransport
118-
:members:
119-
:inherited-members:
120-
:undoc-members:
121-
```
122102

123-
```{eval-rst}
124-
.. autoclass:: kasa.transports.KlapTransport
125-
:members:
126-
:inherited-members:
127-
:undoc-members:
128-
```
129-
130-
```{eval-rst}
131-
.. autoclass:: kasa.transports.KlapTransportV2
132-
:members:
133-
:inherited-members:
134-
:undoc-members:
135-
```
103+
## Errors and exceptions
136104

137-
```{eval-rst}
138-
.. autoclass:: kasa.transports.AesTransport
139-
:members:
140-
:inherited-members:
141-
:undoc-members:
142-
```
143105

144-
## Errors and exceptions
145106

146107
```{eval-rst}
147108
.. autoclass:: kasa.exceptions.KasaException
@@ -171,3 +132,4 @@
171132
.. autoclass:: kasa.exceptions.TimeoutError
172133
:members:
173134
:undoc-members:
135+
```

‎docs/source/topics.md

Lines changed: 10 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -80,14 +80,17 @@ This can be done using the {attr}`~kasa.Device.internal_state` property.
8080
## Modules and Features
8181

8282
The functionality provided by all {class}`~kasa.Device` instances is (mostly) done inside separate modules.
83-
While the individual device-type specific classes provide an easy access for the most import features,
84-
you can also access individual modules through {attr}`kasa.Device.modules`.
85-
You can get the list of supported modules for a given device instance using {attr}`~kasa.Device.supported_modules`.
83+
While the device class provides easy access for most device related attributes,
84+
for components like `light` and `camera` you can access the module through {attr}`kasa.Device.modules`.
85+
The module names are handily available as constants on {class}`~kasa.Module` and will return type aware values from the collection.
8686

87-
```{note}
88-
If you only need some module-specific information,
89-
you can call the wanted method on the module to avoid using {meth}`~kasa.Device.update`.
90-
```
87+
Features represent individual pieces of functionality within a module like brightness, hsv and temperature within a light module.
88+
They allow for instrospection and can be accessed through {attr}`kasa.Device.features`.
89+
Attributes can be accessed via a `Feature` or a module attribute depending on the use case.
90+
Modules tend to provide richer functionality but using the features does not require an understanding of the module api.
91+
92+
:::{include} featureattributes.md
93+
:::
9194

9295
(topics-protocols-and-transports)=
9396
## Protocols and Transports
@@ -137,96 +140,3 @@ The base exception for all library errors is {class}`KasaException <kasa.excepti
137140
- If the library encounters and unsupported deviceit raises an {class}`UnsupportedDeviceError <kasa.exceptions.UnsupportedDeviceError>`.
138141
- If the device fails to respond within a timeout the library raises a {class}`TimeoutError <kasa.exceptions.TimeoutError>`.
139142
- All other failures will raise the base {class}`KasaException <kasa.exceptions.KasaException>` class.
140-
141-
<!-- Commenting out this section keeps git seeing the change as a rename.
142-
143-
API documentation for modules and features
144-
******************************************
145-
146-
.. autoclass:: kasa.Module
147-
:noindex:
148-
:members:
149-
:inherited-members:
150-
:undoc-members:
151-
152-
.. automodule:: kasa.interfaces
153-
:noindex:
154-
:members:
155-
:inherited-members:
156-
:undoc-members:
157-
158-
.. autoclass:: kasa.Feature
159-
:noindex:
160-
:members:
161-
:inherited-members:
162-
:undoc-members:
163-
164-
165-
166-
API documentation for protocols and transports
167-
**********************************************
168-
169-
.. autoclass:: kasa.protocols.BaseProtocol
170-
:members:
171-
:inherited-members:
172-
:undoc-members:
173-
174-
.. autoclass:: kasa.protocols.IotProtocol
175-
:members:
176-
:inherited-members:
177-
:undoc-members:
178-
179-
.. autoclass:: kasa.protocols.SmartProtocol
180-
:members:
181-
:inherited-members:
182-
:undoc-members:
183-
184-
.. autoclass:: kasa.transports.BaseTransport
185-
:members:
186-
:inherited-members:
187-
:undoc-members:
188-
189-
.. autoclass:: kasa.transports.XorTransport
190-
:members:
191-
:inherited-members:
192-
:undoc-members:
193-
194-
.. autoclass:: kasa.transports.KlapTransport
195-
:members:
196-
:inherited-members:
197-
:undoc-members:
198-
199-
.. autoclass:: kasa.transports.KlapTransportV2
200-
:members:
201-
:inherited-members:
202-
:undoc-members:
203-
204-
.. autoclass:: kasa.transports.AesTransport
205-
:members:
206-
:inherited-members:
207-
:undoc-members:
208-
209-
API documentation for errors and exceptions
210-
*******************************************
211-
212-
.. autoclass:: kasa.exceptions.KasaException
213-
:members:
214-
:undoc-members:
215-
216-
.. autoclass:: kasa.exceptions.DeviceError
217-
:members:
218-
:undoc-members:
219-
220-
.. autoclass:: kasa.exceptions.AuthenticationError
221-
:members:
222-
:undoc-members:
223-
224-
.. autoclass:: kasa.exceptions.UnsupportedDeviceError
225-
:members:
226-
:undoc-members:
227-
228-
.. autoclass:: kasa.exceptions.TimeoutError
229-
:members:
230-
:undoc-members:
231-
232-
-->

‎kasa/module.py

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,9 @@
2121
>>> print(light.brightness)
2222
100
2323
24+
.. include:: ../featureattributes.md
25+
:parser: myst_parser.sphinx_
26+
2427
To see whether a device supports specific functionality, you can check whether the
2528
module has that feature:
2629

0 commit comments

Comments
 (0)
0