allelix 2.1.1__tar.gz → 2.2.0__tar.gz

{allelix-2.1.1 → allelix-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: allelix
-Version: 2.1.1
+Version: 2.2.0
 Summary: Open-source genotype analysis toolkit. Format-agnostic ingestion, database-agnostic annotation, offline-first.
 Author: Allelix
 Maintainer-email: dial481 <dial481@users.noreply.github.com>
@@ -29,35 +29,33 @@ Requires-Dist: pysam>=0.22; extra == "cadd"
 Provides-Extra: vcf-index
 Requires-Dist: pysam>=0.22; extra == "vcf-index"
 Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == "dev"
 Requires-Dist: pre-commit>=3.7; extra == "dev"
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-cov<8,>=7; extra == "dev"
 Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0; extra == "dev"
 Dynamic: license-file
 
+<div align="center">
+
+<img src="https://allelix.io/apple-touch-icon.png" width="180" alt="Allelix" />
+
+**Open-source genotype analysis. Format-agnostic. Offline-first.**
+
+[Website](https://allelix.io) · [Quickstart](#quickstart) · [Changelog](https://github.com/allelix/allelix/blob/main/CHANGELOG.md)
+
+[![python](https://img.shields.io/pypi/pyversions/allelix.svg)](https://www.python.org/downloads/)
+[![pypi](https://img.shields.io/pypi/v/allelix.svg)](https://pypi.org/project/allelix/)
+[![license](https://img.shields.io/pypi/l/allelix.svg)](LICENSE)
+[![CI](https://github.com/allelix/allelix/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/allelix/allelix/actions/workflows/ci.yml)
+[![privacy: local-first](https://img.shields.io/badge/privacy-local--first-success)](#privacy)
+
+</div>
+
 # Allelix
 
-Open-source command-line toolkit for analyzing raw genotype files from consumer DNA testing services. Format-agnostic ingestion, database-agnostic annotation, offline-first.
-
-> **Status:** Production — eight parser formats (including VCF + gVCF),
-> four annotators (ClinVar + ClinPGx + GWAS Catalog + SNPedia), three
-> enrichment sources (gnomAD population frequencies + AlphaMissense
-> pathogenicity + CADD deleteriousness), licensable-source gating for
-> commercial users, dual-build ClinVar caches (GRCh37 + GRCh38),
-> HTML/JSON/terminal reports, methylation + pharmacogenomics focused
-> commands, report diffing, persistent config with commercial-mode
-> safety switch. Build auto-detection from position data (ADR-0021).
-> No regex on prose anywhere in production. **Latest: v2.1.0** —
-> ADR-0035 'Cluster B' coordinated model change: `Variant.ref` carries
-> the forward-strand reference allele, per-Annotation `alt` threading
-> on GWAS / SNPedia / ClinPGx enables allele-specific gnomAD /
-> AlphaMissense / CADD enrichment on array inputs, structured GWAS
-> fields (`trait` / `p_value` / `phecode`) replace prose re-parsing in
-> the rollup, and ClinVar / ClinPGx carrier matching is strand-aware
-> with multi-allelic safety guard. JSON `schema_version` bumped 4 → 5
-> (additive, v4 readers unaffected).
-> Release notes:
-> [`CHANGELOG.md`](https://github.com/allelix/allelix/blob/main/CHANGELOG.md).
+> **Status:** Production. Eight parser formats (including VCF + gVCF), four annotators (ClinVar + ClinPGx + GWAS Catalog + SNPedia), three enrichment sources (gnomAD + AlphaMissense + CADD), licensable-source gating for commercial users, dual-build ClinVar caches (GRCh37 + GRCh38), HTML/JSON/terminal reports, methylation + pharmacogenomics focused commands, report diffing, persistent config with commercial-mode safety switch. Build auto-detection from position data (ADR-0021). No regex on prose anywhere in production. The [Changelog](https://github.com/allelix/allelix/blob/main/CHANGELOG.md) tracks every release.
 
 ## Quickstart
 
@@ -97,20 +95,22 @@ See [Development](#development) for source installs and running tests, [Managing
 | MyHeritage DNA | ✓ | CSV, same structure as FTDNA. Detected by "MyHeritage" in comment header. Handles double-double-quoted field variant. |
 | Living DNA | ✓ | Tab-delimited despite `.csv` extension. Handles AX-, AFFX-prefixed and CHR:POS positional SNP IDs. |
 | FTDNA Illumina raw | ✓ | Tab-delimited variant of the FTDNA export (distinct from the CSV format above). `RSID/CHROMOSOME/POSITION/RESULT` columns. Build 37 default. |
+| FTDNA FamFinder | ✓ | Third FTDNA file shape: tab-delimited with **separate `ALLELE1` / `ALLELE2` columns** instead of a concatenated `RESULT`. Detected by the `famfinder` substring in the file header plus the 5-column canonical header. Build 37 default. |
 | VCF / gVCF | ✓ | REF/ALT encoding, `0/1` genotype notation. Plain VCF: absence at a position means reference. gVCF: explicit reference blocks (lines with `<NON_REF>` ALT and `END=` INFO) are skipped — they match nothing in any annotation database. Multi-sample files require `--sample <ID>`. Streams via stdlib; `.vcf.gz` handled transparently. Optional `pip install allelix[vcf-index]` enables pysam-backed tabix random access for fast `extract --snps` on huge VCFs. |
 
 Adding a new format means adding one file to `allelix/parsers/` and registering an instance in the `PARSERS` list in `allelix/parsers/__init__.py`.
 
-### v2.1+ roadmap
+### Roadmap
 
-| Feature | Notes |
+| Release | Theme |
 |---|---|
-| Per-source scoring | Magnitude breakdown by database. Users see which source drove the composite score. |
-| Annotator-level strand awareness (R-1) | Strand-flip matching wired into every annotator's carrier check. Basic `compare` strand support shipped in v1.1; full annotator integration deferred from v2.0.0. |
-| Good / Bad / Neutral repute | Per-annotation repute field. Reframes the report from "here's what's wrong" to "here's your full picture." Requires Annotation model change + renderer updates. |
-| PLINK import | Read .bed/.bim/.fam as an input format (complement to the v1.7.0 export). |
-| PharmCAT integration | Wrap CPIC's PharmCAT as an optional external engine for star-allele / diplotype calling. Requires VCF input (shipped in v2.0.0). |
-| Genome Watchtower | Real-time variant monitoring via database delta feeds. Privacy-preserving: server publishes universal feed, matching happens locally against your deviation set. Replaces full re-analysis with millisecond set intersection. |
+| **v2.2** | Annotation model expansion (cross-source conflict surfacing, risk-allele display, structured MTAG flag), custom-panel UX improvements, methylation panel retune + citations, ClinVar source switch (VCF → `variant_summary.txt`), CLI cleanups (`db clean` / `db path`). |
+| **v2.3** | Per-source magnitude decomposition, Good / Bad / Neutral annotation repute, JSON v3 (AI-legible output contract), plausibility flagging via zygosity × gnomAD MAF, ClinVar review-status weighting, functional-medicine +/− notation. |
+| **v2.4** | ACMG/AMP automated classification engine, variant consequence annotation (VEP-equivalent). |
+| **v2.5+** | CNVs and repeat-expansion support, dbSNP resolution for rsID-less VCFs, gnomAD genomes (non-coding population frequencies), supplemental genotype file merging. |
+| **v3.0** | Ancestry estimation (PCA + 1KG/HGDP reference panels), Polygenic Risk Score (PRS) integration. |
+
+Issues and milestones are tracked at [github.com/allelix/allelix/issues](https://github.com/allelix/allelix/issues). Annotator-level strand-aware carrier matching (R-1) shipped in v2.1.0's ADR-0035 cluster.
 
 ## Supported Databases
 
@@ -254,28 +254,44 @@ Allelix stores reference database caches at `~/.local/share/allelix/` (Linux/mac
 **The caches are disposable and re-downloadable.** Everything here was fetched by `allelix db update` and can be re-fetched at any time. There's no per-user state in the cache — your genotype files never enter this directory. Safe to delete to reclaim space (or to force a full refresh if you suspect a cache went stale):
 
 ```bash
-# Reclaim all ~16-22 GB
-rm -rf ~/.local/share/allelix/
+# Reclaim all ~16-22 GB, with size report and confirmation prompt
+allelix db clean
+
+# Preserve the CADD cache (avoids re-downloading the slowest one, ~5.8 GB)
+allelix db clean --keep-cadd
+
+# Show what would be deleted without acting
+allelix db clean --dry-run
 
-# Reclaim everything except CADD (avoids re-downloading the slowest one)
-find ~/.local/share/allelix/ -mindepth 1 ! -name 'cadd*.sqlite*' -delete
+# Scripted use — skip the confirmation prompt
+allelix db clean --yes
 
 # Re-populate from scratch next time you analyze a file
 allelix db update
 ```
 
-**The one thing worth backing up: `config.toml`.** It lives separately (XDG config dir, typically `~/.config/allelix/config.toml`) and stores your license assertions (commercial-mode toggle, CADD opt-in confirmation) and per-source enable/disable settings. It's the only non-reproducible state in the install. The caches will rebuild on the next `db update`; `config.toml` won't.
+`db clean` refuses to act on a directory that doesn't contain any recognized allelix cache files — a typo'd `--data-dir ~/Documents` won't result in `rm -rf` against an unrelated tree, even with `--yes`. Pass `--force` if you've staged caches under a non-standard name and want to delete them anyway.
+
+For scripting and backup integration, `allelix db path` prints the resolved data directory:
+
+```bash
+ALLELIX_DATA=$(allelix db path)
+du -sh "$ALLELIX_DATA"
+
+# --check additionally verifies the path is writable; exit non-zero if not
+allelix db path --check
+```
+
+**The one thing worth backing up: `config.toml`.** It lives separately (XDG config dir, typically `~/.config/allelix/config.toml`) and stores your license assertions (commercial-mode toggle, CADD opt-in confirmation) and per-source enable/disable settings. It's the only non-reproducible state in the install. The caches will rebuild on the next `db update`; `config.toml` won't. `allelix db clean` preserves `config.toml` even when it lives inside the data directory (older installs).
 
 To fully uninstall allelix and reclaim everything:
 
 ```bash
 pip uninstall allelix
-rm -rf ~/.local/share/allelix/    # reference database caches
+allelix db clean --yes            # reference database caches
 rm -rf ~/.config/allelix/         # license + source-toggle config
 ```
 
-A `allelix db clean` subcommand to automate the cache-clear step (with confirmation prompt and size report) is planned for v2.2 alongside `allelix db path` (prints the resolved data directory for scripting / backup integration).
-
 ## Data Sources & Licensing
 
 Allelix source code is licensed under the **GNU Affero General Public License v3.0 or later** (AGPL-3.0-or-later). Allelix ships with **zero third-party data**. All reference databases are downloaded by the user at runtime via `allelix db update`. Each database retains its original license on the user's machine:
@@ -384,6 +400,8 @@ pytest
 
 The pre-commit hook enforces `ruff check` + `ruff format --check`. If a commit is blocked, fix the underlying problem rather than skipping the hook.
 
+For the full real-data release-validation battery — every parser format, VCF/gVCF, PLINK round-trip, edge cases, the GIAB/1000G corpus — see [`test_data/FULL_TEST_PROTOCOL.md`](test_data/FULL_TEST_PROTOCOL.md). That document is the project's real-data testing story; running `pytest` covers the fast suite that gates every commit.
+
 ## License
 
 GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See `LICENSE`.

{allelix-2.1.1 → allelix-2.2.0}/README.md

@@ -1,26 +1,22 @@
+<div align="center">
+
+<img src="https://allelix.io/apple-touch-icon.png" width="180" alt="Allelix" />
+
+**Open-source genotype analysis. Format-agnostic. Offline-first.**
+
+[Website](https://allelix.io) · [Quickstart](#quickstart) · [Changelog](https://github.com/allelix/allelix/blob/main/CHANGELOG.md)
+
+[![python](https://img.shields.io/pypi/pyversions/allelix.svg)](https://www.python.org/downloads/)
+[![pypi](https://img.shields.io/pypi/v/allelix.svg)](https://pypi.org/project/allelix/)
+[![license](https://img.shields.io/pypi/l/allelix.svg)](LICENSE)
+[![CI](https://github.com/allelix/allelix/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/allelix/allelix/actions/workflows/ci.yml)
+[![privacy: local-first](https://img.shields.io/badge/privacy-local--first-success)](#privacy)
+
+</div>
+
 # Allelix
 
-Open-source command-line toolkit for analyzing raw genotype files from consumer DNA testing services. Format-agnostic ingestion, database-agnostic annotation, offline-first.
-
-> **Status:** Production — eight parser formats (including VCF + gVCF),
-> four annotators (ClinVar + ClinPGx + GWAS Catalog + SNPedia), three
-> enrichment sources (gnomAD population frequencies + AlphaMissense
-> pathogenicity + CADD deleteriousness), licensable-source gating for
-> commercial users, dual-build ClinVar caches (GRCh37 + GRCh38),
-> HTML/JSON/terminal reports, methylation + pharmacogenomics focused
-> commands, report diffing, persistent config with commercial-mode
-> safety switch. Build auto-detection from position data (ADR-0021).
-> No regex on prose anywhere in production. **Latest: v2.1.0** —
-> ADR-0035 'Cluster B' coordinated model change: `Variant.ref` carries
-> the forward-strand reference allele, per-Annotation `alt` threading
-> on GWAS / SNPedia / ClinPGx enables allele-specific gnomAD /
-> AlphaMissense / CADD enrichment on array inputs, structured GWAS
-> fields (`trait` / `p_value` / `phecode`) replace prose re-parsing in
-> the rollup, and ClinVar / ClinPGx carrier matching is strand-aware
-> with multi-allelic safety guard. JSON `schema_version` bumped 4 → 5
-> (additive, v4 readers unaffected).
-> Release notes:
-> [`CHANGELOG.md`](https://github.com/allelix/allelix/blob/main/CHANGELOG.md).
+> **Status:** Production. Eight parser formats (including VCF + gVCF), four annotators (ClinVar + ClinPGx + GWAS Catalog + SNPedia), three enrichment sources (gnomAD + AlphaMissense + CADD), licensable-source gating for commercial users, dual-build ClinVar caches (GRCh37 + GRCh38), HTML/JSON/terminal reports, methylation + pharmacogenomics focused commands, report diffing, persistent config with commercial-mode safety switch. Build auto-detection from position data (ADR-0021). No regex on prose anywhere in production. The [Changelog](https://github.com/allelix/allelix/blob/main/CHANGELOG.md) tracks every release.
 
 ## Quickstart
 
@@ -60,20 +56,22 @@ See [Development](#development) for source installs and running tests, [Managing
 | MyHeritage DNA | ✓ | CSV, same structure as FTDNA. Detected by "MyHeritage" in comment header. Handles double-double-quoted field variant. |
 | Living DNA | ✓ | Tab-delimited despite `.csv` extension. Handles AX-, AFFX-prefixed and CHR:POS positional SNP IDs. |
 | FTDNA Illumina raw | ✓ | Tab-delimited variant of the FTDNA export (distinct from the CSV format above). `RSID/CHROMOSOME/POSITION/RESULT` columns. Build 37 default. |
+| FTDNA FamFinder | ✓ | Third FTDNA file shape: tab-delimited with **separate `ALLELE1` / `ALLELE2` columns** instead of a concatenated `RESULT`. Detected by the `famfinder` substring in the file header plus the 5-column canonical header. Build 37 default. |
 | VCF / gVCF | ✓ | REF/ALT encoding, `0/1` genotype notation. Plain VCF: absence at a position means reference. gVCF: explicit reference blocks (lines with `<NON_REF>` ALT and `END=` INFO) are skipped — they match nothing in any annotation database. Multi-sample files require `--sample <ID>`. Streams via stdlib; `.vcf.gz` handled transparently. Optional `pip install allelix[vcf-index]` enables pysam-backed tabix random access for fast `extract --snps` on huge VCFs. |
 
 Adding a new format means adding one file to `allelix/parsers/` and registering an instance in the `PARSERS` list in `allelix/parsers/__init__.py`.
 
-### v2.1+ roadmap
+### Roadmap
 
-| Feature | Notes |
+| Release | Theme |
 |---|---|
-| Per-source scoring | Magnitude breakdown by database. Users see which source drove the composite score. |
-| Annotator-level strand awareness (R-1) | Strand-flip matching wired into every annotator's carrier check. Basic `compare` strand support shipped in v1.1; full annotator integration deferred from v2.0.0. |
-| Good / Bad / Neutral repute | Per-annotation repute field. Reframes the report from "here's what's wrong" to "here's your full picture." Requires Annotation model change + renderer updates. |
-| PLINK import | Read .bed/.bim/.fam as an input format (complement to the v1.7.0 export). |
-| PharmCAT integration | Wrap CPIC's PharmCAT as an optional external engine for star-allele / diplotype calling. Requires VCF input (shipped in v2.0.0). |
-| Genome Watchtower | Real-time variant monitoring via database delta feeds. Privacy-preserving: server publishes universal feed, matching happens locally against your deviation set. Replaces full re-analysis with millisecond set intersection. |
+| **v2.2** | Annotation model expansion (cross-source conflict surfacing, risk-allele display, structured MTAG flag), custom-panel UX improvements, methylation panel retune + citations, ClinVar source switch (VCF → `variant_summary.txt`), CLI cleanups (`db clean` / `db path`). |
+| **v2.3** | Per-source magnitude decomposition, Good / Bad / Neutral annotation repute, JSON v3 (AI-legible output contract), plausibility flagging via zygosity × gnomAD MAF, ClinVar review-status weighting, functional-medicine +/− notation. |
+| **v2.4** | ACMG/AMP automated classification engine, variant consequence annotation (VEP-equivalent). |
+| **v2.5+** | CNVs and repeat-expansion support, dbSNP resolution for rsID-less VCFs, gnomAD genomes (non-coding population frequencies), supplemental genotype file merging. |
+| **v3.0** | Ancestry estimation (PCA + 1KG/HGDP reference panels), Polygenic Risk Score (PRS) integration. |
+
+Issues and milestones are tracked at [github.com/allelix/allelix/issues](https://github.com/allelix/allelix/issues). Annotator-level strand-aware carrier matching (R-1) shipped in v2.1.0's ADR-0035 cluster.
 
 ## Supported Databases
 
@@ -217,28 +215,44 @@ Allelix stores reference database caches at `~/.local/share/allelix/` (Linux/mac
 **The caches are disposable and re-downloadable.** Everything here was fetched by `allelix db update` and can be re-fetched at any time. There's no per-user state in the cache — your genotype files never enter this directory. Safe to delete to reclaim space (or to force a full refresh if you suspect a cache went stale):
 
 ```bash
-# Reclaim all ~16-22 GB
-rm -rf ~/.local/share/allelix/
+# Reclaim all ~16-22 GB, with size report and confirmation prompt
+allelix db clean
+
+# Preserve the CADD cache (avoids re-downloading the slowest one, ~5.8 GB)
+allelix db clean --keep-cadd
+
+# Show what would be deleted without acting
+allelix db clean --dry-run
 
-# Reclaim everything except CADD (avoids re-downloading the slowest one)
-find ~/.local/share/allelix/ -mindepth 1 ! -name 'cadd*.sqlite*' -delete
+# Scripted use — skip the confirmation prompt
+allelix db clean --yes
 
 # Re-populate from scratch next time you analyze a file
 allelix db update
 ```
 
-**The one thing worth backing up: `config.toml`.** It lives separately (XDG config dir, typically `~/.config/allelix/config.toml`) and stores your license assertions (commercial-mode toggle, CADD opt-in confirmation) and per-source enable/disable settings. It's the only non-reproducible state in the install. The caches will rebuild on the next `db update`; `config.toml` won't.
+`db clean` refuses to act on a directory that doesn't contain any recognized allelix cache files — a typo'd `--data-dir ~/Documents` won't result in `rm -rf` against an unrelated tree, even with `--yes`. Pass `--force` if you've staged caches under a non-standard name and want to delete them anyway.
+
+For scripting and backup integration, `allelix db path` prints the resolved data directory:
+
+```bash
+ALLELIX_DATA=$(allelix db path)
+du -sh "$ALLELIX_DATA"
+
+# --check additionally verifies the path is writable; exit non-zero if not
+allelix db path --check
+```
+
+**The one thing worth backing up: `config.toml`.** It lives separately (XDG config dir, typically `~/.config/allelix/config.toml`) and stores your license assertions (commercial-mode toggle, CADD opt-in confirmation) and per-source enable/disable settings. It's the only non-reproducible state in the install. The caches will rebuild on the next `db update`; `config.toml` won't. `allelix db clean` preserves `config.toml` even when it lives inside the data directory (older installs).
 
 To fully uninstall allelix and reclaim everything:
 
 ```bash
 pip uninstall allelix
-rm -rf ~/.local/share/allelix/    # reference database caches
+allelix db clean --yes            # reference database caches
 rm -rf ~/.config/allelix/         # license + source-toggle config
 ```
 
-A `allelix db clean` subcommand to automate the cache-clear step (with confirmation prompt and size report) is planned for v2.2 alongside `allelix db path` (prints the resolved data directory for scripting / backup integration).
-
 ## Data Sources & Licensing
 
 Allelix source code is licensed under the **GNU Affero General Public License v3.0 or later** (AGPL-3.0-or-later). Allelix ships with **zero third-party data**. All reference databases are downloaded by the user at runtime via `allelix db update`. Each database retains its original license on the user's machine:
@@ -347,6 +361,8 @@ pytest
 
 The pre-commit hook enforces `ruff check` + `ruff format --check`. If a commit is blocked, fix the underlying problem rather than skipping the hook.
 
+For the full real-data release-validation battery — every parser format, VCF/gVCF, PLINK round-trip, edge cases, the GIAB/1000G corpus — see [`test_data/FULL_TEST_PROTOCOL.md`](test_data/FULL_TEST_PROTOCOL.md). That document is the project's real-data testing story; running `pytest` covers the fast suite that gates every commit.
+
 ## License
 
 GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See `LICENSE`.

{allelix-2.1.1 → allelix-2.2.0}/allelix/annotators/__init__.py

@@ -57,18 +57,16 @@ def get_annotators(
     return [clinvar, pharmgkb, gwas, snpedia, gnomad, alphamissense, cadd]
 
 
-_ANNOTATOR_CLASSES: dict[str, type[Annotator]] = {
-    cls.name: cls
-    for cls in [
-        ClinVarAnnotator,
-        PharmGKBAnnotator,
-        GWASCatalogAnnotator,
-        SNPediaAnnotator,
-        GnomadAnnotator,
-        AlphaMissenseAnnotator,
-        CaddAnnotator,
-    ]
-}
+_ANNOTATOR_CLASS_LIST: list[type[Annotator]] = [
+    ClinVarAnnotator,
+    PharmGKBAnnotator,
+    GWASCatalogAnnotator,
+    SNPediaAnnotator,
+    GnomadAnnotator,
+    AlphaMissenseAnnotator,
+    CaddAnnotator,
+]
+_ANNOTATOR_CLASSES: dict[str, type[Annotator]] = {cls.name: cls for cls in _ANNOTATOR_CLASS_LIST}
 
 
 def get_annotator_class(name: str) -> type[Annotator] | None:

{allelix-2.1.1 → allelix-2.2.0}/allelix/annotators/base.py

@@ -4,7 +4,6 @@
 
 from __future__ import annotations
 
-import contextlib
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
 from enum import Enum, auto
@@ -141,43 +140,6 @@ class Annotator(ABC):
         """Bind the annotator to a data directory (created elsewhere)."""
         self.data_dir = data_dir
 
-    def __del__(self) -> None:
-        """Safety-net resource release on GC. Deliberately retained.
-
-        Status (v2.1.1 audit, GH #36):
-        - **Production callsites are clean.** ``run_analysis`` wires every
-          primary + enrichment annotator into ``contextlib.ExitStack``
-          (v2.0.2 fix). ``allelix/cli/utility.py`` lines 221 and 476 each
-          construct a ``GnomadAnnotator`` inside ``try / finally
-          gnomad.close()``. ``allelix/annotators/__init__.py`` returns a
-          list that the pipeline immediately wraps in ``ExitStack``.
-        - **Test callsites NOT yet clean.** ~27 sites in
-          ``tests/reports/test_pipeline.py`` instantiate annotators
-          directly without a context manager or explicit close. The
-          pipeline closes them via its own ``ExitStack`` during
-          ``run_analysis``, but the test still holds the closed-instance
-          reference, and the underlying sqlite3 ``Connection``'s GC
-          finalizer surfaces a ``ResourceWarning`` during the next test's
-          startup. pytest's ``error::PytestUnraisableExceptionWarning``
-          filter then converts it to a hard failure on the gate.
-
-        Removing ``__del__`` without first refactoring the test sites
-        therefore fails the gate (verified — 3 failures, all in
-        ``tests/reports/test_pipeline.py``, triggered by leaks from
-        earlier tests in the same file). The test-site refactor is
-        tracked separately; ``__del__`` stays as the safety net until
-        that lands. v2.1.x task — see the follow-up issue filed at
-        ``#36``-closure-time.
-
-        ``contextlib.suppress(Exception)`` is deliberate — ``__del__``
-        must never raise. GC timing and shutdown-ordering edges are
-        explicitly silenced; this is exactly the "if you must keep
-        ``__del__``, make absolutely sure it can never raise"
-        mitigation the audit recommended.
-        """
-        with contextlib.suppress(Exception):
-            self.close()
-
     def __enter__(self) -> Annotator:
         """Return self for `with` usage."""
         return self

{allelix-2.1.1 → allelix-2.2.0}/allelix/annotators/cadd.py

@@ -24,7 +24,7 @@ from __future__ import annotations
 
 import logging
 import sqlite3
-from typing import TYPE_CHECKING, ClassVar
+from typing import TYPE_CHECKING, Any, ClassVar
 
 from allelix.annotators.base import Annotator, LicenseDescriptor
 from allelix.databases._versions import CADD_SCHEMA_VERSION
@@ -90,9 +90,11 @@ class CaddAnnotator(Annotator):
         self._conn: sqlite3.Connection | None = None
         self._full_mode = full_mode
         self._tabix_path = data_dir / CADD_FULL_FILENAME
-        self._tabix: object | None = None
+        # pysam ships no type stubs (see [tool.mypy.overrides]); the tabix
+        # handle is held as Any so call sites can use `.fetch()` / `.close()`.
+        self._tabix: Any = None
         self._indel_tabix_path = data_dir / CADD_INDEL_FILENAME
-        self._indel_tabix: object | None = None
+        self._indel_tabix: Any = None
 
     def _connection(self) -> sqlite3.Connection:
         if self._conn is None:
@@ -104,11 +106,11 @@ class CaddAnnotator(Annotator):
             self._conn = sqlite3.connect(self._db_path)
         return self._conn
 
-    def _open_tabix(self) -> object:
+    def _open_tabix(self) -> Any:  # noqa: ANN401 — pysam ships no type stubs
         """Open the tabix file for full-mode queries."""
         if self._tabix is None:
             try:
-                import pysam  # type: ignore[import-untyped]
+                import pysam
             except ImportError:
                 raise ImportError(
                     "Full CADD mode requires pysam. Install with: pip install 'allelix[cadd]'"
@@ -122,7 +124,7 @@ class CaddAnnotator(Annotator):
             self._tabix = pysam.TabixFile(str(self._tabix_path))
         return self._tabix
 
-    def _open_indel_tabix(self) -> object | None:
+    def _open_indel_tabix(self) -> Any:  # noqa: ANN401 — pysam ships no type stubs
         """Open the indel tabix file. Returns None if file doesn't exist."""
         if self._indel_tabix is None:
             if not self._indel_tabix_path.exists():
@@ -131,7 +133,7 @@ class CaddAnnotator(Annotator):
             if not tbi.exists():
                 return None
             try:
-                import pysam  # type: ignore[import-untyped]
+                import pysam
             except ImportError:
                 return None
             self._indel_tabix = pysam.TabixFile(str(self._indel_tabix_path))