gapit 0.2.2__py3-none-any.whl

gapit/cmd_db_outdated.py

@@ -0,0 +1,51 @@
+"""The `gapit db outdated` command: typer shell over the use-case
+(:mod:`gapit.db_query_ops`) — installed-database staleness report.
+
+Reports every installed database's age against a staleness threshold and
+the bundled snapshot date. Staleness is a REPORT, never an error state:
+exit 0 even when everything is stale. Read-only: no builds, no network,
+no datadir writes.
+"""
+
+from typing import Annotated
+
+import typer
+
+from gapit.db_query_ops import (
+    DEFAULT_STALE_DAYS,
+    DbOutdatedDocument,
+    outdated_tsv_lines,
+    perform_outdated,
+)
+from gapit.dispatch import Datadir, dispatch
+
+
+def db_outdated_command(
+    datadir: Datadir = None,
+    days: Annotated[
+        int,
+        typer.Option("--days", min=0, help="Staleness threshold in days (stale past this age)."),
+    ] = DEFAULT_STALE_DAYS,
+    as_json: Annotated[
+        bool,
+        typer.Option("--json", help="Print machine-readable JSON instead of a table."),
+    ] = False,
+    quiet: Annotated[bool, typer.Option("--quiet", help="Silence stderr diagnostics.")] = False,
+) -> None:
+    """Report installed database ages and available updates (exit 0 however
+    stale things are — a report, not an error).
+
+    A database is `stale` past --days (default 90) and `snapshot-update`
+    when its provider's bundled snapshot is newer than the installed copy.
+    """
+
+    def run() -> None:
+        entries = perform_outdated(datadir, days=days)
+        if as_json:
+            document = DbOutdatedDocument(databases=tuple(entries))
+            typer.echo(document.model_dump_json(indent=2, by_alias=True))
+            return
+        for line in outdated_tsv_lines(entries):
+            typer.echo(line)
+
+    dispatch(run)

gapit/cmd_db_search.py

@@ -0,0 +1,66 @@
+"""The `gapit db search` command: typer shell over the use-case
+(:mod:`gapit.db_query_ops`) — case-insensitive lookup across the
+``records.jsonl`` truth stores of every installed database (SPEC.md §11).
+
+Read-only: no builds, no network, no datadir writes.
+"""
+
+from typing import Annotated
+
+import typer
+
+from gapit.db_query_ops import (
+    DEFAULT_LIMIT,
+    SearchField,
+    perform_search,
+    search_json_line,
+    search_tsv_row,
+)
+from gapit.dispatch import Datadir, dispatch
+from gapit.proctools import note
+
+
+def db_search_command(
+    term: Annotated[str, typer.Argument(help="Search term (case-insensitive).")],
+    datadir: Datadir = None,
+    db: Annotated[
+        str | None,
+        typer.Option("--db", help="Restrict the scan to one installed database."),
+    ] = None,
+    field: Annotated[
+        SearchField,
+        typer.Option("--field", help="Field to match: gene, accession, function, product, any."),
+    ] = SearchField.any,
+    exact: Annotated[
+        bool,
+        typer.Option("--exact", help="Full-field equality instead of substring."),
+    ] = False,
+    limit: Annotated[
+        int,
+        typer.Option("--limit", min=0, help="Max hits to print (0 = unlimited)."),
+    ] = DEFAULT_LIMIT,
+    as_json: Annotated[
+        bool,
+        typer.Option("--json", help="Print JSONL lines instead of TSV rows."),
+    ] = False,
+    quiet: Annotated[bool, typer.Option("--quiet", help="Silence stderr diagnostics.")] = False,
+) -> None:
+    """Search records.jsonl across installed databases (zero hits exit 0)."""
+
+    def run() -> None:
+        hits, total = perform_search(
+            term,
+            datadir,
+            db=db,
+            field=field,
+            exact=exact,
+            limit=limit,
+            render=search_json_line if as_json else search_tsv_row,
+            quiet=quiet,
+        )
+        if limit > 0 and total > limit:
+            note(quiet, f"truncated to {limit} of {total} matching records (use --limit 0 for all)")
+        for line in hits:
+            typer.echo(line)
+
+    dispatch(run)

