Complete typed collection traversal and effect-model contracts

Open
  • Is something wrong?
#653 3 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Refactor
Clarity
Mostly clear
Activity status
Active
Tech stack
python
Domain
backend-api-design, testing-qa

Research direction

Start with docs/dev/api-quality.md and docs/conventions.md, then inspect the shared Sercol collection base and effect subclasses used by the load_vcf to VariantCollection to MutationEffect path. Run the stated mypy consumer checks and use the reproduction to trace iteration and indexing; completion requires typed traversal and documented model protocols, with static checks rejecting incorrect result usage and runtime tests for changed collection behavior.

Written by the indexing model from the issue text.

Description

Follow-up to the public API sweep in #651.

The first pass gives ordinary annotation methods concrete result types and fixes base effect sequence/offset/tri-state annotations. It does not yet provide a fully typed traversal of those results.

Reproduced with mypy 2.4.0 using the current sweep branch:

variant.effects()                 # EffectCollection
next(iter(variants))              # Any
next(iter(variant.effects()))     # Any

The shared Sercol base and legacy subclass methods leave iteration, indexing, cloning, grouping, and metadata-preserving set operations gradual. Other effect attributes and subclass property overrides still need an audit. The first pass types attached MutantTranscript/ORFAnnotation models and leaves present transcript/gene adapter objects explicitly gradual, avoiding false None-only inference until their shared protocols are defined.

Scope:

  • Trace a typed load_vcf -> VariantCollection -> effects -> MutationEffect loop, including integer indexing, slicing, filtering, cloning and grouping.
  • Preserve structural variants, effect subclasses, grouping keys, collection subclasses, ordering, provenance and metadata. Coordinate shared collection typing upstream when appropriate rather than duplicating its behavior.
  • Describe actual transcript/model protocols accepted by ORF and RNA integrations; do not narrow them to one concrete implementation just to satisfy a checker.
  • Add nullable sequence/offset/model and tri-state change annotations consistently across effect overrides, plus complete NumPy-style Returns/Raises/coordinate documentation.
  • Extend static consumer checks to reject wrong element/result usage, with runtime tests for any changed collection implementation. A runtime Protocol isinstance survey is not sufficient.

Keep this independent of scientific changes to cDNA availability (#179) or uncertainty composition (#421/#423). The audit and conventions live in docs/dev/api-quality.md and docs/conventions.md.

Whole-package diagnostic

Running python -m mypy --config-file <sweep>/pyproject.toml varcode over all 79 source files reports 217 errors in 38 files on the 10.22.0 baseline and 212 errors in 35 files on the rebased sweep commit b0904c1. This is outside the normal gradual lint target, which passes across its 12 selected implementation/consumer files.

The remaining diagnostics include writable base attributes overridden by properties, untyped collections/metadata, and subclass constructor invariants that are not expressed to the checker. Correct optional base sequence types also expose indexing sites whose concrete subclasses guarantee a sequence; express and verify those invariants rather than blindly casting away None. This diagnostic is an audit of incomplete typing, not a claim of 212 demonstrated runtime defects.

Dominant language
Python
Stars
88
Forks
28
Avg merge
3h 10m
Merged PRs (30d)
53

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from openvax/varcode

All issues in openvax/varcode

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.