gapit 0.2.2__py3-none-any.whl

gapit/providers/common.py

@@ -0,0 +1,245 @@
+"""Wave B0 shared provider infrastructure: the generic get_db pipeline.
+
+Every concrete provider (Wave B1..B12) is a :class:`Provider` value — a name,
+a description, a tuple of source URLs, a dbtype, and a ``transform`` that
+turns downloaded files into typed ``Record``s. :func:`fetch_provider` runs
+the generic abricate-get_db flow around it: download each URL into a scratch
+workdir under ``db_dir``, transform, normalize sequences and function classes
+(upstream load_fasta semantics), dedupe by exact normalized sequence
+(first wins), sort by gene, persist ``records.jsonl``, then delegate to
+:func:`gapit.dbbuild.build_database` for the ``sequences`` FASTA, the BLAST
+index, and the manifest (written last, certifying the build).
+
+Upstream's ``is_full_gene`` is deliberately NOT ported: its map result is
+discarded — a no-op.
+"""
+
+import os
+import re
+import urllib.request
+from collections.abc import Callable, Iterable, Sequence
+from dataclasses import dataclass
+from importlib.resources import files
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from typing import Literal
+from urllib.parse import urlparse
+
+from gapit import __version__
+from gapit.dbbuild import build_database
+from gapit.errors import DatabaseError
+from gapit.proctools import note
+from gapit.providers.snapshots import extract_snapshot, read_snapshot_manifest
+from gapit.records import Manifest, Record, write_records
+
+_NUCL_JUNK = re.compile(r"[^AGCT]")
+_PROT_JUNK = re.compile(r"[^A-Z]")
+_WHITESPACE = re.compile(r"\s+")
+_CHUNK_BYTES = 1 << 20
+# Bounded fetch: socket.timeout (an OSError) already maps to DOWNLOAD_FAILED below.
+_DOWNLOAD_TIMEOUT_SECONDS = 60
+
+# mgc.ac.cn (vfdb) 403s "Python-urllib" UAs specifically while serving
+# browser-ish clients (Wave E diagnosis): the Mozilla compatibility token
+# passes those naive UA filters and the gapit/<version> suffix still
+# identifies the tool to servers that log it.
+_USER_AGENT = f"Mozilla/5.0 (compatible; gapit/{__version__})"
+
+Dbtype = Literal["nucl", "prot"]
+
+
+@dataclass(frozen=True, slots=True)
+class Provider:
+    """One database provider: everything fetch_provider needs to know.
+
+    ``transform`` receives the download workdir (each source URL saved under
+    its basename) and yields Records; setting ``db`` to the provider name is
+    the provider module's job. Sequences and function classes may arrive
+    raw — fetch_provider normalizes both.
+
+    ``snapshot`` names a bundled archive (Wave G) under
+    ``gapit/data/snapshots/`` — None (default) for network-only providers.
+    """
+
+    name: str
+    description: str
+    source_urls: tuple[str, ...]
+    dbtype: Dbtype
+    transform: Callable[[Path], Iterable[Record]]
+    snapshot: str | None = None
+
+
+def _basename(url: str) -> str:
+    """Final path segment of a URL, query string excluded ('' for a bare host)."""
+    return urlparse(url).path.rstrip("/").rsplit("/", 1)[-1]
+
+
+def _download(url: str, dest: Path) -> None:
+    """Fetch ``url`` into ``dest`` atomically: urlopen a Request carrying
+    the module User-Agent, stream the body into a hidden .part file beside
+    ``dest`` in chunks, then os.replace. file:// URLs work (tests depend on
+    it). Any URLError/OSError/ValueError becomes DatabaseError
+    ``DOWNLOAD_FAILED`` with the URL in context. No shell, ever.
+    """
+    temp = dest.with_name(f".{dest.name}.part")
+    request = urllib.request.Request(url, headers={"User-Agent": _USER_AGENT})
+    try:
+        with (
+            urllib.request.urlopen(request, timeout=_DOWNLOAD_TIMEOUT_SECONDS) as response,
+            temp.open("wb") as out,
+        ):
+            while chunk := response.read(_CHUNK_BYTES):
+                out.write(chunk)
+        os.replace(temp, dest)
+    except (OSError, ValueError) as exc:
+        raise DatabaseError(
+            f"failed to download {url}: {exc}",
+            code="DOWNLOAD_FAILED",
+            context={"url": url},
+        ) from exc
+    finally:
+        temp.unlink(missing_ok=True)
+
+
+def _normalize_sequence(sequence: str, dbtype: Dbtype) -> str:
+    """Uppercase; then nucl: non-AGCT -> 'N', prot: non-A-Z -> 'X'
+    (upstream load_fasta semantics)."""
+    upper = sequence.upper()
+    match dbtype:
+        case "nucl":
+            return _NUCL_JUNK.sub("N", upper)
+        case "prot":
+            return _PROT_JUNK.sub("X", upper)
+
+
+def _normalize_function(classes: Sequence[str]) -> tuple[str, ...]:
+    """Sorted classes with each whitespace run collapsed to one '_'.
+
+    Upstream sorts, joins with ';', then globally substitutes s/\\s+/_/g —
+    ';' carries no whitespace, so per-class substitution is equivalent.
+    """
+    return tuple(_WHITESPACE.sub("_", drug_class) for drug_class in sorted(classes))
+
+
+def _normalize_record(record: Record, dbtype: Dbtype) -> Record:
+    """Apply the two per-record normalizations; db, gene, and the rest stay."""
+    return record.model_copy(
+        update={
+            "sequence": _normalize_sequence(record.sequence, dbtype),
+            "function": _normalize_function(record.function),
+        }
+    )
+
+
+def _dedupe(records: Sequence[Record]) -> tuple[tuple[Record, ...], int]:
+    """Drop later records whose (already normalized) SEQUENCE was seen; first
+    wins. Returns the kept records and the dropped count (for the caller's
+    stderr note). Duplicate gene NAMES are allowed and kept — upstream too.
+    """
+    seen: set[str] = set()
+    kept: list[Record] = []
+    dropped = 0
+    for record in records:
+        if record.sequence in seen:
+            dropped += 1
+        else:
+            seen.add(record.sequence)
+            kept.append(record)
+    return tuple(kept), dropped
+
+
+def _snapshot_path(provider: Provider) -> Path | None:
+    """Filesystem path of the provider's bundled snapshot archive, or None
+    when the provider has none / the package data is absent (missing
+    archives degrade silently to the network path — Wave G). Tests
+    monkeypatch THIS seam (string setattr), never importlib itself; gapit
+    ships as a regular filesystem package, so the str() round-trip is safe.
+    """
+    if provider.snapshot is None:
+        return None
+    archive = files("gapit").joinpath("data").joinpath("snapshots").joinpath(provider.snapshot)
+    return Path(str(archive)) if archive.is_file() else None
+
+
+def bundled_snapshot_manifest(provider: Provider) -> Manifest | None:
+    """The provider's bundled snapshot manifest read in-memory, or None when
+    the provider ships no resolvable snapshot archive (read-only queries:
+    `db outdated` — same seam fetch_provider uses, so tests patch
+    ``_snapshot_path`` and both paths see the fake)."""
+    archive = _snapshot_path(provider)
+    return None if archive is None else read_snapshot_manifest(archive)
+
+
+def fetch_provider(
+    provider: Provider,
+    db_dir: Path,
+    *,
+    fetched_at: str,
+    force: bool = False,
+    quiet: bool = True,
+    from_source: bool = False,
+    debug: bool = False,
+) -> Manifest:
+    """Run the generic provider pipeline into ``db_dir`` (created if needed).
+
+    Snapshot path (Wave G): unless ``from_source`` is set, a provider with a
+    resolvable bundled snapshot installs its archived ``records.jsonl`` and
+    rebuilds every index locally — ``upstream_version`` comes from the
+    archived manifest, everything else is fresh. Otherwise the network path
+    runs: download each URL, transform, normalize, dedupe, sort.
+
+    Raises DatabaseError (exit 4): ``DB_ALREADY_EXISTS`` when a manifest is
+    present and force is off (upstream: "Won't overwrite existing (use
+    --force)"), ``DOWNLOAD_FAILED`` for a failed source download,
+    ``SNAPSHOT_INVALID`` for a corrupt snapshot archive, and
+    ``PROVIDER_EMPTY`` when the transform+dedupe leaves zero records.
+    """
+    if (db_dir / "gapit-manifest.json").is_file() and not force:
+        raise DatabaseError(
+            f"won't overwrite existing database {provider.name} (use --force)",
+            code="DB_ALREADY_EXISTS",
+            context={"db": provider.name},
+        )
+    db_dir.mkdir(parents=True, exist_ok=True)
+    if not from_source:
+        snapshot = _snapshot_path(provider)
+        if snapshot is not None:
+            archived = extract_snapshot(snapshot, db_dir)
+            note(quiet, f"installed {provider.name} from bundled snapshot {snapshot.name}")
+            return build_database(
+                db_dir,
+                name=provider.name,
+                dbtype=provider.dbtype,
+                source_urls=provider.source_urls,
+                fetched_at=fetched_at,
+                upstream_version=archived.upstream_version,
+                quiet=quiet,
+                debug=debug,
+            )
+    with TemporaryDirectory(dir=db_dir, prefix=".download.") as workdir_name:
+        workdir = Path(workdir_name)
+        for url in provider.source_urls:
+            _download(url, workdir / _basename(url))
+        note(quiet, f"downloaded {len(provider.source_urls)} source file(s)")
+        records = tuple(
+            _normalize_record(record, provider.dbtype) for record in provider.transform(workdir)
+        )
+    kept, dropped = _dedupe(records)
+    note(quiet, f"read {len(records)} records from {provider.name}")
+    note(quiet, f"dropped {dropped} duplicate sequence(s), kept {len(kept)}")
+    if not kept:
+        raise DatabaseError(
+            f"provider {provider.name} yielded no records",
+            code="PROVIDER_EMPTY",
+            context={"db": provider.name},
+        )
+    write_records(sorted(kept, key=lambda record: record.gene), db_dir / "records.jsonl")
+    return build_database(
+        db_dir,
+        name=provider.name,
+        dbtype=provider.dbtype,
+        source_urls=provider.source_urls,
+        fetched_at=fetched_at,
+        quiet=quiet,
+        debug=debug,
+    )

