Skip to content

Release notes

Changes in each published version, newest first. These notes start at 2.27.2; earlier versions are available as Git tags.

2.34.7

Maintenance only; no behaviour change for supported use. Removes the unused EnsemblRelease.normalize_init_values classmethod, which had no callers in PyEnsembl or the packages that depend on it (#522), and stops pinning pickle protocol 2 (a Python 2 leftover) when writing cache files; existing cache files still load. Also deletes the finished implementation plans under tasks/ and the one-off scripts/benchmark_gtf_indexing.py (#513).

2.34.6

pyensembl list no longer reports the HGNC alias snapshot cached by GeneNameAliases.download_hgnc() as a custom genome (#508). The scan for custom genomes now skips every directory PyEnsembl itself keeps under the cache root for other data: dna_cache, aliases and dated_releases. Those three names are therefore reserved: a custom genome installed with one of them as its --reference-name is not listed.

2.34.5

Define Locus.__bool__ returning True so truthiness checks (bool(transcript) or if transcript:) evaluate in constant time instead of falling back to Transcript.__len__() and querying the exon SQLite table on cold or unindexed genomes (#534). len(locus) and len(transcript) are unchanged.

2.34.4

Exit with argparse status 2 when a selection resolves to no genomes (#505), before installation, inspection, verification or deletion can run. Automation can now distinguish an empty selection from successful work.

2.34.3

Make develop.sh directly executable and install through the Python selected by PYTHON (default python), with additional pip arguments forwarded.

2.34.2

Remove the obsolete Polars-to-pandas conversion in database creation: the GTF loader already requests pandas output. Remove the excluded getting-started source stub while retaining its generated redirect to the home page (#522).

2.34.1

2.34.0 was not published. Its release stopped on macOS, where three CLI tests failed. They compared a cache's files before and after running the CLI, including each file's ctime. macOS can tag a file that the CLI opens with com.apple.provenance, which changes its ctime and nothing else. Those comparisons now leave out ctime and still compare content, mode, inode, size and mtime. This release contains 2.34.0's changes:

Transcript.stop_codon_completed_by_polyadenylation identifies mitochondrial reading frames that end in T or TA and get the rest of a TAA stop codon from the poly(A) tail (#527). In human these are MT-ND1, MT-ND2, MT-CO3, MT-ND3, MT-ND4 and MT-CYB. Ensembl annotates no stop codon for them, so coding_sequence and three_prime_utr_sequence were None. For these transcripts coding_sequence now runs from the start codon to the end of the transcript, ending in the T or TA, and three_prime_utr_sequence is empty. complete is still False, since there's no annotated stop codon.

The property requires a mitochondrial contig and a genetic code in which TAA is a stop: not NCBI tables 14 or 33, where it encodes tyrosine. Other transcripts without a stop codon are unchanged.

2.33.2

Lookups by a feature type or attribute that an annotation lacks no longer raise SQLite errors. The index has a table only for the features a GTF contains and a column only for the attributes it uses, so a GTF without start_codon, stop_codon or CDS rows made Transcript.complete and contains_start_codon fail with no such table (#499), and one without transcript_name made transcripts_by_name fail with no such column (#502). Such a lookup now matches nothing: complete, contains_start_codon and start_codon_complete are False, and transcripts_by_name raises the same ValueError as for any name not in the annotation. Accessors that require a feature, such as start_codon_positions or coding_sequence_position_ranges, raise ValueError instead of sqlite3.OperationalError. Existing indexes are used as they are.

2.33.1

pyensembl available with --species, --assembly or another selector printed a TypeError traceback instead of its table whenever the selection included a numbered release, as in pyensembl available --species human (#507). pyensembl verify --release 75 failed the same way. Command-line tables now print numbered releases like any other value. --json output and caches are unchanged.

2.33.0

Tab completion for the pyensembl command (#514), and a fast import (#510). import pyensembl no longer reads the genome cache or imports datacache or SQLite: public names load from their submodules on first use, and ensembl_grch36/37/38 are chosen from the cache the first time each is used rather than at import. from pyensembl import ..., pyensembl.X and pyensembl.<submodule> work as before. The command line imports genome code only when an action runs, so a Tab press takes about 40 ms instead of 125 ms. --release completes the releases in the cache, from directory names only, and --species the registered species names; enable completion with activate-global-python-argcomplete. Adds the argcomplete dependency and requires datacache 1.30, whose lazy import keeps --release completion under 100 ms. Caches, output and exit codes are unchanged.

2.32.6

Install only what the library imports: numpy and tinytimer move from the runtime dependencies to the dev extra, because only the tests use them (#511). Ruff's target version is set explicitly to Python 3.11, matching requires-python. Code, caches and output are unchanged.

2.32.5

Documentation only. The README follows the shared OpenVax layout (Install, Quick start, Command line, Documentation, Development, License) and its quick-start output is now checked with the documentation examples. The documentation site lists the command-line reference before the API reference and includes these release notes. The cache guide puts installation, status and disk-space tasks before file-naming and storage details. Links to sections of earlier READMEs still resolve.

2.32.4

Split the pyensembl command's run() into public, documented per-action functions in pyensembl.shell (validate_arguments, run_prune, run_available, require_ensembl_releases, run_verify, run_install), and let run(argv) take an explicit argument list like the other OpenVax command-line tools. Flags, messages and exit codes are unchanged: only argument mistakes become one-line errors, while listing, checksum and data failures keep their tracebacks. Existing caches are unaffected.

2.32.3

Remove the obsolete typechecks runtime dependency (#456). Keep built-in string/integer validation, including boolean/integer subclasses, TypeError for invalid types and ValueError for empty column names. Validate chromosome types before memoization so a cached integer cannot admit a float or NumPy integer (#497). Add initial type annotations, a py.typed marker and focused mypy checks to lint/CI. Existing on-disk caches and indexes remain usable without changes.

2.32.2

Require datacache 1.29.3 so explicit install --overwrite can recover a corrupt SQLite annotation index (#495). Recovery preserves the database inode, hard links, ownership and permissions; a failed rebuild leaves the old database intact. Normal installation and queries retain existing cache behavior. No reinstall, migration or automatic repair is required.

2.32.1

Finish #387's CLI error handling and fix #494. Missing annotation or reference DNA files now produce a concise runtime error (exit 1), while invalid arguments remain argparse errors (exit 2). Explicitly empty GTF/FASTA paths, mirrors and server URLs are rejected before dataset selection. Malformed data, checksum failures and unexpected internal errors retain their tracebacks. Existing cached data, source paths and indexing behavior are unchanged.

2.32.0

  • Finish the unified numbered/dated release catalogue with scoped, reproducible full-GTF comparison evidence, explicit latest selection, and filtered available output. Serialization pins the concrete selection; existing defaults and cache paths are unchanged.
  • Verify new canonical dated GTF/cDNA/peptide downloads against upstream MD5s. Add explicit read-only verify_sources() / pyensembl verify, preserve checksum pins through serialization, and warn for known subset annotations. Existing caches need no new metadata, migration, reinstall, or reindex.
  • Let reference-name lookup and installed listings reuse known explicit-accession dated cache layouts, while keeping installed numbered releases preferred.

2.31.2

Include required test helpers and fixtures in source distributions (#489). Exclude developer-local data and generated cache files. CI and deployment now extract the source archive and run offline tests before publication. Wheel contents and installed genome caches are unchanged.

2.31.1

Use the species' main (nuclear) genetic code for arbitrary scaffold names and reference lookups without a contig (#490). This corrects the unnecessarily unresolved result in 2.31.0. Preserve nonstandard nuclear codes, recognized mitochondrial/plastid assignments, and explicit source/reference overrides. Unknown species or explicitly unset tables remain unresolved. Existing caches and serialized metadata stay usable in place without migration or reindexing.

2.31.0

Expose offline reference and transcript genetic-code metadata (#481). Genome.genetic_code() returns a compartment-specific NCBI table assignment with provenance or an explicit unknown reason. Transcript.translation_table uses annotation declarations before reference/taxonomy defaults. Retain taxon and species-ancestor IDs, including metadata returned by the new Ensembl API. One reference_metadata argument supports custom contigs and assignments.

Pin metadata through JSON, pickle and mirrors. Existing source paths, cached files and indexes remain unchanged: old indexes can read source declarations from the installed GTF into memory without downloads, migration or reindexing.

2.30.1

Support tomato SL4.0 in Ensembl Genomes 63 (#453). Use its renamed source directory and published cDNA/peptide files without requesting a nonexistent ncRNA FASTA. Missing required files still fail installation. Existing SL3.0 numbered and dated selections keep their URLs, cache paths, and indexes.

2.30.0

Remove the unused EnsemblAnnotation class, module, and package export. Use EnsemblRelease(date, assembly_accession=accession, **options) for the same explicit dated selection. The removed class's imports and serialized objects are no longer supported. Existing cache files, directory layouts, and indexes remain reusable in place; no reinstall or migration is needed.

Exercise numbered, dated, inferred and explicit assembly choices by installing tiny GTF/FASTA datasets, querying the resulting indexes, and reopening the caches offline. Cover human, dog breeds, providers, coverage, optional DNA, custom labels/directories and serialization.

Fix reopening previously installed private DNA attachments rewriting the current attachment manifest (#485). Reuse existing indexed/materialized sources without writes, and track new download-only local attachments individually so switching between them also preserves the manifest.

2.28.3

Share new reference DNA downloads and indexes across dated Ensembl releases when accession, provider, masking, upstream MD5 and compressed size agree (#454). Verify downloaded bytes against the manifest before publication. Missing metadata keeps URLs separate. Existing private dated DNA stays usable in place, without migration, reindexing or metadata rewrites; numbered-release shared caches retain their paths. Both EnsemblRelease and EnsemblAnnotation benefit. Clarify that ordinary dated releases need only EnsemblRelease; EnsemblAnnotation is for explicit assembly, provider and coverage selection.

2.28.2

Fix local transcript/protein FASTA index collisions (#467). Newly created indexes identify the original source path and file contents; new cached copies also identify their original paths. Changed local inputs select fresh indexes, including in loaded readers, without deleting older generations. Unchanged gzip copies with decompression enabled are reused without copying again. Existing basename-only sources and indexes stay usable in place, with no reinstall or automatic migration; they retain their historical source assumptions.

2.28.0

Add EnsemblRelease(...).with_mirror(URL) to reopen the same source-specific Genome installed by pyensembl install --custom-mirror URL (#470). The CLI uses this shared constructor. Mirror downloads and indexes retain their own identity; the default EnsemblRelease constructor continues to select canonical sources. See the cache guide for installation, Python/Varcode use and migration.

2.27.8

Restore in-place reuse of existing basename-only remote caches and their SQLite/FASTA indexes after the 2.27.5 compatibility regression. Existing installations need no reinstall, migration, renaming, or reindexing. New downloads retain URL-specific identity; legacy caches retain their historical source assumptions. Explicit refreshes leave legacy files intact.

2.27.2

Transcript.protein_id, Transcript.protein and Transcript.protein_sequence now return None when a noncoding-only or custom annotation has no CDS protein_id column. This fixes the missing-table error reported in #459 without changing canonical protein identities in ordinary annotations.