Merge pull request #208 from MTrab:Fix-docstrings

Multiple updates to docstrings

.vscode/launch.json

@@ -14,10 +14,10 @@
             "subProcess": true
         },
         {
-            "name": "test_async.py",
+            "name": "test_with.py",
             "type": "python",
             "request": "launch",
-            "program": "${workspaceFolder}/test_async.py",
+            "program": "${workspaceFolder}/test_with.py",
             "console": "integratedTerminal",
             "justMyCode": true,
             "subProcess": true

pyworxcloud/__init__.py

@@ -253,11 +253,8 @@ def disconnect(self) -> None:
     def connect(
         self,
     ) -> bool:
-        """Connect to the cloud service endpoint
-
-        Args:
-            index (int | None, optional): Device number to connect to. Defaults to None.
-            verify_ssl (bool, optional): Should we verify SSL certificate. Defaults to True.
+        """
+        Connect to the cloud service endpoint
 
         Returns:
             bool: True if connection was successful, otherwise False.
@@ -714,7 +711,11 @@ def _fetch(self) -> None:
                 )
 
     def get_mower(self, serial_number: str) -> dict:
-        """Get a specific mower."""
+        """Get a specific mower object.
+
+        Args:
+            serial_number (str): Serial number of the device
+        """
         for mower in self._mowers:
             if mower["serial_number"] == serial_number:
                 return mower
@@ -737,6 +738,9 @@ def update(self, serial_number: str) -> None:
     def start(self, serial_number: str) -> None:
         """Start mowing task
 
+        Args:
+            serial_number (str): Serial number of the device
+
         Raises:
             OfflineError: Raised if the device is offline.
         """
@@ -757,6 +761,9 @@ def home(self, serial_number: str) -> None:
         If the knifes was turned on when this is called,
         it will return home with knifes still turned on.
 
+        Args:
+            serial_number (str): Serial number of the device
+
         Raises:
             OfflineError: Raised if the device is offline.
         """
@@ -775,6 +782,9 @@ def home(self, serial_number: str) -> None:
     def safehome(self, serial_number: str) -> None:
         """Stop and go home with the blades off
 
+        Args:
+            serial_number (str): Serial number of the device
+
         Raises:
             OfflineError: Raised if the device is offline.
         """
@@ -792,22 +802,8 @@ def safehome(self, serial_number: str) -> None:
     def pause(self, serial_number: str) -> None:
         """Pause the mowing task
 
-        Raises:
-            OfflineError: Raised if the device is offline.
-        """
-        mower = self.get_mower(serial_number)
-        if mower["online"]:
-            self.mqtt.command(
-                serial_number if mower["protocol"] == 0 else mower["uuid"],
-                mower["mqtt_topics"]["command_in"],
-                Command.PAUSE,
-                mower["protocol"],
-            )
-        else:
-            raise OfflineError("The device is currently offline, no action was sent.")
-
-    def refresh(self, serial_number: str) -> None:
-        """Force a data refresh from API endpoint.
+        Args:
+            serial_number (str): Serial number of the device
 
         Raises:
             OfflineError: Raised if the device is offline.
@@ -817,7 +813,7 @@ def refresh(self, serial_number: str) -> None:
             self.mqtt.command(
                 serial_number if mower["protocol"] == 0 else mower["uuid"],
                 mower["mqtt_topics"]["command_in"],
-                Command.FORCE_REFRESH,
+                Command.PAUSE,
                 mower["protocol"],
             )
         else:
@@ -827,7 +823,8 @@ def raindelay(self, serial_number: str, rain_delay: str) -> None:
         """Set new rain delay.
 
         Args:
-            rain_delay (str | int): Rain delay in minutes.
+            serial_number (str): Serial number of the device
+            rain_delay (str): Rain delay in minutes.
 
         Raises:
             OfflineError: Raised if the device is offline.
@@ -848,7 +845,8 @@ def set_lock(self, serial_number: str, state: bool) -> None:
         """Set the device locked state.
 
         Args:
-            enabled (bool): True will lock the device, False will unlock the device.
+            serial_number (str): Serial number of the device
+            state (bool): True will lock the device, False will unlock the device.
 
         Raises:
             OfflineError: Raised if the device is offline.
@@ -868,7 +866,8 @@ def set_partymode(self, serial_number: str, state: bool) -> None:
         """Turn on or off the partymode.
 
         Args:
-            enable (bool): True is enabling partymode, False is disabling partymode.
+            serial_number (str): Serial number of the device
+            state (bool): True is enabling partymode, False is disabling partymode.
 
         Raises:
             NoPartymodeError: Raised if the device does not support partymode.
@@ -906,6 +905,7 @@ def setzone(self, serial_number: str, zone: str | int) -> None:
         """Set zone to be mowed when next mowing task is started.
 
         Args:
+            serial_number (str): Serial number of the device
             zone (str | int): Zone to mow, valid possibilities are a number from 1 to 4.
 
         Raises:
@@ -951,6 +951,9 @@ def setzone(self, serial_number: str, zone: str | int) -> None:
     def zonetraining(self, serial_number: str) -> None:
         """Start the zone training task.
 
+        Args:
+            serial_number (str): Serial number of the device
+
         Raises:
             OfflineError: Raised if the device is offline.
         """
@@ -969,6 +972,9 @@ def zonetraining(self, serial_number: str) -> None:
     def restart(self, serial_number: str):
         """Reboot the device baseboard.
 
+        Args:
+            serial_number (str): Serial number of the device
+
         Raises:
             OfflineError: Raised if the device is offline.
         """
@@ -988,6 +994,7 @@ def toggle_schedule(self, serial_number: str, enable: bool) -> None:
         """Turn on or off the schedule.
 
         Args:
+            serial_number (str): Serial number of the device
             enable (bool): True is enabling the schedule, Fasle is disabling the schedule.
 
         Raises:
@@ -1008,6 +1015,7 @@ def ots(self, serial_number: str, boundary: bool, runtime: str) -> None:
         """Start a One-Time-Schedule task
 
         Args:
+            serial_number (str): Serial number of the device
             boundary (bool): If True the device will start the task cutting the edge.
             runtime (str | int): Minutes to run the task before returning to dock.
 
@@ -1040,6 +1048,7 @@ def send(self, serial_number: str, data: str) -> None:
         """Send raw JSON data to the device.
 
         Args:
+            serial_number (str): Serial number of the device
             data (str): Data to be sent, formatted as a valid JSON object.
 
         Raises:

test.py

@@ -1,7 +1,7 @@
 """Basic test file."""
 
-import datetime
 from os import environ
+from pprint import pprint
 
 from pyworxcloud import WorxCloud
 
@@ -19,6 +19,8 @@
 
 # print(vars(cloud))
 
-cloud.update(cloud.devices["Robert"].serial_number)
+for _, device in cloud.devices.items():
+    cloud.update(device.serial_number)
+    pprint(vars(device))
 
 cloud.disconnect()

test_with.py

@@ -0,0 +1,13 @@
+from os import environ
+from pprint import pprint
+
+from pyworxcloud import WorxCloud
+
+EMAIL = environ["EMAIL"]
+PASS = environ["PASSWORD"]
+TYPE = environ["TYPE"]
+
+with WorxCloud(EMAIL, PASS, TYPE) as cloud:
+    for _, device in cloud.devices.items():
+        cloud.update(device.serial_number)
+        pprint(vars(device))