gapit/providers/ecoh.py

@@ -0,0 +1,63 @@
+"""ecoh database provider — E. coli O and H antigen genes (srst2 EcOH).
+
+Transform-only Wave B10 module: ``PROVIDER`` wires the pinned metadata into
+the frozen B0 :class:`gapit.providers.common.Provider` contract and
+:func:`transform` parses the downloaded ``EcOH.fasta`` into typed Records.
+Functional categories are allele-prefix derived — ``fliC*`` → H-antigen,
+``wzx``/``wzy``/``wzt``/``wzm`` → O-antigen — fallback ``antigen``.
+"""
+
+from collections.abc import Iterator
+from pathlib import Path
+
+from gapit.fasta import iter_fasta
+from gapit.providers.common import Provider
+from gapit.records import Record
+
+NAME = "ecoh"
+SOURCE_FILE = "EcOH.fasta"
+
+
+def transform(workdir: Path) -> Iterator[Record]:
+    """Parse ``workdir/EcOH.fasta`` into Records (db = ecoh).
+
+    srst2 header convention: ``>cluster__gene__allele__seq_id acc;word;word``
+    (abricate-get_db ``get_ecoh``). The id splits on ``__`` into exactly 4
+    parts and the gene is part 3 — the allele, e.g. ``fliC-H1``. The
+    description splits on ``;``: the first piece is the accession, the
+    space-joined rest is the product. Ids without exactly 4 ``__``-parts are
+    skipped: upstream perl would read an undefined gene field there, and a
+    typed Record cannot carry one. ``function`` is allele-prefix derived
+    per the module-docstring rule (fallback ``antigen``).
+    """
+    for fasta in iter_fasta(workdir / SOURCE_FILE):
+        parts = fasta.id.split("__")
+        if len(parts) != 4:
+            continue
+        gene = parts[2]
+        if gene.startswith("fliC"):
+            function: tuple[str, ...] = ("H-antigen",)
+        elif gene.startswith(("wzx", "wzy", "wzt", "wzm")):
+            function = ("O-antigen",)
+        else:
+            function = ("antigen",)
+        description = fasta.description.split(";")
+        yield Record(
+            db=NAME,
+            gene=gene,
+            accession=description[0],
+            function=function,
+            product=" ".join(description[1:]),
+            sequence=fasta.sequence,
+            source_id=fasta.id,
+        )
+
+
+PROVIDER = Provider(
+    name=NAME,
+    description="E. coli O and H antigens (srst2 EcOH)",
+    source_urls=("https://raw.githubusercontent.com/katholt/srst2/master/data/EcOH.fasta",),
+    dbtype="nucl",
+    transform=transform,
+    snapshot=None,
+)

