[Hoeze]

tl;dr: VariantSeqExtractor reads any reference with extract and chrom_sizes, checks intervals, variants and REFs against it, and takes extract(interval, variants, *, anchor_pos=None, pad_with_n=False). FastaStringExtractor returns uppercase sequences by default.

Strand and arguments:

• use_strand is a required keyword-only argument of FastaStringExtractor and VariantSeqExtractor. Before, the defaults differed (False and True), so a caller who relied on a default could get reverse-complemented sequences or not without noticing.
• The per-call use_strand of both extract methods is gone. The extractor has one strand handling.
• Both extract methods raise a TypeError for unknown arguments. Before, they swallowed them, so a typo like fixed_length=False passed silently.

Reference:

• kipoiseq2.extractors.base.SequenceExtractor is a protocol with extract(interval) and chrom_sizes. It replaces BaseExtractor, so a reference needs no base class.
• VariantSeqExtractor(reference, *, use_strand) takes the reference as its first argument and raises a TypeError for other objects. It replaces fasta_file and reference_sequence. For a FASTA file, pass FastaStringExtractor(path, use_strand=False).
• VariantSeqExtractor opens no file, so it has no close(). The caller owns the reference and closes it. Before, BaseExtractor closed the files in __del__.
• ref_seq_extractor and the deprecated alias fasta are gone.
• FastaStringExtractor is a context manager.
• FastaStringExtractor.chrom_sizes maps each chromosome to its length, from the index. The pyfaidx object fasta is private.
• FastaStringExtractor uppercases the sequences by default. The keyword-only uppercase=True replaces force_upper=False. uppercase=False keeps the case of the file, e.g. to find soft-masked repeats.
• Encoder and Tokenizer of kipoiseq2.encoders are case-sensitive, so they take the extracted sequences as they are, also in soft-masked repeats. For a lowercase letter, their error now points to FastaStringExtractor, which uppercases by default.
• FastaStringExtractor raises a ValueError for a gzip file that is not bgzip, or a bgzip file without a .gz or .bgz suffix. It raises an ImportError for a bgzip file if Biopython is missing. Before, pyfaidx raised a misleading ImportError or a UnicodeDecodeError.

Checks:

• FastaStringExtractor.extract raises a ValueError for an unknown chromosome and for an interval outside the chromosome. Before, an interval past the chromosome end gave a shorter sequence.
• VariantSeqExtractor.extract reads the chromosome length from the chrom_sizes of the reference, so chrom_len is gone. With pad_with_n=True, it fills the positions outside the chromosome with N. Otherwise it raises a ValueError.
• VariantSeqExtractor.extract raises a ValueError for a variant on another chromosome, a variant outside the chromosome, and a REF that differs from the reference. Before, it applied such variants without a sign. The REF check ignores case, so it also accepts the lowercase bases of a reference that was read with uppercase=False.

anchor_pos:

• One keyword replaces anchor and fixed_len. anchor_pos=None lets the length follow the variants, and an int keeps the width of the interval, anchored at that position. Before, fixed_len=False still needed an anchor without effect.
• anchor_pos must lie from interval.start to interval.end. Before, an anchor outside the interval was moved to the nearest end.
• The docstring states the rule for a variant at the anchor. A variant lies on the side of its REF, and a REF that spans the anchor is split there. So an insertion whose REF ends at the anchor lies left of it, while GenomeKit normalizes it and puts it right.
• is_padding is renamed to pad_with_n.

Internals: the variant sequences are built from (start, end, alt) tuples and strings instead of the classes Subsequence and IntervalSeqBuilder.

Verified:

• 4000 random cases give the same output as 0.1, byte for byte. They cover SNVs, insertions, deletions and MNVs, all strands, anchors in the interval, both length modes, and padding on and off. 10 cases raise a ValueError in both versions.
• New tests compare VariantSeqExtractor with GenomeKit outputs for the same reference and variants. 16 of the 18 cases agree. In the other two, the insertion lies at the anchor, so the tests keep kipoiseq2's value and name GenomeKit's.

BREAKING CHANGE: use_strand is a required keyword-only argument of FastaStringExtractor and VariantSeqExtractor. To keep the 0.1 behavior, pass use_strand=False to FastaStringExtractor and use_strand=True to VariantSeqExtractor. The extract methods no longer take use_strand, and raise a TypeError for unknown arguments. BaseExtractor is removed: a reference is any object with extract(interval) and chrom_sizes. VariantSeqExtractor(fasta_file=path, use_strand=u) becomes VariantSeqExtractor(FastaStringExtractor(path, use_strand=False), use_strand=u), and reference_sequence=extractor becomes the first argument. VariantSeqExtractor.close, ref_seq_extractor and fasta are removed. FastaStringExtractor reads uppercase sequences by default. The keyword-only uppercase=True replaces force_upper=False, and uppercase=False keeps the case of the file. FastaStringExtractor.fasta is private: use chrom_sizes. FastaStringExtractor.extract raises a ValueError for intervals outside the chromosome. VariantSeqExtractor.extract takes (interval, variants, *, anchor_pos=None, pad_with_n=False): anchor=a becomes anchor_pos=a, anchor=a, fixed_len=False becomes anchor_pos=None, and is_padding becomes pad_with_n. It no longer takes chrom_len, and raises a ValueError for an anchor_pos outside the interval, for positions outside the chromosome without pad_with_n=True, and for variants on another chromosome, outside the chromosome or with a REF that differs from the reference.

feat(extractors)!: require use_strand and reject unknown arguments
fix(extractors): raise a clear error for unreadable FASTA files
feat(extractors)!: uppercase FASTA sequences by default
feat(extractors)!: check intervals against the chromosome sizes
feat(extractors)!: check the chrom and REF of variants
feat(extractors)!: merge anchor and fixed_len into anchor_pos