{"id":2412,"library":"biothings-client","title":"BioThings Client","description":"biothings_client is an easy-to-use Python wrapper to access any BioThings API-based backend service. It provides unified access to various biological data APIs such as MyGene.Info, MyVariant.Info, MyChem.Info, MyDisease.Info, MyGeneset.Info, and MyTaxon.Info. The library is actively maintained, with the current stable version being 0.5.0, and typically sees updates and bug fixes on a regular cadence.","status":"active","version":"0.5.0","language":"en","source_language":"en","source_url":"https://github.com/biothings/biothings_client.py","tags":["biology","bioinformatics","API client","gene","variant","chemical","disease","genetics","data-access"],"install":[{"cmd":"pip install biothings_client","lang":"bash","label":"Standard installation"},{"cmd":"pip install biothings_client[dataframe]","lang":"bash","label":"With Pandas DataFrame support"},{"cmd":"pip install biothings_client[caching]","lang":"bash","label":"With local SQLite caching (Python >=3.8)"}],"dependencies":[{"reason":"Required for returning query results as DataFrame objects, installed via `biothings_client[dataframe]` extra.","package":"pandas","optional":true},{"reason":"Required for local SQLite caching, installed via `biothings_client[caching]` extra.","package":"hishel","optional":true},{"reason":"Required for local SQLite caching, installed via `biothings_client[caching]` extra.","package":"anysqlite","optional":true}],"imports":[{"note":"The `biothings_client` is the unified client. Older, specific clients like `mygene` or `myvariant` are now wrappers and may be deprecated.","wrong":"import mygene\nmg = mygene.MyGeneInfo()","symbol":"get_client","correct":"from biothings_client import get_client"}],"quickstart":{"code":"from biothings_client import get_client\n\n# Get a client for the MyGene.info API\nmg_client = get_client(\"gene\")\n\n# Fetch gene annotation for a specific Entrez gene ID\ngene_id = \"1017\" # Example: CDK2 gene\nresult = mg_client.getgene(gene_id, fields=\"symbol,name,entrezgene\")\nprint(f\"Gene ID {gene_id}: {result.get('symbol')} - {result.get('name')}\")\n\n# Query multiple genes by symbol\ngene_symbols = [\"CDK2\", \"BRCA1\", \"TP53\"]\nresults = mg_client.querymany(gene_symbols, scopes=\"symbol\", fields=\"name,entrezgene,ensembl.gene\")\nfor res in results:\n    print(f\"Symbol: {res.get('query')}, Name: {res.get('name')}, Entrez: {res.get('entrezgene')}\")\n\n# Get a client for the MyVariant.info API\nmv_client = get_client(\"variant\")\n\n# Fetch variant annotation\nvariant_id = \"chr1:g.140453134T>C\"\nvariant_result = mv_client.getvariant(variant_id)\n# print(f\"Variant {variant_id}: {variant_result}\") # Uncomment to see full result\nprint(f\"Variant {variant_id}: {variant_result.get('_id')} - {variant_result.get('dbsnp', {}).get('rsid')}\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade to Python 3.7 or newer. For caching features, Python 3.8 or newer is required.","message":"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.","severity":"breaking","affected_versions":">=0.5.0 for Python 3.6, >=0.4.0 for Python <=3.5"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.4.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"0.4.0"},{"fix":"If caching is desired, ensure your Python environment is 3.8 or newer.","message":"The caching feature (`biothings_client[caching]`) explicitly requires Python >=3.8. It will not be available or function correctly on Python 3.7.","severity":"gotcha","affected_versions":"<0.5.0 (for Python 3.7 users trying to use caching)"},{"fix":"New projects and existing projects should migrate to using `biothings_client` directly via `from biothings_client import get_client` to ensure future compatibility.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions when using `as_dataframe=True`"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}