Metadata-Version: 2.4
Name: ensembl-rest-client
Version: 0.2.0
Summary: Python access to the Ensembl REST API
Author-email: Chris Finan <c.finan@ucl.ac.uk>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://cfinan.gitlab.io/ensembl-rest-client
Project-URL: Repository, https://gitlab.com/cfinan/ensembl-rest-client
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: <3.14,>=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: pandas>=2
Requires-Dist: numpy>=1.25
Requires-Dist: requests
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-dependency; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: bump2version; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# Getting Started with ensembl-rest-client
__version__: `0.2.0`

ensembl-rest-client provides Pythonic access to the
[Ensembl REST API](https://rest.ensembl.org/). It implements most current
endpoints at the Ensembl REST base URL
([https://rest.ensembl.org](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"`).

Every public `get_*` / `post_*` method has a core offline test (mocked path
construction). Live probes that hit Ensembl REST are opt-in only (see below).

If you find a wrapper, parameter, or docs page that looks **stale or out of
date** relative to the live
[Ensembl REST service](https://rest.ensembl.org/), **first** check endpoint
coverage against the official catalog (from a clone of this repo):

```bash
python resources/bin/check_endpoint_coverage.py
python resources/bin/check_endpoint_coverage.py --live
```

That reports paths Ensembl lists that we lack, and wrappers we ship that are
no longer on the catalog. Details: Sphinx **User guide → Endpoint coverage**.

If coverage looks fine but behaviour is still wrong, please
[contact us](mailto:c.finan@ucl.ac.uk) (or open an issue on
[GitLab](https://gitlab.com/cfinan/ensembl-rest-client)) and we will refresh
the client.

## 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](https://www.ebi.ac.uk/eqtl/) instead
* **Removed:** gene family methods (REST 15.3)
* **Removed:** regulation microarray / epigenome / regulatory-id wrappers
  (REST 15.9); binding-matrix remains

Full notes are in the **Changelog** (Project admin in these docs) or
[CHANGELOG.md on GitLab](https://gitlab.com/cfinan/ensembl-rest-client/-/blob/master/CHANGELOG.md).

Other Ensembl REST clients exist; depending on your needs you may prefer:

* [pyEnsemblRest on PyPI](https://pypi.org/project/pyEnsemblRest/)
* [ensembl-rest on PyPI](https://pypi.org/project/ensembl-rest/)

## Installation instructions
You can install using pip or conda.

### Installation using pip

```bash
pip install ensembl-rest-client
```

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

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

## Basic usage

```python
from ensembl_rest_client.client import Rest

# Rate-limited client (default max 15 requests/sec); optional on-disk cache
rc = Rest(cache=False)

gene = rc.get_lookup_id("ENSG00000139618")
print(gene["display_name"], gene["biotype"])
```

The `Rest` class merges every endpoint domain (lookup, VEP, sequence, …)
with shared HTTP behaviour (retries, wait times, optional cache). Domain
modules can also be composed as mix-ins; see the **User guide** in these
docs.

Helper workflows (nearest genes, chromosome window traversal, LD from
coordinates) live in `ensembl_rest_client.utils`.

Examples in this documentation (sidebar **Programmer reference**):

* **Narrative notebooks** (with printed output): lookup, sequence, variation,
  VEP, overlap, xrefs, homology, LD
* **API call examples** — minimal call for every public method with truncated
  live sample output (regenerate with
  ``python resources/bin/gen_api_examples.py --with-outputs``)

## 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:

```bash
pip install -e ".[dev]"
```

```bash
# Default: offline suite (no network). Includes full API surface path checks
# plus focused unit suites (VEP kwargs, regulation, removals, …).
pytest ./tests

# Offline API surface only (every get_/post_ method, mocked rest_query)
pytest ./tests/test_api_offline.py -q

# Live probes (must ask for them explicitly):
#   1. set ENSEMBL_LIVE=1
#   2. select the live marker
ENSEMBL_LIVE=1 pytest ./tests -m live

# Live full-surface smokes only (one core call per non-stub method)
ENSEMBL_LIVE=1 pytest ./tests/test_api_live.py -m live
```

- **Offline:** mocks `rest_query`; asserts HTTP method + endpoint path for
  every public `Rest` method (`tests/api_call_specs.py`)
- **Live:** hits the Ensembl REST service
  ([https://rest.ensembl.org](https://rest.ensembl.org)); soft-checks
  dict/list payloads
- **Gate:** both `ENSEMBL_LIVE=1` **and** `@pytest.mark.live` / `-m live`
- Markers and `pythonpath` are registered in `tests/pytest.ini`
- Stub exception: `post_lookup_symbol` raises `NotImplementedError` (covered
  offline only)

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