nexusLIMS.utils.cdcs#

CDCS interaction utilities for NexusLIMS.

This module provides functions for querying, downloading, and deleting records from a CDCS instance. These are non-export operations used primarily for testing and maintenance.

For exporting records to CDCS, use the CDCSDestination plugin in nexusLIMS.exporters.destinations.cdcs instead.

Module Contents#

Classes#

CDCSDataRecord

Type definition for a CDCS Data record returned by the API.

Functions#

get_cdcs_url

Return the URL to the NexusLIMS CDCS instance from environment.

get_workspace_id

Get the workspace ID that the user has access to.

get_template_id

Get the template ID for the schema.

delete_record

Delete a Data record from the NexusLIMS CDCS instance via REST API.

search_records

Search for records in the CDCS instance by title, keyword, or criteria.

download_record

Download the XML content of a record from the CDCS instance.

upload_record_content

Upload a single XML record to the NexusLIMS CDCS instance.

upload_record_files

Upload record files to CDCS.

API#

exception nexusLIMS.utils.cdcs.AuthenticationError(message)[source]#

Bases: Exception

Class for showing an exception having to do with authentication.

class nexusLIMS.utils.cdcs.CDCSDataRecord[source]#

Bases: typing.Dict[str, typing.Any]

Type definition for a CDCS Data record returned by the API.

This represents the structure of record objects returned by CDCS endpoints like /rest/data/query/ and /rest/data/query/keyword/.

Variables:

  • id (int) – The record ID

  • template (int) – The template ID

  • workspace (int | None) – The workspace ID

  • user_id (str) – The user ID that created the record

  • title (str) – The record title

  • checksum (str | None) – The record checksum

  • creation_date (str | None) – The record creation date

  • last_modification_date (str | None) – The last modification date

  • last_change_date (str | None) – The last change date

  • xml_content (str) – The XML content of the record

nexusLIMS.utils.cdcs.get_cdcs_url() → str[source]#

Return the URL to the NexusLIMS CDCS instance from environment.

Returns:

The URL of the NexusLIMS CDCS instance to use

Return type:

str

Raises:

ValueError – If the NX_CDCS_URL setting is not defined

nexusLIMS.utils.cdcs.get_workspace_id() → int[source]#

Get the workspace ID that the user has access to.

This should be the Global Public Workspace in the current NexusLIMS CDCS implementation.

Returns:

The workspace ID

Return type:

int

Raises:

AuthenticationError – If authentication to CDCS fails

nexusLIMS.utils.cdcs.get_template_id() → str[source]#

Get the template ID for the schema.

Returns the template ID so records can be associated with the correct schema.

Returns:

The template ID

Return type:

str

Raises:

AuthenticationError – If authentication to CDCS fails

nexusLIMS.utils.cdcs.delete_record(record_id: str)[source]#

Delete a Data record from the NexusLIMS CDCS instance via REST API.

Parameters:

record_id – The id value (on the CDCS server) of the record to be deleted

Returns:

The REST response returned from the CDCS instance after attempting the delete operation

Return type:

Response

nexusLIMS.utils.cdcs.search_records(title: str | None = None, template_id: str | None = None, keyword: str | None = None) → list[CDCSDataRecord][source]#

Search for records in the CDCS instance by title, keyword, or criteria.

This function uses the CDCS query endpoint to search for records. If no parameters are provided, all records are returned.

.. note::

If keyword is provided, it takes precedence and the title parameter is ignored. The keyword search uses a different CDCS endpoint (/rest/data/query/keyword/) that performs full-text search but does not support title filtering. In this mode, only template_id can be combined with keyword to filter results.

Parameters:

  • title – The title to search for (exact match). Only used when keyword is None.

  • template_id – The template ID to filter by. Can be combined with either title or keyword.

  • keyword – Keyword(s) for full-text search across record content. When provided, takes precedence over title parameter.

Returns:

List of matching record objects from CDCS. Each record is a dictionary containing id, title, xml_content, template, workspace, user_id, checksum, and date fields. See CDCSDataRecord for complete structure.

Return type:

list[CDCSDataRecord]

Raises:
nexusLIMS.utils.cdcs.download_record(record_id: str) → str[source]#

Download the XML content of a record from the CDCS instance.

Parameters:

record_id – The id value (on the CDCS server) of the record to download

Returns:

The XML content of the record

Return type:

str

Raises:
nexusLIMS.utils.cdcs.upload_record_content(xml_content: str, title: str) → tuple[Any, int | None][source]#

Upload a single XML record to the NexusLIMS CDCS instance.

.. note::

This is a low-level utility function primarily used for testing. For production record uploads, use the CDCSDestination exporter plugin in nexusLIMS.exporters.destinations.cdcs instead.

Parameters:

  • xml_content – The actual content of an XML record (rather than a file)

  • title – The title to give to the record in CDCS

Returns:

A tuple of (response, record_id). The response is the REST response returned from the CDCS instance after attempting the upload. The record_id is the id (on the server) of the record that was uploaded, or None if there was an error.

Return type:

tuple[Response, int | None]

nexusLIMS.utils.cdcs.upload_record_files(files_to_upload: List[Path] | None, *, progress: bool = False) → tuple[List[Path], List[int]][source]#

Upload record files to CDCS.

Upload a list of .xml files (or all .xml files in the current directory) to the NexusLIMS CDCS instance using upload_record_content().

.. note::

This is a utility function primarily used for testing and manual uploads. For production record uploads, use the CDCSDestination exporter plugin in nexusLIMS.exporters.destinations.cdcs instead.

Parameters:

  • files_to_upload (List[Path] | None) – The list of .xml files to upload. If None, all .xml files in the current directory will be used instead.

  • progress – Whether to show a progress bar for uploading

Returns:

A tuple of (files_uploaded, record_ids). files_uploaded is a list of the files that were successfully uploaded. record_ids is a list of the record id values (on the server) that were uploaded.

Return type:

tuple[list[Path], list[int]]

Raises:

ValueError – If no .xml files are found