gapit/providers/ecoli_vf.py

@@ -0,0 +1,74 @@
+r"""ecoli_vf provider (phac-nml E. coli virulence factors) — transform only.
+
+Upstream ``get_ecoli_vf`` (abricate-get_db 1.4.0) parses
+``repaired_ecoli_vfs_shortnames.ffn`` in three steps per record::
+
+    >VFG000748(gi:2865308) (espF) EspF [EspF (VF0182)] [Escherichia coli ...]
+
+    1. id  ``^(\w+)(?:\((.*?)\))?$``  -> base id + optional paren accession
+       (upstream ``die``s on a non-match; we SKIP the record instead —
+       same deviation family as vfdb/ecoh, one bad header must not kill
+       a fetch)
+    2. accession = ``$2 || $1``        -> paren content; an absent OR EMPTY
+       capture falls back to the base id (perl ``||`` is falsy-based)
+    3. description: repeatedly strip trailing bracket groups
+       (``s/\s\[.*?\]$//g``), then ``^(?:\((.*?)\)\s+)?(.*)$`` -> a
+       leading paren group RENAMES the gene (overrides the base id), the
+       remainder becomes the product (``$DESC || $ID`` fallback).
+"""
+
+import re
+from collections.abc import Iterable
+from pathlib import Path
+
+from gapit.fasta import iter_fasta
+from gapit.providers.common import Provider
+from gapit.records import Record
+
+_NAME = "ecoli_vf"
+_SOURCE_FILE = "repaired_ecoli_vfs_shortnames.ffn"
+
+# Upstream regexes verbatim (the /x id regex ignores whitespace; joined here).
+_ID = re.compile(r"^(\w+)(?:\((.*?)\))?$")
+_TRAILING_BRACKETS = re.compile(r"\s\[.*?\]$")
+_DESC = re.compile(r"^(?:\((.*?)\)\s+)?(.*)$")
+
+
+def transform(workdir: Path) -> Iterable[Record]:
+    """Yield Records from ``workdir/repaired_ecoli_vfs_shortnames.ffn``.
+
+    Sequence and the leading/trailing-stripped description arrive via
+    gapit.fasta; gene/accession/product derive per the docstring steps.
+    """
+    for fasta in iter_fasta(workdir / _SOURCE_FILE):
+        id_match = _ID.match(fasta.id)
+        if id_match is None:
+            continue
+        base = id_match.group(1)
+        accession = id_match.group(2) or base  # perl $2 || $1: '' is falsy too
+        description = fasta.description
+        while (stripped := _TRAILING_BRACKETS.sub("", description)) != description:
+            description = stripped
+        desc_match = _DESC.match(description)
+        assert desc_match is not None  # (.*) matches any string — cannot fail
+        gene = desc_match.group(1) or base
+        product = desc_match.group(2)
+        yield Record(
+            db=_NAME,
+            gene=gene,
+            sequence=fasta.sequence,
+            accession=accession,
+            function=("virulence",),
+            product=product or gene,  # save_fasta: -desc => ($DESC || $ID)
+            source_id=base,
+        )
+
+
+PROVIDER = Provider(
+    name=_NAME,
+    description="E. coli virulence factors (phac-nml)",
+    source_urls=("https://github.com/phac-nml/ecoli_vf/raw/master/data/" + _SOURCE_FILE,),
+    dbtype="nucl",
+    transform=transform,
+    snapshot=None,
+)

