Consolidate update parameters

kasa/device.py

@@ -233,8 +233,18 @@ class Device(ABC):
         return await connect(host=host, config=config)  # type: ignore[arg-type]
 
     @abstractmethod
-    async def update(self, update_children: bool = True, update_parent: bool = True):
+    async def update(self, update_children_or_parent: bool = True):
-        """Update the device."""
+        """Update the device.
+
+        Must be called after updating any attributes for the state changes
+        to be reflected on the device.
+
+        :param update_children_or_parent: On a parent device when true will
+            call update on all the child devices. On a child device when true
+            will also update the parent device. Setting to false requires
+            knowledge of the inner workings of the library and should be used
+            with caution.
+        """
 
     async def disconnect(self):
         """Disconnect and close any underlying connection resources."""

kasa/iot/iotdevice.py

@@ -283,7 +283,7 @@ class IotDevice(Device):
         """Retrieve system information."""
         return await self._query_helper("system", "get_sysinfo")
 
-    async def update(self, update_children: bool = True):
+    async def update(self, update_children_or_parent: bool = True):
         """Query the device to update the data.
 
         Needed for properties that are decorated with `requires_update`.

kasa/iot/iotstrip.py

@@ -121,12 +121,12 @@ class IotStrip(IotDevice):
         """Return if any of the outlets are on."""
         return any(plug.is_on for plug in self.children)
 
-    async def update(self, update_children: bool = True, update_parent: bool = True):
+    async def update(self, update_children_or_parent: bool = True):
         """Update some of the attributes.
 
         Needed for methods that are decorated with `requires_update`.
         """
-        await self._update(update_children)
+        await self._update(update_children_or_parent)
 
     async def _update(
         self,
@@ -368,13 +368,13 @@ class IotStripPlug(IotPlug):
             for module_feat in module._module_features.values():
                 self._add_feature(module_feat)
 
-    async def update(self, update_children: bool = True, update_parent: bool = True):
+    async def update(self, update_children_or_parent: bool = True):
         """Query the device to update the data.
 
         Needed for properties that are decorated with `requires_update`.
         """
-        if update_parent:
+        if update_children_or_parent:
-            await self.parent._update(update_children=False, called_from_child=self)
+            await self.parent._update(called_from_child=self)
         else:
             await self._update()
 

kasa/smart/smartchilddevice.py

@@ -36,14 +36,14 @@ class SmartChildDevice(SmartDevice):
         self._id = info["device_id"]
         self.protocol = _ChildProtocolWrapper(self._id, parent.protocol)
 
-    async def update(self, update_children: bool = True, update_parent: bool = True):
+    async def update(self, update_children_or_parent: bool = True):
         """Update the device.
 
         Calling update directly on a child device will update the parent
         and only this child.
         """
-        if update_parent:
+        if update_children_or_parent:
-            await self._parent._update(update_children=False, called_from_child=self)
+            await self._parent._update(called_from_child=self)
         else:
             await self._update()
 

kasa/smart/smartdevice.py

@@ -147,9 +147,9 @@ class SmartDevice(Device):
         if "child_device" in self._components and not self.children:
             await self._initialize_children()
 
-    async def update(self, update_children: bool = True, update_parent: bool = True):
+    async def update(self, update_children_or_parent: bool = True):
         """Update the device."""
-        await self._update(update_children)
+        await self._update(update_children_or_parent)
 
     async def _update(
         self, update_children: bool = True, called_from_child: SmartDevice | None = None

kasa/tests/test_childdevice.py

@@ -120,29 +120,29 @@ async def test_device_updates(dev: Device, mocker: MockerFixture):
     parent_spy = mocker.spy(dev, "_update")
     child_spies = {child: mocker.spy(child, "_update") for child in dev.children}
 
-    # update children
+    # update children, all devices call update
-    await dev.update(update_children=True)
+    await dev.update(update_children_or_parent=True)
     parent_spy.assert_called_once()
     for child_spy in child_spies.values():
         child_spy.assert_called_once()
 
-    # do not update children
+    # do not update children, only parent calls update
     parent_spy.reset_mock()
     for child_spy in child_spies.values():
         child_spy.reset_mock()
 
-    await dev.update(update_children=False)
+    await dev.update(update_children_or_parent=False)
     parent_spy.assert_called_once()
     for child_spy in child_spies.values():
         child_spy.assert_not_called()
 
-    # update parent
+    # update parent, only the parent and one child call update
     parent_spy.reset_mock()
     for child_spy in child_spies.values():
         child_spy.reset_mock()
 
     child_to_update = dev.children[0]
-    await child_to_update.update(update_parent=True)
+    await child_to_update.update(update_children_or_parent=True)
     parent_spy.assert_called_once()
     assert child_to_update
     for child, child_spy in child_spies.items():
@@ -151,12 +151,12 @@ async def test_device_updates(dev: Device, mocker: MockerFixture):
         else:
             child_spy.assert_not_called()
 
-    # do not update parent
+    # do not update parent, only the one child calls update
     parent_spy.reset_mock()
     for child_spy in child_spies.values():
         child_spy.reset_mock()
 
-    await child_to_update.update(update_parent=False)
+    await child_to_update.update(update_children_or_parent=False)
     parent_spy.assert_not_called()
     assert child_to_update
     for child, child_spy in child_spies.items():