dynamic-test-engine 0.1.0__py3-none-any.whl

automation/utils/cache.py

@@ -0,0 +1,135 @@
+import glob
+import json
+import logging
+import os
+import tempfile
+
+from automation import config
+
+logger = logging.getLogger(__name__)
+
+class JsonFileCache:
+
+    def __init__(self, cache_dir: str | None = None) -> None:
+        self._dir = cache_dir or config.UIA_CACHE_DIR
+
+    def _path(self, package: str) -> str:
+        os.makedirs(self._dir, exist_ok=True)
+        safe = package.replace(":", "_").replace("/", "_")
+        return os.path.join(self._dir, f"{safe}.json")
+
+    @staticmethod
+    def _screen_key(activity: str, version: str, device_fp: str) -> str:
+        return f"{activity}|{version}|{device_fp}"
+
+    def _load_screens(self, package: str) -> dict:
+        path = self._path(package)
+        if not os.path.exists(path):
+            return {}
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                data = json.load(f)
+        except (json.JSONDecodeError, OSError) as e:
+            logger.warning("cache: Laden fehlgeschlagen, Datei wird als leer behandelt path=%r error=%s", path, e)
+            return {}
+        return data.get("screens", {})
+
+    def get(self, package: str, activity: str, version: str, device_fp: str) -> dict | None:
+        screens = self._load_screens(package)
+        return screens.get(self._screen_key(activity, version, device_fp))
+
+    def put(self, package: str, activity: str, version: str, device_fp: str,
+            elements, index=None, framework_version: str = "") -> None:
+        screens = self._load_screens(package)
+        # Versions-Invalidierung: Einträge einer anderen App-Version derselben Package verwerfen.
+        screens = {k: v for k, v in screens.items() if v.get("version") == version}
+        # Merge statt Überschreiben: vorhandenes custom_elements-Feld bleibt erhalten (sonst löscht ein OCR-Miss den Icon-Cache).
+        entry = screens.setdefault(self._screen_key(activity, version, device_fp), {})
+        entry.update({
+            "activity": activity,
+            "version": version,
+            "device_fingerprint": device_fp,
+            "elements": elements,
+        })
+        # index/framework_version nur überschreiben, wenn der Aufruf sie liefert (Vision nie ->
+        # vom UIA-Index-Writer geschriebene Werte bleiben erhalten).
+        if framework_version:
+            entry["framework_version"] = framework_version
+        else:
+            entry.setdefault("framework_version", "")
+        if index is not None:
+            entry["index"] = index
+        else:
+            entry.setdefault("index", {})
+        _atomic_write(self._path(package), {
+            "schema_version": "2",
+            "package": package,
+            "screens": screens,
+        })
+
+    def get_custom_element_matches(self, package: str, activity: str, version: str,
+                                   device_fp: str, element_path: str) -> list[dict] | None:
+        entry = self.get(package, activity, version, device_fp)
+        if entry is None:
+            return None
+        return entry.get("custom_elements", {}).get(element_path)
+
+    def put_custom_element_matches(self, package: str, activity: str, version: str,
+                                   device_fp: str, element_path: str, boxes: list[dict]) -> None:
+        screens = self._load_screens(package)
+        # Versions-Invalidierung wie in put (sonst wächst die Datei über App-Versionen hinweg an).
+        screens = {k: v for k, v in screens.items() if v.get("version") == version}
+        key = self._screen_key(activity, version, device_fp)
+        # Minimaleintrag, falls der Screen-Key noch kein OCR-Layout hat; custom_elements wird
+        # ergänzt ohne elements zu berühren.
+        entry = screens.setdefault(key, {
+            "activity": activity, "version": version,
+            "device_fingerprint": device_fp, "framework_version": "",
+            "elements": [], "index": {},
+        })
+        entry.setdefault("custom_elements", {})[element_path] = boxes
+        _atomic_write(self._path(package), {
+            "schema_version": "2", "package": package, "screens": screens,
+        })
+
+    def get_uia_hint(self, package: str, activity: str, version: str,
+                    device_fp: str, action_key: str) -> dict | None:
+        entry = self.get(package, activity, version, device_fp)
+        if entry is None:
+            return None
+        return entry.get("uia_hints", {}).get(action_key)
+
+    def put_uia_hint(self, package: str, activity: str, version: str,
+                    device_fp: str, action_key: str, hint: dict) -> None:
+        screens = self._load_screens(package)
+        screens = {k: v for k, v in screens.items() if v.get("version") == version}
+        key = self._screen_key(activity, version, device_fp)
+        entry = screens.setdefault(key, {
+            "activity": activity, "version": version,
+            "device_fingerprint": device_fp, "framework_version": "",
+            "elements": [], "index": {},
+        })
+        entry.setdefault("uia_hints", {})[action_key] = hint
+        _atomic_write(self._path(package), {
+            "schema_version": "2", "package": package, "screens": screens,
+        })
+
+    def invalidate(self, package: str | None = None) -> None:
+        if package is not None:
+            path = self._path(package)
+            if os.path.exists(path):
+                os.remove(path)
+            logger.info("cache: invalidate package=%r", package)
+            return
+        paths = glob.glob(os.path.join(self._dir, "*.json"))
+        for path in paths:
+            os.remove(path)
+        logger.info("cache: invalidate package=all deleted=%d", len(paths))
+
+def _atomic_write(path: str, data: dict) -> None:
+    dir_ = os.path.dirname(os.path.abspath(path))
+    with tempfile.NamedTemporaryFile("w", dir=dir_, delete=False,
+                                     suffix=".tmp", encoding="utf-8") as f:
+        json.dump(data, f, ensure_ascii=False, indent=2)
+        tmp = f.name
+    os.replace(tmp, path)

