holado 0.13.22__py3-none-any.whl

holado_core/common/drivers/driver.py

@@ -0,0 +1,153 @@
+#################################################
+# 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.exceptions.technical_exception import TechnicalException
+from holado.common.handlers.object import DeleteableObject
+from holado_core.common.exceptions.functional_exception import FunctionalException
+from holado_core.common.finders.tools.find_builder import FindBuilder
+from holado.common.handlers.enums import ObjectStates
+
+logger = logging.getLogger(__name__)
+
+
+
+class Driver(DeleteableObject):
+    """ Base class for drivers.
+    """
+    __metaclass__ = abc.ABCMeta
+    
+    def __init__(self, name=None):
+        super().__init__(name or "Driver")
+        
+        self.__internal_driver = None
+        self.__internal_api = None
+        
+        # Tools
+        self.__text_verifier = None
+        self.__find_builder = None      # Builder used to create default find context and parameters
+    
+    @property
+    def _has_internal_driver(self):
+        """
+        @return If internal driver is defined
+        """
+        return self.__internal_driver is not None
+    
+    @property
+    def internal_driver(self):
+        """
+        @return Internal driver
+        """
+        if not self._has_internal_driver():
+            raise TechnicalException("Internal driver is not defined.")
+        return self.__internal_driver
+    
+    @internal_driver.setter
+    def internal_driver(self, internal_driver):
+        self.__internal_driver = internal_driver
+    
+    @property
+    def internal_api(self):
+        """
+        @return Internal API
+        """
+        if self.__internal_api is None:
+            raise TechnicalException("Internal API is not defined.")
+        return self.__internal_api
+    
+    @property
+    def text_verifier(self):
+        """
+        @return Text verifier to use
+        """
+        if self.__text_verifier is None:
+            raise TechnicalException("Text verifier is not defined")
+        return self.__text_verifier
+    
+    @text_verifier.setter
+    def text_verifier(self, text_verifier):
+        """
+        @param text_verifier Text verifier to use
+        """
+        self.__text_verifier = text_verifier
+    
+    @property
+    def find_builder(self):
+        """
+        @return Find builder (if not set a default one is instantiated)
+        """
+        if self.__find_builder is None:
+            self.__find_builder = FindBuilder()
+        return self.__find_builder
+    
+    @find_builder.setter
+    def find_builder(self, find_builder):
+        """
+        @param find_builder Find builder to use rather than default
+        """
+        self.__find_builder = find_builder
+    
+    def initialize(self):
+        """
+        Initialize driver
+        """
+        self.__internal_api = self._initialize_internal_api()
+    
+    def _initialize_internal_api(self):
+        """
+        Method used internally at driver initialization, in order to instantiate the appropriate internal API type.
+        @return a new internal API instance
+        """
+        raise NotImplementedError
+
+    def is_open(self):
+        """
+        @return True if driver is open
+        """
+        return self._has_internal_driver()
+    
+    def _verify_is_open(self):
+        if not self.is_open():
+            raise FunctionalException("Driver is not opened")
+    
+    def open(self):
+        """
+        Open driver
+        """
+        self.object_state = ObjectStates.Opening
+        self._close_driver()
+        self.object_state = ObjectStates.Open
+
+    def _open_driver(self):
+        """
+        Implement open process
+        """
+        raise NotImplementedError
+    
+    def close(self):
+        """
+        Close driver
+        """
+        self.object_state = ObjectStates.Closing
+        self._close_driver()
+        self.object_state = ObjectStates.Closed
+    
+    def _close_driver(self):
+        """
+        Implement close process
+        """
+        raise NotImplementedError
+    
+    
+    

holado_core/common/drivers/element_driver.py

@@ -0,0 +1,30 @@
+#################################################
+# 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.drivers.driver import Driver
+
+logger = logging.getLogger(__name__)
+
+
+
+class ElementDriver(Driver):
+    """ Base class for element drivers.
+    """
+    __metaclass__ = abc.ABCMeta
+    
+    def __init__(self, name=None):
+        super().__init__(name or "ElementDriver")
+    
+    
+    

