Add Python utils with Timer and WaitHandler classes (#63)

* Add Python utils with Timer and WaitHandler classes

Signed-off-by: jparisu <javierparis@eprosima.com>

* Add BooleanWaitHandler

Signed-off-by: jparisu <javierparis@eprosima.com>

* Add features to py utils

Signed-off-by: jparisu <javierparis@eprosima.com>

* apply suggestions

Signed-off-by: jparisu <javierparis@eprosima.com>

* Add IntWaitHandler tests

Signed-off-by: jparisu <javierparis@eprosima.com>

* Document code

Signed-off-by: jparisu <javierparis@eprosima.com>

* document new feature

Signed-off-by: jparisu <javierparis@eprosima.com>

* fix py linter

Signed-off-by: jparisu <javierparis@eprosima.com>

---------

Signed-off-by: jparisu <javierparis@eprosima.com>

Author: jparisu

py_utils/package.xml

@@ -0,0 +1,23 @@
+<?xml version="1.0"?>
+<?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
+<package format="3">
+  <name>py_utils</name>
+  <version>0.3.0</version>
+  <description>
+     *eprosima* Dev Utils Module is a Python implementation for some generic utils methods and classes.
+  </description>
+  <maintainer email="RaulSanchezMateos@eprosima.com">Raul Sánchez-Mateos</maintainer>
+  <maintainer email="javierparis@eprosima.com">Javier París</maintainer>
+  <maintainer email="juanlopez@eprosima.com">Juan López</maintainer>
+  <license file="LICENSE">Apache 2.0</license>
+
+  <url type="website">https://www.eprosima.com/</url>
+  <url type="bugtracker">https://github.com/eProsima/dev-utils/issues</url>
+  <url type="repository">https://github.com/eProsima/dev-utils</url>
+
+  <test_depend>python3-pytest</test_depend>
+
+  <export>
+    <build_type>ament_python</build_type>
+  </export>
+</package>

py_utils/py_utils/__init__.py

@@ -0,0 +1,38 @@
+# Copyright 2023 Proyectos y Sistemas de Mantenimiento SL (eProsima).
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+This file contains utils to debug python code.
+"""
+
+from py_utils.logging.log_utils import logger
+
+
+def debug_object_introspection(obj):
+    """Log in debug introspection information regarding an object."""
+    class_name = type(obj).__name__
+    methods = [method_name for method_name in dir(obj) if callable(getattr(obj, method_name))]
+    logger.debug(f'{{Class: <{class_name}; Methods: {methods}}}')
+
+
+def debug_function_decorator(
+        func):
+    """Decorator to debug information regarding start, arguments and finish of a function."""
+    def wrapper(*args, **kwargs):
+        logger.debug(f'Function <{func.__name__}> called with arguments: <{args}>, <{kwargs}>')
+        result = func(*args, **kwargs)
+        logger.debug(f'Function <{func.__name__}> finished')
+        return result
+
+    return wrapper

py_utils/py_utils/debugging/__init__.py

@@ -0,0 +1,67 @@
+# Copyright 2023 Proyectos y Sistemas de Mantenimiento SL (eProsima).
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+This file contains utils to use native python Log.
+
+Implement a Custom Logger class and creates a global object of such class.
+In order to use this log handler, import logger object from this module and use it
+as any other Logger:
+- logger.info(...)
+- logger.debug(...)
+- logger.log(logging.DEBUG, ...)
+
+In order to set a different log level, use set_log_level or activate_debug logger methods.
+"""
+
+import logging
+
+
+class CustomLogger(logging.Logger):
+    """
+    Class to create a global Logger shared by the whole process.
+    It inherits from native logging.Logger and implement auxiliary methods.
+    """
+
+    def __init__(
+            self,
+            log_level=logging.INFO,
+            logger_name: str = 'GLOBAL_LOG'):
+        """Creates an object of Logger class and set log level and default format."""
+        super().__init__(logger_name)
+        self.set_format()
+        self.set_log_level(log_level)
+
+    def set_format(
+            self,
+            format: str = '[%(asctime)s][%(name)s][%(levelname)s] %(message)s'):
+        """Modifies format for logger."""
+        l_format = logging.Formatter(format)
+        l_handler = logging.StreamHandler()
+        l_handler.setFormatter(l_format)
+        self.addHandler(l_handler)
+
+    def set_log_level(
+            self,
+            log_level):
+        """Modifies logger level."""
+        self.setLevel(log_level)
+
+    def activate_debug(self):
+        """Modifies logger level so it accepts everything equalt or greater than DEBUG."""
+        self.set_log_level(logging.DEBUG)
+
+
+"""Global instance of logger using CustomLogger class."""
+logger = CustomLogger()

py_utils/py_utils/debugging/debug_utils.py

@@ -0,0 +1,51 @@
+# Copyright 2023 Proyectos y Sistemas de Mantenimiento SL (eProsima).
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Timer class implementation.
+"""
+
+import time
+
+
+class Timer:
+    """
+    A simple timer class for measuring elapsed time.
+
+    Attributes:
+        _start_time (float): The start time of the timer in seconds since the epoch.
+
+    NOTE: Chat GPT has written all this (including tests (⊙_⊙) )
+    """
+
+    def __init__(self):
+        """
+        Initializes a new Timer instance and sets the start time to the current time.
+        """
+        self._start_time = time.time()
+
+    def reset(self):
+        """
+        Resets the timer by setting the start time to the current time.
+        """
+        self._start_time = time.time()
+
+    def elapsed(self):
+        """
+        Calculates the elapsed time since the start time.
+
+        Returns:
+            float: The elapsed time in seconds.
+        """
+        return time.time() - self._start_time

py_utils/py_utils/logging/__init__.py

@@ -0,0 +1,61 @@
+# Copyright 2023 Proyectos y Sistemas de Mantenimiento SL (eProsima).
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+BooleanWaitHandler class implementation.
+"""
+
+from py_utils.wait.WaitHandler import WaitHandler
+
+
+class BooleanWaitHandler(WaitHandler):
+    """
+    BooleanWaitHandler is a WaitHandler that waits on a boolean value.
+    Whenever this value is True, threads awake. This is also called open.
+    Whenever it is False, threads wait. This is also called close.
+    """
+
+    def __init__(
+            self,
+            enabled: bool,
+            init_value: bool):
+        """
+        BooleanWaitHandler ctor.
+
+        Arguments:
+            enabled (bool): whether the handler must start enabled or disabled.
+            init_value (bool): whether the handler starts opened or closed.
+        """
+        super().__init__(enabled, init_value)
+
+    def open(self):
+        """Set internal value to True: awake all waiting threads."""
+        self.set_value(True)
+
+    def close(self):
+        """Set internal value to False: new threads will wait."""
+        self.set_value(False)
+
+    def wait(
+            self,
+            timeout: float = None):
+        """
+        Wait till any thread open this object.
+
+        Specialization of parent method with a specific predicate.
+
+        Arguments:
+            timeout: if thread awaken because timeout reached.
+        """
+        return super().wait(predicate=(lambda v: v), timeout=timeout)

py_utils/py_utils/logging/log_utils.py

@@ -0,0 +1,77 @@
+# Copyright 2023 Proyectos y Sistemas de Mantenimiento SL (eProsima).
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+IntWaitHandler class implementation.
+"""
+
+from py_utils.wait.WaitHandler import WaitHandler
+
+
+class IntWaitHandler(WaitHandler):
+    """
+    IntWaitHandler is a WaitHandler that waits on a int value.
+    It implements functions to wait for a specific value, or wait for the value to
+    be greater or greater equal.
+    It also implements functions to increase or decrease the internal value.
+
+    This is useful, for instance, to wait for an event to happen N or more times.
+
+    For more specific set or wait methods, implement a child class.
+    """
+
+    def __init__(
+            self,
+            enabled: bool,
+            init_value: int = 0):
+        """
+        IntWaitHandler ctor.
+
+        Arguments:
+            enabled (bool): whether the handler must start enabled or disabled.
+            init_value (int): initial value of the internal integer.
+        """
+        super().__init__(enabled, init_value)
+
+    def increase(self, value: int = 1):
+        """Increment the internal integer in value."""
+        with self._lock:
+            self._value += value
+            self._condition.notify_all()
+
+    def decrease(self, value: int = 1):
+        """Decrease the internal integer in value."""
+        with self._lock:
+            self._value -= value
+            self._condition.notify_all()
+
+    def wait_equal(self, value, timeout=None):
+        """
+        Wait till internal object is equal the given value.
+
+        Specialization of parent method with a specific predicate.
+
+        Arguments:
+            value: value to wait to be equal the internal integer.
+            timeout: if thread awaken because timeout reached.
+        """
+        return super().wait(predicate=(lambda v: value == v), timeout=timeout)
+
+    def wait_greater_equal(self, value, timeout=None):
+        """Wait for the internal integer to be greater or equal the value given."""
+        return super().wait(predicate=(lambda v: v >= value), timeout=timeout)
+
+    def wait_greater(self, value, timeout=None):
+        """Wait for the internal integer to be greater than value given."""
+        return super().wait(predicate=(lambda v: v > value), timeout=timeout)