tksearchengine 1.0.0__tar.gz

tksearchengine-1.0.0/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: tksearchengine
+Version: 1.0.0
+Summary: A reusable Tkinter search widget with fuzzy multi-word matching
+Author: WhatIsMyRealName
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: X11 Applications
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# tksearchengine
+
+`tksearchengine` provides a reusable Tkinter search field with fuzzy,
+multi-word suggestions. It combines an entry, a search button, and a listbox
+in a single configurable widget.
+
+## Features
+
+- Placeholder text while the empty entry is not focused.
+- Live suggestions while the entry is focused.
+- Mouse selection and keyboard navigation with Up and Down.
+- Tab accepts the highlighted suggestion, or the first suggestion by default.
+- Return and the search button invoke the same callback.
+- Case-insensitive, accent-insensitive, multi-word fuzzy matching.
+- `-` and `'` are treated as word separators.
+- Missing spaces and spaces accidentally replaced by `n` or `b` are handled.
+- Exact words, exact prefixes, approximate prefixes, and approximate complete
+  words are ranked in that order.
+- No third-party runtime dependencies.
+
+## Requirements
+
+- Python 3.10 or newer.
+- Tkinter, which is included with many Python installations but may require a
+  separate operating-system package on Linux. For example, Debian and Ubuntu provide it in the `python3-tk` package.
+
+## Installation
+
+From PyPI:
+
+```console
+python -m pip install tksearchengine
+```
+
+From the project directory:
+
+```console
+python -m pip install .
+```
+
+For editable development:
+
+```console
+python -m pip install -e .
+```
+
+## Basic usage
+
+```python
+import tkinter as tk
+
+from tksearchengine import SearchEngine
+
+
+def run_search(text: str, selected_item: str | None) -> None:
+    print("Search text:", text)
+    print("Selected suggestion:", selected_item)
+
+
+root = tk.Tk()
+
+search = SearchEngine(
+    root,
+    items=["Paris", "Marseille", "Lyon", "Orléans"],
+    command=run_search,
+    placeholder="Search for a city",
+    max_visible_results=6,
+)
+search.pack(fill="x", padx=20, pady=20)
+
+root.mainloop()
+```
+
+## Configuration
+
+The constructor accepts:
+
+- `items`: searchable strings.
+- `command`: callback receiving the current text and the selected suggestion. The second argument is `None` when the user submits free text without accepting a suggestion.
+- `placeholder`: text displayed when the unfocused entry is empty.
+- `button_text`: label or symbol displayed on the search button.
+- `search_function`: optional replacement for the complete ranking function.
+- `max_distance_function`: optional function returning the accepted edit
+  distance for a given reference-word length.
+- `max_visible_results`: maximum visible listbox rows.
+- `placeholder_color` and `text_color`: entry text colors.
+- `entry_options`, `button_options`, and `listbox_options`: mappings forwarded
+  to the corresponding Tkinter widgets.
+- Any remaining keyword arguments are forwarded to the containing `tk.Frame`.
+
+Here is the `__init__` shape:
+```python
+    def __init__(
+        self,
+        master: tk.Misc | None = None,
+        *,
+        items: Sequence[str] = (),
+        command: SearchCallback | None = None,
+        placeholder: str = "Search…",
+        button_text: str = "🔍",
+        search_function: SearchFunction | None = None,
+        max_distance_function: MaxDistanceFunction = _default_max_distance,
+        max_visible_results: int = 8,
+        placeholder_color: str = "grey",
+        text_color: str = "black",
+        entry_options: Mapping[str, Any] | None = None,
+        button_options: Mapping[str, Any] | None = None,
+        listbox_options: Mapping[str, Any] | None = None,
+        **frame_options: Any,
+    ) -> None:
+```
+
+Example with widget customization:
+
+```python
+search = SearchEngine(
+    root,
+    items=["Paris", "Marseille", "Lyon", "Orléans"],
+    entry_options={
+        "width": 32,
+        "font": ("Segoe UI", 11),
+        "relief": "solid",
+    },
+    button_options={
+        "text": "Search",
+        "font": ("Segoe UI", 10, "bold"),
+        "padx": 12,
+    },
+    listbox_options={
+        "font": ("Segoe UI", 10),
+        "height": 6,
+        "activestyle": "dotbox",
+    },
+)
+```
+
+These mappings are passed directly to `tk.Entry`, `tk.Button`, and `tk.Listbox`.
+`SearchEngine` still owns the entry text variable, the button command, the
+listbox selection behavior, and the visible result count.
+
+A custom search function has this shape:
+
+```python
+from collections.abc import Sequence
+
+
+def custom_search(items: Sequence[str], query: str) -> Sequence[str]:
+    normalized_query = query.lower()
+    return [item for item in items if normalized_query in item.lower()]
+```
+
+Pass it with `search_function=custom_search`. When a custom search function is
+provided, it is responsible for filtering and ordering all results.
+
+## Public methods
+
+- `get()` returns the current search text without the placeholder.
+- `set(text)` replaces the current search text.
+- `set_items(items)` replaces the searchable collection.
+- `invoke()` runs the configured callback.
+- `selected_item` returns the highlighted or accepted suggestion, if any.
+
+## Matching behavior
+
+The default matcher normalizes text to lowercase, replaces common accented
+letters with their unaccented forms, and treats `-` and `'` as spaces. Results are
+ranked by:
+
+1. number of unmatched query words;
+2. match type, from exact word to approximate complete word;
+3. normalized Levenshtein distance;
+4. query-word order;
+5. original item order.
+
+The default maximum edit distance is `(word_length + 2) // 5`. Override
+`max_distance_function(word_length)` when an application needs stricter or more permissive
+matching.
+
+## Running the example
+
+The example contains 1,000 French commune names:
+
+```console
+python examples/communes.py
+```
+Filtering the 1,000 sample names should feel immediate on a typical desktop Python installation.
+
+## Running the tests
+
+After an editable installation:
+
+```console
+python -m unittest discover -s tests -v
+```

