elabapi package#

Submodules#

elabapi.elabapi module#

class elabapi.elabapi.ELabApi#

Bases: object

Represents a connection to the root ELabFTW API.

Authenticates via API key provided at init time (though this could be changed) and provides simple interfaces to various API endpoints. Currently mostly read-only

__init__(api_base_url, api_key)#
api_base_url: str#

An ELabFTW API URL root (e.g. https://elabftw.net/api/v2/)

api_key: str#

An ELabFTW API key

api_req(function, endpoint, limit=None, offset=None, **kwargs)#

Make a request to the ELabFTW API.

A helper method that wraps a function from requests, but adds a local certificate authority chain to validate any custom certificates. Will automatically retry on 500 errors using a strategy suggested here: https://stackoverflow.com/a/35636367.

Parameters:

  • function (str) – The function from the requests library to use (e.g. 'GET', 'POST', 'PATCH', etc.)

  • endpoint (str) – The API endpoint to fetch (will be appended to ELAB_URL environment variable)

  • limit (int | Literal['all'] | None) – The number of records to return from the API request. If 'all' (the default for ‘GET’ requests), the API call will be repeated until no more records are found

  • offset (int | None) – Used together with limit, this is the pagination offset value to send to the API. Note, for both limit and offset, any value provided as an argument to this function will override any value provided via URL parameters in the params kwarg. Any value for offset will be ignored if limit is 'all'.

  • **kwargs (dict | None) – Other keyword arguments are passed along to the fn

Returns:

A list of dictionaries, one for each JSON object returned by the API

Return type:

r

Raises:

ValueError – If multiple methods of authentication are provided to the function

export_experiment(experiment_id, output_filename=None, format='pdf', overwrite=False)#

Export and download an experiment in the specified format.

Allowed formats are ‘csv’, ‘eln’, ‘json’, ‘qrpdf’, ‘qrpng’, ‘pdf’, ‘pdfa’, ‘zip’, or ‘zipa’. If no filename/path is provided, a filename in the current directory will be autogenerated and returned as a Path object. The overwrite option controls whether a file that already exists on disk will be overwritten.

Parameters:
Return type:

Path

get_api_keys()#
get_config()#
get_experiment(experiment_id)#
Parameters:

experiment_id (int)

get_experiments()#
Return type:

list[Dict]

get_experiments_by_category(category, **kwargs)#

Get experiments matching a given category

Parameters:

  • category (str) – The text of the category to search. Note, the ELabFTW search syntax is case insensitive

  • *kwargs* – Additional keyword arguments are passed to api_req()

Return type:

list[Dict]

get_experiments_by_status(status)#
Parameters:

status (str)

Return type:

list[Dict]

get_item(item_id)#
Parameters:

item_id (int)

get_item_by_elabid(elabid)#
Parameters:

elabid (str)

Return type:

dict[str, str] | None

get_user(user_id)#
Parameters:

user_id (int)

set_experiment_category(experiment_id, category_id=None, category_name=None)#
Parameters:

  • experiment_id (int)

  • category_id (int | None)

  • category_name (str | None)

Return type:

list[Dict]

class elabapi.elabapi.TeamApi#

Bases: ELabApi

Represents a single ELabFTW Team by communicating with the REST API.

Provides methods to get information about a team and its content. Also provides a few static methods to get information about other teams. Currently is read-only.

__init__(api_base_url, api_key, team_id='current')#
Parameters:
get_experiments_categories()#

Get the experiments categories of a team

https://doc.elabftw.net/api/v2/#/Experiments%20categories/read-team-experiments-categories

Return type:

list[Dict]

get_experiments_category(cat_id)#

Get a single experiments category of a team

https://doc.elabftw.net/api/v2/#/Experiments%20categories/read-team-experiments-categories

Parameters:

cat_id (int)

Return type:

Dict | None

get_experiments_category_by_name(cat_name)#

Get a single experiments category of a team by name

https://doc.elabftw.net/api/v2/#/Experiments%20categories/read-team-experiments-categories

Parameters:

cat_name (str)

Return type:

Dict | None

get_experiments_status(status_id)#

Get a single experiments status of a team

https://doc.elabftw.net/api/v2/#/Experiments%20status/read-team-one-expstatus

Parameters:

status_id (int)

Return type:

Dict | None

get_experiments_status_by_title(title)#

Get a single experiments status of a team by its name

Parameters:

title (str)

Return type:

Dict | None

get_experiments_statuses()#

Get the experiments statuses of a team

https://doc.elabftw.net/api/v2/#/Experiments%20status/read-team-experiments-status

Return type:

list[Dict]

get_items_status(status_id)#

Get a single items status of a team

https://doc.elabftw.net/api/v2/#/Resources%20status/read-team-one-resstatus

Parameters:

status_id (int)

Return type:

Dict | None

get_items_status_by_title(title)#

Get a single items status of a team by its name

Parameters:

title (str)

Return type:

Dict | None

get_items_statuses()#

Get the items statuses of a team

https://doc.elabftw.net/api/v2/#/Resources%20status/read-team-items-status

Return type:

list[Dict]

get_team(id='current')#

Get a team definition by id

https://doc.elabftw.net/api/v2/#/Teams/read-team

Parameters:

id (int | Literal['current'])

Return type:

Dict

get_team_by_name(name)#
Parameters:

name (str)

Return type:

Dict | None

get_team_tag(id)#

Get a specific tag defined for this team

https://doc.elabftw.net/api/v2/#/Team%20tags/read-team_tag

Return type:

Dict | None

get_team_tags()#

Get the tags defined for this team

https://doc.elabftw.net/api/v2/#/Team%20tags/read-team_tags

Return type:

list[Dict]

get_teams()#

Get all teams from the API (always refreshes from API and adds to cache)

https://doc.elabftw.net/api/v2/#/Teams/read-teams

Return type:

list[Dict]

known_teams: Dict[int, Dict] = {}#

A cache of known teams used to help limit API requests if they’re unnecessary

team: Dict#

the dictionary/JSON returned by the ELabFTW API for this team

team_id: int | Literal['current']#

the identifier number for this team; if ‘current’, this attribute will be overwritten with the actual integer identifier the first time the API is queried

Module contents#

On this page
Show Source