BioReqs: Bioinformatic Requisitions

bioreqs is a Python library that defines lightweight client interfaces for a number of publicly accessible, bioinformatics-focused web APIs, including those from organizations like the National Center for Biotechnology Information (NCBI). In so doing, it provides users with programmatic access to essential bioinformatics data without also requiring them to have an overt familiarity with their underlying API schemata.

Quick Start

If you're using a dependency manager like uv or poetry and plan to invoke bioreqs clients from within a project context, simply add it to your pyproject.toml dependency list:

• poetry: poetry add bioreqs
• uv: uv add bioreqs

On the other hand, if you're using vanilla pip but still want to work out of a virtual environment (as you should!), do:

python -m venv rqenv           # Create a new virtual environment named `rqenv`.
source ./rqenv/bin/activate    # Activate the `rqenv` virtual environment.
pip install --upgrade pip      # Upgrade to the latest version of `pip`.
pip install bioreqs       # Install the `bioreqs` package.

Finally, if you only want to use it interactively — or in a script meant to be invoked by your system-level Python interpreter — you can simply do:

# Assuming the system-level `pip` binary is in your `PATH` environment variable:
pip install --upgrade pip      # Upgrade to the latest version of `pip`.
pip install bioreqs       # Install the library system-wide.

Each of the package's modules corresponds to an individual organization and implements the relevant API client(s) for that organization. As a convenience, all clients are also surfaced at the package level, making them directly available in the bioreqs namespace. Thus, for example, to initialize a client object for the NCBI's popular Entrez E-utilities web API, the following code suffices:

# Import the Entrez E-utilities API client.
# from bioreqs.ncbi import Entrez
#
# Or, equivalently:
from bioreqs import Entrez

# Initialize the client, providing a valid email address, as required.
client = Entrez("email@example.com")

Clients

Presently, bioreqs provides only the above introduced client for the Entrez E-utilities web API, but it will hopefully tout a much more robust client library soon enough.

Entrez E-utilities (NCBI)

Use bioreqs.ncbi.Entrez and its instance methods to interact with the E-utilities web API. Since the NCBI requires one to include their email address when querying these endpoints, you should call Entrez with yours as the first argument. Alternatively, you can set your system's NCBI_EMAIL environment variable to store your email address; Entrez automatically detects it.

from bioreqs import Entrez

# Assuming the `NCBI_EMAIL` environment variable is set to your email address,
# this is a valid invocation of the `Entrez` constructor.
client = Entrez()

After creating and storing an instance of the API client (client, in the example above), you call instance methods on that object to query specific endpoints:

# Get the RefSeq for human COL5A2 as a FASTA-formatted string via its accession.
COL5A2_ACCESSION = "NM_000393.5"
COL5A2_REFERENCE = client.get_refseq(COL5A2_ACCESSION)
print(COL5A2_REFERENCE)  # Print the FASTA output.

# Download the FASTA-formatted RefSeq data for human kallikrein-related
# peptidase 15 via its accession, and write it to disk, storing the returned
# output path, if successful.
KLK15_ACCESSION = "NM_001277081.2"
ouput_path = client.save_refseq(KLK15_ACCESSION)