tksearchengine-1.0.0/README.md

@@ -0,0 +1,194 @@
+# tksearchengine
+
+`tksearchengine` provides a reusable Tkinter search field with fuzzy,
+multi-word suggestions. It combines an entry, a search button, and a listbox
+in a single configurable widget.
+
+## Features
+
+- Placeholder text while the empty entry is not focused.
+- Live suggestions while the entry is focused.
+- Mouse selection and keyboard navigation with Up and Down.
+- Tab accepts the highlighted suggestion, or the first suggestion by default.
+- Return and the search button invoke the same callback.
+- Case-insensitive, accent-insensitive, multi-word fuzzy matching.
+- `-` and `'` are treated as word separators.
+- Missing spaces and spaces accidentally replaced by `n` or `b` are handled.
+- Exact words, exact prefixes, approximate prefixes, and approximate complete
+  words are ranked in that order.
+- No third-party runtime dependencies.
+
+## Requirements
+
+- Python 3.10 or newer.
+- Tkinter, which is included with many Python installations but may require a
+  separate operating-system package on Linux. For example, Debian and Ubuntu provide it in the `python3-tk` package.
+
+## Installation
+
+From PyPI:
+
+```console
+python -m pip install tksearchengine
+```
+
+From the project directory:
+
+```console
+python -m pip install .
+```
+
+For editable development:
+
+```console
+python -m pip install -e .
+```
+
+## Basic usage
+
+```python
+import tkinter as tk
+
+from tksearchengine import SearchEngine
+
+
+def run_search(text: str, selected_item: str | None) -> None:
+    print("Search text:", text)
+    print("Selected suggestion:", selected_item)
+
+
+root = tk.Tk()
+
+search = SearchEngine(
+    root,
+    items=["Paris", "Marseille", "Lyon", "Orléans"],
+    command=run_search,
+    placeholder="Search for a city",
+    max_visible_results=6,
+)
+search.pack(fill="x", padx=20, pady=20)
+
+root.mainloop()
+```
+
+## Configuration
+
+The constructor accepts:
+
+- `items`: searchable strings.
+- `command`: callback receiving the current text and the selected suggestion. The second argument is `None` when the user submits free text without accepting a suggestion.
+- `placeholder`: text displayed when the unfocused entry is empty.
+- `button_text`: label or symbol displayed on the search button.
+- `search_function`: optional replacement for the complete ranking function.
+- `max_distance_function`: optional function returning the accepted edit
+  distance for a given reference-word length.
+- `max_visible_results`: maximum visible listbox rows.
+- `placeholder_color` and `text_color`: entry text colors.
+- `entry_options`, `button_options`, and `listbox_options`: mappings forwarded
+  to the corresponding Tkinter widgets.
+- Any remaining keyword arguments are forwarded to the containing `tk.Frame`.
+
+Here is the `__init__` shape:
+```python
+    def __init__(
+        self,
+        master: tk.Misc | None = None,
+        *,
+        items: Sequence[str] = (),
+        command: SearchCallback | None = None,
+        placeholder: str = "Search…",
+        button_text: str = "🔍",
+        search_function: SearchFunction | None = None,
+        max_distance_function: MaxDistanceFunction = _default_max_distance,
+        max_visible_results: int = 8,
+        placeholder_color: str = "grey",
+        text_color: str = "black",
+        entry_options: Mapping[str, Any] | None = None,
+        button_options: Mapping[str, Any] | None = None,
+        listbox_options: Mapping[str, Any] | None = None,
+        **frame_options: Any,
+    ) -> None:
+```
+
+Example with widget customization:
+
+```python
+search = SearchEngine(
+    root,
+    items=["Paris", "Marseille", "Lyon", "Orléans"],
+    entry_options={
+        "width": 32,
+        "font": ("Segoe UI", 11),
+        "relief": "solid",
+    },
+    button_options={
+        "text": "Search",
+        "font": ("Segoe UI", 10, "bold"),
+        "padx": 12,
+    },
+    listbox_options={
+        "font": ("Segoe UI", 10),
+        "height": 6,
+        "activestyle": "dotbox",
+    },
+)
+```
+
+These mappings are passed directly to `tk.Entry`, `tk.Button`, and `tk.Listbox`.
+`SearchEngine` still owns the entry text variable, the button command, the
+listbox selection behavior, and the visible result count.
+
+A custom search function has this shape:
+
+```python
+from collections.abc import Sequence
+
+
+def custom_search(items: Sequence[str], query: str) -> Sequence[str]:
+    normalized_query = query.lower()
+    return [item for item in items if normalized_query in item.lower()]
+```
+
+Pass it with `search_function=custom_search`. When a custom search function is
+provided, it is responsible for filtering and ordering all results.
+
+## Public methods
+
+- `get()` returns the current search text without the placeholder.
+- `set(text)` replaces the current search text.
+- `set_items(items)` replaces the searchable collection.
+- `invoke()` runs the configured callback.
+- `selected_item` returns the highlighted or accepted suggestion, if any.
+
+## Matching behavior
+
+The default matcher normalizes text to lowercase, replaces common accented
+letters with their unaccented forms, and treats `-` and `'` as spaces. Results are
+ranked by:
+
+1. number of unmatched query words;
+2. match type, from exact word to approximate complete word;
+3. normalized Levenshtein distance;
+4. query-word order;
+5. original item order.
+
+The default maximum edit distance is `(word_length + 2) // 5`. Override
+`max_distance_function(word_length)` when an application needs stricter or more permissive
+matching.
+
+## Running the example
+
+The example contains 1,000 French commune names:
+
+```console
+python examples/communes.py
+```
+Filtering the 1,000 sample names should feel immediate on a typical desktop Python installation.
+
+## Running the tests
+
+After an editable installation:
+
+```console
+python -m unittest discover -s tests -v
+```

