diff --git a/pymammotion/utility/constant/device_constant.py b/pymammotion/utility/constant/device_constant.py index cb30d0b..c3d9706 100644 --- a/pymammotion/utility/constant/device_constant.py +++ b/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", diff --git a/pymammotion/utility/datatype_converter.py b/pymammotion/utility/datatype_converter.py index a9aabfc..69426c5 100644 --- a/pymammotion/utility/datatype_converter.py +++ b/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) diff --git a/pymammotion/utility/device_type.py b/pymammotion/utility/device_type.py index 0079e14..17978c7 100644 --- a/pymammotion/utility/device_type.py +++ b/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,6 +163,15 @@ 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() @@ -107,6 +179,20 @@ def is_yuka(device_name): @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"] diff --git a/pymammotion/utility/periodic.py b/pymammotion/utility/periodic.py index 70cbfdb..969fbd1 100644 --- a/pymammotion/utility/periodic.py +++ b/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) diff --git a/pymammotion/utility/rocker_util.py b/pymammotion/utility/rocker_util.py index b485e30..9e94cfc 100644 --- a/pymammotion/utility/rocker_util.py +++ b/pymammotion/utility/rocker_util.py @@ -16,13 +16,36 @@ def __init__(self): @classmethod def getInstance(cls): - """Generated source for method getInstance""" + """Return the instance of RockerControlUtil if it exists, otherwise create + a new instance. + + This method checks if an instance of RockerControlUtil exists. If not, + it creates a new instance and returns it. + + Args: + cls (class): The class for which the instance is being retrieved. + + Returns: + RockerControlUtil: An instance of RockerControlUtil. + """ if cls.instance_ == None: cls.instance_ = RockerControlUtil() return cls.instance_ def transfrom(self, f, f2): - """Generated source for method transfrom""" + """Perform a transformation based on the input angles and distance. + + This method calculates the transformation based on the input angle 'f' + and distance 'f2'. It determines the appropriate radians based on the + angle and performs the transformation. + + Args: + f (float): The angle in degrees for transformation. + f2 (float): The distance for transformation. + + Returns: + list: A list containing the transformed coordinates. + """ radians = 0.0 self.list_.clear() i = self.thresholdValue_2 @@ -55,7 +78,23 @@ def transfrom(self, f, f2): return copy.copy(self.list_) def transfrom2(self, f, f2): - """Generated source for method transfrom2""" + """Calculate the transformation of input angles to radians and perform + trigonometric calculations. + + This method takes two input parameters, an angle 'f' and a value 'f2', + and calculates the corresponding radians based on the angle. It then + performs trigonometric calculations using the radians and 'f2' value to + generate a list of transformed values. + + Args: + self: The instance of the class. + f (float): The input angle in degrees. + f2 (float): The input value for trigonometric calculations. + + Returns: + list: A list containing the transformed values based on trigonometric + calculations. + """ radians = 0.0 self.list_.clear() i = self.thresholdValue_2 @@ -97,7 +136,23 @@ def transfrom2(self, f, f2): return copy.copy(self.list_) def transfrom3(self, f, f2): - """Generated source for method transfrom3""" + """Calculate the transformation of input angles to radians and perform + trigonometric calculations. + + This method calculates the transformation of input angles to radians + based on certain threshold values. It then performs trigonometric + calculations using sine and cosine functions to determine the output + values. + + Args: + self: The object instance. + f (float): The input angle in degrees. + f2 (float): The input value for trigonometric calculations. + + Returns: + list: A list containing the calculated values based on trigonometric + functions. + """ radians = 0.0 self.list_.clear() i = self.thresholdValue_2