gapit/providers/megares.py

@@ -0,0 +1,71 @@
+"""megares database provider — MEGARes v3 antimicrobial resistance genes.
+
+Transform-only Wave B9 module: ``PROVIDER`` wires the pinned metadata into
+the frozen B0 :class:`gapit.providers.common.Provider` contract and
+:func:`transform` unpacks the downloaded ``megares_v3.00.zip`` and parses
+every ``megares_drugs_*.fasta`` inside it into typed Records.
+"""
+
+import zipfile
+from collections.abc import Iterator
+from pathlib import Path
+
+from gapit.fasta import iter_fasta
+from gapit.providers.common import Provider
+from gapit.records import Record
+
+NAME = "megares"
+ARCHIVE = "megares_v3.00.zip"
+_DATABASE_GLOB = "megares_drugs_*.fasta"
+
+
+def transform(workdir: Path) -> Iterator[Record]:
+    """Extract ``workdir/megares_v3.00.zip`` and parse every nested
+    ``megares_drugs_*.fasta`` into Records (db = megares).
+
+    MEGARes v3 header convention (abricate-get_db ``get_megares``):
+    ``>id|type|class|mech|group|note`` where the note field exists only on
+    records requiring SNP confirmation — a non-empty note skips the record
+    (SPEC §8). Keepers map gene=group, accession=source_id=id (the MEG_
+    number), product=colon-joined type/class/mech/group; function = the
+    ``class`` field (x[2], e.g. Tetracyclines) as a 1-tuple — upstream
+    sets no ABX, the class IS the functional category. Archives often nest
+    the fasta one directory deep — upstream
+    ``unzip -j`` flattens, here the glob is recursive (sorted, so multi-file
+    archives parse deterministically).
+
+    Documented deviation: upstream perl splits into six list variables and
+    keeps records even when fields are missing (undef gene, empty product
+    pieces); gapit skips ids with fewer than 5 pipe-fields or an empty among
+    the 5 leading ones. ``split('|', 5)`` mirrors perl's implicit
+    list-assignment limit: any pipes past the group fold into the note, and
+    a folded note is non-empty, so over-long ids skip exactly like upstream.
+    """
+    with zipfile.ZipFile(workdir / ARCHIVE) as archive:
+        archive.extractall(workdir)
+    for fasta_path in sorted(workdir.rglob(_DATABASE_GLOB)):
+        for fasta in iter_fasta(fasta_path):
+            parts = fasta.id.split("|", 5)
+            if len(parts) < 5 or "" in parts[:5]:
+                continue
+            if len(parts) == 6 and parts[5]:
+                continue
+            yield Record(
+                db=NAME,
+                gene=parts[4],
+                accession=parts[0],
+                function=(parts[2],),
+                product=":".join(parts[1:5]),
+                sequence=fasta.sequence,
+                source_id=parts[0],
+            )
+
+
+PROVIDER = Provider(
+    name=NAME,
+    description="MEGARes antimicrobial resistance genes",
+    source_urls=("https://www.meglab.org/downloads/megares_v3.00.zip",),
+    dbtype="nucl",
+    transform=transform,
+    snapshot=None,
+)