gapit/cmd_screen.py

@@ -0,0 +1,214 @@
+"""The `gapit screen` command: contig files (blastn) or reads and assemblies
+(minimap2) screening.
+
+Lives outside cli.py to keep that module small; cli.py registers it via
+``register_screen_command``.
+"""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from gapit.dispatch import Datadir, dispatch
+from gapit.errors import usage_fail
+from gapit.reads import ReadTypeEnum
+from gapit.screening import AlignerEnum, OutputFormat, run_screen
+from gapit.screening_reads import run_screen_assemblies, run_screen_reads
+
+
+def _split_read_list(raw: str, flag: str) -> list[Path]:
+    """Split a comma-separated --r1/--r2 value into paths; empty elements
+    are usage errors (an empty string would silently become the cwd)."""
+    parts = [part.strip() for part in raw.split(",")]
+    if any(not part for part in parts):
+        usage_fail(f"{flag} contains an empty element: {raw!r}")
+    return [Path(part) for part in parts]
+
+
+def screen_command(
+    files: Annotated[
+        list[Path] | None,
+        typer.Argument(help="Input FASTA/GBK/EMBL contig file(s) to screen."),
+    ] = None,
+    r1: Annotated[
+        str | None,
+        typer.Option(
+            "--r1",
+            help="Comma-separated FASTQ reads or assembly FASTA file(s), one per lane.",
+        ),
+    ] = None,
+    r2: Annotated[
+        str | None,
+        typer.Option("--r2", help="Comma-separated mate FASTQ file(s); must match --r1 count."),
+    ] = None,
+    read_type: Annotated[
+        ReadTypeEnum | None,
+        typer.Option(
+            "--read-type",
+            help=(
+                "minimap2 preset for reads mode (default: sr for FASTQ, map-ont"
+                " for assembly FASTA)."
+            ),
+        ),
+    ] = None,
+    min_breadth: Annotated[
+        float,
+        typer.Option("--min-breadth", help="Reads mode: minimum %breadth for presence."),
+    ] = 90.0,
+    min_identity: Annotated[
+        float,
+        typer.Option(
+            "--min-identity",
+            help=(
+                "Reads mode: minimum %identity per alignment, 0 <= x <= 100 (0 = off;"
+                " any nonzero value emits gapit.reads/2)."
+            ),
+        ),
+    ] = 0.0,
+    min_mapq: Annotated[
+        int,
+        typer.Option(
+            "--min-mapq",
+            help=(
+                "Reads mode: minimum MAPQ per alignment (0 = off; any nonzero value"
+                " emits gapit.reads/2)."
+            ),
+        ),
+    ] = 0,
+    aligner: Annotated[
+        AlignerEnum | None,
+        typer.Option(
+            "--aligner",
+            help=(
+                "Alignment engine (default: blastn for contig files, minimap2 for --r1/--r2 reads)."
+            ),
+        ),
+    ] = None,
+    db: Annotated[
+        str, typer.Option("--db", help="Database to screen against (datadir subdir).")
+    ] = "ncbi",
+    datadir: Datadir = None,
+    minid: Annotated[
+        float, typer.Option("--minid", help="Minimum %identity, 0 < x <= 100.")
+    ] = 80.0,
+    mincov: Annotated[
+        float, typer.Option("--mincov", help="Minimum %coverage, 0 <= x <= 100.")
+    ] = 80.0,
+    threads: Annotated[int, typer.Option("--threads", help="BLAST worker threads.")] = 1,
+    jobs: Annotated[
+        int,
+        typer.Option(
+            "--jobs",
+            help=(
+                "Screen N input files concurrently (gapit extension; output order is"
+                " always input order). Each worker runs its own BLAST against the"
+                " shared db index, which BLAST mmaps — concurrent readers are fine."
+            ),
+        ),
+    ] = 1,
+    fofn: Annotated[
+        Path | None,
+        typer.Option("--fofn", help="File of filenames; replaces the positional FILEs."),
+    ] = None,
+    quiet: Annotated[bool, typer.Option("--quiet", help="Silence stderr diagnostics.")] = False,
+    noheader: Annotated[bool, typer.Option("--noheader", help="Suppress the header row.")] = False,
+    nopath: Annotated[bool, typer.Option("--nopath", help="Basename the FILE column.")] = False,
+    debug: Annotated[bool, typer.Option("--debug", help="Verbose stderr diagnostics.")] = False,
+    output_format: Annotated[
+        OutputFormat | None,
+        typer.Option("--format", help="Output format (reads mode defaults to json)."),
+    ] = None,
+) -> None:
+    """Screen contig files or FASTQ reads (R1 and R2 comma-lists, one lane
+    each) for AMR/virulence genes."""
+
+    def run() -> None:
+        if (r1 is not None or r2 is not None) and files:
+            usage_fail("--r1/--r2 and positional contig FILEs are mutually exclusive")
+        if r2 is not None and r1 is None:
+            usage_fail("--r2 requires --r1")
+        if (
+            (min_identity > 0 or min_mapq > 0)
+            and r1 is None
+            and aligner is not AlignerEnum.minimap2
+        ):
+            usage_fail("--min-identity/--min-mapq are reads-mode only (minimap2 engine)")
+        if r1 is not None or r2 is not None:
+            if fofn is not None:
+                usage_fail("--fofn is not available in reads mode")
+            if noheader:
+                usage_fail("--noheader is not available in reads mode")
+            if nopath:
+                usage_fail("--nopath is not available in reads mode")
+            if jobs != 1:
+                usage_fail("--jobs is not available in reads mode")
+            typer.echo(
+                run_screen_reads(
+                    _split_read_list(r1 or "", "--r1"),
+                    _split_read_list(r2, "--r2") if r2 is not None else None,
+                    db,
+                    datadir,
+                    read_type,
+                    min_breadth,
+                    min_identity,
+                    min_mapq,
+                    threads,
+                    output_format,
+                    quiet,
+                    debug,
+                    aligner=aligner,
+                    minid=minid,
+                    mincov=mincov,
+                ),
+                nl=False,
+            )
+        elif aligner is AlignerEnum.minimap2:
+            typer.echo(
+                run_screen_assemblies(
+                    files,
+                    fofn,
+                    db,
+                    datadir,
+                    read_type,
+                    min_breadth,
+                    min_identity,
+                    min_mapq,
+                    threads,
+                    jobs,
+                    noheader,
+                    nopath,
+                    output_format,
+                    quiet,
+                    debug,
+                    minid=minid,
+                    mincov=mincov,
+                ),
+                nl=False,
+            )
+        else:
+            typer.echo(
+                run_screen(
+                    files,
+                    db,
+                    datadir,
+                    minid,
+                    mincov,
+                    threads,
+                    jobs,
+                    fofn,
+                    quiet,
+                    noheader,
+                    nopath,
+                    debug,
+                    output_format or OutputFormat.tsv,
+                ),
+                nl=False,
+            )
+
+    dispatch(run)
+
+
+def register_screen_command(app: typer.Typer) -> None:
+    """Attach the screen command to the CLI app."""
+    app.command("screen")(screen_command)

