nexusLIMS.harvesters.nemo.connector#

Defines the NemoConnector class that is used to interface with the NEMO API.

Module Contents#

Classes#

NemoConnector

A connection to an instance of the API of the NEMO laboratory management software.

API#

class nexusLIMS.harvesters.nemo.connector.NemoConnector(base_url: str, token: str, strftime_fmt: str | None = None, strptime_fmt: str | None = None, timezone: str | None = None, retries: int = 5)[source]#

A connection to an instance of the API of the NEMO laboratory management software.

Provides helper methods for fetching data from the API.

Parameters:

  • base_url (str) – The “root” of the API including a trailing slash; e.g. ‘https://nemo.example.com/api/’

  • token (str) – An authentication token for this NEMO instance

  • strftime_fmt (str) – The “date format” to use when encoding dates to send as filters to the NEMO API. Should follow the same convention as strftime() and strptime() Behavior. If None, ISO 8601 format will be used.

  • strptime_fmt (str) – The “date format” to use when decoding date strings received in the response from the API. Should follow the same convention as strftime() and strptime() Behavior. If None, ISO 8601 format will be used.

  • timezone (str) – The timezone to use when decoding date strings received in the response from the API. Should be a IANA time zone database string; e.g. “America/New_York”. Useful if no timezone information is returned from an instance of the NEMO API. If None, no timezone setting will be done and the code will use whatever was returned from the server as is.

  • retries (int) – The number of retries that will be used for failed HTTP requests before actually failing.

tools#

Type: dict[int, dict]

users#

Type: dict[int, dict]

users_by_username#

Type: dict[str, dict]

projects#

Type: dict[int, dict]

strftime(date_dt) → str[source]#

Convert datetime to appropriate string format for this connector.

Using the settings for this NemoConnector, convert a datetime object to a string that will be understood by the API. If the strftime_fmt attribute for this NemoConnector is None, ISO 8601 format will be used.

Parameters:

date_dt – The date to be converted as a datetime object

Returns:

date_str – The date formatted as a string that will be understandable by the API for this NemoConnector

Return type:

str

strptime(date_str) → datetime[source]#

Convert string to datetime using this connector’s API date format.

Using the settings for this NemoConnector, convert a datetime string representation from the API into a datetime object that can be used in Python. If the strptime_fmt attribute for this NemoConnector is None, ISO 8601 format will be assumed. If a timezone is specified for this server, the resulting datetime will be coerced to that timezone.

Parameters:

date_str – The date formatted as a string that is returned by the API for this NemoConnector

Returns:

date_dt – The date to be converted as a datetime object

Return type:

datetime

get_tools(tool_id: Union[int, List[int]]) → List[dict][source]#

Get a list of one or more tools from the NEMO API in a dictionary.

Parameters:

