arda-mapper 2.0.2__tar.gz → 2.0.3__tar.gz

{arda_mapper-2.0.2 → arda_mapper-2.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: arda-mapper
-Version: 2.0.2
+Version: 2.0.3
 Summary: Antigen Receptor Domain Annotation — fast TCR/BCR FR/CDR region annotation
 Keywords: immunology,tcr,bcr,airr,igblast,mmseqs2,annotation
 Author-Email: Mikhail Shugay <mikhail.shugay@gmail.com>
@@ -37,6 +37,7 @@ Description-Content-Type: text/markdown
 <h1 align="center">arda — Antigen Receptor Domain Annotation</h1>
 
 <p align="center">
+  <a href="https://pypi.org/project/arda-mapper/"><img alt="PyPI" src="https://img.shields.io/pypi/v/arda-mapper"></a>
   <a href="https://github.com/antigenomics/arda/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/antigenomics/arda/actions/workflows/ci.yml/badge.svg"></a>
   <a href="https://docs.isalgo.dev/arda/"><img alt="docs" src="https://github.com/antigenomics/arda/actions/workflows/docs.yml/badge.svg"></a>
   <img alt="python" src="https://img.shields.io/badge/python-3.10%2B-blue">
@@ -69,6 +70,13 @@ IgBLAST is the gold standard but is slow to invoke per-batch and awkward to embe
 
 ## Install
 
+```bash
+pip install arda-mapper   # from PyPI (imports as `arda`); binary wheels ship the C++ extension
+```
+
+`mmseqs2` (the search backend) is fetched/managed by arda at runtime. For development — and to
+get the committed germline references on disk — use `setup.sh`:
+
 ```bash
 bash setup.sh            # creates conda env `arda`, fetches IgBLAST, pip install -e .
 conda activate arda
@@ -76,7 +84,8 @@ conda activate arda
 
 Flags: `--no-conda` (use the active env), `--build-db` (rebuild references after
 install), `--tests` (run the fast suites). The committed `database/vdj/<organism>/`
-references mean **most users never need to build anything**.
+references mean **most users never need to build anything**; a `pip`-only install builds them
+on first use (or set `$ARDA_HOME` to a checkout).
 
 Supported organisms: **human, mouse** (full IG + TR), **rat, rabbit, rhesus_monkey**
 (IG only — IgBLAST ships no TR internal annotation for these).

{arda_mapper-2.0.2 → arda_mapper-2.0.3}/README.md

@@ -8,6 +8,7 @@
 <h1 align="center">arda — Antigen Receptor Domain Annotation</h1>
 
 <p align="center">
+  <a href="https://pypi.org/project/arda-mapper/"><img alt="PyPI" src="https://img.shields.io/pypi/v/arda-mapper"></a>
   <a href="https://github.com/antigenomics/arda/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/antigenomics/arda/actions/workflows/ci.yml/badge.svg"></a>
   <a href="https://docs.isalgo.dev/arda/"><img alt="docs" src="https://github.com/antigenomics/arda/actions/workflows/docs.yml/badge.svg"></a>
   <img alt="python" src="https://img.shields.io/badge/python-3.10%2B-blue">
@@ -40,6 +41,13 @@ IgBLAST is the gold standard but is slow to invoke per-batch and awkward to embe
 
 ## Install
 
+```bash
+pip install arda-mapper   # from PyPI (imports as `arda`); binary wheels ship the C++ extension
+```
+
+`mmseqs2` (the search backend) is fetched/managed by arda at runtime. For development — and to
+get the committed germline references on disk — use `setup.sh`:
+
 ```bash
 bash setup.sh            # creates conda env `arda`, fetches IgBLAST, pip install -e .
 conda activate arda
@@ -47,7 +55,8 @@ conda activate arda
 
 Flags: `--no-conda` (use the active env), `--build-db` (rebuild references after
 install), `--tests` (run the fast suites). The committed `database/vdj/<organism>/`
-references mean **most users never need to build anything**.
+references mean **most users never need to build anything**; a `pip`-only install builds them
+on first use (or set `$ARDA_HOME` to a checkout).
 
 Supported organisms: **human, mouse** (full IG + TR), **rat, rabbit, rhesus_monkey**
 (IG only — IgBLAST ships no TR internal annotation for these).

{arda_mapper-2.0.2 → arda_mapper-2.0.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "scikit_build_core.build"
 
 [project]
 name = "arda-mapper"  # PyPI distribution name (`arda` is taken); imports as `arda`
-version = "2.0.2"
+version = "2.0.3"
 description = "Antigen Receptor Domain Annotation — fast TCR/BCR FR/CDR region annotation"
 readme = "README.md"
 requires-python = ">=3.10"

{arda_mapper-2.0.2 → arda_mapper-2.0.3}/src/arda/__init__.py

@@ -6,7 +6,7 @@ via offline IgBLAST-built references mapped at runtime with MMseqs2.
 
 from __future__ import annotations
 
-__version__ = "2.0.1"
+__version__ = "2.0.3"
 
 from .adapter import annotate_sequences  # noqa: E402
 

arda_mapper-2.0.3/src/arda/_database_fetch.py

@@ -0,0 +1,68 @@
+"""Auto-fetch the curated arda reference database (a GitHub release asset).
+
+The wheel ships code only; the ~50 MB curated ``vdj/`` reference (allele FASTAs + region
+markup, per species, AA + NT) is published as the ``arda-reference-vdj.tar.gz`` asset on the
+matching ``vX.Y.Z`` GitHub release and downloaded once into the per-user cache on first use.
+Version-sensitive precompiled mmseqs DBs are *not* shipped — they are built on demand from
+the fetched FASTAs into ``<cache>/data``.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+import tarfile
+import tempfile
+from pathlib import Path
+
+from . import __version__
+from ._mmseqs_fetch import _download  # reuse the hardened UA/retry downloader
+
+_ASSET = "arda-reference-vdj.tar.gz"
+_URL = "https://github.com/antigenomics/arda/releases/download/v{version}/" + _ASSET
+
+
+def reference_url(version: str | None = None) -> str:
+    """Release-asset URL for the reference tarball at ``version`` (default: this build)."""
+    return _URL.format(version=version or __version__)
+
+
+def fetch_database(dest: Path, *, force: bool = False, version: str | None = None) -> Path:
+    """Download + extract the reference (``vdj/<org>/...``) into ``dest``; return ``dest``.
+
+    Skips the download if ``dest/vdj`` already exists (unless ``force``). Extraction rejects
+    symlinks/hardlinks and any path that escapes the temp dir (same guards as the mmseqs
+    fetch), then moves the ``vdj`` tree into place atomically-ish.
+    """
+    dest = Path(dest)
+    if (dest / "vdj").is_dir() and not force:
+        return dest
+    dest.mkdir(parents=True, exist_ok=True)
+    url = reference_url(version)
+    print(f"[arda] fetching reference database (one-time): {url}", file=sys.stderr)
+    with tempfile.TemporaryDirectory(prefix="arda_db_") as td:
+        tmp = Path(td)
+        tarball = tmp / _ASSET
+        _download(url, tarball)
+        with tarfile.open(tarball) as tf:
+            tmp_resolved = tmp.resolve()
+            for member in tf.getmembers():
+                if member.issym() or member.islnk():
+                    raise RuntimeError(f"Refusing to extract link from archive: {member.name}")
+                member_path = (tmp / member.name).resolve()
+                if not str(member_path).startswith(str(tmp_resolved) + os.sep):
+                    raise RuntimeError(f"Refusing to extract path outside temp dir: {member.name}")
+            tf.extractall(tmp)
+        # tarball root holds vdj/ (created with `tar -C database ... vdj`); tolerate a nested layout.
+        src = tmp / "vdj"
+        if not src.is_dir():
+            src = next((p for p in tmp.rglob("vdj") if p.is_dir()), None)
+        if src is None:
+            raise RuntimeError(f"Unexpected reference archive layout in {_ASSET} (no vdj/)")
+        target = dest / "vdj"
+        if target.exists():
+            shutil.rmtree(target)
+        shutil.move(str(src), str(target))
+    print(f"[arda] installed reference -> {dest}", file=sys.stderr)
+    return dest

arda_mapper-2.0.3/src/arda/paths.py

@@ -0,0 +1,107 @@
+"""Filesystem layout discovery for arda.
+
+Two modes, resolved transparently:
+
+* **Source checkout** (``$ARDA_HOME`` or an editable/development install) — ``bin/``,
+  ``data/`` and ``database/`` live next to ``pyproject.toml``, exactly as committed.
+* **PyPI install** (``pip install arda-mapper``, no source tree) — there is no bundled
+  ``database/`` in the wheel (it is 50+ MB of curated references), so everything lives under
+  a per-user cache (``$XDG_CACHE_HOME/arda`` or ``~/.cache/arda``). The curated reference is
+  **auto-fetched once** into the cache on first use (see :mod:`arda._database_fetch`), and
+  mmseqs target DBs are built there on demand. No ``ARDA_HOME`` needed.
+
+Set ``$ARDA_NO_AUTO_FETCH`` to disable the one-time reference download (e.g. air-gapped
+runs where the cache was pre-populated).
+"""
+
+from __future__ import annotations
+
+import os
+from functools import lru_cache
+from pathlib import Path
+
+__all__ = [
+    "project_root",
+    "cache_root",
+    "bin_dir",
+    "data_dir",
+    "database_dir",
+    "vdj_dir",
+]
+
+_MARKERS = ("pyproject.toml", "setup.sh")
+_REFERENCE_MARKER = "vdj"  # database_dir()/vdj must exist for the reference to be usable
+
+
+@lru_cache(maxsize=1)
+def _source_root() -> Path | None:
+    """The source checkout root if this is a dev/editable install, else ``None``.
+
+    Honors ``$ARDA_HOME`` (must be a directory); otherwise walks up from this file looking
+    for a directory that has both ``database/`` and a project marker. Never raises for a
+    plain PyPI install — it simply returns ``None`` and the caller falls back to the cache.
+    """
+    env = os.environ.get("ARDA_HOME")
+    if env:
+        root = Path(env).expanduser().resolve()
+        if not root.is_dir():
+            raise RuntimeError(f"ARDA_HOME={env!r} is not a directory")
+        return root
+    here = Path(__file__).resolve()
+    for parent in here.parents:
+        if (parent / "database").is_dir() and any((parent / m).exists() for m in _MARKERS):
+            return parent
+    return None
+
+
+@lru_cache(maxsize=1)
+def cache_root() -> Path:
+    """Per-user cache root (``$XDG_CACHE_HOME/arda`` or ``~/.cache/arda``)."""
+    base = os.environ.get("XDG_CACHE_HOME")
+    root = (Path(base) if base else Path.home() / ".cache") / "arda"
+    root.mkdir(parents=True, exist_ok=True)
+    return root
+
+
+@lru_cache(maxsize=1)
+def project_root() -> Path:
+    """Source checkout root if present, else the per-user cache root.
+
+    Unlike older arda, this never raises: a PyPI install with no source tree resolves to the
+    cache dir, where the reference is auto-fetched and mmseqs DBs are built.
+    """
+    return _source_root() or cache_root()
+
+
+def bin_dir() -> Path:
+    """Directory holding the downloaded mmseqs/IgBLAST binaries (gitignored / cached)."""
+    return project_root() / "bin"
+
+
+def data_dir() -> Path:
+    """Writable scratch directory for downloads and built mmseqs DBs (gitignored / cached)."""
+    return project_root() / "data"
+
+
+@lru_cache(maxsize=1)
+def database_dir() -> Path:
+    """Curated reference database root.
+
+    Source checkout → the committed ``database/``. PyPI install → ``<cache>/database``, with
+    the reference auto-fetched on first call unless ``$ARDA_NO_AUTO_FETCH`` is set.
+    """
+    src = _source_root()
+    if src is not None:
+        return src / "database"
+    db = cache_root() / "database"
+    if not (db / _REFERENCE_MARKER).is_dir() and "ARDA_NO_AUTO_FETCH" not in os.environ:
+        from ._database_fetch import fetch_database
+
+        fetch_database(db)
+    return db
+
+
+def vdj_dir(species: str | None = None) -> Path:
+    """``database/vdj`` (or a single species subdirectory)."""
+    base = database_dir() / "vdj"
+    return base / species if species else base

arda_mapper-2.0.2/src/arda/paths.py

@@ -1,74 +0,0 @@
-"""Filesystem layout discovery for arda.
-
-Resolves the locations of the project's ``bin/`` (downloaded IgBLAST release),
-``data/`` (scratch/downloads), and ``database/`` (committed curated references).
-
-Resolution order for the project root:
-
-1. ``$ARDA_HOME`` if set.
-2. Walking up from this file to find a directory containing both ``database``
-   and one of ``pyproject.toml`` / ``setup.sh`` (the editable-install / source case).
-"""
-
-from __future__ import annotations
-
-import os
-from pathlib import Path
-from functools import lru_cache
-
-__all__ = [
-    "project_root",
-    "bin_dir",
-    "data_dir",
-    "database_dir",
-    "vdj_dir",
-]
-
-_MARKERS = ("pyproject.toml", "setup.sh")
-
-
-@lru_cache(maxsize=1)
-def project_root() -> Path:
-    """Return the arda project root directory.
-
-    Honors ``$ARDA_HOME``; otherwise searches parent directories for a source
-    checkout. Raises ``RuntimeError`` if neither resolves.
-    """
-    env = os.environ.get("ARDA_HOME")
-    if env:
-        root = Path(env).expanduser().resolve()
-        if not root.is_dir():
-            raise RuntimeError(f"ARDA_HOME={env!r} is not a directory")
-        return root
-
-    here = Path(__file__).resolve()
-    for parent in here.parents:
-        if (parent / "database").is_dir() and any(
-            (parent / m).exists() for m in _MARKERS
-        ):
-            return parent
-    raise RuntimeError(
-        "Could not locate the arda project root. Set $ARDA_HOME to the checkout "
-        "directory (the one containing 'database/')."
-    )
-
-
-def bin_dir() -> Path:
-    """Directory holding the downloaded IgBLAST release (gitignored)."""
-    return project_root() / "bin"
-
-
-def data_dir() -> Path:
-    """Scratch directory for downloads and intermediate artifacts (gitignored)."""
-    return project_root() / "data"
-
-
-def database_dir() -> Path:
-    """Committed curated reference database root."""
-    return project_root() / "database"
-
-
-def vdj_dir(species: str | None = None) -> Path:
-    """``database/vdj`` (or a single species subdirectory)."""
-    base = database_dir() / "vdj"
-    return base / species if species else base