automation/utils/device_interface.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import numpy as np
+
+
+class DeviceInterface(ABC):
+
+    @abstractmethod
+    def screenshot(self) -> np.ndarray: ...
+
+    @abstractmethod
+    def tap(self, x: int, y: int) -> None: ...
+
+    @abstractmethod
+    def type_text(self, text: str) -> None:
+        """Tippt literalen Text in das aktuell fokussierte Element.
+        PoC: nur Leerzeichen werden behandelt, kein Sonderzeichen-Escaping."""
+        ...
+
+    @abstractmethod
+    def scroll(self, x: int, y: int, amount: int, duration_ms: int | None = None) -> None:
+        """Scrollt die Ansicht unter (x, y) um `amount` (Vorzeichen = Richtung). Plattformspezifische
+        Geste: Touch-Drag auf Android, Mausrad auf Windows."""
+        ...
+
+    @abstractmethod
+    def connect(self, target: str | None = None) -> None: ...
+
+    @abstractmethod
+    def screen_key(self) -> tuple[str, str, str, str] | None:
+        """Stabile Screen-Identität (package/prozess, activity/fenster, version, device_fp).
+        None bei jedem Fehler -> Cache übersprungen."""
+        ...
+
+    def move_mouse(self, x: int, y: int) -> None:
+        """Bewegt den Mauszeiger an (x, y) ohne zu klicken. Nur auf Plattformen mit
+        Zeigerkonzept (Windows) implementiert."""
+        raise NotImplementedError(f"{type(self).__name__} unterstützt move_mouse nicht.")
+
+    def verify_focus_in_target(self) -> bool:
+        """Prüft, ob der Eingabefokus im verbundenen Zielprozess liegt. Default True."""
+        return True
+
+    def active_region(self) -> tuple[int, int, int, int] | None:
+        """Ausdehnung des obersten Dialog-/Fenster-Overlays in Screenshot-relativen Koordinaten,
+        None ohne Overlay. Nur auf Plattformen mit Overlay-Fensterkonzept implementiert."""
+        raise NotImplementedError(f"{type(self).__name__} unterstützt active_region nicht.")
+
+    def value_region(self, text: str) -> tuple[int, int, int, int] | None:
+        """Ausdehnung des einen editierbaren Elements mit aktuellem Wert == text, None bei
+        0/>1 Treffern. Nur auf Windows implementiert."""
+        raise NotImplementedError(f"{type(self).__name__} unterstützt value_region nicht.")
+
+    def clear_focused_field(self, x: int, y: int) -> None:
+        """Leert das Eingabefeld an Position (x, y) vor der Texteingabe."""
+        raise NotImplementedError(f"{type(self).__name__} unterstützt clear_focused_field nicht.")

