BioThings Client

Warnings

• breaking Support for Python 3.6 was dropped in version 0.5.0. The last version to support Python 3.6 is 0.4.1. Python <=3.5 (including 2.7) was dropped as of version 0.4.0, with 0.3.1 being the last supporting version.
  Fix: Upgrade to Python 3.7 or newer. For caching features, Python 3.8 or newer is required.
• breaking Version 0.4.0 replaced the underlying HTTP client from `requests` to `httpx` and the caching library from `requests_cache` to `hishel`. Code directly interacting with these internal components or expecting their behavior might break.
  Fix: Review any code that relied on `requests` or `requests_cache` internals or direct imports. Update to use the `biothings_client`'s public API or `httpx` and `hishel` directly if custom HTTP/caching logic is needed.
• breaking Version 0.4.0 introduced an `ImportError: cannot import name 'alwayslist' from 'biothings_client'` for some downstream libraries. This indicates a change in the public API or internal structure.
  Fix: Ensure `biothings_client` is updated to a version that includes fixes for this import error (e.g., 0.4.1 or later) or adjust imports in dependent code.
• gotcha The caching feature (`biothings_client[caching]`) explicitly requires Python >=3.8. It will not be available or function correctly on Python 3.7.
  Fix: If caching is desired, ensure your Python environment is 3.8 or newer.
• gotcha Older, specific BioThings API clients (e.g., `mygene.py`, `myvariant.py`) are now thin wrappers around `biothings_client` and are expected to be deprecated in the future.
  Fix: New projects and existing projects should migrate to using `biothings_client` directly via `from biothings_client import get_client` to ensure future compatibility.
• gotcha When requesting data as pandas DataFrames (using `as_dataframe=True`), especially for APIs returning very large or complex objects (e.g., `MyChem.info`), deeply nested data structures might lead to hard-to-use DataFrames or even cause hangs.
  Fix: Avoid requesting entire objects as DataFrames without specifying particular fields, or manually parse the JSON response if the structure is too complex for direct DataFrame conversion.

Install

• pip install biothings_client Standard installation
• pip install biothings_client[dataframe] With Pandas DataFrame support
• pip install biothings_client[caching] With local SQLite caching (Python >=3.8)

Imports

• get_client

  from biothings_client import get_client

  The `biothings_client` is the unified client. Older, specific clients like `mygene` or `myvariant` are now wrappers and may be deprecated.

Quickstart

This quickstart demonstrates how to instantiate clients for MyGene.info and MyVariant.info, fetch a single gene by ID, query multiple genes by symbol, and fetch a variant annotation. It uses common fields for demonstration.

from biothings_client import get_client

# Get a client for the MyGene.info API
mg_client = get_client("gene")

# Fetch gene annotation for a specific Entrez gene ID
gene_id = "1017" # Example: CDK2 gene
result = mg_client.getgene(gene_id, fields="symbol,name,entrezgene")
print(f"Gene ID {gene_id}: {result.get('symbol')} - {result.get('name')}")

# Query multiple genes by symbol
gene_symbols = ["CDK2", "BRCA1", "TP53"]
results = mg_client.querymany(gene_symbols, scopes="symbol", fields="name,entrezgene,ensembl.gene")
for res in results:
    print(f"Symbol: {res.get('query')}, Name: {res.get('name')}, Entrez: {res.get('entrezgene')}")

# Get a client for the MyVariant.info API
mv_client = get_client("variant")

# Fetch variant annotation
variant_id = "chr1:g.140453134T>C"
variant_result = mv_client.getvariant(variant_id)
# print(f"Variant {variant_id}: {variant_result}") # Uncomment to see full result
print(f"Variant {variant_id}: {variant_result.get('_id')} - {variant_result.get('dbsnp', {}).get('rsid')}")