holado_core/common/drivers/element_internal_api.py

@@ -0,0 +1,239 @@
+#################################################
+# 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.drivers.internal_api import InternalAPI
+from holado_core.common.finders.tools.find_context import ContainerFindContext,\
+    ListContainersFindContext
+from holado_core.common.exceptions.element_exception import TooManyElementsException,\
+    NoSuchElementException
+from holado_core.common.exceptions.technical_exception import TechnicalException
+from holado_core.common.tools.tools import Tools
+
+logger = logging.getLogger(__name__)
+
+
+
+class ElementInternalAPI(InternalAPI):
+    """ Base class for element internal API.
+    """
+    __metaclass__ = abc.ABCMeta
+    
+    def __init__(self, driver):
+        super().__init__(driver)
+    
+    def find_element(self, criteria, find_context, find_parameters):
+        """
+        Find element with given criteria
+        @param criteria Criteria
+        @param find_context Find context
+        @param find_parameters Find parameters
+        @return Found element
+        """
+        if isinstance(find_context, ContainerFindContext) and find_context.container is not None:
+            return self.find_element_by_container(criteria, find_context.container, find_context, find_parameters)
+        elif isinstance(find_context, ListContainersFindContext) and find_context.nb_containers > 0:
+            return self.find_element_by_candidates(criteria, find_context.containers, find_context, find_parameters)
+        else:
+            raise TechnicalException("Find context has no container")
+    
+    
+    def find_element_by_container(self, criteria, container, find_context, find_parameters):
+        """
+        Find element with given criteria and container
+        
+        A default implementation use find_elements_by_container.
+        It is usually recommended to override it with a dedicated implementation.
+        @param criteria Criteria
+        @param container Container
+        @param find_context Find context
+        @param find_parameters Find parameters
+        @return Found element
+        """
+        # Manage no candidates
+        if container is None:
+            if find_parameters.raise_no_such_element:
+                raise NoSuchElementException("No container")
+            else:
+                return None
+        
+        found_elements = self.find_elements_by_container(criteria, container, find_context, find_parameters)
+        return self._get_element_from_list(found_elements, 1, criteria, find_context, find_parameters)
+    
+    def find_element_by_candidates(self, criteria, candidates, find_context, find_parameters):
+        """
+        Find element in given candidates with given criteria
+        
+        This default implementation use find_elements_by_candidates.
+        It is usually recommended to override it with a dedicated implementation.
+        @param candidates List of candidates
+        @param criteria Criteria
+        @param find_context Find context
+        @param find_parameters Find parameters
+        @return Found element
+        """
+        # Manage no candidates
+        if len(candidates) == 0:
+            if find_parameters.raise_no_such_element:
+                raise NoSuchElementException("No candidates")
+            else:
+                return None
+        
+        found_elements = self.find_elements_by_candidates(criteria, candidates, find_context, find_parameters)
+        return self._get_element_from_list(found_elements, len(candidates), criteria, find_context, find_parameters)
+    
+    def find_elements(self, criteria, find_context, find_parameters):
+        """
+        Find elements in context container with given criteria
+        @param criteria Criteria
+        @param find_context Find context
+        @param find_parameters Find parameters
+        @return Found elements
+        """
+        if isinstance(find_context, ContainerFindContext) and find_context.container is not None:
+            return self.find_elements_by_container(criteria, find_context.container, find_context, find_parameters)
+        elif isinstance(find_context, ListContainersFindContext) and find_context.nb_containers > 0:
+            return self.find_elements_by_candidates(criteria, find_context.containers, find_context, find_parameters)
+        else:
+            raise TechnicalException("Find context has no container")
+    
+    def find_elements_by_container(self, criteria, container, find_context, find_parameters):
+        """
+        Find elements in given container with given criteria
+        @param criteria Criteria
+        @param container Container
+        @param find_context Find context
+        @param find_parameters Find parameters
+        @return Found elements
+        """
+        raise NotImplementedError
+
+    def find_elements_by_candidates(self, criteria, candidates, find_context, find_parameters):
+        """
+        Find elements in given candidates with given criteria
+        
+        This default implementation use find_elements_by_container.
+        It is usually recommended to override it with a dedicated implementation.
+        @param candidates List of candidates
+        @param criteria Criteria
+        @param find_context Find context
+        @param find_parameters Find parameters
+        @return Found elements
+        """
+        if criteria is None:
+            return candidates
+        else:
+            res = []
+            if find_parameters.add_valid_container:
+                res = self.validate_elements(criteria, candidates, find_context, find_parameters)
+                
+            # Continue if max number of elements is not reached
+            if find_parameters.nb_max_elements is None or len(res) < find_parameters.nb_max_elements:
+                sub_find_parameters = find_parameters.with_valid_container(False)
+                for el in candidates:
+                    found_elements = self.find_elements_by_container(criteria, el, find_context, sub_find_parameters)
+                    res.extend(found_elements)
+                    
+                    # Stop if max number of elements is reached
+                    if find_parameters.nb_max_elements is not None and len(res) >= find_parameters.nb_max_elements:
+                        break
+            
+            if Tools.do_log(logger, logging.TRACE):  # @UndefinedVariable
+                logger.trace(f"find_elements_by_candidates: criteria={criteria} ; nb candidates={len(candidates)} ; max nb={find_parameters.nb_max_elements} ; visibility={find_parameters.visibility}   ->  {len(res)} elements")
+            return res
+
+    def validate_elements(self, criteria, elements, find_context, find_parameters):
+        """
+        @param criteria Criteria
+        @param elements List of elements to validate
+        @param find_context Find context
+        @param find_parameters Find parameters
+        @return List of elements validating given criteria
+        """
+        if criteria is None:
+            return elements
+        else:
+            res = []
+            criteria_context = find_context.get_criteria_context()
+            criteria_parameters = find_parameters.get_criteria_parameters()
+
+            # Search elements
+            for el in elements:
+                if criteria.validate(el, criteria_context, criteria_parameters):
+                    res.add(el)
+                       
+                    # Stop if max number of elements is reached
+                    if criteria_parameters.nb_max_elements is not None and len(res) >= criteria_parameters.nb_max_elements:
+                        break
+            
+            if Tools.do_log(logger, logging.TRACE):  # @UndefinedVariable
+                logger.trace(f"Validate {len(elements)} elements: criteria={criteria} ; nbMax={criteria_parameters.nb_max_elements} ; visibility={criteria_parameters.visibility}   ->  {len(res)} elements")
+            return res
+    
+    def _get_element_from_list(self, found_elements, nb_candidates, criteria, find_context, find_parameters):
+        """
+        Get element from found elements that should contain only one element.
+        @param found_elements List of elements previously found
+        @param criteria Criteria
+        @param find_context Find context
+        @param find_parameters Find parameters
+        @return Found element
+        """
+        # Analyze search result
+        if len(found_elements) == 1:
+            return found_elements[0]
+        elif len(found_elements) > 1:
+            msg_list = ["More than one"]
+            if find_parameters.nb_max_elements is not None:
+                msg_list.append(f" (at least {len(found_elements)})")
+            else:
+                msg_list.append(f" ({len(found_elements)})")
+            msg_list.append(f" element was found")
+            if nb_candidates > 1:
+                msg_list.append(f" (in {nb_candidates} candidates)")
+            if criteria is not None:
+                msg_list.append(f" with criteria={criteria}")
+            msg_list.append(":\n")
+            msg_list.append(self.represent_elements(found_elements, 4))
+            raise TooManyElementsException("".join(msg_list))
+        elif find_parameters.raise_no_such_element:
+            msg_list = ["Unable to find element"]
+            if nb_candidates > 1:
+                msg_list.append(f" (in {nb_candidates} candidates)")
+            if criteria is not None:
+                msg_list.append(f" with criteria={criteria}")
+            raise NoSuchElementException("".join(msg_list))
+    
+    def represent_elements(self, elements, indent):
+        """
+        @param elements Elements
+        @param indent Indent
+        @return String representing elements
+        """
+        res_list = []
+
+        for i, el in enumerate(elements):
+            res_list.append(f"{i} : {self.get_element_description(el)}")
+        
+        return Tools.indent_string(indent, "\n".join(res_list))
+    
+    def get_element_description(self, element):
+        """
+        @param element Element
+        @return Element description
+        """
+        raise NotImplementedError
+    
+    
+    
+    

