MNT: Add type annotations and improve function signatures.

>> - Enhanced type annotations across botcity/core/bot.py and botcity/core/cv2find.py for better type safety and developer experience.
>> - Added type hints to parameters and return types in key methods like find, find_all, find_until, and _load_cv2.
>> - Ensured proper usage of Optional, List, Tuple, and Generator in function definitions.
>> - Standardized method signatures for consistency, explicitly defining default values and expected data types.
>> - Updated imports to include necessary types like Union, Optional, List, Tuple, Dict, and Generator.

Author: welli7ngton

botcity/core/bot.py

@@ -6,8 +6,8 @@
 import subprocess
 import time
 import webbrowser
-from typing import Union, Tuple, Optional, List
-
+from typing import Union, Tuple, Optional, List, Dict, Box, Generator, Any
+from numpy import ndarray
 
 import pyperclip
 from botcity.base import BaseBot, State
@@ -121,7 +121,7 @@ def app(self, app: Union["Application", "WindowSpecification"]):
     # Display
     ##########
 
-    def add_image(self, label, path):
+    def add_image(self, label: str, path: str) -> None:
         """
         Add an image into the state image map.
 
@@ -131,7 +131,7 @@ def add_image(self, label, path):
         """
         self.state.map_images[label] = path
 
-    def get_image_from_map(self, label):
+    def get_image_from_map(self, label: str) -> None:
         """
         Return an image from teh state image map.
 
@@ -149,25 +149,25 @@ def get_image_from_map(self, label):
 
     def find_multiple(
         self,
-        labels,
-        x=None,
-        y=None,
-        width=None,
-        height=None,
+        labels: List,
+        x: int = 0,
+        y: int = 0,
+        width: Optional[int] = None,
+        height: Optional[int] = None,
         *,
-        threshold=None,
-        matching=0.9,
-        waiting_time=10000,
-        best=True,
-        grayscale=False,
-    ):
+        threshold: Optional[int] = None,
+        matching: float = 0.9,
+        waiting_time: int = 10000,
+        best: bool = True,
+        grayscale: bool = False,
+    ) -> Dict:
         """
         Find multiple elements defined by label on screen until a timeout happens.
 
         Args:
             labels (list): A list of image identifiers
-            x (int, optional): Search region start position x. Defaults to 0.
-            y (int, optional): Search region start position y. Defaults to 0.
+            x (int): Search region start position x. Defaults to 0.
+            y (int): Search region start position y. Defaults to 0.
             width (int, optional): Search region width. Defaults to screen width.
             height (int, optional): Search region height. Defaults to screen height.
             threshold (int, optional): The threshold to be applied when doing grayscale search.
@@ -190,8 +190,6 @@ def _to_dict(lbs, elems):
             return {k: v for k, v in zip(lbs, elems)}
 
         screen_w, screen_h = self._fix_display_size()
-        x = x or 0
-        y = y or 0
         w = width or screen_w
         h = height or screen_h
 
@@ -253,7 +251,14 @@ def _fix_display_size(self) -> Tuple[int, int]:
 
         return int(width * 2), int(height * 2)
 
-    def _find_multiple_helper(self, haystack, region, confidence, grayscale, needle):
+    def _find_multiple_helper(
+        self,
+        haystack: Image.Image,
+        region: Tuple[int, int, int, int],
+        confidence: float,
+        grayscale: bool,
+        needle: Union[Image.Image, ndarray, str]
+    ) -> Union[Box, None]:
         ele = cv2find.locate_all_opencv(
             needle, haystack, region=region, confidence=confidence, grayscale=grayscale
         )
@@ -265,18 +270,18 @@ def _find_multiple_helper(self, haystack, region, confidence, grayscale, needle)
 
     def find(
         self,
-        label,
-        x=None,
-        y=None,
-        width=None,
-        height=None,
+        label: str,
+        x: Optional[int] = None,
+        y: Optional[int] = None,
+        width: Optional[int] = None,
+        height: Optional[int] = None,
         *,
-        threshold=None,
-        matching=0.9,
-        waiting_time=10000,
-        best=True,
-        grayscale=False,
-    ):
+        threshold: Optional[int] = None,
+        matching: float = 0.9,
+        waiting_time: int = 10000,
+        best: bool = True,
+        grayscale: bool = False,
+    ) -> Tuple[int, int, int, int] | None:
         """
         Find an element defined by label on screen until a timeout happens.
 
@@ -315,18 +320,18 @@ def find(
 
     def find_until(
         self,
-        label,
-        x=None,
-        y=None,
-        width=None,
-        height=None,
+        label: str,
+        x: Optional[int] = None,
+        y: Optional[int] = None,
+        width: Optional[int] = None,
+        height: Optional[int] = None,
         *,
-        threshold=None,
-        matching=0.9,
-        waiting_time=10000,
-        best=True,
-        grayscale=False,
-    ):
+        threshold: Optional[int] = None,
+        matching: float = 0.9,
+        waiting_time: int = 10000,
+        best: bool = True,
+        grayscale: bool = False,
+    ) -> Tuple[int, int, int, int] | None:
         """
         Find an element defined by label on screen until a timeout happens.
 