gapit/cmd_summary.py

@@ -0,0 +1,65 @@
+"""The `gapit summary` command: matrix over abricate-format report tables.
+
+Lives outside cli.py to keep that module small; cli.py registers it via
+``register_summary_command``.
+"""
+
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from gapit.dispatch import dispatch
+from gapit.errors import usage_fail
+from gapit.formats.summary import format_summary_tsv, render_summary_json, render_summary_md
+from gapit.screening import OutputFormat
+from gapit.summary import SummaryParams, build_summary
+
+
+def summary_command(
+    files: Annotated[
+        list[Path] | None,
+        typer.Argument(help="Abricate-format report file(s) to summarize."),
+    ] = None,
+    identity: Annotated[
+        bool,
+        typer.Option("--identity", help="Cells show %IDENTITY instead of %COVERAGE."),
+    ] = False,
+    nopath: Annotated[
+        bool,
+        typer.Option("--nopath", help="Basename row keys (FILE values / input filenames)."),
+    ] = False,
+    quiet: Annotated[bool, typer.Option("--quiet", help="Silence stderr diagnostics.")] = False,
+    output_format: Annotated[
+        OutputFormat, typer.Option("--format", help="Output format.")
+    ] = OutputFormat.tsv,
+) -> None:
+    """Summarize report table(s) into a gene presence/absence matrix."""
+
+    def run() -> None:
+        if not files:
+            usage_fail("summary needs >= 1 report file(s)")
+        if identity and not quiet:
+            typer.echo("Using %IDENTITY for the summary table instead of %COVERAGE", err=True)
+        params = SummaryParams(identity=identity, nopath=nopath)
+
+        def warn(message: str) -> None:
+            if not quiet:
+                typer.echo(f"WARNING: {message}", err=True)
+
+        matrix = build_summary(list(files), params, warn=warn)
+        now = datetime.now(UTC)
+        if output_format is OutputFormat.json:
+            typer.echo(render_summary_json(matrix, now=now), nl=False)
+        elif output_format is OutputFormat.md:
+            typer.echo(render_summary_md(matrix, now=now), nl=False)
+        else:
+            typer.echo(format_summary_tsv(matrix, csv=output_format is OutputFormat.csv), nl=False)
+
+    dispatch(run)
+
+
+def register_summary_command(app: typer.Typer) -> None:
+    """Attach the summary command to the CLI app."""
+    app.command("summary")(summary_command)