tksearchengine-1.0.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tksearchengine"
+version = "1.0.0"
+description = "A reusable Tkinter search widget with fuzzy multi-word matching"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "WhatIsMyRealName" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: X11 Applications",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: User Interfaces",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+tksearchengine = ["py.typed"]

tksearchengine-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tksearchengine-1.0.0/src/tksearchengine/__init__.py

@@ -0,0 +1,5 @@
+"""A reusable fuzzy search widget for Tkinter."""
+
+from .search_engine import SearchEngine
+
+__all__ = ["SearchEngine"]

tksearchengine-1.0.0/src/tksearchengine/search_engine.py

@@ -0,0 +1,447 @@
+"""Reusable Tkinter search widget with autocomplete suggestions."""
+
+from __future__ import annotations
+
+import tkinter as tk
+from collections.abc import Callable, Mapping, Sequence
+from fractions import Fraction
+from functools import lru_cache
+from typing import Any, TypeAlias
+
+SearchCallback: TypeAlias = Callable[[str, str | None], None]
+SearchFunction: TypeAlias = Callable[[Sequence[str], str], Sequence[str]]
+MaxDistanceFunction: TypeAlias = Callable[[int], int]
+
+__version__ = "1.0.0"
+__author__ = "WhatIsMyRealName"
+__created_with__ = "Codex"
+__created_on__ = "2026-07-17"
+
+__all__ = ["SearchEngine"]
+
+_NORMALIZATION_TABLE = str.maketrans(
+    {
+        "à": "a",
+        "á": "a",
+        "â": "a",
+        "ä": "a",
+        "ã": "a",
+        "å": "a",
+        "æ": "ae",
+        "ç": "c",
+        "é": "e",
+        "è": "e",
+        "ê": "e",
+        "ë": "e",
+        "ì": "i",
+        "í": "i",
+        "î": "i",
+        "ï": "i",
+        "ñ": "n",
+        "ò": "o",
+        "ó": "o",
+        "ô": "o",
+        "ö": "o",
+        "õ": "o",
+        "œ": "oe",
+        "ù": "u",
+        "ú": "u",
+        "û": "u",
+        "ü": "u",
+        "ý": "y",
+        "ÿ": "y",
+        "-": " ",
+        "'": " ",
+    }
+)
+
+
+@lru_cache(maxsize=8192)
+def _normalize(text: str) -> str:
+    return text.lower().translate(_NORMALIZATION_TABLE) # ajouter la suppression de plusieurs espaces consécutifs, en début et fin de chaîne comme au début ? *(  )+* => * *
+
+
+def _default_max_distance(length: int) -> int:
+    return (length + 2) // 5
+
+
+@lru_cache(maxsize=8192)
+def _levenshtein_distance(first: str, second: str) -> int:
+    """Return the Levenshtein edit distance between two strings.
+
+    The distance is the minimum number of insertions, deletions and
+    substitutions required to transform one string into the other.
+    """
+    if len(first) < len(second):
+        first, second = second, first
+
+    previous_row = list(range(len(second) + 1))
+    for first_index, first_character in enumerate(first, start=1):
+        current_row = [first_index]
+        for second_index, second_character in enumerate(second, start=1):
+            insertion = current_row[second_index - 1] + 1
+            deletion = previous_row[second_index] + 1
+            substitution = previous_row[second_index - 1] + (
+                first_character != second_character
+            )
+            current_row.append(min(insertion, deletion, substitution))
+        previous_row = current_row
+
+    return previous_row[-1]
+
+
+def _candidate_variants(words: Sequence[str]) -> list[list[str]]:
+    variants = [list(words)]
+    for boundary in range(len(words) - 1):
+        before = list(words[:boundary])
+        after = list(words[boundary + 2 :])
+        for replacement in ("", "n", "b"):
+            merged = words[boundary] + replacement + words[boundary + 1]
+            variants.append([*before, merged, *after])
+    return variants
+
+
+def _word_match_score(
+    query_word: str,
+    candidate_word: str,
+    max_distance_function: MaxDistanceFunction,
+) -> tuple[int, Fraction] | None:
+    if query_word == candidate_word:
+        return 0, Fraction(0)
+
+    if len(query_word) < len(candidate_word):
+        candidate_prefix = candidate_word[: len(query_word)]
+        prefix_distance = _levenshtein_distance(query_word, candidate_prefix)
+        if prefix_distance == 0:
+            return 1, Fraction(0)
+        if prefix_distance <= max_distance_function(len(query_word)):
+            return 2, Fraction(prefix_distance, len(query_word) or 1)
+
+    reference_length = len(candidate_word)
+    maximum_distance = max_distance_function(reference_length)
+    if abs(len(query_word) - reference_length) > maximum_distance:
+        return None
+
+    distance = _levenshtein_distance(query_word, candidate_word)
+    if distance > maximum_distance:
+        return None
+
+    normalization_length = max(len(query_word), reference_length)
+    return 3, Fraction(distance, normalization_length or 1)
+
+
+def _score_variant(
+    query_words: Sequence[str],
+    candidate_words: Sequence[str],
+    max_distance_function: MaxDistanceFunction,
+) -> tuple[int, int, Fraction, int]:
+    match_scores: list[list[tuple[int, Fraction] | None]] = []
+    for query_word in query_words:
+        row: list[tuple[int, Fraction] | None] = []
+        for candidate_word in candidate_words:
+            row.append(
+                _word_match_score(
+                    query_word, candidate_word, max_distance_function
+                )
+            )
+        match_scores.append(row)
+
+    @lru_cache(maxsize=None)
+    def find_best(
+        query_index: int, used_candidates: int
+    ) -> tuple[int, int, Fraction, int]:
+        if query_index == len(query_words):
+            return 0, 0, Fraction(0), 0
+
+        unmatched, match_priority, distance_sum, inversions = find_best(
+            query_index + 1, used_candidates
+        )
+        best = unmatched + 1, match_priority, distance_sum, inversions
+
+        for candidate_index, match_score in enumerate(match_scores[query_index]):
+            candidate_bit = 1 << candidate_index
+            if match_score is None or used_candidates & candidate_bit:
+                continue
+            priority, normalized_distance = match_score
+            child = find_best(query_index + 1, used_candidates | candidate_bit)
+            preceding_inversions = sum(
+                1
+                for previous_index in range(candidate_index + 1, len(candidate_words))
+                if used_candidates & (1 << previous_index)
+            )
+            score = (
+                child[0],
+                child[1] + priority,
+                child[2] + normalized_distance,
+                child[3] + preceding_inversions,
+            )
+            if score < best:
+                best = score
+
+        return best
+
+    return find_best(0, 0)
+
+
+def _fuzzy_search(
+    items: Sequence[str],
+    query: str,
+    max_distance_function: MaxDistanceFunction,
+) -> list[str]:
+    query_words = _normalize(query).split()
+    if not query_words:
+        return list(items)
+
+    ranked_items: list[tuple[tuple[int, int, Fraction, int, int], str]] = []
+    for original_index, item in enumerate(items):
+        candidate_words = _normalize(item).split()
+        if not candidate_words:
+            continue
+        best_score = min(
+            _score_variant(query_words, variant, max_distance_function)
+            for variant in _candidate_variants(candidate_words)
+        )
+        unmatched_words, match_priority, distance_sum, inversions = best_score
+        if unmatched_words == len(query_words):
+            continue
+        ranked_items.append(
+            (
+                (
+                    unmatched_words,
+                    match_priority,
+                    distance_sum,
+                    inversions,
+                    original_index,
+                ),
+                item,
+            )
+        )
+
+    ranked_items.sort(key=lambda ranked_item: ranked_item[0])
+    return [item for _score, item in ranked_items]
+
+
+class SearchEngine(tk.Frame):
+    """A search field with a button and a filtered suggestion list.
+
+    ``command`` is called with the current text and the selected suggestion
+    (or ``None``). It is invoked both by Return and by the search button.
+
+    Widget-specific Tk options can be passed through ``entry_options``,
+    ``button_options`` and ``listbox_options``. Remaining keyword arguments
+    are applied to the containing :class:`tk.Frame`.
+    """
+
+    def __init__(
+        self,
+        master: tk.Misc | None = None,
+        *,
+        items: Sequence[str] = (),
+        command: SearchCallback | None = None,
+        placeholder: str = "Search…",
+        button_text: str = "🔍",
+        search_function: SearchFunction | None = None,
+        max_distance_function: MaxDistanceFunction = _default_max_distance,
+        max_visible_results: int = 8,
+        placeholder_color: str = "grey",
+        text_color: str = "black",
+        entry_options: Mapping[str, Any] | None = None,
+        button_options: Mapping[str, Any] | None = None,
+        listbox_options: Mapping[str, Any] | None = None,
+        **frame_options: Any,
+    ) -> None:
+        super().__init__(master, **frame_options)
+
+        if max_visible_results < 1:
+            raise ValueError("max_visible_results must be greater than or equal to 1")
+        if search_function is not None and not callable(search_function):
+            raise TypeError("search_function must be callable or None")
+        if not callable(max_distance_function):
+            raise TypeError("max_distance_function must be callable")
+        if command is not None and not callable(command):
+            raise TypeError("command must be callable or None")
+
+        self._items = list(items)
+        self._command = command
+        self._placeholder = placeholder
+        self._search_function = search_function
+        self._max_distance_function = max_distance_function
+        self._max_visible_results = max_visible_results
+        self._placeholder_color = placeholder_color
+        self._text_color = text_color
+        self._showing_placeholder = False
+        self._filtered_items: list[str] = []
+        self._accepted_item: str | None = None
+
+        self.variable = tk.StringVar(self)
+
+        entry_config = dict(entry_options or {})
+        entry_config["textvariable"] = self.variable
+        self.entry = tk.Entry(self, **entry_config)
+
+        button_config = dict(button_options or {})
+        button_config.setdefault("text", button_text)
+        button_config["command"] = self.invoke
+        self.button = tk.Button(self, **button_config)
+
+        listbox_config = dict(listbox_options or {})
+        listbox_config.setdefault("exportselection", False)
+        listbox_config.setdefault("height", 1)
+        self.listbox = tk.Listbox(self, **listbox_config)
+
+        self.entry.grid(row=0, column=0, sticky="ew")
+        self.button.grid(row=0, column=1, sticky="ns")
+        self.columnconfigure(0, weight=1)
+
+        self.entry.bind("<FocusIn>", self._on_focus_in)
+        self.entry.bind("<FocusOut>", self._on_focus_out)
+        self.entry.bind("<KeyRelease>", self._on_key_release)
+        self.entry.bind("<Return>", self._on_submit)
+        self.entry.bind("<KP_Enter>", self._on_submit)
+        self.entry.bind("<Tab>", self._on_tab)
+        self.entry.bind("<Down>", self._on_down)
+        self.entry.bind("<Up>", self._on_up)
+        self.listbox.bind("<ButtonRelease-1>", self._on_listbox_click)
+        self.listbox.bind("<Return>", self._on_listbox_accept)
+
+        self._display_placeholder()
+
+    def get(self) -> str:
+        """Return the search text, excluding the visual placeholder."""
+        return "" if self._showing_placeholder else self.variable.get()
+
+    def set(self, text: str) -> None:
+        """Replace the search text and refresh suggestions when focused."""
+        self._accepted_item = None
+        self._showing_placeholder = False
+        self.entry.configure(fg=self._text_color)
+        self.variable.set(text)
+        if self.entry.focus_get() == self.entry:
+            self._refresh_results()
+        elif not text:
+            self._display_placeholder()
+
+    def set_items(self, items: Sequence[str]) -> None:
+        """Replace the searchable values."""
+        self._items = list(items)
+        if self.entry.focus_get() == self.entry:
+            self._refresh_results()
+
+    def invoke(self) -> None:
+        """Run the configured search callback."""
+        if self._command is not None:
+            self._command(self.get(), self.selected_item)
+
+    @property
+    def selected_item(self) -> str | None:
+        """Return the highlighted suggestion, if any."""
+        selection = self.listbox.curselection()
+        if not selection:
+            return self._accepted_item
+        index = selection[0]
+        if index >= len(self._filtered_items):
+            return None
+        return self._filtered_items[index]
+
+    def _display_placeholder(self) -> None:
+        if self.variable.get() or self.entry.focus_get() == self.entry:
+            return
+        self._showing_placeholder = True
+        self.entry.configure(fg=self._placeholder_color)
+        self.variable.set(self._placeholder)
+
+    def _hide_results(self) -> None:
+        self.listbox.grid_remove()
+
+    def _refresh_results(self) -> None:
+        query = self.get()
+        if self._search_function is None:
+            results = _fuzzy_search(
+                self._items, query, self._max_distance_function
+            )
+        else:
+            results = self._search_function(self._items, query)
+        self._filtered_items = list(results)
+
+        self.listbox.delete(0, tk.END)
+        for item in self._filtered_items:
+            self.listbox.insert(tk.END, item)
+
+        if not self._filtered_items:
+            self._hide_results()
+            return
+
+        self.listbox.configure(
+            height=min(len(self._filtered_items), self._max_visible_results)
+        )
+        self.listbox.grid(row=1, column=0, columnspan=2, sticky="ew")
+
+    def _on_focus_in(self, _event: tk.Event[tk.Misc]) -> None:
+        if self._showing_placeholder:
+            self.variable.set("")
+            self._showing_placeholder = False
+            self.entry.configure(fg=self._text_color)
+        self._refresh_results()
+
+    def _on_focus_out(self, _event: tk.Event[tk.Misc]) -> None:
+        self.after_idle(self._finish_focus_out)
+
+    def _finish_focus_out(self) -> None:
+        focused = self.focus_get()
+        if focused == self.listbox:
+            return
+        self._hide_results()
+        self._display_placeholder()
+
+    def _on_key_release(self, event: tk.Event[tk.Misc]) -> None:
+        if event.keysym not in {"Up", "Down", "Tab", "Return", "KP_Enter"}:
+            self._accepted_item = None
+            self._refresh_results()
+
+    def _on_submit(self, _event: tk.Event[tk.Misc]) -> str:
+        self.invoke()
+        return "break"
+
+    def _on_tab(self, _event: tk.Event[tk.Misc]) -> str | None:
+        if not self._filtered_items:
+            return None
+        selection = self.listbox.curselection()
+        self._accept_index(selection[0] if selection else 0)
+        return "break"
+
+    def _move_selection(self, step: int) -> str:
+        if not self._filtered_items:
+            return "break"
+        selection = self.listbox.curselection()
+        current = selection[0] if selection else (-1 if step > 0 else 0)
+        target = (current + step) % len(self._filtered_items)
+        self.listbox.selection_clear(0, tk.END)
+        self.listbox.selection_set(target)
+        self.listbox.activate(target)
+        self.listbox.see(target)
+        return "break"
+
+    def _on_down(self, _event: tk.Event[tk.Misc]) -> str:
+        return self._move_selection(1)
+
+    def _on_up(self, _event: tk.Event[tk.Misc]) -> str:
+        return self._move_selection(-1)
+
+    def _accept_index(self, index: int) -> None:
+        accepted_item = self._filtered_items[index]
+        self.set(accepted_item)
+        self._accepted_item = accepted_item
+        self.entry.icursor(tk.END)
+        self.entry.focus_set()
+        self._hide_results()
+
+    def _on_listbox_click(self, _event: tk.Event[tk.Misc]) -> None:
+        selection = self.listbox.curselection()
+        if selection:
+            self._accept_index(selection[0])
+
+    def _on_listbox_accept(self, _event: tk.Event[tk.Misc]) -> str:
+        selection = self.listbox.curselection()
+        if selection:
+            self._accept_index(selection[0])
+        return "break"

