holado 0.13.22__py3-none-any.whl

holado_core/common/handlers/redo.py

@@ -0,0 +1,119 @@
+
+#################################################
+# HolAdo (Holistic Automation do)
+#
+# (C) Copyright 2021-2025 by Eric Klumpp
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy of self software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and self permission notice shall be included in all copies or substantial portions of the Software.
+
+# The Software is provided “as is”, without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the Software.
+#################################################
+
+import logging
+import abc
+from holado_core.common.handlers.abstracts.base_redo import BaseRedo
+
+logger = logging.getLogger(__name__)
+
+
+class Redo(BaseRedo):
+    """ Redo a process until timeout.
+    """
+    __metaclass__ = abc.ABCMeta
+
+    def __init__(self, name):
+        super().__init__(name)
+        self.__is_redo_while_null = False
+        self.__is_redo_while_not_null = False
+        self.__redo_while_values = []
+        self.__is_redo_until_none = False
+        self.__is_redo_until_not_none = False
+        self.__redo_until_values = []
+    
+    def _is_redo_needed(self, result):
+        if self.__is_redo_while_null and result is None:
+            return True
+        if self.__is_redo_until_none and result is None:
+            return False
+        
+        if self.__is_redo_while_not_null and result is not None:
+            return True
+        if self.__is_redo_until_not_none and result is not None:
+            return False
+        
+        if len(self.__redo_while_values) > 0 and result is not None:
+            for value in self.__redo_while_values:
+                if result == value:
+                    return True
+        
+        if len(self.__redo_until_values) > 0:
+            if result is None:
+                return True
+            else:
+                for value in self.__redo_until_values:
+                    if result == value:
+                        return False
+        
+        # If redo until something, then return True, else return False
+        return self.__is_redo_until_none or self.__is_redo_until_not_none or len(self.__redo_until_values) > 0
+    
+    def redo_while_none(self):
+        """
+        Redo while result is None
+        Note: can be combined with any other redo_XXX method
+        @return self
+        """
+        self.__is_redo_while_null = True
+        return self
+    
+    def redo_while_not_none(self):
+        """
+        Redo while result is not None
+        Note: can be combined with any other redo_XXX method
+        @return self
+        """
+        self.__is_redo_while_not_null = True
+        return self
+    
+    def redo_while(self, value):
+        """
+        Redo while result is equal to given value
+        Note: can be combined with any other redo_XXX method
+        @param value Value
+        @return self
+        """
+        self.__redo_while_values.append(value)
+        return self
+    
+    def redo_until_none(self):
+        """
+        Redo until result is None
+        Note: can be combined with any other redo_XXX method
+        @return self
+        """
+        self.__is_redo_until_none = True
+        return self
+    
+    def redo_until_not_none(self):
+        """
+        Redo until result is not None
+        Note: can be combined with any other redo_XXX method
+        @return self
+        """
+        self.__is_redo_until_not_none = True
+        return self
+    
+    def redo_until(self, value):
+        """
+        Redo until result is equal to given value
+        Note: can be combined with any other redo_XXX method
+        @param value Value
+        @return self
+        """
+        self.__redo_until_values.append(value)
+        return self
+        
+        
+        

holado_core/common/handlers/wait.py

