ELabFTW Python API#
This repository (usnistgov/elabftw-python-api) contains a (work in progress) Python library that can be used to communicate with APIv2 of eLabFTW (Github). It was written primarily by Josh Taillon to develop scripts that interface with the NIST instance of eLabFTW. In general, it provides mostly read-only interfaces to access information about experiments and items within an eLabFTW instance (see the “Usage” section below). It is in a pre-release state currently, but is functional enough to be useful.
Note: there is an official Python API library available from elabftw/elabapi-python, which works perfectly well, but requires quite a bit of boilerplate code for simple tasks. The goal of this library is to provide a simple interface for common tasks such as exporting experiments, changing status, etc.
Installation#
pip install git+https://github.com/usnistgov/elabftw-python-api
or, to install from sources with poetry:
$ git clone https://github.com/usnistgov/elabftw-python-api
$ cd elabftw-python-api
$ poetry install
Usage#
Check the documentation strings or the dedicated documentation page (https://pages.nist.gov/elabftw-python-api), but in general usage works as follows:
# import the library:
from elabapi import ELabApi, TeamApi
# create an instance of the API with URL and credentials
e = ELabApi(
api_base_url=os.environ.get("ELAB_URL"),
api_key=os.environ.get("ELAB_API_KEY"),
)
# get an experiment's JSON representation:
e.get_experiment(64)
# get all experiments with a given status:
e.get_experiments_by_status(status="Ready for Export")
# export an experiment
e.export_experiment(64, format='pdf') # exports to a pdf file in the current directory
e.export_experiment(64, format='eln') # export to ELN format archive (see https://github.com/TheELNConsortium/TheELNFileFormat/blob/master/SPECIFICATION.md)
Settings#
There are a couple settings you need to provide, which are the base URL for the API
endpoint, and an API Key. These can either be provided as strings when you initialize an
ELabApi() instance, or (better) can be provided by querying from the environment. I
like to use the python-dotenv library to
do this, which allows you to place a .env file in the current directory with values
you want to be part of the environment, and then call:
from dotenv import load_dotenv
load_dotenv()
to make them available to your script via os.environ.get() (as used in the example
above). This repo includes a .env.example file that you can rename to .env and use
by replacing your API key. An API key for your ELab user can be generated at
from the relevant tab in your “User control panel”.
The CERT_BUNDLE variable allows you to use a custom certificate bundle to validate
requests to the API. This can be used if your deployment of eLabFTW uses internal or
self-signed certificates. Otherwise, if the value is not defined, SSL verification
will be disabled (which is fine for testing, but not recommended for production
deployment).
API Reference#
The following links will bring you to the API reference documents auto-generated from the docstrings in the code.