tksearchengine-1.0.0/src/tksearchengine.egg-info/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: tksearchengine
+Version: 1.0.0
+Summary: A reusable Tkinter search widget with fuzzy multi-word matching
+Author: WhatIsMyRealName
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: X11 Applications
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# tksearchengine
+
+`tksearchengine` provides a reusable Tkinter search field with fuzzy,
+multi-word suggestions. It combines an entry, a search button, and a listbox
+in a single configurable widget.
+
+## Features
+
+- Placeholder text while the empty entry is not focused.
+- Live suggestions while the entry is focused.
+- Mouse selection and keyboard navigation with Up and Down.
+- Tab accepts the highlighted suggestion, or the first suggestion by default.
+- Return and the search button invoke the same callback.
+- Case-insensitive, accent-insensitive, multi-word fuzzy matching.
+- `-` and `'` are treated as word separators.
+- Missing spaces and spaces accidentally replaced by `n` or `b` are handled.
+- Exact words, exact prefixes, approximate prefixes, and approximate complete
+  words are ranked in that order.
+- No third-party runtime dependencies.
+
+## Requirements
+
+- Python 3.10 or newer.
+- Tkinter, which is included with many Python installations but may require a
+  separate operating-system package on Linux. For example, Debian and Ubuntu provide it in the `python3-tk` package.
+
+## Installation
+
+From PyPI:
+
+```console
+python -m pip install tksearchengine
+```
+
+From the project directory:
+
+```console
+python -m pip install .
+```
+
+For editable development:
+
+```console
+python -m pip install -e .
+```
+
+## Basic usage
+
+```python
+import tkinter as tk
+
+from tksearchengine import SearchEngine
+
+
+def run_search(text: str, selected_item: str | None) -> None:
+    print("Search text:", text)
+    print("Selected suggestion:", selected_item)
+
+
+root = tk.Tk()
+
+search = SearchEngine(
+    root,
+    items=["Paris", "Marseille", "Lyon", "Orléans"],
+    command=run_search,
+    placeholder="Search for a city",
+    max_visible_results=6,
+)
+search.pack(fill="x", padx=20, pady=20)
+
+root.mainloop()
+```
+
+## Configuration
+
+The constructor accepts:
+
+- `items`: searchable strings.
+- `command`: callback receiving the current text and the selected suggestion. The second argument is `None` when the user submits free text without accepting a suggestion.
+- `placeholder`: text displayed when the unfocused entry is empty.
+- `button_text`: label or symbol displayed on the search button.
+- `search_function`: optional replacement for the complete ranking function.
+- `max_distance_function`: optional function returning the accepted edit
+  distance for a given reference-word length.
+- `max_visible_results`: maximum visible listbox rows.
+- `placeholder_color` and `text_color`: entry text colors.
+- `entry_options`, `button_options`, and `listbox_options`: mappings forwarded
+  to the corresponding Tkinter widgets.
+- Any remaining keyword arguments are forwarded to the containing `tk.Frame`.
+
+Here is the `__init__` shape:
+```python
+    def __init__(
+        self,
+        master: tk.Misc | None = None,
+        *,
+        items: Sequence[str] = (),
+        command: SearchCallback | None = None,
+        placeholder: str = "Search…",
+        button_text: str = "🔍",
+        search_function: SearchFunction | None = None,
+        max_distance_function: MaxDistanceFunction = _default_max_distance,
+        max_visible_results: int = 8,
+        placeholder_color: str = "grey",
+        text_color: str = "black",
+        entry_options: Mapping[str, Any] | None = None,
+        button_options: Mapping[str, Any] | None = None,
+        listbox_options: Mapping[str, Any] | None = None,
+        **frame_options: Any,
+    ) -> None:
+```
+
+Example with widget customization:
+
+```python
+search = SearchEngine(
+    root,
+    items=["Paris", "Marseille", "Lyon", "Orléans"],
+    entry_options={
+        "width": 32,
+        "font": ("Segoe UI", 11),
+        "relief": "solid",
+    },
+    button_options={
+        "text": "Search",
+        "font": ("Segoe UI", 10, "bold"),
+        "padx": 12,
+    },
+    listbox_options={
+        "font": ("Segoe UI", 10),
+        "height": 6,
+        "activestyle": "dotbox",
+    },
+)
+```
+
+These mappings are passed directly to `tk.Entry`, `tk.Button`, and `tk.Listbox`.
+`SearchEngine` still owns the entry text variable, the button command, the
+listbox selection behavior, and the visible result count.
+
+A custom search function has this shape:
+
+```python
+from collections.abc import Sequence
+
+
+def custom_search(items: Sequence[str], query: str) -> Sequence[str]:
+    normalized_query = query.lower()
+    return [item for item in items if normalized_query in item.lower()]
+```
+
+Pass it with `search_function=custom_search`. When a custom search function is
+provided, it is responsible for filtering and ordering all results.
+
+## Public methods
+
+- `get()` returns the current search text without the placeholder.
+- `set(text)` replaces the current search text.
+- `set_items(items)` replaces the searchable collection.
+- `invoke()` runs the configured callback.
+- `selected_item` returns the highlighted or accepted suggestion, if any.
+
+## Matching behavior
+
+The default matcher normalizes text to lowercase, replaces common accented
+letters with their unaccented forms, and treats `-` and `'` as spaces. Results are
+ranked by:
+
+1. number of unmatched query words;
+2. match type, from exact word to approximate complete word;
+3. normalized Levenshtein distance;
+4. query-word order;
+5. original item order.
+
+The default maximum edit distance is `(word_length + 2) // 5`. Override
+`max_distance_function(word_length)` when an application needs stricter or more permissive
+matching.
+
+## Running the example
+
+The example contains 1,000 French commune names:
+
+```console
+python examples/communes.py
+```
+Filtering the 1,000 sample names should feel immediate on a typical desktop Python installation.
+
+## Running the tests
+
+After an editable installation:
+
+```console
+python -m unittest discover -s tests -v
+```