@@ -0,0 +1,127 @@
+
+#################################################
+# HolAdo (Holistic Automation do)
+#
+# (C) Copyright 2021-2025 by Eric Klumpp
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy of self software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and self permission notice shall be included in all copies or substantial portions of the Software.
+
+# The Software is provided “as is”, without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the Software.
+#################################################
+
+import logging
+from holado_core.common.handlers.redo import Redo
+from holado.common.handlers.undefined import undefined_value
+from holado.holado_config import Config
+
+logger = logging.getLogger(__name__)
+
+
+class WaitOnEventResult(Redo):
+    def __init__(self, name, on_event_func):
+        super().__init__(name)
+        self.__on_event_func = on_event_func
+        self.__on_event_func_result = None
+        
+    def _process(self):
+        return self.__on_event_func_result
+    
+    def on_event(self, *args, **kwargs):
+        self.__on_event_func_result = self.__on_event_func(*args, **kwargs)
+
+
+class WaitIsTrueOnEvent(WaitOnEventResult):
+    def __init__(self, name, on_event_func):
+        super().__init__(name, on_event_func)
+        self.redo_until(True)
+
+
+class WaitFuncResult(Redo):
+    def __init__(self, name, func):
+        super().__init__(name)
+        self.__func = func
+        
+    def _process(self):
+        return self.__func()
+
+class WaitFuncResultVerifying(WaitFuncResult):
+    def __init__(self, name, result_func, result_verify_func):
+        super().__init__(name, result_func)
+        self.__result_verify_func = result_verify_func
+        
+    def _is_redo_needed(self, result):
+        return not self.__result_verify_func(result)
+
+
+class WaitChange(WaitFuncResult):
+    def __init__(self, name, func, *, do_process_in_thread=True, result_reference=undefined_value, timeout_seconds=None, polling_seconds=None):
+        super().__init__(name, func)
+        self.with_process_in_thread(do_process_in_thread)
+        self.__result_reference = result_reference
+        
+        # Compute default timeout and polling if needed
+        if timeout_seconds is None:
+            timeout_seconds = Config.timeout_seconds
+        if polling_seconds is None:
+            polling_seconds = timeout_seconds / 1000
+            if polling_seconds > 0.01:
+                polling_seconds = 0.01
+                
+        self.with_timeout(timeout_seconds)
+        self.polling_every(polling_seconds)
+        
+    def _is_redo_needed(self, result):
+        if self.__result_reference is undefined_value:
+            # Update reference with first run result
+            self.__result_reference = result
+            return True
+        else:
+            return result == self.__result_reference
+
+class WaitEndChange(WaitFuncResult):
+    def __init__(self, name, func, *, do_process_in_thread=True, result_reference=undefined_value, first_timeout_seconds=None, window_seconds=None, polling_seconds=None):
+        super().__init__(name, func)
+        self.with_process_in_thread(do_process_in_thread)
+        self.__result_reference = result_reference
+        
+        # Compute default timeouts and duration if needed
+        if window_seconds is None:
+            if first_timeout_seconds is not None and first_timeout_seconds > 0:
+                window_seconds = first_timeout_seconds / 10
+            else:
+                window_seconds = 1
+            if window_seconds < 0.01:
+                window_seconds = 0.01       # a window period below 10 ms is usually not efficient in testing context
+        if polling_seconds is None:
+            min_window = min(first_timeout_seconds, window_seconds) if first_timeout_seconds is not None else window_seconds
+            polling_seconds = min_window / 100       # 1% of error on window detection
+            if polling_seconds > 0.1:
+                polling_seconds = 0.1       # a polling period over 100 ms is usually not efficient in testing context
+            elif polling_seconds < 0.001:
+                polling_seconds = 0.001       # a polling period below 1 ms is usually not efficient in testing context
+        if first_timeout_seconds is None:
+            first_timeout_seconds = window_seconds
+        
+        # Start with a timeout equal to first_timeout_seconds
+        self.with_timeout(first_timeout_seconds)
+        
+        self.polling_every(polling_seconds)
+        self.__window_seconds = window_seconds
+    
+    def _execute_after_process(self, result):
+        if self.__result_reference is undefined_value:
+            # Update reference with first run result
+            self.__result_reference = result
+        elif result != self.__result_reference:
+            self.__result_reference = result
+            
+            # As a change is received, update timeout with window duration and do not raise on timeout anymore
+            self.update_timeout(self.__window_seconds)
+            self.without_raise_on_timeout()
+        
+    def _is_redo_needed(self, result):
+        return True
+
+

holado_core/common/inspectors/element_inspector.py