holado_core/common/drivers/internal_api.py

@@ -0,0 +1,40 @@
+#################################################
+# 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
+
+logger = logging.getLogger(__name__)
+
+
+
+class InternalAPI(object):
+    """ Base class for internal API.
+    
+    An internal API is an interface to internal tool that is usually an external dependency.
+    The goal is to abstract all internal tools with a common API.
+    """
+    __metaclass__ = abc.ABCMeta
+    
+    def __init__(self, driver):
+        self.__driver = driver
+    
+    @property
+    def driver(self):
+        return self.__driver
+    
+    @property
+    def internal_driver(self):
+        return self.__driver.internal_driver
+    
+    
+    

holado_core/common/drivers/tree_driver.py

@@ -0,0 +1,30 @@
+#################################################
+# 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.drivers.element_driver import ElementDriver
+
+logger = logging.getLogger(__name__)
+
+
+
+class TreeDriver(ElementDriver):
+    """ Base class for elements tree drivers.
+    """
+    __metaclass__ = abc.ABCMeta
+    
+    def __init__(self, name=None):
+        super().__init__(name or "TreeDriver")
+    
+    
+    

holado_core/common/drivers/tree_internal_api.py

@@ -0,0 +1,176 @@
+#################################################
+# 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.finders.tools.find_context import ContainerFindContext
+from holado_core.common.exceptions.element_exception import NoSuchElementException
+from holado_core.common.exceptions.technical_exception import TechnicalException
+from holado_core.common.drivers.element_internal_api import ElementInternalAPI
+from holado_core.common.tools.tools import Tools
+
+logger = logging.getLogger(__name__)
+
+
+
+class TreeInternalAPI(ElementInternalAPI):
+    """ Base class for elements tree internal API.
+    """
+    __metaclass__ = abc.ABCMeta
+    
+    def __init__(self, driver):
+        super().__init__(driver)
+    
+    def find_children(self, criteria, container, find_context, find_parameters):
+        """
+        Find the children elements verifying given criteria.
+        @param container Container in which search
+        @param criteria Criteria to verify
+        @param find_context Find context
+        @param find_parameters Find parameters
+        @return Children elements
+        """
+        if container is None:
+            if isinstance(find_context, ContainerFindContext) and find_context.container is not None:
+                container = find_context.container
+            else:
+                raise TechnicalException("Find context has no container")
+            
+        children = self.find_children_elements(container, find_context, find_parameters)
+        return self.validate_elements(criteria, children, find_context, find_parameters)
+    
+    def find_children_elements(self, container, find_context, find_parameters):
+        """
+        Find the children elements of given element.
+        @param container An element
+        @param find_context Find context
+        @param find_parameters Find parameters
+        @return Children elements
+        """
+        raise NotImplementedError
+
+    def find_element_in_tree(self, criteria, container, find_context, find_parameters):
+        """
+        Find, in container tree, the element verifying given criteria.
+        @param container Container in which search
+        @param criteria Criteria to verify
+        @param find_context Find context
+        @param find_parameters Find parameters
+        @return Found element
+        """
+        sub_find_parameters = find_parameters.with_analyze_time_spent(False)
+        candidates = self.find_elements_in_tree(criteria, container, find_context, sub_find_parameters)
+        return self._get_element_from_list(candidates, 1, find_context, sub_find_parameters)
+    
+    def find_elements_in_tree(self, criteria, container, find_context, find_parameters):
+        """
+        Find, in container tree, all elements verifying given criteria.
+        When an element verifies given criteria, its sub tree is not explored.
+        
+        @param container Container in which search
+        @param criteria Criteria to verify
+        @param find_context Find context
+        @param find_parameters Find parameters
+        @return List of elements
+        """
+        if container is None:
+            if isinstance(find_context, ContainerFindContext) and find_context.container is not None:
+                container = find_context.container
+            else:
+                raise TechnicalException("Find context has no container")
+            
+        res = []
+        sub_find_parameters = find_parameters.get_next_level().with_valid_container(True)
+        criteria_context = find_context.get_criteria_context()
+        criteria_parameters = find_parameters.get_criteria_parameters()
+        
+        # Verify this element
+        is_validated = False
+        if find_parameters.add_valid_container:
+            is_validated = criteria.validate(container, criteria_context, criteria_parameters)
+            if is_validated:
+                res.append(container)
+        
+        # Verify in its children
+        if not is_validated:
+            children = self.find_children(None, container, find_context, sub_find_parameters.with_nb_max_elements(None))
+            for child in children:
+                if find_parameters.nb_max_elements is not None:
+                    # Search only remaining max elements to find
+                    res.extend( self.find_elements_in_tree(criteria, child, find_context, sub_find_parameters.with_nb_max_elements(find_parameters.nb_max_elements - len(res))) )
+                       
+                    # Stop if max number of elements is reached
+                    if len(res) >= find_parameters.nb_max_elements:
+                        break
+                else:
+                    res.extend( self.find_elements_in_tree(criteria, child, find_context, sub_find_parameters) )
+            
+        if Tools.do_log(logger, logging.TRACE):  # @UndefinedVariable
+            logger.trace(f"find_elements_in_tree: criteria={criteria} ; container={container} ; max nb={find_parameters.nb_max_elements} ; visibility={find_parameters.visibility}     ->  {len(res)} elements")
+        return res
+    
+    def find_parent(self, criteria, element, find_context, find_parameters):
+        """
+        Find the parent element for given element, verifying given criteria.
+        @param element An element
+        @param criteria Criteria
+        @param find_context Find context
+        @param find_parameters Find parameters
+        @return The parent element
+        """
+        if element is None:
+            if isinstance(find_context, ContainerFindContext) and find_context.container is not None:
+                element = find_context.container
+            else:
+                raise TechnicalException("Find context has no container")
+            
+        parent_element = element
+        found = False
+        sub_find_parameters = find_parameters.get_next_level()
+        criteria_context = find_context.get_criteria_context()
+        criteria_parameters = sub_find_parameters.get_criteria_parameters()
+        
+        while not found:
+            # Find parent
+            parent_element = self.find_parent_element(parent_element, find_context, sub_find_parameters)
+            
+            # Break if reached top of hierarchy
+            if parent_element is None:
+                break
+
+            # Verify criteria
+            if criteria is not None:
+                found = criteria.validate(parent_element, criteria_context, criteria_parameters)
+            else:
+                found = True
+            
+        if not found:
+            if find_parameters.raise_no_such_element:
+                raise NoSuchElementException(f"Unable to find parent with criteria: {criteria}")
+            else:
+                parent_element = None
+           
+        return parent_element
+    
+    def find_parent_element(self, element, find_context, find_parameters):
+        """
+        Find the parent element for given element.
+        @param element An element
+        @param find_context Find context
+        @param find_parameters Find parameters
+        @return The parent element
+        """
+        raise NotImplementedError
+    
+    
+    
+