tksearchengine-1.0.0/src/tksearchengine.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+src/tksearchengine/__init__.py
+src/tksearchengine/search_engine.py
+src/tksearchengine.egg-info/PKG-INFO
+src/tksearchengine.egg-info/SOURCES.txt
+src/tksearchengine.egg-info/dependency_links.txt
+src/tksearchengine.egg-info/top_level.txt
+tests/test_search_engine.py

tksearchengine-1.0.0/src/tksearchengine.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tksearchengine-1.0.0/src/tksearchengine.egg-info/top_level.txt

@@ -0,0 +1 @@
+tksearchengine

tksearchengine-1.0.0/tests/test_search_engine.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+import sys
+import types
+import unittest
+from collections.abc import Sequence
+
+try:
+    import tkinter  # noqa: F401
+except ModuleNotFoundError:
+    tkinter_stub = types.ModuleType("tkinter")
+    tkinter_stub.Frame = object
+    tkinter_stub.END = "end"
+    sys.modules["tkinter"] = tkinter_stub
+
+import tksearchengine
+from tksearchengine import SearchEngine, search_engine
+
+
+class LevenshteinTests(unittest.TestCase):
+    def test_common_distances_and_symmetry(self) -> None:
+        cases = {
+            ("", ""): 0,
+            ("", "abc"): 3,
+            ("chat", "chat"): 0,
+            ("chat", "chats"): 1,
+            ("kitten", "sitting"): 3,
+        }
+        for (first, second), expected in cases.items():
+            with self.subTest(first=first, second=second):
+                self.assertEqual(
+                    search_engine._levenshtein_distance(first, second), expected
+                )
+                self.assertEqual(
+                    search_engine._levenshtein_distance(second, first), expected
+                )
+
+    def test_default_threshold_boundaries(self) -> None:
+        expected = {2: 0, 3: 1, 7: 1, 8: 2, 10: 2, 12: 2, 13: 3}
+        self.assertEqual(
+            {length: search_engine._default_max_distance(length) for length in expected},
+            expected,
+        )
+
+
+class FuzzySearchTests(unittest.TestCase):
+    def search(self, items: list[str], query: str) -> list[str]:
+        return search_engine._fuzzy_search(
+            items, query, search_engine._default_max_distance
+        )
+
+    def test_empty_query_preserves_every_item(self) -> None:
+        items = ["Premier", "", "Troisième"]
+        self.assertEqual(self.search(items, "   "), items)
+
+    def test_case_and_accents_are_ignored(self) -> None:
+        self.assertEqual(self.search(["École élémentaire"], "ecole ELEMENTAIRE"), [
+            "École élémentaire"
+        ])
+
+    def test_hyphens_are_treated_as_spaces(self) -> None:
+        self.assertEqual(
+            self.search(["Saint-Étienne"], "saint etienne"),
+            ["Saint-Étienne"],
+        )
+
+    def test_incomplete_word_matches_an_exact_prefix(self) -> None:
+        self.assertEqual(self.search(["Orléans", "Paris"], "orl"), ["Orléans"])
+
+    def test_one_letter_matches_only_exact_prefixes(self) -> None:
+        self.assertEqual(
+            self.search(["Orléans", "Orange", "Paris"], "o"),
+            ["Orléans", "Orange"],
+        )
+
+    def test_approximate_prefix_is_supported(self) -> None:
+        self.assertEqual(self.search(["Orléans"], "orx"), ["Orléans"])
+
+    def test_exact_word_precedes_exact_prefix(self) -> None:
+        self.assertEqual(
+            self.search(["Orléans", "Or"], "or"),
+            ["Or", "Orléans"],
+        )
+
+    def test_more_matched_keywords_have_priority(self) -> None:
+        items = ["alpha", "alphi beto"]
+        self.assertEqual(self.search(items, "alpha beta"), ["alphi beto", "alpha"])
+
+    def test_distance_then_word_order_then_original_order_break_ties(self) -> None:
+        items = ["beta alpha", "alpha beta", "alpha beta"]
+        self.assertEqual(
+            self.search(items, "alpha beta"),
+            ["alpha beta", "alpha beta", "beta alpha"],
+        )
+
+    def test_one_candidate_word_cannot_match_two_keywords(self) -> None:
+        items = ["chat", "chat shat"]
+        self.assertEqual(self.search(items, "chat chat"), ["chat shat", "chat"])
+
+    def test_missing_or_replaced_space_is_recognized(self) -> None:
+        items = ["Jean Dupont"]
+        for query in ("Jean Dupont", "JeanDupont", "JeannDupont", "JeanbDupont"):
+            with self.subTest(query=query):
+                self.assertEqual(self.search(items, query), items)
+
+    def test_only_one_boundary_is_repaired(self) -> None:
+        self.assertEqual(
+            self.search(["un deux trois"], "unbdeuxbtrois"),
+            [],
+        )
+
+    def test_items_without_a_match_are_excluded(self) -> None:
+        self.assertEqual(self.search(["Paris", "Londres"], "zzzz"), [])
+
+    def test_custom_threshold_is_used(self) -> None:
+        strict = lambda _length: 0
+        self.assertEqual(search_engine._fuzzy_search(["chat"], "chut", strict), [])
+
+
+class _ListboxStub:
+    def delete(self, _first: object, _last: object) -> None:
+        pass
+
+    def insert(self, _index: object, _item: str) -> None:
+        pass
+
+    def configure(self, **_options: object) -> None:
+        pass
+
+    def grid(self, **_options: object) -> None:
+        pass
+
+    def grid_remove(self) -> None:
+        pass
+
+
+class WidgetFilteringTests(unittest.TestCase):
+    def test_each_search_receives_the_complete_item_list(self) -> None:
+        queries = iter(("a", "ab"))
+        received_items: list[list[str]] = []
+
+        def search(items: Sequence[str], query: str) -> list[str]:
+            received_items.append(list(items))
+            return [item for item in items if query in item]
+
+        widget = types.SimpleNamespace(
+            get=lambda: next(queries),
+            _items=["a", "ab", "b"],
+            _search_function=search,
+            _max_distance_function=search_engine._default_max_distance,
+            _filtered_items=[],
+            _max_visible_results=8,
+            listbox=_ListboxStub(),
+            _hide_results=lambda: None,
+        )
+
+        SearchEngine._refresh_results(widget)
+        SearchEngine._refresh_results(widget)
+
+        self.assertEqual(received_items, [["a", "ab", "b"], ["a", "ab", "b"]])
+
+    def test_only_search_engine_is_exported(self) -> None:
+        self.assertIs(tksearchengine.SearchEngine, SearchEngine)
+        self.assertEqual(tksearchengine.__all__, ["SearchEngine"])
+        self.assertEqual(search_engine.__all__, ["SearchEngine"])
+
+
+if __name__ == "__main__":
+    unittest.main()