Authoritative Sources

Last researched: 2026-07-23

Skill baseline: pysam 0.24.0, released 2026-04-27, wrapping HTSlib/samtools/bcftools 1.23.1.

Use these sources in priority order when refreshing this skill. Do not assume that the newest standalone HTSlib release is the version embedded in the current pysam wheel.

Pysam Release and Package Metadata

• pysam on PyPI — current published version, release date, wheels, release history, and provenance attestations
• Pysam release notes — 0.24 CRAM changes, Python support, bundled component versions, bug fixes, and deprecations
• pysam-developers/pysam — upstream source and current development state
• pysam 0.24.0 source tag — version-specific implementation and tests

As of the research date, PyPI identifies 0.24.0 as latest. The 0.24 release notes state:

• tested Python versions: 3.8 through 3.14
• wheels: macOS and Linux, ARM and x86-64
• bundled HTSlib/samtools/bcftools: 1.23.1
• default newly written CRAM: 3.1
• implicit EBI CRAM reference fetching: removed
• format_options: Python str values work as documented
• top-level CIGAR constants remain compatibility aliases; prefer pysam.CIGAR_OPS

Re-check all of these before changing the version pin.

Official Pysam Documentation

• Documentation index
• Installation
• Usage guide
• API reference
• FAQ
• Release notes
• Glossary

Use the API reference for signatures and documented defaults. Use the FAQ for iterator lifetime, threading, coordinate, pileup, and quality-editing behavior. Where prose in the older usage guide conflicts with the current API, verify against the 0.24 source/tests and installed runtime.

One known example: a real Python file object exposing fileno() works with AlignmentFile, while io.BytesIO does not. The API constructor documents file-object support; the usage guide's broad statement about "true python file objects" is too general.

Bundled Tool Manuals

Pysam 0.24 wraps the 1.23.1 tool line. Consult manuals matching that line when using dispatchers:

• samtools 1.23 manual
• bcftools 1.23 manual
• tabix 1.23 manual
• bgzip 1.23 manual
• faidx 1.23 format/manual
• HTSlib documentation index

Pysam dispatchers emulate command-line subcommands but capture stdout/stderr. The pysam usage guide, not only the tool manual, defines catch_stdout, save_stdout, split_lines, get_messages(), and SamtoolsError.

CRAM References

• Pysam 0.24 release notes — CRAM 3.1 default and removal of implicit EBI lookup
• Samtools reference-sequence guidance — CRAM reference search order and REF_PATH/REF_CACHE
• Using CRAM within Samtools — reference-based compression, M5 tags, local caches, and workflow concepts

The older CRAM workflow page describes historical fallback to EBI. For pysam 0.24/HTSlib 1.23 behavior, the 0.24 release notes and matching samtools manual take precedence: implicit EBI lookup is no longer the default.

Canonical Format Specifications

• HTS format specifications index
• SAM/BAM and BAI specification
• SAM optional tags specification
• CRAM 3 specification
• VCF 4.5 specification
• BCF 2 quick reference
• Tabix index specification
• CSI specification
• BED 1 specification

Use format specifications for coordinate fields, flags, tags, header semantics, binary encodings, and index limits. Use pysam documentation for how those concepts are translated into Python properties.

Research Queries Used for This Refresh

Parallel web search/extract was used for:

• current stable pysam version, date, Python range, and wheel platforms
• recent 0.22–0.24 release changes and deprecations
• current AlignmentFile, pileup, VariantFile, FASTA/FASTQ, and Tabix APIs
• current coordinate, iterator, thread-safety, and pileup FAQ guidance
• HTSlib CRAM reference behavior and canonical format specifications

Context7 cross-checked the upstream source documentation for:

• pysam 0.24 release/CRAM behavior
• AlignmentFile signatures and defaults
• VariantFile, FastaFile, FastxFile, and TabixFile APIs

No generated research JSON is part of this skill.

Refresh Checklist

When updating:

1. Check PyPI for the newest published pysam.
2. Read all release notes since the pinned version.
3. Record the embedded HTSlib/samtools/bcftools version.
4. Verify supported Python versions and wheel platforms.
5. Re-check CRAM defaults and reference lookup.
6. Compare API signatures in api.html and the tagged source.
7. Run bundled scripts against the new version.
8. Re-run Agent Skills validation and the security scanner.