Squashed commit of the following:

commit d95e646
Author: Dave Amies <damies13@gmail.com>
Date:   Sun Feb 27 13:23:14 2022 +1000

    Add timeout option to keywords - Issue eficode#61

    Keywords that now have the optional timeout are:
    - Click Image
    - Click To The Above Of Image
    - Click To The Below Of Image
    - Click To The Left Of Image
    - Click To The Right Of Image
    - Copy From The Above Of
    - Copy From The Below Of
    - Copy From The Left Of
    - Copy From The Right Of

    The default timeout is 0 sec so there is no functional change from previous version unless a timeout is set, this does require  Pull request eficode#64 (fix for issue eficode#60) as a prerequisite for this change in order to work as expected. Please only merge after Pull request eficode#64

Author: noubar

src/ImageHorizonLibrary/recognition/_recognize_images.py

@@ -12,6 +12,7 @@
 
 class _RecognizeImages(object):
 
+    dflt_timeout = 0
     pixel_ratio = 0.0
 
     def __get_pixel_ratio(self):
@@ -33,13 +34,15 @@ def __normalize(self, path):
             raise InvalidImageException('Image path not found: "%s".' % path)
         return path
 
-    def click_image(self, reference_image):
-        '''Finds the reference image on screen and clicks it once.
+    def click_image(self, reference_image, timeout=dflt_timeout):
+        '''Finds the reference image on screen and clicks it's center point once.
 
         ``reference_image`` is automatically normalized as described in the
         `Reference image names`.
+
+        ``timeout`` optional value, in whole seconds. default is 0
         '''
-        center_location = self.locate(reference_image)
+        center_location = self.wait_for(reference_image, timeout)
         LOGGER.info('Clicking image "%s" in position %s' % (reference_image,
                                                             center_location))
         ag.click(center_location)
@@ -50,13 +53,13 @@ def _click_to_the_direction_of(self, direction, location, offset,
         raise NotImplementedError('This is defined in the main class.')
 
     def _locate_and_click_direction(self, direction, reference_image, offset,
-                                    clicks, button, interval):
-        location = self.locate(reference_image)
+                                    clicks, button, interval, timeout=dflt_timeout):
+        location = self.wait_for(reference_image, timeout)
         self._click_to_the_direction_of(direction, location, offset, clicks,
                                         button, interval)
 
     def click_to_the_above_of_image(self, reference_image, offset, clicks=1,
-                                    button='left', interval=0.0):
+                                    button='left', interval=0.0, timeout=dflt_timeout):
         '''Clicks above of reference image by given offset.
 
         See `Reference image names` for documentation for ``reference_image``.
@@ -65,38 +68,40 @@ def click_to_the_above_of_image(self, reference_image, offset, clicks=1,
         image.
 
         ``clicks`` and ``button`` are documented in `Click To The Above Of`.
+
+        ``timeout`` optional value, in whole seconds. default is 0
         '''
         self._locate_and_click_direction('up', reference_image, offset,
-                                         clicks, button, interval)
+                                         clicks, button, interval, timeout)
 
     def click_to_the_below_of_image(self, reference_image, offset, clicks=1,
-                                    button='left', interval=0.0):
+                                    button='left', interval=0.0, timeout=dflt_timeout):
         '''Clicks below of reference image by given offset.
 
         See argument documentation in `Click To The Above Of Image`.
         '''
         self._locate_and_click_direction('down', reference_image, offset,
-                                         clicks, button, interval)
+                                         clicks, button, interval, timeout)
 
     def click_to_the_left_of_image(self, reference_image, offset, clicks=1,
-                                   button='left', interval=0.0):
+                                   button='left', interval=0.0, timeout=dflt_timeout):
         '''Clicks left of reference image by given offset.
 
         See argument documentation in `Click To The Above Of Image`.
         '''
         self._locate_and_click_direction('left', reference_image, offset,
-                                         clicks, button, interval)
+                                         clicks, button, interval, timeout)
 
     def click_to_the_right_of_image(self, reference_image, offset, clicks=1,
-                                    button='left', interval=0.0):
+                                    button='left', interval=0.0, timeout=dflt_timeout):
         '''Clicks right of reference image by given offset.
 
         See argument documentation in `Click To The Above Of Image`.
         '''
         self._locate_and_click_direction('right', reference_image, offset,
-                                         clicks, button, interval)
+                                         clicks, button, interval, timeout)
 
-    def copy_from_the_above_of(self, reference_image, offset):
+    def copy_from_the_above_of(self, reference_image, offset, timeout=dflt_timeout):
         '''Clicks three times above of reference image by given offset and
         copies.
 
@@ -106,39 +111,41 @@ def copy_from_the_above_of(self, reference_image, offset):
 
         Copy is done by pressing ``Ctrl+C`` on Windows and Linux and ``⌘+C``
         on OS X.
+
+        ``timeout`` optional value, in whole seconds. default is 0
         '''
         self._locate_and_click_direction('up', reference_image, offset,
-                                         clicks=3, button='left', interval=0.0)
+                                         clicks=3, button='left', interval=0.0, timeout=timeout)
         return self.copy()
 
-    def copy_from_the_below_of(self, reference_image, offset):
+    def copy_from_the_below_of(self, reference_image, offset, timeout=dflt_timeout):
         '''Clicks three times below of reference image by given offset and
         copies.
 
         See argument documentation in `Copy From The Above Of`.
         '''
         self._locate_and_click_direction('down', reference_image, offset,
-                                         clicks=3, button='left', interval=0.0)
+                                         clicks=3, button='left', interval=0.0, timeout=timeout)
         return self.copy()
 
-    def copy_from_the_left_of(self, reference_image, offset):
+    def copy_from_the_left_of(self, reference_image, offset, timeout=dflt_timeout):
         '''Clicks three times left of reference image by given offset and
         copies.
 
         See argument documentation in `Copy From The Above Of`.
         '''
         self._locate_and_click_direction('left', reference_image, offset,
-                                         clicks=3, button='left', interval=0.0)
+                                         clicks=3, button='left', interval=0.0, timeout=timeout)
         return self.copy()
 
-    def copy_from_the_right_of(self, reference_image, offset):
+    def copy_from_the_right_of(self, reference_image, offset, timeout=dflt_timeout):
         '''Clicks three times right of reference image by given offset and
         copies.
 
         See argument documentation in `Copy From The Above Of`.
         '''
         self._locate_and_click_direction('right', reference_image, offset,
-                                         clicks=3, button='left', interval=0.0)
+                                         clicks=3, button='left', interval=0.0, timeout=timeout)
         return self.copy()
 
     @contextmanager
@@ -244,7 +251,7 @@ def wait_for(self, reference_image, timeout=10):
 
         See `Reference image names` for documentation for ``reference_image``.
 
-        ``timeout`` is given in seconds.
+        ``timeout`` is given in whole seconds.
 
         Returns Python tuple ``(x, y)`` of the coordinates.
         '''