gapit/providers/ncbi.py

@@ -0,0 +1,103 @@
+"""ncbi database provider — NCBI AMRFinderPlus curated AMR (Wave B1).
+
+Transform-only module mirroring abricate-get_db ``get_ncbi``: pair
+``AMR_CDS.fa`` records with ``ReferenceGeneCatalog.txt`` rows keyed by
+``refseq_nucleotide_accession`` (column 10, 0-based), keeping only plain
+(non-fusion) genes whose catalog row is scope core / type AMR / subtype AMR.
+``PROVIDER`` wires the pinned metadata into the frozen B0
+:class:`gapit.providers.common.Provider` contract.
+"""
+
+import re
+from collections.abc import Iterator
+from pathlib import Path
+
+from gapit.fasta import iter_fasta
+from gapit.providers.common import Provider
+from gapit.records import Record
+
+NAME = "ncbi"
+AMR_CDS_FILE = "AMR_CDS.fa"
+CATALOG_FILE = "ReferenceGeneCatalog.txt"
+_ACCESSION_COLUMN = 10
+_VERSIONED_ACCESSION = re.compile(r"\.\d+$")
+_LATEST = (
+    "https://ftp.ncbi.nlm.nih.gov/pathogen/Antimicrobial_resistance/AMRFinderPlus/database/latest"
+)
+
+
+def _load_catalog(path: Path) -> dict[str, dict[str, str]]:
+    """ReferenceGeneCatalog rows as ``{accession: {header name: value}}``.
+
+    The first line is the header; every later row is keyed by column 10
+    (``refseq_nucleotide_accession``). Duplicate accessions keep the FIRST
+    row (upstream's ``||=``), and rows are padded to the header width so
+    lookups of unused trailing columns cannot fail on short rows.
+    """
+    rows: dict[str, dict[str, str]] = {}
+    header: list[str] | None = None
+    with path.open(encoding="utf-8") as handle:
+        for line in handle:
+            columns = line.rstrip("\r\n").split("\t")
+            if header is None:
+                header = columns
+                continue
+            width = max(len(header), _ACCESSION_COLUMN + 1)
+            padded = columns + [""] * (width - len(columns))
+            if (acc := padded[_ACCESSION_COLUMN]) and acc not in rows:
+                rows[acc] = dict(zip(header, padded, strict=False))  # perl zip: shorter wins
+    return rows
+
+
+def transform(workdir: Path) -> Iterator[Record]:
+    """Parse ``workdir/AMR_CDS.fa`` + ``ReferenceGeneCatalog.txt`` (db = ncbi).
+
+    AMRFinderPlus fasta ids are ``pi|acc|fp|fn|gene|fam|prod`` — perl's
+    7-variable ``split`` assignment imposes LIMIT 7, so everything past the
+    sixth pipe belongs to ``prod``. Records are skipped — passively, like
+    upstream — unless the id yields 7 non-empty fields, fp/fn are both "1"
+    (fusion filter), and the accession (``.1`` appended unless already
+    versioned, e.g. ``NG_050200`` -> ``NG_050200.1``) matches a catalog row
+    with scope ``core``, type ``AMR``, and subtype ``AMR``. Sequences and
+    function categories stay raw: fetch_provider owns normalization.
+    """
+    catalog = _load_catalog(workdir / CATALOG_FILE)
+    for fasta in iter_fasta(workdir / AMR_CDS_FILE):
+        fields = fasta.id.split("|")
+        if len(fields) < 7:
+            continue
+        pi, acc, fp, fn, gene, fam = fields[:6]
+        prod = "|".join(fields[6:])
+        if not all((pi, acc, fp, fn, gene, fam, prod)):
+            continue
+        if fp != "1" or fn != "1":
+            continue
+        if not _VERSIONED_ACCESSION.search(acc):
+            acc += ".1"
+        row = catalog.get(acc)
+        if row is None:
+            continue
+        if row["scope"] != "core" or row["type"] != "AMR" or row["subtype"] != "AMR":
+            continue
+        yield Record(
+            db=NAME,
+            gene=gene,
+            accession=row["refseq_nucleotide_accession"],
+            function=tuple(part for part in row["subclass"].split("/") if part),
+            product=prod.replace("_", " "),
+            sequence=fasta.sequence,
+            source_id=pi,
+        )
+
+
+PROVIDER = Provider(
+    name=NAME,
+    description="NCBI AMRFinderPlus (reference finder) curated AMR",
+    source_urls=(
+        f"{_LATEST}/AMR_CDS.fa",
+        f"{_LATEST}/ReferenceGeneCatalog.txt",
+    ),
+    dbtype="nucl",
+    transform=transform,
+    snapshot=None,
+)

