`nexusLIMS.utils.labarchives`#

Low-level API client for LabArchives electronic lab notebook.

This module provides a reusable client for interacting with the LabArchives API. Authentication uses HMAC-SHA-512 signed requests (akid + method + expires, keyed with the access password).

LabArchives API documentation: https://api.labarchives.com/api_docs/

Example usage: >>> from nexusLIMS.utils.labarchives import get_labarchives_client >>> client = get_labarchives_client() >>> nodes = client.get_tree_level(“12345”, “0”) >>> for node in nodes: … print(f”{node[‘tree_id’]}: {node[‘display_text’]}”) >>> folder_id = client.insert_folder(“12345”, “0”, “My Folder”) >>> page_id = client.insert_page(“12345”, folder_id, “My Page”)

Module Contents#

Classes#

LabArchivesClient

Low-level client for the LabArchives API.

Functions#

get_labarchives_client

Get configured LabArchives client from settings.

API#

exception nexusLIMS.utils.labarchives.LabArchivesError[source]#

Bases: Exception

Base exception for LabArchives API errors.

exception nexusLIMS.utils.labarchives.LabArchivesAuthenticationError[source]#

Bases: nexusLIMS.utils.labarchives.LabArchivesError

Authentication failed (invalid credentials or session expired).

exception nexusLIMS.utils.labarchives.LabArchivesPermissionError[source]#

Bases: nexusLIMS.utils.labarchives.LabArchivesError

Insufficient permissions for the requested operation.

exception nexusLIMS.utils.labarchives.LabArchivesNotFoundError[source]#

Bases: nexusLIMS.utils.labarchives.LabArchivesError

Requested resource not found.

exception nexusLIMS.utils.labarchives.LabArchivesRateLimitError[source]#

Bases: nexusLIMS.utils.labarchives.LabArchivesError

Server error or rate limit exceeded (5xx response).

class nexusLIMS.utils.labarchives.LabArchivesClient(base_url: str, akid: str, password: str, uid: str)[source]#

Low-level client for the LabArchives API.

Authentication uses HMAC-SHA-512 signed requests. Each request includes:

akid: Access Key ID
expires: Unix timestamp in milliseconds
sig: URL-encoded base64 HMAC-SHA-512 signature of akid + method + expires

Parameters:

base_url (str) – API base URL including the /api path segment (e.g., "https://api.labarchives.com/api").
akid (str) – Access Key ID for API authentication.
password (str) – Access password (HMAC signing secret).
uid (str) – LabArchives user ID for the account that owns records.

Examples:

>>> client = LabArchivesClient(
...     base_url="https://api.labarchives.com/api",
...     akid="your-akid",
...     password="your-password",
...     uid="your-uid",
... )
>>> nodes = client.get_tree_level("12345", "0")

get_tree_level(nbid: str, parent_tree_id: str = '0') → list[dict[str, Any]][source]#

Get child nodes at a tree level in a notebook.

Parameters:

nbid (str) – Notebook ID
parent_tree_id (str, optional) – Parent tree node ID; “0” for the root level

Returns:

Each dict has tree_id, display_text, and is_page keys.

Return type:

list of dict

Raises:

LabArchivesError – If the API call fails

get_page_entries(nbid: str, page_tree_id: str, *, include_content: bool = False) → list[dict[str, Any]][source]#

Get all entries on a notebook page.

Parameters:

nbid (str) – Notebook ID
page_tree_id (str) – Tree ID of the page
include_content (bool, optional) – When True, each entry dict will include an entry_data key containing the raw HTML/text content of the entry.

Returns:

Each dict has eid and part_type keys, plus entry_data when include_content is True.

Return type:

list of dict

Raises:

LabArchivesError – If the API call fails

insert_folder(nbid: str, parent_tree_id: str, name: str) → str[source]#

Create a folder in a notebook tree.

Parameters:

nbid (str) – Notebook ID
parent_tree_id (str) – Parent tree node ID; "0" for the root level
name (str) – Display name for the new folder

Returns:

The tree_id of the newly created folder

Return type:

str

Raises:

LabArchivesError – If the API call fails

