Metadata-Version: 2.4
Name: ensemblrestpy
Version: 15.11
Summary: Python client for Ensembl REST API
Author-email: Liu Sun <sunliu@yxnu.edu.cn>
Project-URL: Homepage, https://github.com/liu-sun/ensemblrestpy
Project-URL: Issues, https://github.com/liu-sun/ensemblrestpy/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# ensemblrestpy

[![PyPI](https://img.shields.io/pypi/v/ensemblrestpy)](https://pypi.org/project/ensemblrestpy/)
[![Python](https://img.shields.io/pypi/pyversions/ensemblrestpy)](https://pypi.org/project/ensemblrestpy/)
[![License](https://img.shields.io/pypi/l/ensemblrestpy)](https://github.com/liu-sun/ensemblrestpy/blob/main/LICENSE)

**Python client for the [Ensembl REST API](https://rest.ensembl.org).**

Complete access to all Ensembl REST API endpoints. Supports both procedural (standalone functions) and object-oriented (`Ensembl` class) interfaces. Works with GRCh38 and GRCh37 genome assemblies. Includes a CLI tool (`ensembl`) for terminal use.

---

## Installation

**Requirements:** Python ≥ 3.12, `requests`

### From PyPI

```bash
pip install ensemblrestpy
```

### From source

```bash
git clone https://github.com/liu-sun/ensemblrestpy.git
cd ensemblrestpy
pip install -e .
```

After installation, the `ensembl` command is available in your terminal.

---

## Quick Start

### Module-level functions (GRCh38)

```python
>>> from ensemblrestpy import ping, archive_id, vep_hgvs

>>> ping()
{"ping": 1}

>>> archive_id("ENSG00000157764")
{"id": "ENSG00000157764", "version": 15, "type": "Gene", ...}

>>> vep_hgvs("NM_000410.4:c.845G>A", "human")
[{"input": "NM_000410.4:c.845G>A", "transcript_consequences": [...], ...}]
```

### Ensembl class (session reuse for multiple calls)

```python
>>> from ensemblrestpy import Ensembl
>>> e = Ensembl()
>>> e.ping()
{"ping": 1}
>>> e.archive_id("ENSG00000157764")
{"id": "ENSG00000157764", "version": 15, ...}
```

### Command-line interface

```bash
$ ensembl ping
{"ping": 1}

$ ensembl archive_id ENSG00000157764
{
  "id": "ENSG00000157764",
  "version": 15,
  "type": "Gene"
}

$ ensembl vep_hgvs "NM_000410.4:c.845G>A" human
$ ensembl grch37 ping
$ ensembl --format xml ping
```

### GRCh37

```python
>>> from ensemblrestpy.grch37 import ping, archive_id, vep_hgvs
>>> ping()
{"ping": 1}
>>> archive_id("ENSG00000157764")
{"id": "ENSG00000157764", "version": 8, "assembly": "GRCh37", ...}
```

```bash
$ ensembl grch37 archive_id ENSG00000157764
```

---

## Key Features

### Response formats

Ten formats supported via `response_format` (default `json`):

`json` | `xml` | `fasta` | `text` | `yaml` | `nh` | `phyloxml` | `orthoxml` | `gff3` | `bed` | `seqxml`

```python
>>> from ensemblrestpy import sequence_id
>>> seq = sequence_id("ENSG00000157764", response_format="fasta")
```

CLI: `ensembl --format fasta sequence_id ENSG00000157764`

### Singledispatch: single ID vs bulk list

Endpoints that accept one or many IDs use Python's `singledispatch`:

```python
>>> variation_id("rs1800562", "human")                    # GET: single
>>> variation_id(["rs1800562", "rs1799945"], "human")      # POST: bulk
```

### Automatic rate limiting

`requests.Session` with retry/backoff. HTTP 429 responses are retried automatically.

### Convenience partials (species="human" pre-filled)

```python
>>> from ensemblrestpy import vep_hgvs_human, variation_id_human
>>> vep_hgvs_human("NM_000410.4:c.845G>A")
>>> variation_id_human("rs1800562")
```

---

## Endpoint Reference

### Archive
`archive_id`

### Comparative Genomics
`cafe_tree` `cafe_tree_member_symbol` `cafe_tree_species_member_id`
`genetree` `genetree_member_symbol` `genetree_species_member_id`
`genomic_alignment_region` `homology_species_gene_id` `homology_symbol`

### Cross References
`xref_external` `xref_id` `xref_name`

### Info & Metadata
`analysis` `assembly_info` `assembly_stats` `biotypes` `biotypes_groups`
`biotypes_name` `compara_methods` `compara_species_sets` `comparas` `data`
`eg_version` `external_dbs` `info_divisions` `info_genome`
`info_genomes_accession` `info_genomes_assembly` `info_genomes_division`
`info_genomes_taxonomy` `ping` `rest` `software` `species`
`variation_consequence_types` `variation_populations`
`variation_population_name`

### Lookup
`lookup_id` `lookup_symbol`

### Mapping
`assembly_cdna` `assembly_cds` `assembly_map` `assembly_translation`

### Ontology & Taxonomy
`ontology_ancestors` `ontology_ancestors_chart` `ontology_descendants`
`ontology_id` `ontology_name` `taxonomy_classification` `taxonomy_id`
`taxonomy_name`

### Overlap
`overlap_id` `overlap_region` `overlap_translation`

### Phenotype
`phenotype_accession` `phenotype_gene` `phenotype_region` `phenotype_term`

### Regulation
`get_binding_matrix`

### Sequences
`sequence_id` `sequence_region` `sequence_region_post`

### Transcript Haplotypes
`transcript_haplotypes_get`

### Variation
`variation` `variation_id` `variation_pmcid` `variation_pmid`
`variation_post` `ld_id_get` `ld_pairwise_get` `ld_region_get`

### VEP (Variant Effect Predictor)
`vep_hgvs` `vep_id` `vep_region` `variant_recoder`

### GA4GH
`beacon_get` `beacon_query_get` `beacon_query_post` `features_id`
`features_post` `gacallSet` `gacallset_id` `gadataset` `gadataset_id`
`gafeatureset` `gafeatureset_id` `gavariant_id` `gavariantannotations`
`gavariants` `gavariantset` `gavariantset_id` `references` `references_id`
`referenceSets` `referenceSets_id` `VariantAnnotationSet`
`VariantAnnotationSet_id`

> Every endpoint is available as both a module-level function and an `Ensembl` class method. All endpoints are available for both GRCh38 and GRCh37.

---

## License

MIT — see [LICENSE](LICENSE).

## Links

- PyPI: [pypi.org/project/ensemblrestpy](https://pypi.org/project/ensemblrestpy/)
- GitHub: [github.com/liu-sun/ensemblrestpy](https://github.com/liu-sun/ensemblrestpy)
- Issues: [github.com/liu-sun/ensemblrestpy/issues](https://github.com/liu-sun/ensemblrestpy/issues)
- Ensembl REST API: [rest.ensembl.org](https://rest.ensembl.org)