gapit/config.py

@@ -0,0 +1,51 @@
+"""Datadir resolution and configuration defaults."""
+
+import os
+from pathlib import Path
+
+from gapit.errors import DatabaseError
+
+ENV_DATADIR = "GAPIT_DATADIR"
+DEFAULT_DATADIR = Path("~/.local/share/gapit/db")
+
+
+def resolve_datadir(cli_value: Path | None) -> Path:
+    """Resolve the datadir: CLI ``--datadir`` > ``$GAPIT_DATADIR`` > ``~/.local/share/gapit/db``.
+
+    Expands ``~`` and resolves to an absolute path; raises DatabaseError when the
+    resolved directory does not exist.
+    """
+    raw = cli_value if cli_value is not None else os.environ.get(ENV_DATADIR, DEFAULT_DATADIR)
+    datadir = Path(raw).expanduser().resolve()
+    if not datadir.is_dir():
+        raise DatabaseError(
+            f"datadir does not exist: {datadir}",
+            code="DATADIR_NOT_FOUND",
+            context={"datadir": str(datadir)},
+        )
+    return datadir
+
+
+def ensure_datadir(cli_value: Path | None) -> Path:
+    """Resolve the datadir and mkdir it when absent (fresh-machine bootstrap).
+
+    Write paths (``db fetch``, ``db build``) bootstrap a missing root; every
+    read path still demands it via ``resolve_datadir``. The resolved path is
+    recovered from ``resolve_datadir``'s DATADIR_NOT_FOUND context — this
+    module stays the single owner of resolution.
+    """
+    try:
+        root = resolve_datadir(cli_value)
+    except DatabaseError as exc:
+        if exc.code != "DATADIR_NOT_FOUND":
+            raise
+        root = Path(exc.context["datadir"])
+    try:
+        root.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        raise DatabaseError(
+            f"cannot create datadir: {root}",
+            code="DATADIR_CREATE_FAILED",
+            context={"datadir": str(root)},
+        ) from exc
+    return root

gapit/db.py

