adds a dedicated find_image method (#15)

Author: cle-b

README.md

@@ -6,7 +6,7 @@ Niobium extends the Python Selenium client with nice features.
 
 Selenium is a good tool for web automation, but sometimes it's hard to write a clean automation script.
 
-With Niobium, you can keep using Selenium while simplifying your scripts. For example, Niobium adds a new element locator,` By.IMAGE`, which enables image recognition in `WebDriver.find_element` to locate an element on the webpage.
+With Niobium, you can keep using Selenium while simplifying your scripts. For example, Niobium adds a new method that uses image recognition to interact with the webpage.
 
 The goal of Niobium is not to replace Selenium. We only want to add to Selenium the functions we will love to see in Selenium natively.
 
@@ -30,7 +30,7 @@ In order to use Niobium, you just need to import it in your script. Selenium wil
     driver.implicitly_wait(10)
     driver.get("https://www.python.org/")
 
-    driver.find_element(By.IMAGE, "logo_python.png")
+    driver.find_image("logo_python.png")
 
     driver.quit()
 ```

docs/image.md

@@ -7,22 +7,22 @@ Niobium adds computer vision to Selenium.
 You can locate an image in the page using the following method:
 
 ```python
-    find_element(By.IMAGE, filename)
+    WebDriver.find_image(filename: str) -> ImageElement
 ```
 
 And to find multiple images (this method returns a list)
 
 ```python
-    find_elements(By.IMAGE, filename)
+    WebDriver.find_images(filename: str) -> list[ImageElement]
 ```
 
-These methods have the same behavior than the classic `find_element` methods but they return an `ImageElement` instead of a `WebElement` if you use the `By.IMAGE` selector.
+These methods have the same behavior than the classic `find_element` methods but they return an `ImageElement` instead of a `WebElement`.
 
 They take only one argument which is the path to the PNG image that you search.
 
 ## Find element by image
 
-The methods `find_element` and `find_elements` using the selector `By.IMAGE` are available only from the `WebDriver` object. Only the visible page is analyzed in order to locate the image.
+The methods `find_image` and `find_images` are available only from the `WebDriver` object. Only the visible page is analyzed in order to locate the image.
 
 ```python
     from selenium import webdriver
@@ -32,7 +32,7 @@ The methods `find_element` and `find_elements` using the selector `By.IMAGE` are
     driver.implicitly_wait(10)
     driver.get("https://www.python.org/")
 
-    driver.find_element(By.IMAGE, "logo_python.png")
+    driver.find_image("logo_python.png")
 
     driver.quit()
 ```
@@ -42,7 +42,7 @@ The methods `find_element` and `find_elements` using the selector `By.IMAGE` are
 You can click on the element.
 
 ```python
-    driver.find_element(By.IMAGE, "logo_python.png").click()
+    driver.find_image("logo_python.png").click()
 ```
 
 By default, the click is performed on the center of the element.
@@ -52,21 +52,21 @@ By default, the click is performed on the center of the element.
 You can click to a specific location related to the top left corner of the element with the `click_at(xoffset, yoffset)` function.
 
 ```python
-    driver.find_element(By.IMAGE, "logo_python.png").click_at(100, -100) 
+    driver.find_image("logo_python.png").click_at(100, -100) 
 ```
 
 ## Move the cursor over the element
 
 You can move the cursor to the center of the element with the `move_to()` function.
 
 ```python
-    driver.find_element(By.IMAGE, "logo_python.png").move_to()
+    driver.find_image("logo_python.png").move_to()
 ```
 
 ## Move the cursor with offset
 
 You can move the cursor to a specific location related to the top left corner of the element with the `move_at(xoffset, yoffset)` function.
 
 ```python
-    driver.find_element(By.IMAGE, "logo_python.png").move_at(20, 20)
+    driver.find_image("logo_python.png").move_at(20, 20)
 ```

docs/index.md

@@ -6,7 +6,8 @@ Niobium extends the Python Selenium client with nice features.
 
 Selenium is a good tool for web automation, but sometimes it's hard to write a clean automation script.
 
-With Niobium, you can keep using Selenium while simplifying your scripts. For example, Niobium adds a new element locator,` By.IMAGE`, which enables image recognition in `WebDriver.find_element` to locate an element on the webpage.
+With Niobium, you can keep using Selenium while simplifying your scripts. For example, Niobium adds a new method that uses image recognition to interact with the webpage.
+
 
 The goal of Niobium is not to replace Selenium. We only want to add to Selenium the functions we will love to see in Selenium natively.
 
@@ -30,7 +31,7 @@ In order to use Niobium, you just need to import it in your script. Selenium wil
     driver.implicitly_wait(10)
     driver.get("https://www.python.org/")
 
-    driver.find_element(By.IMAGE, "logo_python.png")
+    driver.find_image("logo_python.png")
 
     driver.quit()
 ```

niobium/__init__.py

@@ -13,4 +13,4 @@
 
 __all__ = ["selenium"]
 
-__version__ = "0.5.0"
+__version__ = "1.0.0"

niobium/find_image.py

@@ -1,28 +1,15 @@
 import io
-from typing import Optional
-from typing import Union
-
 
 import cv2
 import numpy as np
 from PIL import Image
 from selenium.common.exceptions import NoSuchElementException
 from selenium.common.exceptions import WebDriverException
-from selenium.webdriver.common.by import By as OriginalBy
 from selenium.webdriver.remote.webdriver import WebDriver
-from selenium.webdriver.remote.webelement import WebElement
-
 
 from niobium.image_element import ImageElement
 from niobium.timeout import ImplicitWait
 
-original_webdriver_find_element = WebDriver.find_element
-original_webdriver_find_elements = WebDriver.find_elements
-
-
-class By(OriginalBy):
-    IMAGE = "image"
-
 
 def match_template(img_src, img_template, threshold=0.9):
     # we remove alpha channel if exists
@@ -44,7 +31,7 @@ def match_template(img_src, img_template, threshold=0.9):
         return []
 
 
-def find_elements_by_image(self: WebDriver, filename: str) -> list[ImageElement]:
+def find_images(self: WebDriver, filename: str) -> list[ImageElement]:
     """
     Locate all the occurence of an image in the webpage.
 
@@ -70,7 +57,7 @@ def find_elements_by_image(self: WebDriver, filename: str) -> list[ImageElement]
     ]
 
 
-def find_element_by_image(self: WebDriver, filename: str) -> ImageElement:
+def find_image(self: WebDriver, filename: str) -> ImageElement:
     """
     Locate an image in the webpage.
 
@@ -86,32 +73,14 @@ def find_element_by_image(self: WebDriver, filename: str) -> ImageElement:
     implicit_wait = ImplicitWait()
     implicit_wait.start()
 
-    elements = find_elements_by_image(self, filename)
+    elements = find_images(self, filename)
 
     while len(elements) == 0 and not implicit_wait.max_time_exceeded:
-        elements = find_elements_by_image(self, filename)
+        elements = find_images(self, filename)
 
     if len(elements) == 0:
         raise NoSuchElementException(
             'Unable to locate element: [image="{filename}"]'.format(filename=filename)
         )
     else:
         return elements[0]
-
-
-def find_element(
-    self: WebDriver, by=By.ID, value: Optional[str] = None
-) -> Union[WebElement, ImageElement]:
-    if by == By.IMAGE and value is not None:
-        return find_element_by_image(self, value)
-    else:
-        return original_webdriver_find_element(self, by, value)
-
-
-def find_elements(
-    self: WebDriver, by=By.ID, value: Optional[str] = None
-) -> Union[list[WebElement], list[ImageElement]]:
-    if by == By.IMAGE and value is not None:
-        return find_elements_by_image(self, value)
-    else:
-        return original_webdriver_find_elements(self, by, value)

niobium/patch.py

@@ -1,38 +1,38 @@
 from selenium.webdriver.remote.webdriver import WebDriver
 from selenium.webdriver.remote.webelement import WebElement
-from selenium.webdriver.common import by
 
-from niobium.find_image import By as NiobiumBy
-from niobium.find_image import find_element
-from niobium.find_image import find_elements
+from niobium.find_image import find_image
+from niobium.find_image import find_images
 from niobium.timeout import _patch_implicitly_wait
 from niobium.webelement_action import click_at, move_to, move_at
 from niobium.webelement_wait import wait
 
 
 def patch_image():
 
-    by.By = NiobiumBy
+    if not hasattr(WebDriver, "find_image"):
+        WebDriver.find_image = find_image
 
-    WebDriver.find_element = find_element
-    WebDriver.find_elements = find_elements
+    if not hasattr(WebDriver, "find_images"):
+        WebDriver.find_images = find_images
 
 
 def patch_timeout():
     WebDriver.implicitly_wait = _patch_implicitly_wait
 
 
 def patch_webelement_action():
-    if "click_at" not in dir(WebElement):
+
+    if not hasattr(WebElement, "click_at"):
         WebElement.click_at = click_at
 
-    if "move_to" not in dir(WebElement):
+    if not hasattr(WebElement, "move_to"):
         WebElement.move_to = move_to
 
-    if "move_at" not in dir(WebElement):
+    if not hasattr(WebElement, "move_at"):
         WebElement.move_at = move_at
 
 
 def patch_webelement_wait():
-    if "wait" not in dir(WebElement):
+    if not hasattr(WebElement, "wait"):
         WebElement.wait = wait