docs: modernize docstrings across the repository#1682
docs: modernize docstrings across the repository#1682ZeliardM wants to merge 1 commit intopython-kasa:masterfrom
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #1682 +/- ##
==========================================
+ Coverage 93.22% 93.24% +0.02%
==========================================
Files 157 157
Lines 9815 9815
Branches 1003 1003
==========================================
+ Hits 9150 9152 +2
+ Misses 472 471 -1
+ Partials 193 192 -1 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Pull request overview
This PR updates the IotBulb class docstring examples to use the current module-based API (bulb.modules[Module.Light], Module.LightPreset) instead of deprecated device-level properties, and adjusts the doctest fixture setup to match the new example outputs.
Changes:
- Modernize
kasa/iot/iotbulb.pydocstring examples to useModule.Light/has_feature()/get_feature()andModule.LightPreset. - Update doctest expectations (alias text, color temp range example, preset example syntax/output).
- Set the bulb alias in
tests/test_readme_examples.pyso the doctest output matches the new docstring.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| kasa/iot/iotbulb.py | Updates IotBulb docstring examples to the Module-based interfaces and fixes doctest example issues. |
| tests/test_readme_examples.py | Sets the fixture bulb alias to align doctest output with updated docstring examples. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Fix :func: -> :meth: Sphinx references for instance methods (iotbulb, iotdevice, iotplug, iotstrip, iotdimmer, discover) - Fix >>> -> ... for continuation lines in code examples across all docstrings (device, deviceconfig, discover, feature, module, tutorial, light, lightpreset, lighteffect, childsetup, childdevice, iotstrip) - Fix stale class references: SmartPlug -> IotPlug, SmartBulb -> IotBulb (iotstrip, iotdimmer, iotlightstrip) - Fix set literal -> dict literal bug in lighteffect.py example - Suppress return values in tutorial.py to fix xdoctest output matching - Modernize IotBulb docstring to use Module.Light/Module.LightPreset interface instead of deprecated device-level properties - Update test_readme_examples.py fixture for modernized bulb docstring
2615cb7 to
f5fb74d
Compare
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 18 out of 18 changed files in this pull request and generated 3 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
@rytilahti This PR should be good to go as well now for all of the docstring updates. |
Summary
Comprehensive docstring cleanup across the repository — fix Sphinx cross-references, Python REPL continuation syntax, stale class names, and modernize the IotBulb docstring to use the
Module.Light/Module.LightPresetinterface.Changes
Sphinx cross-references (
:func:→:meth:):iotbulb.py:update(),has_feature,turn_on/off,set_hsv/color_temp/brightness,save_presetiotdevice.py,iotplug.py,iotstrip.py,iotdimmer.py:update()discover.py:Discover.discover(),discover_single()REPL continuation syntax (
>>>→...):device.py,deviceconfig.py,discover.py,feature.py,module.py,tutorial.py,light.py,lightpreset.py,lighteffect.py,childsetup.py,childdevice.py,iotstrip.py...for continuation lines insideforloops,ifblocks, and multi-line function callsStale class references:
iotstrip.py::class:\SmartPlug`→:class:`IotPlug``iotdimmer.py::class:\SmartPlug`→:class:`IotPlug`` (x2)iotlightstrip.py::class:\SmartBulb`→:class:`IotBulb`` (x2)Bug fixes:
lighteffect.py: Fixed set literal{ "brightness", 50 }→ dict literal{"brightness": 50}tutorial.py: Suppressset_effect()/set_value()return values that leaked into xdoctest outputIotBulb docstring modernization:
bulb.brightness,bulb.is_dimmable, etc.) withModule.Light/Module.LightPresetinterfacetest_readme_examples.pyfixture to use KL130 with matching aliasFiles changed (18)
docs/tutorial.py,kasa/device.py,kasa/deviceconfig.py,kasa/discover.py,kasa/feature.py,kasa/interfaces/childsetup.py,kasa/interfaces/light.py,kasa/interfaces/lighteffect.py,kasa/interfaces/lightpreset.py,kasa/iot/iotbulb.py,kasa/iot/iotdevice.py,kasa/iot/iotdimmer.py,kasa/iot/iotlightstrip.py,kasa/iot/iotplug.py,kasa/iot/iotstrip.py,kasa/module.py,kasa/smart/modules/childdevice.py,tests/test_readme_examples.pyMerge order
This is PR 3 of 9 in the test modernization series. Independent of test annotation PRs.
Verification
tests/test_readme_examples.py)