@@ -0,0 +1,226 @@
+"""Database layer: discovery, ``~~~`` header parsing, makeblastdb/blastdbcmd wrappers."""
+
+import os
+import re
+import shlex
+import sys
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel
+
+from gapit.errors import DatabaseError, InputError
+from gapit.fasta import iter_fasta
+from gapit.proctools import run_tool
+
+IDSEP = "~~~"
+
+
+class DbHeader(BaseModel, frozen=True):
+    """Parsed ``~~~`` fields of a database sequence id (SPEC.md §4 step 5).
+
+    ``function`` carries functional categories (AMR classes, virulence, ...):
+    the legacy ``~~~`` branch fills it with abricate's 4th resistance field
+    verbatim — same bytes, better name (Wave F1).
+    """
+
+    database: str
+    gene: str
+    accession: str
+    function: str
+
+
+class BlastDbInfo(BaseModel, frozen=True):
+    """Introspection of one built BLAST database (``blastdbcmd -info``)."""
+
+    n_sequences: int
+    dbtype: Literal["nucl", "prot"]
+    title: str
+    date: str
+
+
+class Database(BaseModel, frozen=True):
+    """One discovered database directory under the datadir."""
+
+    name: str
+    path: Path
+    sequences_path: Path
+
+
+class DatabaseInfo(BaseModel, frozen=True):
+    """One row of ``gapit list`` output."""
+
+    name: str
+    n_sequences: int
+    dbtype: Literal["nucl", "prot"]
+    date: str
+
+
+def parse_db_header(seqid: str, default_db: str) -> DbHeader:
+    """Split a seqid on ``~~~`` into (database, gene, accession, function).
+
+    Without any ``~~~`` the whole seqid is the gene and the default database is
+    used; partial headers leave trailing fields empty; an empty database field
+    also falls back to ``default_db`` (SPEC.md §4 step 5).
+    """
+    fields = seqid.split(IDSEP)
+    if len(fields) == 1:
+        return DbHeader(database=default_db, gene=seqid, accession="", function="")
+    fields += [""] * (4 - len(fields))
+    database, gene, accession, function = fields[:4]
+    return DbHeader(
+        database=database or default_db,
+        gene=gene,
+        accession=accession,
+        function=function,
+    )
+
+
+_AGTC_TABLE = str.maketrans("", "", "AGTCagtc")
+
+
+def mol_type(letters: str) -> Literal["nucl", "prot"]:
+    """Abricate heuristic (SPEC.md §2): protein iff non-[AGTC] letters are
+    strictly more than half of the input (empty input is nucleotide)."""
+    non_agtc = len(letters.translate(_AGTC_TABLE))
+    return "prot" if 2 * non_agtc > len(letters) else "nucl"
+
+
+def make_blast_db(
+    sequences_path: Path,
+    name: str,
+    *,
+    dbtype: Literal["nucl", "prot"] | None = None,
+    debug: bool = False,
+) -> None:
+    """(Re)build the BLAST index for one database directory.
+
+    ``dbtype=None`` (the default) keeps the abricate ``mol_type`` heuristic;
+    an explicit ``"nucl"``/``"prot"`` — e.g. from a gapit manifest, which
+    declares the type — skips the heuristic entirely. With ``debug``, echo
+    the makeblastdb argv to stderr (abricate --debug parity).
+    """
+    if dbtype is None:
+        letters = "".join(record.sequence for record in iter_fasta(sequences_path))
+        dbtype = mol_type(letters)
+    for index_file in sequences_path.parent.glob(f"{sequences_path.name}.[np]??"):
+        index_file.unlink()
+    argv = [
+        "makeblastdb",
+        "-in",
+        str(sequences_path),
+        "-title",
+        name,
+        "-dbtype",
+        dbtype,
+        "-logfile",
+        "/dev/null",
+    ]
+    if debug:
+        print(f"gapit: run: {shlex.join(argv)}", file=sys.stderr)
+    result = run_tool(argv)
+    if result.returncode != 0:
+        raise DatabaseError(
+            f"makeblastdb failed for {name}: {result.stderr.strip()}",
+            code="MAKEBLASTDB_FAILED",
+        )
+
+
+_SEQUENCES_RE = re.compile(r"([\d,]+)\s+sequences;")
+_TITLE_RE = re.compile(r"^Database:[ \t]*(.*)$", re.MULTILINE)
+_DATE_RE = re.compile(r"Date:\s*([A-Za-z]{3})\s+(\d{1,2}),\s+(\d{4})")
+
+
+def parse_blastdbcmd_info(text: str) -> BlastDbInfo:
+    """Parse ``blastdbcmd -info`` output (SPEC.md §2)."""
+    sequences_match = _SEQUENCES_RE.search(text)
+    title_match = _TITLE_RE.search(text)
+    date_match = _DATE_RE.search(text)
+    if sequences_match is None or title_match is None or date_match is None:
+        raise DatabaseError(
+            f"could not parse blastdbcmd output: {text!r}",
+            code="BLASTDBCMD_PARSE_FAILED",
+        )
+    month, day, year = date_match.group(1), date_match.group(2), date_match.group(3)
+    return BlastDbInfo(
+        n_sequences=int(sequences_match.group(1).replace(",", "")),
+        dbtype="prot" if "total residues" in text else "nucl",
+        title=title_match.group(1).strip(),
+        date=f"{year}-{month}-{int(day):02d}",
+    )
+
+
+def blast_db_info(db_prefix: Path) -> BlastDbInfo:
+    """Introspect a built BLAST database via ``blastdbcmd -info``."""
+    result = run_tool(["blastdbcmd", "-info", "-db", str(db_prefix)])
+    if result.returncode != 0:
+        raise DatabaseError(
+            f"Database {db_prefix} is not indexed, please try: gapit setupdb",
+            code="DATABASE_NOT_INDEXED",
+            context={"db": str(db_prefix)},
+        )
+    return parse_blastdbcmd_info(result.stdout)
+
+
+def discover_databases(datadir: Path) -> list[Database]:
+    """Immediate subdirectories of the datadir holding a readable ``sequences``
+    file, sorted by name."""
+    databases: list[Database] = []
+    for child in datadir.iterdir():
+        sequences = child / "sequences"
+        if child.is_dir() and sequences.is_file() and os.access(sequences, os.R_OK):
+            databases.append(Database(name=child.name, path=child, sequences_path=sequences))
+    return sorted(databases, key=lambda database: database.name)
+
+
+def _manifest_dbtype(db_dir: Path) -> Literal["nucl", "prot"] | None:
+    """The dbtype declared by a database's gapit manifest, or ``None`` when the
+    directory has none (abricate-built) — the caller then falls back to the
+    ``mol_type`` heuristic. A malformed manifest propagates (no silent
+    degradation).
+
+    Lazy import: records -> formats.json -> reads -> db is a cycle at module
+    level (Wave C-a notepad hazard).
+    """
+    from gapit.records import read_manifest
+
+    try:
+        return read_manifest(db_dir / "gapit-manifest.json").dbtype
+    except InputError as exc:
+        if exc.code != "INPUT_NOT_FOUND":
+            raise
+        return None
+
+
+def list_databases(datadir: Path, *, setupdb: bool, debug: bool = False) -> list[DatabaseInfo]:
+    """Enumerate databases (building indices first when ``setupdb``), requiring
+    every database to be indexed; returns one DatabaseInfo per database."""
+    infos: list[DatabaseInfo] = []
+    for database in discover_databases(datadir):
+        if setupdb:
+            make_blast_db(
+                database.sequences_path,
+                database.name,
+                dbtype=_manifest_dbtype(database.path),
+                debug=debug,
+            )
+        sequences = database.sequences_path
+        index_exists = any(
+            (sequences.parent / f"{sequences.name}{suffix}").exists() for suffix in (".nin", ".pin")
+        )
+        if not index_exists:
+            raise DatabaseError(
+                f"Database {database.name} is not indexed, please try: gapit setupdb",
+                code="DATABASE_NOT_INDEXED",
+                context={"db": database.name},
+            )
+        info = blast_db_info(sequences)
+        infos.append(
+            DatabaseInfo(
+                name=database.name,
+                n_sequences=info.n_sequences,
+                dbtype=info.dbtype,
+                date=info.date,
+            )
+        )
+    return infos