tool_id – The tool(s) to fetch, as indexed by the NEMO instance (i.e. tool_id should be the internal primary key used by NEMO to identify the tool. If an empty list is given, all tools will be returned.

Returns:

tools – A list (could be empty) of tools that match the id (or ids) given in tool_id

Return type:

List[dict]

Raises:

HTTPError – Raised if the request to the API did not go through correctly

get_users(user_id: Union[int, List[int]] | None = None) → List[dict][source]#

Get a list of one or more users from the NEMO API in a dictionary.

The results will be cached in the NemoConnector instance to prevent multiple API queries if not necessary.

Parameters:

user_id – The user(s) to fetch, as indexed by the NEMO instance (i.e. user_id should be the internal primary key used by NEMO to identify the user. If an empty list or None is given, all users will be returned.

Returns:

users – A list (could be empty) of users that match the ids and/or usernames given

Return type:

List[dict]

Raises:

HTTPError – Raised if the request to the API did not go through correctly

get_users_by_username(username=None) → List[source]#

Get a list of one or more users from the NEMO API in a dictionary.

The results will be cached in the NemoConnector instance to prevent multiple API queries if not necessary.

Parameters:

username (str or list of str) – The user(s) to fetch, as indexed by their usernames in the NEMO instance. If an empty list or None is given, all users will be returned.

Returns:

users – A list (could be empty) of users that match the ids and/or usernames given

Return type:

list

Raises:

HTTPError – Raised if the request to the API did not go through correctly

get_projects(proj_id: Union[int, List[int]]) → List[dict][source]#

Get a list of one or more projects from the NEMO API in a dictionary.

The local cache will be checked prior to fetching from the API to save a network request if possible.

Parameters:

proj_id – The project(s) to fetch, as indexed by the NEMO instance (i.e. proj_id should be the internal primary key used by NEMO to identify the project. If an empty list is given, all projects will be returned.

Returns:

projects – A list (could be empty) of projects that match the id (or ids) given in proj_id

Return type:

List[dict]

Raises:

HTTPError – Raised if the request to the API did not go through correctly

get_reservations(dt_from: datetime | None = None, dt_to: datetime | None = None, tool_id: Union[int, List[int]] | None = None, *, cancelled: bool | None = False) → List[dict][source]#

Get reservations from the NEMO API filtered in various ways.

Return a list of reservations from the API, filtered by date (inclusive). If only one argument is provided, the API will return all reservations either before or after the parameter. With no arguments, the method will return all reservations. The method will “auto-expand” linked information such as user, project, tool, etc. so results will have a full dictionary for each of those fields, rather than just the index (as returned from the API).

Parameters:

  • dt_from – The “starting point” of the time range; only reservations at or after this point in time will be returned

  • dt_to – The “ending point” of the time range; only reservations at or prior to this point in time will be returned

  • tool_id – A tool identifier (or list of them) to limit the scope of the reservation search (this should be the NEMO internal integer ID)

  • cancelled – Whether to get canceled or active reservations in the response (default is False – meaning non-cancelled active reservations are returned by default). Set to None to include all reservations regardless of whether they are cancelled or active.

Returns:

reservations – A list (could be empty) of reservations that match the date range supplied

Return type:

List[dict]

get_usage_events(event_id: Union[int, List[int]] | None = None, user: Union[str, int] | None = None, dt_range: Tuple[datetime | None, datetime | None] | None = None, tool_id: Union[int, List[int]] | None = None) → List[source]#

Get usage events from the NEMO API filtered in various ways.

Return a list of usage events from the API, filtered by date (inclusive). If only one argument is provided, the API will return all reservations either before or after the parameter. With no arguments, the method will return all reservations. The method will “auto-expand” linked information such as user, project, tool, etc. so results will have a full dictionary for each of those fields, rather than just the index (as returned from the API).

Parameters:

  • event_id – The NEMO integer identifier (or a list of them) to fetch. If None, the returned usage events will not be filtered by ID number

  • user – The user for which to fetch usage events, as either an integer representing their id in the NEMO instance, or as a string containing their username. If None is given, usage events from all users will be returned.

  • dt_range – The “starting” and “end” points of the time range; only usage events starting between these points in time will be returned

  • tool_id – A tool identifier (or list of them) to limit the scope of the usage event search (this should be the NEMO internal integer ID). Regardless of what value is given, this method will always limit the API query to tools specified in the NexusLIMS DB for this harvester

Returns:

usage_events – A list (could be empty) of usage events that match the filters supplied

Return type:

List

write_usage_event_to_session_log(event_id: int) → None[source]#

Write a usage event to the NexusLIMS database session log.

Inserts two rows (if needed) into the session_log (marking the start and end of a usage event), only for instruments recognized by NexusLIMS (i.e. that have a row in the instruments table of the DB). If the usage event has not ended yet, no action is performed.

Parameters:

event_id – The NEMO id number for the event to insert

get_session_from_usage_event(event_id: int) → Session | None[source]#

Get a Session representation of a usage event.

Get a Session representation of a usage event for use in dry runs of the record builder.

Parameters:

event_id – The NEMO id number for the event to insert

Returns:

session – A representation of the usage_event from NEMO as a Session object

Return type:

Session

get_known_tool_ids() → List[int][source]#

Get NEMO tool ID values from the NexusLIMS database.

Inspect the api_url values of known Instruments (from the instruments table in the DB), and extract their tool_id number if it is from this NemoConnector.

Returns:

tool_ids – The list of tool ID numbers known to NexusLIMS for this harvester

Return type:

List[int]