automation/utils/image_processing.py

@@ -0,0 +1,258 @@
+from __future__ import annotations
+
+import logging
+import platform
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import numpy as np
+
+from automation import config
+
+logger = logging.getLogger(__name__)
+
+
+def load_image(path: str) -> np.ndarray:
+    import cv2
+    img = cv2.imread(path)
+    if img is None:
+        raise FileNotFoundError(f"load_image: image not found: {path}")
+    return img
+
+
+def to_grayscale(image: np.ndarray) -> np.ndarray:
+    import cv2
+    return cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+
+
+def match_custom_element(
+    screenshot: np.ndarray,
+    custom_element: np.ndarray,
+    threshold: float,
+) -> list[tuple[int, int]]:
+    import cv2
+    import numpy as np
+    gray_screen = to_grayscale(screenshot)
+    gray_element = to_grayscale(custom_element)
+    result = cv2.matchTemplate(gray_screen, gray_element, cv2.TM_CCOEFF_NORMED)
+    locations = np.where(result >= threshold)
+    h, w = gray_element.shape
+    matches = [(int(x + w // 2), int(y + h // 2)) for x, y in zip(locations[1], locations[0])]
+    logger.debug("match_custom_element: threshold=%s matches=%s", threshold, len(matches))
+    return matches
+
+
+def filter_matches(
+    matches: list[tuple[int, int]],
+    min_distance: int = 20,
+) -> list[tuple[int, int]]:
+    filtered = []
+    for candidate in matches:
+        too_close = any(
+            abs(candidate[0] - kept[0]) < min_distance
+            and abs(candidate[1] - kept[1]) < min_distance
+            for kept in filtered
+        )
+        if not too_close:
+            filtered.append(candidate)
+    logger.debug("filter_matches: input=%s min_distance=%s filtered=%s", len(matches), min_distance, len(filtered))
+    return filtered
+
+
+def _maybe_invert(image: np.ndarray) -> np.ndarray:
+    import cv2
+    import numpy as np
+    gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+    if float(np.mean(gray)) < 100:
+        return cv2.bitwise_not(image)
+    return image
+
+
+def _find_dark_regions(gray: np.ndarray, min_area: int = 500) -> list[tuple[int, int, int, int]]:
+    """Begrenzungsrechtecke einzelner dunkler Blöcke in einem ansonsten hellen Bild.
+    MORPH_OPEN statt CLOSE, damit normaler schwarzer Text nicht mit zu Blöcken verschmilzt."""
+    import cv2
+    import numpy as np
+    mask = (gray < 100).astype("uint8") * 255
+    kernel = np.ones((9, 9), np.uint8)
+    opened = cv2.morphologyEx(mask, cv2.MORPH_OPEN, kernel)
+    contours, _ = cv2.findContours(opened, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+    boxes = [cv2.boundingRect(c) for c in contours]
+    return [b for b in boxes if b[2] * b[3] >= min_area]
+
+
+def _merge_new_tokens(results: list[dict], new_tokens: list[dict], dx: int = 0, dy: int = 0) -> None:
+    """Fügt new_tokens (optional um dx/dy verschoben) hinzu. Ersetzt dabei überlappende
+    ältere Boxen, die im neuen Token aufgehen, statt am Overlap zu scheitern."""
+    margin = 5
+    for tok in new_tokens:
+        left = tok["left"] + dx
+        top = tok["top"] + dy
+        box = (left - margin, top - margin, left + tok["width"] + margin, top + tok["height"] + margin)
+        new_area = tok["width"] * tok["height"]
+        superseded, is_duplicate = _resolve_overlaps(results, box, new_area)
+        if is_duplicate:
+            continue
+        for r in superseded:
+            results.remove(r)
+        tok["left"], tok["top"] = left, top
+        results.append(tok)
+
+
+def _resolve_overlaps(
+    results: list[dict], box: tuple[int, int, int, int], new_area: int,
+) -> tuple[list[dict], bool]:
+    """Prüft box gegen bestehende results. superseded sind Boxen, die box vollständig ersetzt,
+    is_duplicate=True wenn box selbst in einer bestehenden Box aufgeht."""
+    bx0, by0, bx1, by1 = box
+    superseded = []
+    for r in results:
+        ox0, oy0 = max(bx0, r["left"]), max(by0, r["top"])
+        ox1, oy1 = min(bx1, r["left"] + r["width"]), min(by1, r["top"] + r["height"])
+        if ox0 >= ox1 or oy0 >= oy1:
+            continue
+        overlap_area = (ox1 - ox0) * (oy1 - oy0)
+        r_area = r["width"] * r["height"]
+        if r_area > 0 and overlap_area / r_area >= 0.8 and new_area > r_area:
+            superseded.append(r)
+        else:
+            return superseded, True
+    return superseded, False
+
+
+def ocr_find_text(
+    image: np.ndarray,
+    lang: str = "deu+eng",
+    scale: float | None = None,
+) -> list[dict]:
+    import cv2
+    import numpy as np
+    import pytesseract
+    if platform.system() == "Windows":
+        _venv_tess = Path(__file__).parents[2] / ".venv" / "Scripts" / "tesseract.exe"
+        if _venv_tess.exists():
+            pytesseract.pytesseract.tesseract_cmd = str(_venv_tess)
+    scale = scale or config.OCR_SCALE
+    if scale <= 0:
+        scale = 1.0
+
+    def _run_ocr(
+        src: np.ndarray,
+        block_offset: int = 0,
+        psm: int | None = None,
+        low_conf_sink: list[dict] | None = None,
+    ) -> list[dict]:
+        proc = src
+        if scale != 1.0:
+            h, w = proc.shape[:2]
+            proc = cv2.resize(proc, (int(w * scale), int(h * scale)))
+        _psm = psm if psm is not None else config.OCR_PSM
+        custom_config = f"--psm {_psm} --oem {config.OCR_OEM}"
+        data = pytesseract.image_to_data(proc, lang=lang, config=custom_config, output_type=pytesseract.Output.DICT)
+        out = []
+        for i, text in enumerate(data["text"]):
+            if not text.strip():
+                continue
+            conf = int(data["conf"][i])
+            token = {
+                "text":      text.strip(),
+                "left":      int(data["left"][i] / scale),
+                "top":       int(data["top"][i] / scale),
+                "width":     int(data["width"][i] / scale),
+                "height":    int(data["height"][i] / scale),
+                "block_num": int(data["block_num"][i]) + block_offset,
+                "par_num":   int(data["par_num"][i]) + block_offset,
+                "line_num":  int(data["line_num"][i]),
+            }
+            if conf > config.OCR_CONFIDENCE:
+                out.append(token)
+            elif conf > 0 and low_conf_sink is not None:
+                low_conf_sink.append(token)
+        return out
+
+    def _crop_ocr_merge(
+        results: list[dict],
+        x: int, y: int, w: int, h: int,
+        pad_x: int, pad_y: int,
+        block_offset: int, psm: int,
+        transform=None, downscale: int = 1,
+    ) -> None:
+        """Croppt einen Bereich (plus Padding), OCR't ihn separat und mergt die Treffer zurück
+        in results. Gemeinsame Grundlage für Dark-Region- und Low-Conf-Rescue-Pass."""
+        x0, x1 = max(0, x - pad_x), min(image.shape[1], x + w + pad_x)
+        y0, y1 = max(0, y - pad_y), min(image.shape[0], y + h + pad_y)
+        crop = image[y0:y1, x0:x1]
+        if crop.size == 0:
+            return
+        if transform is not None:
+            crop = transform(crop)
+        tokens = _run_ocr(crop, block_offset=block_offset, psm=psm)
+        if downscale != 1:
+            for tok in tokens:
+                tok["left"] //= downscale
+                tok["top"] //= downscale
+                tok["width"] //= downscale
+                tok["height"] //= downscale
+        _merge_new_tokens(results, tokens, dx=x0, dy=y0)
+
+    gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+    is_dark = float(np.mean(gray)) < 100
+    low_conf_tokens: list[dict] = []
+    results = _run_ocr(_maybe_invert(image), low_conf_sink=low_conf_tokens)
+
+    if is_dark:
+        _merge_new_tokens(results, _run_ocr(image, block_offset=1000, psm=3))
+    else:
+        pad = 6
+        for i, (x, y, w, h) in enumerate(_find_dark_regions(gray)):
+            _crop_ocr_merge(
+                results, x, y, w, h, pad_x=pad, pad_y=pad,
+                block_offset=2000 + i * 100, psm=6, transform=cv2.bitwise_not,
+            )
+
+    # Adaptive-Upscale-Rescue: Tokens, die Tesseract erkannt, aber nicht sicher gelesen hat
+    # (z. B. abgeschnittene CamelCase-Compound-Wörter wie "CollectionNavigator"), sind ein
+    # generischer Hinweis auf zu geringe Zeichenauflösung an dieser Stelle - unabhängig von
+    # Schriftgröße, da dieselbe Bildschirmschrift an anderer Stelle sauber gelesen wird.
+    # Einzelzeichen-Fragmente (Icon-Glyphen, Ziffern) werden ausgeklammert, da Upscaling dort
+    # nichts rekonstruiert, was nicht schon vorhanden ist.
+    upscale = 3
+    for i, tok in enumerate(low_conf_tokens):
+        if len(tok["text"]) < 2:
+            continue
+        left, t, w, h = tok["left"], tok["top"], tok["width"], tok["height"]
+        pad_x, pad_y = max(40, h * 6), max(15, h * 2)
+        _crop_ocr_merge(
+            results, left, t, w, h, pad_x=pad_x, pad_y=pad_y,
+            block_offset=3000 + i * 100, psm=3,
+            transform=lambda c: cv2.resize(c, None, fx=upscale, fy=upscale, interpolation=cv2.INTER_CUBIC),
+            downscale=upscale,
+        )
+
+    logger.debug(
+        "ocr_find_text: lang=%s scale=%s results=%s low_conf_rescued=%s",
+        lang, scale, len(results), len(low_conf_tokens),
+    )
+    return results
+
+
+def _merge_line(line: list[dict]) -> dict:
+    """Fasst die Tokens einer OCR-Zeile zu einer Bounding-Box mit zusammengefügtem Text zusammen."""
+    words, x0, y0, x1, y1 = [], line[0]["left"], line[0]["top"], 0, 0
+    for t in line:
+        words.append(t["text"])
+        y0 = min(y0, t["top"])
+        x1 = max(x1, t["left"] + t["width"])
+        y1 = max(y1, t["top"] + t["height"])
+    return {"text": " ".join(words), "left": x0, "top": y0, "width": x1 - x0, "height": y1 - y0}
+
+
+def ocr_group_lines(tokens: list[dict]) -> list[dict]:
+    # Erwartet Tokens mit den Schlüsseln: block_num, par_num, line_num, left, top, width, height, text.
+    if not tokens:
+        return []
+    groups: dict[tuple, list[dict]] = {}
+    for t in tokens:
+        groups.setdefault((t["block_num"], t["par_num"], t["line_num"]), []).append(t)
+    return [_merge_line(sorted(groups[key], key=lambda t: t["left"])) for key in sorted(groups)]

automation/utils/scroll_centering.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import logging
+import time
+
+from automation import config
+from automation.utils.device_interface import DeviceInterface
+
+logger = logging.getLogger(__name__)
+
+
+def center_in_safe_area(
+    device: DeviceInterface,
+    x: int,
+    screen_height: int,
+    el_center_y: int,
+    margin_percent: float | None = None,
+    max_shift: int | None = None,
+) -> bool:
+    """Verschiebt ein per Scroll gefundenes Element minimal in den sicheren Bereich, falls es
+    außerhalb liegt. Gibt zurück, ob eine Korrektur nötig war."""
+    if margin_percent is None:
+        margin_percent = config.SCROLL_SAFE_MARGIN_PERCENT
+
+    top = screen_height * margin_percent
+    bottom = screen_height * (1 - margin_percent)
+    if top <= el_center_y <= bottom:
+        return False  # bereits im sicheren Bereich, keine Korrektur nötig
+
+    # Ziel = nächste Bereichsgrenze → minimale Bewegung, kann nie über die Mitte hinausschießen
+    target_y = bottom if el_center_y > bottom else top
+    delta = int(el_center_y - target_y)  # >0: Element nach oben holen; <0: nach unten
+    if max_shift is not None:
+        delta = max(-max_shift, min(delta, max_shift))
+    # Unterhalb dieser Schwelle ist ein adb-Swipe vom Gerät nicht von einem Tap zu unterscheiden.
+    # Mikrokorrekturen überspringen, das Element ist nah genug an der Bereichsgrenze.
+    if abs(delta) < 30:
+        return False
+
+    # Scroll-Distanz = |delta| (exakte Korrektur), zentriert um den Bildschirm-Mittelpunkt,
+    # damit Start- und Endkoordinaten sicher im sichtbaren Bereich bleiben.
+    mid = screen_height // 2
+    logger.info(
+        "center_in_safe_area el_center_y=%s target_y=%s delta=%s", el_center_y, int(target_y), delta
+    )
+    device.scroll(x, mid, delta, duration_ms=config.CENTERING_SWIPE_DURATION_MS)
+    time.sleep(0.2)  # Korrektur-Swipe abwarten, bevor der Aufrufer den Bildschirmzustand liest
+    return True

automation/utils/spatial.py

@@ -0,0 +1,63 @@
+"""Geometrischer Relations-Resolver (engine-unabhängig), arbeitet rein auf Bounding-Boxes."""
+
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+RELATIONS = ("near", "left_of", "right_of", "above", "below")
+
+def center(box: dict) -> tuple[int, int]:
+    return box["left"] + box["width"] // 2, box["top"] + box["height"] // 2
+
+def _rows_overlap(a: dict, b: dict, tol: int) -> bool:
+    # Vertikale Bereiche überlappen sich (gleiche Zeile), mit Toleranz.
+    return a["top"] < b["top"] + b["height"] + tol and b["top"] < a["top"] + a["height"] + tol
+
+def _cols_overlap(a: dict, b: dict, tol: int) -> bool:
+    # Horizontale Bereiche überlappen sich (gleiche Spalte), mit Toleranz.
+    return a["left"] < b["left"] + b["width"] + tol and b["left"] < a["left"] + a["width"] + tol
+
+def _distance(a: dict, b: dict) -> float:
+    ax, ay = center(a)
+    bx, by = center(b)
+    return ((ax - bx) ** 2 + (ay - by) ** 2) ** 0.5
+
+def resolve(
+    anchor: dict,
+    candidates: list[dict],
+    relation: str,
+    *,
+    overlap_tol: int = 0,
+    max_distance: int = 0,
+) -> dict | None:
+    """Gibt die Kandidaten-Box zurück, die die Relation zum Anker erfüllt und am nächsten liegt,
+    None wenn kein Kandidat passt oder max_distance überschritten wird."""
+    if relation not in RELATIONS:
+        raise ValueError(f"Unbekannte Relation: '{relation}'. Erlaubt: {RELATIONS}")
+    acx, acy = center(anchor)
+    matching = []
+    for c in candidates:
+        ccx, ccy = center(c)
+        if relation == "near":
+            ok = True
+        elif relation == "left_of":
+            ok = ccx < acx and _rows_overlap(anchor, c, overlap_tol)
+        elif relation == "right_of":
+            ok = ccx > acx and _rows_overlap(anchor, c, overlap_tol)
+        elif relation == "above":
+            ok = ccy < acy and _cols_overlap(anchor, c, overlap_tol)
+        else:  # below
+            ok = ccy > acy and _cols_overlap(anchor, c, overlap_tol)
+        if ok:
+            matching.append(c)
+    if not matching:
+        logger.debug("resolve event=no_match relation=%s candidates=%d", relation, len(candidates))
+        return None
+    best = min(matching, key=lambda c: _distance(anchor, c))
+    if max_distance and _distance(anchor, best) > max_distance:
+        logger.debug("resolve event=max_distance_exceeded relation=%s distance=%.1f max_distance=%d",
+                    relation, _distance(anchor, best), max_distance)
+        return None
+    return best