@@ -0,0 +1,57 @@
+#################################################
+# HolAdo (Holistic Automation do)
+#
+# (C) Copyright 2021-2025 by Eric Klumpp
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+#
+# The Software is provided “as is”, without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the Software.
+#################################################
+
+import logging
+from holado_core.common.inspectors.inspector import Inspector
+from holado_core.common.finders.tools.enums import FindType
+from holado_core.common.finders.then_finder import ThenFinder
+import abc
+from holado_core.common.inspectors.tools.inspect_context import InspectContext
+from holado_core.common.inspectors.tools.inspect_parameters import InspectParameters
+
+logger = logging.getLogger(__name__)
+
+
+
+class ElementInspector(Inspector):
+    """ Base class for inspector on elements.
+    """
+    __metaclass__ = abc.ABCMeta
+    
+    def __init__(self, module_name):
+        super().__init__(module_name)
+    
+    def get_finder_element_in(self, finder_container, finder_element, inspect_context:InspectContext=None, inspect_parameters:InspectParameters=None):
+        """
+        Find element with given finder, in given container
+        @param finder_container Finder for container
+        @param finder_element Finder for element to find
+        @param inspect_context Inspect context
+        @param inspect_parameters Inspect parameters
+        @return Finder
+        """
+        if finder_container is None or finder_element is None:
+            return self._build_result_finder(finder_element, inspect_context, inspect_parameters)
+
+        res = ThenFinder(f"{finder_element.element_description} in {finder_container.element_description}")
+
+        # Find container
+        res.set_next_finder(finder_container)
+
+        # Then find element in container
+        res.set_next_finder(FindType.In, True, finder_element)
+
+        return self._build_result_finder(res, inspect_context, inspect_parameters)
+    
+    
+    
+    

holado_core/common/inspectors/inspector.py