@@ -399,17 +404,17 @@ def find_until(
 
     def find_all(
         self,
-        label,
-        x=None,
-        y=None,
-        width=None,
-        height=None,
+        label: str,
+        x: Optional[int] = None,
+        y: Optional[int] = None,
+        width: Optional[int] = None,
+        height: Optional[int] = None,
         *,
-        threshold=None,
-        matching=0.9,
-        waiting_time=10000,
-        grayscale=False,
-    ):
+        threshold: Optional[int] = None,
+        matching: float = 0.9,
+        waiting_time: int = 10000,
+        grayscale: bool = False,
+    ) -> Generator[Box, Any, None]:
         """
         Find all elements defined by label on screen until a timeout happens.
 
@@ -504,16 +509,16 @@ def find_same(item, items):
 
     def find_text(
         self,
-        label,
-        x=None,
-        y=None,
-        width=None,
-        height=None,
+        label: str,
+        x: Optional[int] = None,
+        y: Optional[int] = None,
+        width: Optional[int] = None,
+        height: Optional[int] = None,
         *,
-        threshold=None,
-        matching=0.9,
-        waiting_time=10000,
-        best=True,
+        threshold: Optional[int] = None,
+        matching: float = 0.9,
+        waiting_time: int = 10000,
+        best: bool = True,
     ):
         """
         Find an element defined by label on screen until a timeout happens.
@@ -570,7 +575,7 @@ def find_process(self, name: str = None, pid: str = None) -> Process:
                 pass
         return None
 
-    def terminate_process(self, process: Process):
+    def terminate_process(self, process: Process) -> None:
         """
         Terminate the process via the received Process object.
 
@@ -582,7 +587,7 @@ def terminate_process(self, process: Process):
         if process.is_running():
             raise Exception("Terminate process failed")
 
-    def get_last_element(self):
+    def get_last_element(self) -> Tuple[int, int, int, int]:
         """
         Return the last element found.
 
@@ -681,8 +686,14 @@ def save_screenshot(self, path: str) -> None:
         self.screenshot(path)
 
     def get_element_coords(
-        self, label, x=None, y=None, width=None, height=None, matching=0.9, best=True
-    ):
+        self, label: str,
+        x: Optional[int] = None,
+        y: Optional[int] = None,
+        width: Optional[int] = None,
+        height: Optional[int] = None,
+        matching: float = 0.9,
+        best: bool = True
+    ) -> Tuple[int, int] | Tuple[None, None]:
         """
         Find an element defined by label on screen and returns its coordinates.
 
@@ -736,7 +747,14 @@ def get_element_coords(
         return ele.left, ele.top
 
     def get_element_coords_centered(
-        self, label, x=None, y=None, width=None, height=None, matching=0.9, best=True
+        self,
+        label: str,
+        x: Optional[int] = None,
+        y: Optional[int] = None,
+        width: Optional[int] = None,
+        height: Optional[int] = None,
+        matching: float = 0.9,
+        best: bool = True
     ):
         """
         Find an element defined by label on screen and returns its centered coordinates.

botcity/core/cv2find.py

@@ -33,6 +33,8 @@
 import collections
 import cv2
 import numpy
+from PIL.Image import Image
+from typing import Union, Tuple, Optional, Generator, Any
 
 RUNNING_CV_2 = cv2.__version__[0] < '3'
 
@@ -46,7 +48,7 @@
     LOAD_GRAYSCALE = cv2.IMREAD_GRAYSCALE
 
 
-def _load_cv2(img, grayscale=False):
+def _load_cv2(img: Union[Image, numpy.ndarray, str], grayscale: bool = False) -> numpy.ndarray:
     """
     TODO
     """
@@ -86,8 +88,15 @@ def _load_cv2(img, grayscale=False):
     return img_cv
 
 
-def locate_all_opencv(needle_image, haystack_image, grayscale=False, limit=10000, region=None, step=1,
-                      confidence=0.999):
+def locate_all_opencv(
+    needle_image: Union[Image, numpy.ndarray, str],
+    haystack_image: Union[Image, numpy.ndarray, str],
+    grayscale: bool = False,
+    limit: int = 10000,
+    region: Optional[Tuple[int, int, int, int]] = None,
+    step: int = 1,
+    confidence: float = 0.999
+) -> Generator[Box, Any, None]:
     """
     TODO - rewrite this
         faster but more memory-intensive than pure python