gapit/providers/plasmidfinder.py

@@ -0,0 +1,69 @@
+"""plasmidfinder database provider — CGE PlasmidFinder replicons (transform only).
+
+Upstream ``get_plasmidfinder`` (abricate-get_db 1.4.0) downloads the bitbucket
+HEAD.zip — an archive with an arbitrary top-level directory — unzips every
+``*.fsa`` and, per record, splits the accession suffix off the id::
+
+    >IncFII_1_NC_004631.1  ->  gene IncFII_1, accession NC_004631.1
+
+Perl semantics preserved exactly (verified against the parity env): the
+product is the ORIGINAL full id (DESC is assigned before the regex munging),
+trailing underscore runs are stripped from the captured id, and a non-matching
+id — or one that strips to empty — keeps the ORIGINAL id as gene with an empty
+accession. Upstream additionally warns on the empty-id case; the transform has
+no diagnostic channel, so the record is kept silently (``fetch_provider`` owns
+stderr). The ``_1`` copy number STAYS on the gene: only the accession suffix
+is removed.
+"""
+
+import re
+import zipfile
+from collections.abc import Iterator
+from pathlib import Path
+
+from gapit.fasta import iter_fasta
+from gapit.providers.common import Provider
+from gapit.records import Record
+
+NAME = "plasmidfinder"
+ARCHIVE = "HEAD.zip"
+
+# Upstream regex verbatim: group 2 is the accession ([A-Z]+ prefix or the
+# literal NC_, digits, optional .version); group 1 is everything before the
+# last viable underscore — greedy, so the copy number stays in group 1.
+_ID = re.compile(r"^(.*)_(([A-Z]+|NC_)\d+(\.\d+)?)$")
+_FUNCTION = ("replicon",)  # locked gapit/v1 func vocabulary (Wave F2c)
+
+
+def transform(workdir: Path) -> Iterator[Record]:
+    """Yield Records from every ``*.fsa`` inside ``workdir/HEAD.zip``.
+
+    Members are extracted into the workdir (bitbucket archives nest under an
+    arbitrary top-level directory) and matched with a recursive glob, in
+    sorted order for determinism.
+    """
+    with zipfile.ZipFile(workdir / ARCHIVE) as archive:
+        archive.extractall(workdir)
+    for fsa in sorted(workdir.glob("**/*.fsa")):
+        for fasta in iter_fasta(fsa):
+            id_match = _ID.match(fasta.id)
+            captured = id_match.group(1).rstrip("_") if id_match is not None else ""
+            yield Record(
+                db=NAME,
+                gene=captured or fasta.id,
+                accession=id_match.group(2) if id_match is not None else "",
+                function=_FUNCTION,
+                product=fasta.id,
+                sequence=fasta.sequence,
+                source_id=fasta.id,
+            )
+
+
+PROVIDER = Provider(
+    name=NAME,
+    description="CGE PlasmidFinder replicons",
+    source_urls=("https://bitbucket.org/genomicepidemiology/plasmidfinder_db/get/HEAD.zip",),
+    dbtype="nucl",
+    transform=transform,
+    snapshot=None,
+)