@@ -0,0 +1,221 @@
+#################################################
+# HolAdo (Holistic Automation do)
+#
+# (C) Copyright 2021-2025 by Eric Klumpp
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+#
+# The Software is provided “as is”, without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the Software.
+#################################################
+
+import logging
+from holado_core.common.exceptions.technical_exception import TechnicalException
+from holado_core.common.exceptions.functional_exception import FunctionalException
+from holado_core.common.finders.tools.find_builder import FindBuilder
+from holado_core.common.inspectors.tools.inspect_builder import InspectBuilder
+from holado_core.common.inspectors.tools.inspect_parameters import InspectParameters
+from holado_core.common.inspectors.tools.inspect_context import InspectContext
+import abc
+from holado_python.standard_library.typing import Typing
+
+logger = logging.getLogger(__name__)
+
+
+
+class Inspector(object):
+    """ Base class for inspector.
+    """
+    __metaclass__ = abc.ABCMeta
+    
+    def __init__(self, module_name):
+        # Modules management
+        self.__module_name = module_name
+        self.__inspector_by_module_name = {}
+    
+        # Builders to use
+        self.__inspect_builder = None
+        self.__find_builder = None
+    
+    
+    def initialize(self):
+        """
+        Initialize inspector
+        """
+        self.__inspect_builder = self.default_inspect_builder()
+        self.__find_builder = self.default_find_builder()
+    
+    @property
+    def find_builder(self):
+        """
+        @return Find builder defined for this inspector
+        """
+        return self.__find_builder
+    
+    @property
+    def inspect_builder(self):
+        """
+        @return Inspect builder defined for this inspector
+        """
+        return self.__inspect_builder
+    
+    @property
+    def module_name(self):
+        return self.__module_name
+    
+    @property
+    def default_inspect_builder(self):
+        """
+        @return New default inspect builder for this inspector
+        """
+        res = InspectBuilder()
+        res.initialize(self)
+        return res
+    
+    @property
+    def default_find_builder(self):
+        """
+        @return New default find builder for this inspector
+        """
+        return FindBuilder()
+    
+    def _get_inspector_for_module(self, name):
+        """
+        @param name Module name
+        @return Module inspector
+        """
+        if name not in self.__inspector_by_module_name:
+            self.__inspector_by_module_name[name] = self._initialize_module(name)
+        return self.__inspector_by_module_name[name]
+    
+    def _initialize_module(self, name):
+        """
+        Initialize a new instance of given module name
+        @param name Module name
+        @return New module instance
+        """
+        raise TechnicalException(f"Unmanaged module '{name}'")
+    
+    def _get_finder_from_modules(self, method_name, method_args=None, method_kwargs=None, inspect_context:InspectContext=None, inspect_parameters:InspectParameters=None):
+        method_args = [] if method_args is None else method_args
+        method_kwargs = {} if method_kwargs is None else method_kwargs
+        inspect_context = self.inspect_builder.context() if inspect_context is None else inspect_context
+        inspect_parameters = self.inspect_builder.parameters() if inspect_parameters is None else inspect_parameters
+        
+        finders = []
+        for module_name in self.inspect_builder.module_names:
+            module = self._get_inspector_for_module(module_name)
+            if hasattr(module, method_name):
+                method = getattr(module, method_name)
+                module_parameters = self.inspect_builder.get_parameters_for_module(module_name, inspect_parameters)
+                try:
+                    finder = method(*method_args, **method_kwargs, inspect_context=inspect_context, inspect_parameters=module_parameters)
+                except FunctionalException as e:
+                    raise TechnicalException("Unexpected exception") from e
+                
+                if finder is not None:
+                    self._add_finder_to_list(finders, finder, inspect_context, inspect_parameters)
+        
+        return self._build_result_finder_from_list(finders=finders, inspect_context=inspect_context, inspect_parameters=inspect_parameters)
+    
+    def _remove_none_from_list(self, list_):
+        if list_ is None:
+            return
+        
+        i = 0
+        while i < len(list_):
+            if list_[i] is None:
+                del list_[i]
+            else:
+                i += 1
+    
+    def _build_result_finder(self, finder, inspect_context:InspectContext=None, inspect_parameters:InspectParameters=None):
+        """
+        Build result finder, considering given inspect parameters.
+        @param finder Finder to return
+        @param inspect_context Inspect context
+        @param inspect_parameters Inspect parameters
+        @return Result finder
+        """
+        if finder is None:
+            if inspect_parameters.raise_no_such_finder:
+                raise TechnicalException(f"No such finder")
+            else:
+                return None
+        
+        if inspect_context.finder_type is not None and inspect_context.finder_type not in inspect_parameters.finder_types:
+            return None
+        
+        finder.inspector = self
+        if self.__module_name is not None:
+            finder.info.module_name = self.__module_name
+        if inspect_context.finder_type is not None:
+            finder.info.finder_type = inspect_context.finder_type
+        
+        return finder
+    
+    
+    def _build_result_finder_from_list(self, finders, inspect_context:InspectContext=None, inspect_parameters:InspectParameters=None, element_description=None):
+        """
+        Build result finder with description copied from first finder in list
+        @param finders Finders list
+        @param inspect_context Inspect context
+        @param inspect_parameters Inspect parameters
+        @param element_description Element description
+        @return Result finder
+        """
+        if element_description is None and finders is not None and len(finders) > 0:
+            element_description = finders[0].element_description
+        
+        self._remove_none_from_list(finders)
+    
+        if finders is None or len(finders) == 0:
+            if inspect_parameters.raise_no_such_finder:
+                raise TechnicalException(f"No such finder")
+            else:
+                return None
+        elif finders.size() == 1:
+            return self._build_result_finder(finders[0], inspect_context, inspect_parameters)
+        else:
+            res = inspect_parameters.result_finder_type(element_description)
+            for finder in finders:
+                if hasattr(res, "set_next_finder"):
+                    res.set_next_finder(finder)
+                elif hasattr(res, "add_finder"):
+                    res.add_finder(finder)
+                else:
+                    raise TechnicalException(f"Unmanaged result finder type '{Typing.get_object_class_fullname(res)}'")
+            return self._build_result_finder(res, inspect_context, inspect_parameters)
+        
+    def _merge_result_finders(self, result_finders, inspect_context:InspectContext=None, inspect_parameters:InspectParameters=None):
+        """
+        Merge result finders to first result finder
+        @param result_finders Finders list
+        @param inspect_context Inspect context
+        @param inspect_parameters Inspect parameters
+        @return Result finder
+        """
+        self._remove_none_from_list(result_finders)
+        
+        if result_finders is None or len(result_finders) == 0:
+            if inspect_parameters.raise_no_such_finder:
+                raise TechnicalException(f"No such finder")
+            else:
+                return None
+        else:
+            res = result_finders[0]
+            for result_finder in result_finders[1:]:
+                if hasattr(res, "set_next_finder"):
+                    res.set_next_finder(result_finder)
+                elif hasattr(res, "add_finder"):
+                    res.add_finder(result_finder)
+                else:
+                    raise TechnicalException(f"Unmanaged result finder type '{Typing.get_object_class_fullname(res)}'")
+            return res
+    
+    def _add_finder_to_list(self, finders, finder, inspect_context:InspectContext=None, inspect_parameters:InspectParameters=None):
+        if finder is not None:
+            finders.add(self._build_result_finder(finder, inspect_context, inspect_parameters))
+    
+