python-lucide 0.4.0__tar.gz → 0.5.0__tar.gz

{python_lucide-0.4.0 → python_lucide-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: python-lucide
-Version: 0.4.0
+Version: 0.5.0
 Summary: A Python package for working with Lucide icons
 Keywords: lucide,icons,svg,sqlite
 Author: Mike Macpherson
@@ -15,6 +15,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: cairosvg>=2.7.0 ; extra == 'search'
 Requires-Dist: fastembed>=0.4.0 ; extra == 'search'
 Requires-Python: >=3.10
 Project-URL: Bug Tracker, https://github.com/mmacpherson/python-lucide/issues
@@ -43,6 +44,7 @@ in your Python projects, with no javascript in sight.
 
 ## Features
 - 🎨 **Access 1600+ Lucide icons** directly from Python
+- 🔍 **Semantic search** - find icons by meaning, in the terminal or [in the browser](https://mmacpherson.github.io/python-lucide/)
 - 🛠 **Customize icons** with classes, sizes, colors, and other SVG attributes
 - 🚀 **Framework-friendly** with examples for FastHTML, Flask, Django, and more
 - 📦 **Lightweight** with minimal dependencies
@@ -83,6 +85,60 @@ lucide_icon("user", fill="currentColor")  # Inherit color from CSS
 lucide_icon("user", stroke="#ff6b6b")     # Hex colors work too
 ```
 
+## Semantic Search
+
+Find icons by describing what you mean, not what they're called — in English
+or [50+ languages](https://mmacpherson.github.io/python-lucide/):
+
+<p align="center">
+  <a href="https://mmacpherson.github.io/python-lucide/">
+    <img src="https://raw.githubusercontent.com/mmacpherson/python-lucide/main/.github/images/search-english.png" width="49%" alt="Searching &quot;celebrate a big achievement&quot; returns trophy, award, medal, party-popper">
+    <img src="https://raw.githubusercontent.com/mmacpherson/python-lucide/main/.github/images/search-multilingual.png" width="49%" alt="Searching in Japanese with the multilingual model returns key, user-key, lock icons">
+  </a>
+</p>
+
+```bash
+# One-off, no install (requires uv)
+uvx --from "python-lucide[search]" lucide search "waiting for a download"
+
+# Or install the search extra
+pip install "python-lucide[search]"
+lucide search "celebrate a big achievement"
+```
+
+<img src="https://raw.githubusercontent.com/mmacpherson/python-lucide/main/.github/images/search-cli.png" width="360" alt="Terminal output of lucide search: each result icon renders inline next to its name and match score">
+
+In terminals supporting the Kitty graphics protocol (kitty, Ghostty,
+WezTerm), the icons render inline as above — inside tmux too, with
+`tmux set -g allow-passthrough on`. Elsewhere you get the plain text
+list. (Rendering uses the cairo system library; if it's missing, the
+CLI prints a hint.)
+
+Icons are matched against AI-generated descriptions using the same embedding
+model the [web app](https://mmacpherson.github.io/python-lucide/) uses,
+so descriptive phrases ("an idea just occurred to me") work better than
+keywords. Options:
+
+- `--model multilingual` — search in 50+ languages (default `bge-small` ranks
+  best for English)
+- `--limit N` — number of results; `--verbose` — include each icon's description
+
+The first search downloads the embedding model (~67 MB) and the pre-built
+search index (11 MB); both are cached, and every search after that runs
+locally in well under a second.
+
+The same search is available as a Python API:
+
+```python
+from lucide.search import search_icons
+
+for r in search_icons("secure login", limit=5):
+    print(r.name, r.score)
+```
+
+Prefer not to install anything? The [browser version](https://mmacpherson.github.io/python-lucide/)
+runs the whole pipeline client-side.
+
 ## Framework Integration Examples
 
 ### Starlette

{python_lucide-0.4.0 → python_lucide-0.5.0}/README.md

@@ -18,6 +18,7 @@ in your Python projects, with no javascript in sight.
 
 ## Features
 - 🎨 **Access 1600+ Lucide icons** directly from Python
+- 🔍 **Semantic search** - find icons by meaning, in the terminal or [in the browser](https://mmacpherson.github.io/python-lucide/)
 - 🛠 **Customize icons** with classes, sizes, colors, and other SVG attributes
 - 🚀 **Framework-friendly** with examples for FastHTML, Flask, Django, and more
 - 📦 **Lightweight** with minimal dependencies
@@ -58,6 +59,60 @@ lucide_icon("user", fill="currentColor")  # Inherit color from CSS
 lucide_icon("user", stroke="#ff6b6b")     # Hex colors work too
 ```
 
+## Semantic Search
+
+Find icons by describing what you mean, not what they're called — in English
+or [50+ languages](https://mmacpherson.github.io/python-lucide/):
+
+<p align="center">
+  <a href="https://mmacpherson.github.io/python-lucide/">
+    <img src="https://raw.githubusercontent.com/mmacpherson/python-lucide/main/.github/images/search-english.png" width="49%" alt="Searching &quot;celebrate a big achievement&quot; returns trophy, award, medal, party-popper">
+    <img src="https://raw.githubusercontent.com/mmacpherson/python-lucide/main/.github/images/search-multilingual.png" width="49%" alt="Searching in Japanese with the multilingual model returns key, user-key, lock icons">
+  </a>
+</p>
+
+```bash
+# One-off, no install (requires uv)
+uvx --from "python-lucide[search]" lucide search "waiting for a download"
+
+# Or install the search extra
+pip install "python-lucide[search]"
+lucide search "celebrate a big achievement"
+```
+
+<img src="https://raw.githubusercontent.com/mmacpherson/python-lucide/main/.github/images/search-cli.png" width="360" alt="Terminal output of lucide search: each result icon renders inline next to its name and match score">
+
+In terminals supporting the Kitty graphics protocol (kitty, Ghostty,
+WezTerm), the icons render inline as above — inside tmux too, with
+`tmux set -g allow-passthrough on`. Elsewhere you get the plain text
+list. (Rendering uses the cairo system library; if it's missing, the
+CLI prints a hint.)
+
+Icons are matched against AI-generated descriptions using the same embedding
+model the [web app](https://mmacpherson.github.io/python-lucide/) uses,
+so descriptive phrases ("an idea just occurred to me") work better than
+keywords. Options:
+
+- `--model multilingual` — search in 50+ languages (default `bge-small` ranks
+  best for English)
+- `--limit N` — number of results; `--verbose` — include each icon's description
+
+The first search downloads the embedding model (~67 MB) and the pre-built
+search index (11 MB); both are cached, and every search after that runs
+locally in well under a second.
+
+The same search is available as a Python API:
+
+```python
+from lucide.search import search_icons
+
+for r in search_icons("secure login", limit=5):
+    print(r.name, r.score)
+```
+
+Prefer not to install anything? The [browser version](https://mmacpherson.github.io/python-lucide/)
+runs the whole pipeline client-side.
+
 ## Framework Integration Examples
 
 ### Starlette

{python_lucide-0.4.0 → python_lucide-0.5.0}/pyproject.toml

@@ -41,10 +41,10 @@ license = {text = "MIT"}
 name = "python-lucide"
 readme = "README.md"
 requires-python = ">=3.10"
-version = "0.4.0"
+version = "0.5.0"
 
 [project.optional-dependencies]
-search = ["fastembed>=0.4.0"]
+search = ["cairosvg>=2.7.0", "fastembed>=0.4.0"]
 
 [project.scripts]
 check-lucide-version = "lucide.dev_utils:print_version_status"

{python_lucide-0.4.0 → python_lucide-0.5.0}/src/lucide/cli.py

@@ -529,6 +529,40 @@ def _cmd_build_search(args: argparse.Namespace) -> int:
     return 0
 
 
+def _first_run_downloads(model: str) -> list[str]:
+    """Human-readable one-time downloads the next search will trigger.
+
+    Best-effort: peeks at fastembed's model cache and the search-DB cache;
+    any surprise in their layout just means the notice is skipped.
+    """
+    from .search import search_available  # noqa: PLC0415
+
+    pending = []
+    try:
+        from fastembed import TextEmbedding  # noqa: PLC0415
+        from fastembed.common.utils import define_cache_dir  # noqa: PLC0415
+
+        fastembed_name = EMBEDDING_MODELS[model].fastembed_model
+        meta = next(
+            m
+            for m in TextEmbedding.list_supported_models()
+            if m["model"] == fastembed_name
+        )
+        hf_repo = (meta.get("sources") or {}).get("hf") or ""
+        size_mb = round(meta["size_in_GB"] * 1000)
+        model_dir = (
+            pathlib.Path(define_cache_dir(None))
+            / f"models--{hf_repo.replace('/', '--')}"
+        )
+        if hf_repo and not model_dir.exists():
+            pending.append(f"embedding model (~{size_mb} MB)")
+    except Exception:
+        pass
+    if not search_available():
+        pending.append("search index (11 MB)")
+    return pending
+
+
 def _cmd_search(args: argparse.Namespace) -> int:
     """Handle ``lucide search``."""
     import os  # noqa: PLC0415
@@ -549,6 +583,19 @@ def _cmd_search(args: argparse.Namespace) -> int:
             if candidate.exists():
                 os.environ["LUCIDE_SEARCH_DB_PATH"] = str(candidate)
 
+    # Downloading without a token is expected here; the hf_xet download
+    # backend's HF_TOKEN nudge reads like an error mid-download, so keep
+    # warnings from its logger out of the way
+    logging.getLogger("hf_xet").setLevel(logging.ERROR)
+
+    pending = _first_run_downloads(args.model)
+    if pending:
+        print(
+            f"First run: downloading {' and '.join(pending)} — "
+            "cached for future searches.",
+            file=sys.stderr,
+        )
+
     try:
         results = search_icons(args.query, limit=args.limit, model=args.model)
     except Exception as e:
@@ -559,7 +606,9 @@ def _cmd_search(args: argparse.Namespace) -> int:
         print("No results found.")
         return 0
 
-    show_icons = _terminal_supports_graphics()
+    show_icons, graphics_tip = _graphics_support()
+    if graphics_tip:
+        print(graphics_tip, file=sys.stderr)
     svgs: dict[str, str] = {}
     if show_icons:
         svgs = _load_svgs_for_results([r.name for r in results])
@@ -570,36 +619,77 @@ def _cmd_search(args: argparse.Namespace) -> int:
     cyan = "\033[38;2;100;200;220m"
 
     for r in results:
-        if show_icons and r.name in svgs:
-            _display_kitty_image(svgs[r.name])
-        print(f"  {bold}{cyan}{r.name}{reset}  {dim}{r.score:.3f}{reset}")
+        prefix = "  "
+        if show_icons:
+            drawn = r.name in svgs and _display_kitty_image(svgs[r.name])
+            # The image sits in columns 1-2 (cursor untouched, C=1), so
+            # step over it to keep names aligned whether or not it drew
+            prefix = "\033[3C" if drawn else "   "
+        print(f"{prefix}{bold}{cyan}{r.name}{reset}  {dim}{r.score:.0%}{reset}")
         if args.verbose and r.description:
             print(f"    {dim}{r.description[:100]}{reset}")
-        if show_icons:
-            print()
 
     return 0
 
 
-def _terminal_supports_graphics() -> bool:
-    """Check if the terminal supports the Kitty graphics protocol.
+def _graphics_support() -> tuple[bool, str | None]:
+    """Decide whether to render inline icons via the Kitty graphics protocol.
 
-    Note: tmux passthrough (allow-passthrough on) theoretically supports
-    Kitty graphics, but cursor positioning is unreliable. Disabled for
-    now — see python-lucide-TODO (beads).
+    Returns:
+        A ``(show_icons, tip)`` pair. *tip* is a one-line stderr hint for
+        the cases where the terminal could show icons but something the
+        user can fix is in the way (tmux passthrough off, cairosvg not
+        installed) — silently dropping the feature proved confusing.
     """
     import os  # noqa: PLC0415
 
-    # tmux blocks reliable graphics rendering
-    if os.environ.get("TMUX") or "screen" in os.environ.get("TERM", ""):
-        return False
-
     term = os.environ.get("TERM_PROGRAM", "")
-    if term in ("ghostty", "kitty", "WezTerm"):
-        return True
-    if os.environ.get("GHOSTTY_RESOURCES_DIR"):
-        return True
-    return "kitty" in os.environ.get("TERM", "")
+    host_capable = (
+        term in ("ghostty", "kitty", "WezTerm")
+        or bool(os.environ.get("GHOSTTY_RESOURCES_DIR"))
+        or bool(os.environ.get("KITTY_WINDOW_ID"))
+        or "kitty" in os.environ.get("TERM", "")
+    )
+    if not host_capable:
+        return False, None
+
+    if os.environ.get("TMUX") and not _tmux_allows_passthrough():
+        return False, (
+            "Tip: your terminal can show icons inline, but tmux blocks "
+            "them — run: tmux set -g allow-passthrough on"
+        )
+
+    try:
+        import cairosvg  # noqa: F401, PLC0415
+    except ImportError:
+        return False, (
+            "Tip: your terminal can show icons inline — install cairosvg "
+            "to enable (pip install cairosvg, or uvx --with cairosvg)."
+        )
+    except OSError:
+        # cairosvg is installed but the native cairo library is absent;
+        # cairocffi raises OSError (not ImportError) from its dlopen
+        return False, (
+            "Tip: inline icons need the cairo system library "
+            "(e.g. apt install libcairo2, or brew install cairo)."
+        )
+
+    return True, None
+
+
+def _tmux_allows_passthrough() -> bool:
+    """Check whether the current tmux pane permits escape passthrough."""
+    try:
+        proc = subprocess.run(
+            ["tmux", "show", "-Apv", "allow-passthrough"],
+            capture_output=True,
+            text=True,
+            timeout=2,
+            check=False,
+        )
+    except Exception:
+        return False
+    return proc.stdout.strip() in ("on", "all")
 
 
 def _load_svgs_for_results(names: list[str]) -> dict[str, str]:
@@ -619,30 +709,45 @@ def _load_svgs_for_results(names: list[str]) -> dict[str, str]:
     return svgs
 
 
-def _display_kitty_image(svg_content: str) -> None:
-    """Render an SVG and display it inline via the Kitty graphics protocol."""
+def _display_kitty_image(svg_content: str) -> bool:
+    """Render an SVG as a one-row inline image at the cursor position.
+
+    Emits with ``C=1`` so the cursor stays put and the caller controls
+    layout with ordinary cursor movement — which is also what makes tmux
+    passthrough safe: tmux never sees the image escape, and everything
+    that *does* move the cursor goes through tmux normally.
+
+    Returns:
+        True if an image escape was written.
+    """
     import base64  # noqa: PLC0415
-    import sys  # noqa: PLC0415
+    import os  # noqa: PLC0415
 
     try:
         import cairosvg  # noqa: PLC0415
-    except ImportError:
-        return
+    except (ImportError, OSError):
+        return False
 
     try:
         # Insert a white background rect so icons show on any terminal bg
         bg_rect = '<rect width="100%" height="100%" fill="white" rx="3"/>'
         padded_svg = svg_content.replace(">", f">{bg_rect}", 1)
+        # Rendered larger than displayed; the terminal downscales, which
+        # keeps strokes crisp on hidpi displays
         png_data: bytes = cairosvg.svg2png(
             bytestring=padded_svg.encode("utf-8"),
-            output_width=48,
-            output_height=48,
+            output_width=96,
+            output_height=96,
         )
         b64 = base64.b64encode(png_data).decode("ascii")
-        sys.stdout.write(f"\033_Gf=100,t=d,a=T,r=2,c=4,q=2;{b64}\033\\\n")
+        seq = f"\033_Gf=100,t=d,a=T,r=1,c=2,C=1,q=2;{b64}\033\\"
+        if os.environ.get("TMUX"):
+            seq = "\033Ptmux;" + seq.replace("\033", "\033\033") + "\033\\"
+        sys.stdout.write(seq)
         sys.stdout.flush()
     except Exception:
-        pass
+        return False
+    return True
 
 
 def _cmd_cluster(args: argparse.Namespace) -> int:

{python_lucide-0.4.0 → python_lucide-0.5.0}/src/lucide/config.py

@@ -35,8 +35,10 @@ class EmbeddingModelConfig:
         pooling: transformers.js pooling mode ("mean" or "cls").
         web_dtype: transformers.js quantization. Document vectors always
             come from fastembed (fp32), so a quantized browser model only
-            perturbs the query vector — q8 stays ~0.994 cosine to fp32,
-            which is ranking-equivalent, and roughly quarters the download.
+            perturbs the query vector — q8 stays ~0.985-0.996 cosine to
+            fp32 across our models, which is ranking-equivalent (top-1
+            changes are swaps between near-tied results), and roughly
+            quarters the download.
         query_prefix: Prefix prepended to queries (asymmetric retrieval).
         document_prefix: Prefix prepended to documents at build time.
         label: Human-facing label for the web UI model toggle.
@@ -53,23 +55,20 @@ class EmbeddingModelConfig:
     label: str = ""
 
 
+# Two models, not three: at q8 bge-small is 33 MB, close enough to
+# all-MiniLM's 22 MB that a separate "Faster" tier bought nothing —
+# evaluated against bge-base and arctic-embed-m (both ~104 MB q8) too,
+# and neither beat bge-small on this corpus.
 EMBEDDING_MODELS: dict[str, EmbeddingModelConfig] = {
-    "minilm": EmbeddingModelConfig(
-        id="minilm",
-        fastembed_model="sentence-transformers/all-MiniLM-L6-v2",
-        web_model="Xenova/all-MiniLM-L6-v2",
-        dim=384,
-        pooling="mean",
-        label="Faster",
-    ),
     "bge-small": EmbeddingModelConfig(
         id="bge-small",
         fastembed_model="BAAI/bge-small-en-v1.5",
         web_model="Xenova/bge-small-en-v1.5",
         dim=384,
         pooling="cls",
+        web_dtype="q8",
         query_prefix="Represent this sentence for searching relevant passages: ",
-        label="Better",
+        label="English",
     ),
     "multilingual": EmbeddingModelConfig(
         id="multilingual",

{python_lucide-0.4.0 → python_lucide-0.5.0}/src/lucide/search.py

@@ -280,7 +280,7 @@ def search_icons(
     """Search for icons by natural language query.
 
     On the first call the search database is downloaded and cached in
-    ``~/.cache/python-lucide/``.  The embedding model (~35-130 MB depending
+    ``~/.cache/python-lucide/``.  The embedding model (~67-220 MB depending
     on *model*) is also downloaded once by *fastembed*.
 
     Args:

{python_lucide-0.4.0 → python_lucide-0.5.0}/tests/cli_test.py

@@ -223,3 +223,108 @@ class TestMainSubcommands:
         ):
             result = cli.main()
         assert result == 1
+
+
+class TestInlineIcons:
+    GRAPHICS_ENV_VARS = (
+        "TERM_PROGRAM",
+        "GHOSTTY_RESOURCES_DIR",
+        "KITTY_WINDOW_ID",
+        "TERM",
+        "TMUX",
+    )
+
+    @pytest.fixture(autouse=True)
+    def clean_env(self, monkeypatch):
+        for var in self.GRAPHICS_ENV_VARS:
+            monkeypatch.delenv(var, raising=False)
+
+    def test_plain_terminal_no_icons_no_tip(self, monkeypatch):
+        monkeypatch.setenv("TERM", "xterm-256color")
+        show, tip = cli._graphics_support()
+        assert show is False
+        assert tip is None
+
+    def test_ghostty_enables_icons(self, monkeypatch):
+        monkeypatch.setenv("GHOSTTY_RESOURCES_DIR", "/usr/share/ghostty")
+        show, tip = cli._graphics_support()
+        assert show is True
+        assert tip is None
+
+    def test_tmux_without_passthrough_tips_instead(self, monkeypatch):
+        monkeypatch.setenv("GHOSTTY_RESOURCES_DIR", "/usr/share/ghostty")
+        monkeypatch.setenv("TMUX", "/tmp/tmux-1000/default,1234,0")
+        with mock.patch.object(cli, "_tmux_allows_passthrough", return_value=False):
+            show, tip = cli._graphics_support()
+        assert show is False
+        assert "allow-passthrough" in tip
+
+    def test_tmux_with_passthrough_enables_icons(self, monkeypatch):
+        monkeypatch.setenv("GHOSTTY_RESOURCES_DIR", "/usr/share/ghostty")
+        monkeypatch.setenv("TMUX", "/tmp/tmux-1000/default,1234,0")
+        with mock.patch.object(cli, "_tmux_allows_passthrough", return_value=True):
+            show, tip = cli._graphics_support()
+        assert show is True
+        assert tip is None
+
+    def test_missing_cairosvg_tips_instead(self, monkeypatch):
+        monkeypatch.setenv("GHOSTTY_RESOURCES_DIR", "/usr/share/ghostty")
+        with mock.patch.dict("sys.modules", {"cairosvg": None}):
+            show, tip = cli._graphics_support()
+        assert show is False
+        assert "cairosvg" in tip
+
+    def test_tmux_passthrough_query_handles_missing_tmux(self):
+        with mock.patch.object(cli.subprocess, "run", side_effect=FileNotFoundError):
+            assert cli._tmux_allows_passthrough() is False
+
+    SVG = (
+        '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">'
+        '<circle cx="12" cy="12" r="9" stroke="black" fill="none"/></svg>'
+    )
+
+    def test_image_escape_bare(self, capfd):
+        pytest.importorskip("cairosvg")
+        assert cli._display_kitty_image(self.SVG) is True
+        out = capfd.readouterr().out
+        assert out.startswith("\033_G")
+        assert out.endswith("\033\\")
+        assert "C=1" in out and "r=1,c=2" in out
+
+    def test_image_escape_tmux_passthrough(self, capfd, monkeypatch):
+        pytest.importorskip("cairosvg")
+        monkeypatch.setenv("TMUX", "/tmp/tmux-1000/default,1234,0")
+        assert cli._display_kitty_image(self.SVG) is True
+        out = capfd.readouterr().out
+        assert out.startswith("\033Ptmux;")
+        assert out.endswith("\033\\")
+        body = out[len("\033Ptmux;") : -2]
+        # Inside the passthrough envelope every ESC must be doubled
+        i = 0
+        while i < len(body):
+            if body[i] == "\033":
+                assert body[i + 1] == "\033"
+                i += 2
+            else:
+                i += 1
+
+    def test_missing_cairosvg_returns_false(self):
+        with mock.patch.dict("sys.modules", {"cairosvg": None}):
+            assert cli._display_kitty_image(self.SVG) is False
+
+    def test_broken_native_cairo_tips_system_library(self, monkeypatch):
+        import builtins  # noqa: PLC0415
+
+        monkeypatch.setenv("GHOSTTY_RESOURCES_DIR", "/usr/share/ghostty")
+        real_import = builtins.__import__
+
+        def fake_import(name, *args, **kwargs):
+            # cairocffi raises OSError from dlopen when libcairo is absent
+            if name == "cairosvg":
+                raise OSError("no library called 'cairo-2' was found")
+            return real_import(name, *args, **kwargs)
+
+        monkeypatch.setattr(builtins, "__import__", fake_import)
+        show, tip = cli._graphics_support()
+        assert show is False
+        assert "cairo system library" in tip