Getting Started with enembl-rest-client

version: 0.2.0a0

enembl-rest-client provides Pythonic access to the Ensembl REST API. It implements most current endpoints at https://rest.ensembl.org and was last refreshed against Ensembl REST ~15.12–16.0.

Python support: 3.9–3.13 (requires-python = ">=3.9,<3.14").

Note that not all endpoint methods have full live coverage. Offline unit tests cover recent path and surface changes; additional pytest coverage is added as methods are used.

Breaking changes in 0.2.x

Hard removals and signature changes (no compatibility shims):

• Comparative genomics member/homology by-id methods require species as the first argument (path form used by Ensembl REST ≥15.8)
• Removed: eQTL wrappers (Ensembl REST 15.0) — use the EMBL-EBI eQTL Catalogue instead
• Removed: gene family methods (REST 15.3)
• Removed: regulation microarray / epigenome / regulatory-id wrappers (REST 15.9); binding-matrix remains

Full notes: CHANGELOG.md.

Now there are other ensembl rest implementations. You may be better using these:

• https://pypi.org/project/pyEnsemblRest/
• https://pypi.org/project/ensembl-rest/

There is online documentation for ensembl-rest-client.

Installation instructions

You can install using pip or conda.

Installation using pip

pip install ensembl-rest-client

Installation using conda

I maintain a conda package in my personal conda channel. To install this please run:

conda install -c cfin -c conda-forge ensembl-rest-client

Basic usage

There are some examples in ./resources/examples where . is the root of the cloned repository.

Run tests

If you have cloned the repository, install an editable checkout first so tests use this tree rather than an older wheel from site-packages:

pip install -e ".[dev]"

# Full suite (archive / lookup / overlap / xrefs hit live Ensembl REST;
# conftest pings rest.ensembl.org at session start)
pytest ./tests

# Offline-only suites (mock rest_query; no network required for these files)
pytest ./tests/test_comp_genomics.py \
       ./tests/test_client_surface.py \
       ./tests/test_regulation.py \
       ./tests/test_vep.py -q

# Optional live comparative-genomics probes (and other @pytest.mark.live tests)
ENSEMBL_LIVE=1 pytest ./tests -m live

• Marker: live — optional integration probes against Ensembl REST
• Gate: set ENSEMBL_LIVE=1 or those tests are skipped
• Markers and pythonpath are registered in tests/pytest.ini

If any fail please contact us (see the contribution page for contact info).