Generated Documentation (#49)

Co-authored-by: penify-dev[bot] <146478655+penify-dev[bot]@users.noreply.github.com>

pymammotion/utility/constant/device_constant.py

@@ -210,6 +210,19 @@ class WorkMode:
 
 
 def device_mode(value):
+    """Return the mode corresponding to the given value.
+
+    This function takes a value and returns the corresponding mode from a
+    predefined dictionary.
+
+    Args:
+        value (int): The value for which mode needs to be determined.
+
+    Returns:
+        str: The mode corresponding to the input value. Returns "Invalid mode" if no
+            mode is found.
+    """
+
     modes = {
         0: "MODE_NOT_ACTIVE",
         1: "MODE_ONLINE",

pymammotion/utility/datatype_converter.py

@@ -6,6 +6,18 @@ class DatatypeConverter:
 
     @staticmethod
     def init_encode_map():
+        """Initialize the encode map for DatatypeConverter if it is not already
+        initialized.
+
+        This function initializes the encode map for DatatypeConverter by
+        creating a list of 64 elements and populating it with characters for
+        encoding. If the encode map is already initialized, it returns the
+        existing encode map.
+
+        Returns:
+            list: The encode map for DatatypeConverter.
+        """
+
         if DatatypeConverter.encode_map is None:
             cArr = [0] * 64
             for i in range(26):
@@ -33,6 +45,20 @@ def encode(i):
 
     @staticmethod
     def _printBase64Binary(bArr, i=0, i2=None):
+        """Print the Base64 binary representation of a byte array.
+
+        This function takes a byte array and optional start and end indices to
+        print the Base64 binary representation.
+
+        Args:
+            bArr (list): A list of bytes to be converted to Base64 binary.
+            i (int): The starting index of the byte array (default is 0).
+            i2 (int): The ending index of the byte array (default is the length of bArr).
+
+        Returns:
+            str: The Base64 binary representation of the input byte array.
+        """
+
         if i2 is None:
             i2 = len(bArr)
         cArr = [""] * (((i2 + 2) // 3) * 4)
@@ -41,6 +67,26 @@ def _printBase64Binary(bArr, i=0, i2=None):
 
     @staticmethod
     def _printBase64Binary_core(bArr, i, i2, cArr, i3):
+        """Encode binary data into Base64 format.
+
+        This function encodes binary data into Base64 format following the
+        Base64 encoding algorithm.
+
+        Args:
+            bArr (list): List of binary data to be encoded.
+            i (int): Starting index of the binary data to be encoded.
+            i2 (int): Length of binary data to be encoded.
+            cArr (list): List to store the encoded Base64 characters.
+            i3 (int): Starting index in the cArr to store the encoded characters.
+
+        Returns:
+            int: The index in cArr where encoding ends.
+
+        Note:
+            This function assumes that DatatypeConverter has a method 'encode' and
+            'init_encode_map' for encoding.
+        """
+
         DatatypeConverter.init_encode_map()  # Ensure encode_map is initialized
         while i2 >= 3:
             cArr[i3] = DatatypeConverter.encode(bArr[i] >> 2)

pymammotion/utility/device_type.py

@@ -30,6 +30,18 @@ def set_value(self, value):
 
     @staticmethod
     def valueof(value):
+        """Return the corresponding DeviceType based on the input value.
+
+        This function takes an integer value as input and returns the
+        corresponding DeviceType enum value.
+
+        Args:
+            value (int): An integer representing the device type.
+
+        Returns:
+            DeviceType: The corresponding DeviceType enum value based on the input value.
+        """
+
         if value == 0:
             return DeviceType.RTK
         elif value == 1:
@@ -43,6 +55,17 @@ def valueof(value):
 
     @staticmethod
     def value_of_str(device_name, product_key=""):
+        """Determine the type of device based on the provided device name and
+        product key.
+
+        Args:
+            device_name (str): The name of the device.
+            product_key (str?): The product key associated with the device. Defaults to "".
+
+        Returns:
+            DeviceType: The type of device based on the provided information.
+        """
+
         if not device_name and not product_key:
             return DeviceType.UNKNOWN
 
@@ -73,6 +96,21 @@ def value_of_str(device_name, product_key=""):
 
     @staticmethod
     def has_4g(device_name, product_key=""):
+        """Check if the device has 4G capability based on the device name and
+        optional product key.
+
+        This function determines the device type based on the device name and
+        product key (if provided). It then checks if the device type has a value
+        greater than or equal to the 4G threshold.
+
+        Args:
+            device_name (str): The name of the device.
+            product_key (str?): The product key associated with the device. Defaults to "".
+
+        Returns:
+            bool: True if the device has 4G capability, False otherwise.
+        """
+
         if not product_key:
             device_type = DeviceType.value_of_str(device_name)
         else:
@@ -82,6 +120,20 @@ def has_4g(device_name, product_key=""):
 
     @staticmethod
     def is_luba1(device_name, product_key=""):
+        """Check if the given device is of type LUBA.
+
+        This function determines if the device specified by 'device_name' is of
+        type LUBA. If 'product_key' is provided, it is used to further identify
+        the device type.
+
+        Args:
+            device_name (str): The name of the device.
+            product_key (str?): The product key associated with the device. Defaults to "".
+
+        Returns:
+            bool: True if the device is of type LUBA, False otherwise.
+        """
+
         if not product_key:
             device_type = DeviceType.value_of_str(device_name)
         else:
@@ -91,6 +143,17 @@ def is_luba1(device_name, product_key=""):
 
     @staticmethod
     def is_luba_2(device_name, product_key=""):
+        """Check if the device type is LUBA 2 or higher based on the device name
+        and optional product key.
+
+        Args:
+            device_name (str): The name of the device.
+            product_key (str?): The product key associated with the device. Defaults to "".
+
+        Returns:
+            bool: True if the device type is LUBA 2 or higher, False otherwise.
+        """
+
         if not product_key:
             device_type = DeviceType.value_of_str(device_name)
         else:
@@ -100,13 +163,36 @@ def is_luba_2(device_name, product_key=""):
 
     @staticmethod
     def is_yuka(device_name):
+        """Check if the given device name corresponds to a LUBA_YUKA device type.
+
+        Args:
+            device_name (str): The name of the device to be checked.
+
+        Returns:
+            bool: True if the device type is LUBA_YUKA, False otherwise.
+        """
+
         return (
             DeviceType.value_of_str(device_name).get_value()
             == DeviceType.LUBA_YUKA.get_value()
         )
 
     @staticmethod
     def is_rtk(device_name, product_key=""):
+        """Check if the device type is within the range of RTK devices.
+
+        This function determines if the device type corresponding to the given
+        device name and optional product key falls within the range of RTK
+        (Real-Time Kinematic) devices.
+
+        Args:
+            device_name (str): The name of the device.
+            product_key (str?): The product key associated with the device. Defaults to "".
+
+        Returns:
+            bool: True if the device type is within the RTK range, False otherwise.
+        """
+
         if not product_key:
             device_type = DeviceType.value_of_str(device_name)
         else:
@@ -120,12 +206,31 @@ def is_rtk(device_name, product_key=""):
 
     @staticmethod
     def contain_rtk_product_key(product_key):
+        """Check if the given product key is in a predefined list of RTK product
+        keys.
+
+        Args:
+            product_key (str): The product key to be checked.
+
+        Returns:
+            bool: True if the product key is in the predefined list, False otherwise.
+        """
+
         if not product_key:
             return False
         return product_key in ["a1qXkZ5P39W", "a1Nc68bGZzX"]
 
     @staticmethod
     def contain_luba_product_key(product_key):
+        """Check if the given product key is in the list of valid product keys.
+
+        Args:
+            product_key (str): The product key to be checked.
+
+        Returns:
+            bool: True if the product key is in the list of valid keys, False otherwise.
+        """
+
         if not product_key:
             return False
         return product_key in [
@@ -144,6 +249,15 @@ def contain_luba_product_key(product_key):
 
     @staticmethod
     def contain_luba_2_product_key(product_key):
+        """Check if the given product key is present in a predefined list.
+
+        Args:
+            product_key (str): The product key to be checked.
+
+        Returns:
+            bool: True if the product key is in the predefined list, False otherwise.
+        """
+
         if not product_key:
             return False
         return product_key in ["a1iMygIwxFC", "a1LLmy1zc0j", "a1LLmy1zc0j"]

pymammotion/utility/periodic.py

@@ -10,12 +10,24 @@ def __init__(self, func, time):
         self._task = None
 
     def start(self):
+        """Start the task if it is not already started.
+
+        If the task is not already started, it sets the 'is_started' flag to
+        True and initiates a task to call a function periodically using asyncio.
+        """
+
         if not self.is_started:
             self.is_started = True
             # Start task to call func periodically:
             self._task = asyncio.ensure_future(self._run())
 
     async def stop(self):
+        """Stop the task if it is currently running.
+
+        If the task is currently running, it will be cancelled and awaited until
+        it stops.
+        """
+
         if self.is_started:
             self.is_started = False
             # Stop task and await it stopped:
@@ -24,14 +36,63 @@ async def stop(self):
                 await self._task
 
     async def _run(self):
+        """Run the specified function at regular intervals using asyncio.
+
+        This method runs the specified function at regular intervals based on
+        the time provided.
+
+        Args:
+            self: The instance of the class.
+        """
+
         while True:
             await asyncio.sleep(self.time)
             await self.func()
 
 
 def periodic(period):
+    """Schedule a function to run periodically at a specified time interval.
+
+    This decorator function takes a period (in seconds) as input and returns
+    a scheduler function. The scheduler function, when applied as a
+    decorator to another function, will run the decorated function
+    periodically at the specified time interval.
+
+    Args:
+        period (int): Time interval in seconds at which the decorated function should run
+            periodically.
+
+    Returns:
+        function: A scheduler function that can be used as a decorator to run a function
+            periodically.
+    """
+
     def scheduler(fcn):
+        """Schedule the execution of a given async function periodically.
+
+        This function takes an async function as input and returns a new async
+        function that will execute the input function periodically at a
+        specified interval.
+
+        Args:
+            fcn (function): The async function to be scheduled.
+
+        Returns:
+            function: An async function that will execute the input function periodically.
+        """
+
         async def wrapper(*args, **kwargs):
+            """Execute the given function periodically using asyncio tasks.
+
+            This function continuously creates an asyncio task to execute the
+            provided function with the given arguments and keyword arguments. It
+            then waits for a specified period of time before creating the next task.
+
+            Args:
+                *args: Variable length argument list to be passed to the function.
+                **kwargs: Arbitrary keyword arguments to be passed to the function.
+            """
+
             while True:
                 asyncio.create_task(fcn(*args, **kwargs))
                 await asyncio.sleep(period)