allelix 2.1.1

v2.1.1

on Python PyPI

Patch release. Focus: docs drift cleanup — a stale SECURITY.md "Supported versions" table, a missing ADR index entry, sparse operational docs — plus one structural refactor that eliminates an internal-field leak-by-omission risk at the model boundary. No user-facing behavior changes; existing v2.1.0 caches and reports stay current.

Upgrade

pip install --upgrade allelix

No cache invalidation. v2.1.1 ships zero schema or interpreter changes on any annotator cache. The ClinVar interpreter version stays at 2 (v2.0.1 bump); PharmGKB / gnomAD / AlphaMissense / CADD interpreter / schema versions all unchanged. JSON schema_version stays at 5 (set in v2.1.0). Existing v2.1.0 caches remain current; only the standard allelix db update freshness check runs.

Highlights

• SECURITY.md "Supported versions" table was stuck at 1.8.x while v1.9.0, v2.0.0, v2.0.1, v2.0.2, and v2.1.0 all shipped. Anyone reading the public security policy was being told only 1.8.x got security fixes — for over a year. Table corrected to 2.1.x ✓ / < 2.1 ✗. The out-of-scope third-party data list was also bumped: PharmGKB → "ClinPGx (formerly PharmGKB)" to match the v2.0+ display-name conventions, plus AlphaMissense and CADD added (annotators shipped after SECURITY.md was last touched). The reporting URL was already current.
• Operational and data-lifecycle README pass. New "Managing your data" section under the database-sizes block now documents where the caches live (default ~/.local/share/allelix/), the per-file footprint (~16 GB default install, ~22 GB with the CADD opt-in), the disposability rule (caches are re-downloadable; safe to delete to reclaim space), the manual cleanup path, config.toml as the only non-reproducible state worth backing up, and the full uninstall procedure. A new "Troubleshooting" section covers six common failure states: the Python 3.10 ImportError: cannot import name 'UTC' from 'datetime'; partial allelix db update failures (idempotent re-run); "not ready" annotators after a release upgrade; build mismatch warnings (real-world MHG / Tempus header drift, GRCh36 external-liftover path); the signal-driven staleness model; and a reminder that report output files contain real annotations of your genome and should be treated as sensitive. The Python 3.11+ requirement is promoted from a buried sentence to the first line of Quickstart with the exact ImportError users see on 3.10 (grep-able). The CADD entry in the supported-databases table was tightened from a full-paragraph cell to a one-line summary plus a new "CADD modes" subsection that holds the cache-vs-full-mode explanation. The status banner refreshes from a stale "Latest: v2.0.0" to v2.1.0 with the ADR-0035 summary.
• Centralized internal-field exclusion for public Annotation serialization. Three production sites previously duplicated the same inline filter (asdict(a) minus is_must_include): the JSON report's main annotations list, the JSON diff's "new" entries, and the diff change-record serializer. A fourth public-output path that forgot the filter would have leaked an internal boolean into reports without breaking anything obvious at PR time. New allelix.models.annotation_to_public_dict() helper plus a module-level _INTERNAL_ANNOTATION_FIELDS frozenset are the single place to remember the rule. All three production serializers now route through the helper. Adding a new internal-only field is one line in the frozenset; every existing serializer picks up the exclusion automatically. No JSON schema change — same fields produced, same values, same shape.
• __del__ removal audit completed for production code. v2.0.2 deferred the full Annotator.__del__ removal pending an audit of every callsite. v2.1.1 finishes the audit: zero production paths rely on __del__ for SQLite-connection cleanup. The pipeline wires every primary and enrichment annotator into a contextlib.ExitStack (the v2.0.2 partial fix); two CLI utility paths construct annotators inside explicit try / finally close(); the annotators factory returns a list the pipeline immediately wraps. The remaining work to actually remove __del__ is a refactor of ~27 test sites that construct annotators outside a context manager and surface ResourceWarnings during the next test's startup. That refactor is filed separately and ships in the next patch; until then, __del__ stays as the safety net with an updated docstring documenting the partial-closure state.

Known limitations

Carried forward from v2.0.x / v2.1.0 — no new structural debt added in this patch.

• ClinVar per-(classification, condition) pairing still surfaces the primary aggregate classification plus the union of associated conditions; per-1:1 pairing requires the structured submission_summary.txt.gz export and is tracked for a future minor release.
• Annotator.__del__ removal pending the test-site refactor. v2.1.1 closed the production-side audit; the test-side cleanup lands in the next patch.
• PharmGKB → ClinPGx rebrand. PharmGKB officially rebranded to ClinPGx in July 2025 (redirects live). The allelix-internal annotator name, cache filename, and source string remain pharmgkb for backward compatibility; the rename bundles with the next schema-breaking change so users rebuild caches once.

Security

• SECURITY.md "Supported versions" table refreshed. See Highlights above.

Changed

• Internal-field exclusion centralized via annotation_to_public_dict(). See Highlights above for the full motivation and structure.

Documentation

• README operational pass. New "Managing your data" + "Troubleshooting" sections; Python 3.11+ requirement promoted to first line of Quickstart with the grep-able ImportError; CADD table cell tightened to a summary plus a new "CADD modes" subsection; status banner refreshed to v2.1.0 with the ADR-0035 summary.
• __del__ removal audit — partial closure. Production callsites verified context-managed; docstring updated documenting the partial-closure state and the test-side blocker. Full removal lands in the next patch.
• ADR-0035 added to the ADR index. The design doc shipped in v2.1.0 but the index was one entry short until v2.1.1. Index entry added with the supersedes note that ADR-0035 partially supersedes ADR-0033's strict-per-field schema-version bump policy for documented coordinated changes.

Verification

Full pytest: 1,578 pass / 0 skip / 0 warnings, 94.25% coverage. Ruff clean. plink2 v2.0.0-a.6.5 installed so the no-silent-skips invariant from v2.0.2 was exercised end-to-end. No carrier-count shift expected on any input — v2.1.1 is docs / internal-refactor only, no behavior surface touched.