insert_page(nbid: str, parent_tree_id: str, name: str) → str[source]#

Create a page in a notebook tree.

Parameters:

nbid (str) – Notebook ID
parent_tree_id (str) – Parent tree node ID (folder tree_id or "0" for root)
name (str) – Display name for the new page

Returns:

The tree_id of the newly created page

Return type:

str

Raises:

LabArchivesError – If the API call fails

add_entry(nbid: str, page_tree_id: str, entry_data: str, part_type: str = 'text entry') → str[source]#

Add a text/HTML entry to a notebook page.

Parameters:

nbid (str) – Notebook ID
page_tree_id (str) – Tree ID of the target page
entry_data (str) – HTML or plain-text content for the entry
part_type (str, optional) – Entry part type (default: “text entry”)

Returns:

The eid (entry ID) of the newly created entry

Return type:

str

Raises:

LabArchivesError – If the API call fails

add_attachment(nbid: str, page_tree_id: str, filename: str, data: bytes, caption: str = '') → str[source]#

Upload a file attachment to a notebook page.

Parameters:

nbid (str) – Notebook ID
page_tree_id (str) – Tree ID of the target page
filename (str) – Name to use for the uploaded file
data (bytes) – Raw file content
caption (str, optional) – Caption for the attachment

Returns:

The eid (entry ID) of the attachment entry

Return type:

str

Raises:

LabArchivesError – If the API call fails

attach_file(nbid: str, page_tree_id: str, path: Path, caption: str = '') → str[source]#

Upload a file from disk as an attachment to a notebook page.

Convenience wrapper around add_attachment() that reads the file and derives the filename from the path automatically.

Parameters:

nbid (str) – Notebook ID
page_tree_id (str) – Tree ID of the target page
path (Path) – Local file to upload
caption (str, optional) – Caption for the attachment

Returns:

The eid (entry ID) of the attachment entry

Return type:

str

Raises:

LabArchivesError – If the API call fails

get_attachment_content(eid: str) → bytes[source]#

Download the raw content of an attachment entry.

Parameters:

eid (str) – Entry ID of the attachment (as returned by add_attachment())

Returns:

Raw file content of the attachment

Return type:

bytes

Raises:

LabArchivesNotFoundError – If the entry does not exist
LabArchivesError – If the API call fails

get_user_info(login: str, password: str) → dict[str, Any][source]#

Exchange login credentials for user info and notebook list.

This method is used to obtain the uid for a LabArchives account. The returned uid should be stored in NX_LABARCHIVES_USER_ID for subsequent API calls.

Parameters:

login (str) – LabArchives login (email address)
password (str) – LabArchives account password

Returns:

User info including uid, email, and notebooks list.

Return type:

dict

Raises:

LabArchivesAuthenticationError – If login credentials are invalid
LabArchivesError – If the API call fails

get_user_info_by_uid(uid: str | None = None) → dict[str, Any][source]#

Fetch user info for a LabArchives account using a uid.

Calls the users/user_info_via_id endpoint, which requires only the uid (no login password). When uid is omitted the client’s own uid is used.

Parameters:: uid (str, optional) – LabArchives user ID. Defaults to the client’s configured uid.
Returns:: User info including uid, email, and notebooks list.
Return type:: dict
Raises:: LabArchivesError – If the API call fails

nexusLIMS.utils.labarchives.get_labarchives_client() → LabArchivesClient[source]#

Get configured LabArchives client from settings.

Creates a LabArchivesClient using credentials from the NexusLIMS configuration (NX_LABARCHIVES_* settings).

Returns:: Configured client instance
Return type:: LabArchivesClient
Raises:: LabArchivesError – If required settings are not configured

Examples:

>>> from nexusLIMS.utils.labarchives import get_labarchives_client
>>> client = get_labarchives_client()
>>> nodes = client.get_tree_level("12345", "0")
>>> folder_id = client.insert_folder("12345", "0", "My Folder")
>>> page_id = client.insert_page("12345", folder_id, "My Page")

nexusLIMS.utils.labarchives#

Module Contents#

Classes#

Functions#

API#

This Page

`nexusLIMS.utils.labarchives`#