bkbit.utils.ncbi_taxonomy_cache module

Lazy, self-provisioning access to NCBI taxonomy names.

bkbit needs three lookups from the NCBI taxonomy: scientific name -> taxon id, taxon id -> scientific name, and taxon id -> common name. This module serves those lookups from two layers, in order:

  1. A subset bundled inside the wheel (ncbi_taxonomy_data/taxonomy_subset.json.gz, ~600KB, every taxon that has a GenBank common name). No network, no setup, loads in milliseconds. This covers effectively every organism a genome annotation pipeline is run against.

  2. The full NCBI taxonomy dump, downloaded and cached on first use for taxa that are not in the subset. The cache lives in a per-user cache directory - never inside site-packages, which may be read-only and is wiped on upgrade.

Nothing here runs at import time: the bundled subset is loaded on first lookup and the full dump is only fetched if a lookup actually misses the subset.

Environment variables:

BKBIT_DATA_DIR: Overrides the cache directory used for the full taxonomy. BKBIT_NO_DOWNLOAD: If set to a truthy value, a lookup that misses the

bundled subset raises instead of downloading the full taxonomy.

bkbit.utils.ncbi_taxonomy_cache.build_full_cache(url: str = 'https://ftp.ncbi.nih.gov/pub/taxonomy/taxdmp.zip', cache_dir: Path | None = None) → Dict[str, Path][source]

Downloads the NCBI taxdump and writes the full cache to disk.

Parameters:

  • url – The URL of the taxdump zip to download and process.

  • cache_dir – Destination directory. Defaults to data_dir().

Returns:

The written cache paths, as returned by full_cache_paths().

Return type:

dict

bkbit.utils.ncbi_taxonomy_cache.data_dir() → Path[source]

Returns the directory bkbit uses for the downloaded NCBI taxonomy cache.

Honours BKBIT_DATA_DIR if set, otherwise falls back to the platform’s per-user cache directory (which respects XDG_CACHE_HOME on Linux).

bkbit.utils.ncbi_taxonomy_cache.download_and_extract_zip_in_memory(url: str = 'https://ftp.ncbi.nih.gov/pub/taxonomy/taxdmp.zip') → str[source]

Downloads the taxdump zip from the given URL and returns ‘names.dmp’.

Parameters:

url – The URL of the zip file to download.

Returns:

The content of the ‘names.dmp’ file as a string.

Return type:

str

Raises:

requests.exceptions.HTTPError – If the download fails.

bkbit.utils.ncbi_taxonomy_cache.ensure_full_cache(reload: bool = False, cache_dir: Path | None = None) → Path[source]

Makes sure the full taxonomy cache exists on disk, downloading if needed.

Parameters:

  • reload – Re-download even if a complete cache is already present.

  • cache_dir – Destination directory. Defaults to data_dir().

Returns:

The directory containing the cache.

Return type:

Path

bkbit.utils.ncbi_taxonomy_cache.full_cache_paths(cache_dir: Path | None = None) → Dict[str, Path][source]

Returns the paths of the three JSON files that make up the full cache.

Parameters:

cache_dir – Directory to resolve against. Defaults to data_dir().

Returns:

Keys scientific, common, and scientific_to_taxid.

Return type:

dict

bkbit.utils.ncbi_taxonomy_cache.lookup_common_name(taxid: str) → str | None[source]

Returns the GenBank common name for a taxon id, or None if it has none.

Parameters:

taxid – NCBI taxon id, as a string, e.g. "9606".

bkbit.utils.ncbi_taxonomy_cache.lookup_scientific_name(taxid: str) → str | None[source]

Returns the scientific name for a taxon id, or None if it is unknown.

Parameters:

taxid – NCBI taxon id, as a string, e.g. "9606".

bkbit.utils.ncbi_taxonomy_cache.lookup_taxid(scientific_name: str) → str | None[source]

Returns the taxon id for a scientific name, or None if it is unknown.

Parameters:

scientific_name – Scientific name, e.g. "Homo sapiens".

bkbit.utils.ncbi_taxonomy_cache.parse_dmp_content(dmp_content: str) → Tuple[dict, dict, dict][source]

Parses the content of a names.dmp file into taxonomy name lookups.

Parameters:

dmp_content – The content of the DMP file.

Returns:

(taxid_to_scientific_name, taxid_to_common_name, scientific_name_to_taxid).

Return type:

tuple