pyicat_plus.client.interface.IcatClientInterface#

class pyicat_plus.client.interface.IcatClientInterface[source]#

Bases: object

add_files(dataset_id=None)[source]#

Add missing files to a dataset already ingested.

Parameters:

dataset_id (Optional[int]) – The ICAT dataset identifier.

disconnect()[source]#
do_log_in(password, username=None, plugin='esrf')[source]#

Login to access the restricted part of the API.

Parameters:

  • password (str)

  • username (Optional[str]) – optional username

  • plugin (str) – authentication plugin, defaults to ‘esrf’

Return type:

dict

Returns:

authentication info

download_file_by(sample_id, resource_id, use_chunks=False, chunk_size=8192)[source]#

Download a file associated to a sample.

Parameters:

  • sample_id (str) – Sample identifier.

  • resource_id (str) – Identifier of the resource/file to download.

  • use_chunks (bool) – Read the file in chunks or the entire file into memory at once.

  • chunk_size (int) – Size of each chunk in bytes when use_chunks is True. Default is 8192 (8 KB).

Return type:

bytes

Returns:

The content of the file as bytes.

property expire_datasets_on_close: bool#

A flag indicating whether the dataset expires when it is closed or if it is synchronized with the metadata catalog.

get_datasets_by(investigation_id=None, dataset_ids=None)[source]#

Returns a list of dataset matching the provided criteria.

Parameters:

  • investigation_id (Optional[str]) – an investigationId

  • dataset_ids (Optional[str]) – comma separated list of dataset Ids

Return type:

List[dict]

get_investigations_by(filter=None, instrument_name=None, start_date=None, end_date=None, ids=None)[source]#

Returns a list of investigations matching the provided criteria.

Parameters:

  • filter (Optional[str])

  • instrument_name (Optional[str])

  • start_date (Optional[datetime])

  • end_date (Optional[datetime])

  • ids (Optional[str])

Return type:

List[dict]

Returns:

list of investigations

get_parcels_by(investigation_id)[source]#

Returns the list of parcels associated to an investigation.

Parameters:

investigation_id (str)

Return type:

List[dict]

Returns:

list of parcel information

get_sample_files_information_by(sample_id)[source]#

Returns the sample file information for a given sample.

Parameters:

sample_id (str) – Sample identifier.

Return type:

dict

Returns:

Sample file information as dict.

get_sample_metadata_by(proposal, beamline, session_start_date=None)[source]#

Returns the list of sample metadata associated to a proposal and a beamline.

Parameters:

  • proposal (str) – Proposal identifier (e.g., “hg237”).

  • beamline (str) – Beamline identifier (e.g., “id13”).

  • session_start_date (Optional[date]) – Experiment session start date (format yyyy-MM-dd).

Return type:

List[SampleMetadata]

Returns:

List of sample metadata.

get_samples_by(investigation_id=None, sample_ids=None)[source]#

Returns a list of samples matching the provided criteria.

Parameters:

  • investigation_id (Optional[str]) – an investigationId

  • sample_ids (Optional[str]) – comma separated list of sampleIds

Return type:

List[dict]

get_session_information()[source]#

Returns the information about a session.

Return type:

List[dict]

Returns:

session information

investigation_info(beamline, proposal, date=None, allow_open_ended=True, timeout=None)[source]#

Return the information of the experiment session corresponding to a beamline, proposal and date.

Parameters:

  • beamline (str) – The beamline name.

  • proposal (str) – The proposal name.

  • date (Union[datetime, date, None]) – The date of the proposal, current date by default.

  • allow_open_ended (bool) – If True, enable to select an unofficial experiment session.

  • timeout (Optional[float]) – Set a timeout for the ICAT request.

Return type:

Optional[dict]

Returns:

If found, return the proposal, beamline, e-logbbok url and data portal url of the experiment session.

investigation_info_string(beamline, proposal, date=None, allow_open_ended=True, timeout=None)[source]#

Return the experiment session information as a string.

Parameters:

  • beamline (str) – The beamline name.

  • proposal (str) – The proposal name.

  • date (Union[datetime, date, None]) – The date of the proposal, current date by default.

  • allow_open_ended (bool) – If True, enable to select an unofficial experiment session.

  • timeout (Optional[float]) – Set a timeout for the ICAT request.

Return type:

str

Returns:

If found, return the experiment session information from the metadata catalog as a string.

investigation_summary(beamline, proposal, date=None, allow_open_ended=True, timeout=None)[source]#

Return the experiment session information as a Tuple.

Parameters:

  • beamline (str) – The beamline name.

  • proposal (str) – The proposal name.

  • date (Union[datetime, date, None]) – The date of the proposal, current date by default.

  • allow_open_ended (bool) – If True, enable to select an unofficial experiment session.

  • timeout (Optional[float]) – Set a timeout for the ICAT request.

Return type:

List[Tuple]

Returns:

If found, return the experiment session information from the metadata catalog as a Tuple.

property reason_for_missing_information: str#

A string explaining why some information is missing in the metadata catalog.

registered_dataset_ids(beamline, proposal, date=None, allow_open_ended=True, timeout=None)[source]#

Return the dataset list of an experiment session.

Parameters:

  • beamline (str) – The beamline name of the proposal.

  • proposal (str) – The proposal name.

  • date (Union[datetime, date, None]) – The date of the proposal, current date by default.

  • allow_open_ended (bool) – If True, enable to select an unofficial experiment session.

  • timeout (Optional[float]) – Set a timeout for the ICAT request.

Return type:

Optional[List[DatasetId]]

Returns:

The list of datasets (name and path).

registered_datasets(beamline, proposal, date=None, allow_open_ended=True, timeout=None)[source]#

Return the dataset information list of an experiment session.

Parameters:

  • beamline (str) – The beamline name of the proposal.

  • proposal (str) – The proposal name.

  • date (Union[datetime, date, None]) – The date of the proposal, current date by default.

  • allow_open_ended (bool) – If True, enable to select an unofficial experiment session.

  • timeout (Optional[float]) – Set a timeout for the ICAT request.

Return type:

Optional[List[Dataset]]

Returns:

The list of datasets (name, path, ICAT identifier, and DatasetMetadata).

reschedule_investigation(investigation_id)[source]#

Reschedule an investigation defined by its id.

Parameters:

investigation_id (str)

send_binary_data(data, mimetype=None, beamline=None, proposal=None, investigation_id=None, beamline_only=None, **payload)[source]#

Send an image in base64 format to the proposal or beamline e-logbook.

Parameters:

  • data (bytes) – The binary message content.

  • mimetype (Optional[str]) – {‘text/plain’, ‘text/html’}, optional.

  • beamline (Optional[str]) – The beamline name of the proposal or beamline e-logbook.

  • proposal (Optional[str]) – The proposal name of the e-logbook. Ignored if beamline_only is True.

  • investigation_id (Optional[str]) – The investigation identifier in the ICAT database.

  • beamline_only (Optional[bool]) – if True, the message will be stored in the beamline e-logbook.

  • payload – Additional payload for the e-logbook message. It can contain tags (list of strings or list of dictionaries), the machine, the software.

send_binary_file(filename, beamline=None, proposal=None, beamline_only=None, **payload)[source]#

Send the content of a file as a binary image to the proposal or beamline e-logbook.

Parameters:

  • filename (str) – The filename of the image to be sent.

  • beamline (Optional[str]) – The beamline name of the proposal or beamline e-logbook.

  • proposal (Optional[str]) – The proposal name of the e-logbook. Ignored if beamline_only is True.

  • beamline_only (Optional[bool]) – if True, the message will be stored in the beamline e-logbook.

  • payload – Additional payload for the e-logbook message. It can contain tags (list of strings or list of dictionaries), the machine, the software.

send_message(msg, msg_type=None, beamline=None, proposal=None, investigation_id=None, dataset=None, beamline_only=None, **payload)[source]#

Send a message to the proposal or beamline e-logbook.

Parameters:

  • msg (str) – The message content.

  • msg_type (Optional[str]) – {‘comment’, ‘debug’, ‘info’, ‘error’, ‘commandLine’}, optional.

  • beamline (Optional[str]) – The beamline name of the proposal or beamline e-logbook.

  • proposal (Optional[str]) – The proposal name of the e-logbook. Ignored if beamline_only is True.

  • investigation_id (Optional[str]) – The investigation identifier in the ICAT database.

  • dataset (Optional[str]) – The specific dataset name to link the message to.

  • beamline_only (Optional[bool]) – if True, the message will be stored in the beamline e-logbook.

  • editable – Used with the formatted field, to determine the category of message. Annotation characterizes editable and unformatted messages, while Notification charaterizes non-editable and formatted messages.

  • formatted – Used with the editable field, to determine the category of message. Annotation characterizes editable and unformatted messages, while Notification charaterizes non-editable and formatted messages.

  • mimetype – {‘text/plain’, ‘text/html’}, optional.

  • payload – Additional payload for the message. It can contain tags (list of strings or list of dictionaries), the machine, the software.

send_text_file(filename, beamline=None, proposal=None, dataset=None, investigation_id=None, beamline_only=None, **payload)[source]#

Send the content of a text file as a message to the proposal or beamline e-logbook.

Parameters:

  • filename (str) – The filename containing the message to be sent.

  • beamline (Optional[str]) – The beamline name of the proposal or beamline e-logbook.

  • proposal (Optional[str]) – The proposal name of the e-logbook. Ignored if beamline_only is True.

  • investigation_id (Optional[str]) – The investigation identifier in the ICAT database.

  • beamline_only (Optional[bool]) – if True, the message will be stored in the beamline e-logbook.

  • payload – Additional payload for the e-logbook message. It can contain tags (list of strings or list of dictionaries), the machine, the software.

  • dataset (Optional[str])

start_investigation(beamline=None, proposal=None, start_datetime=None, end_datetime=None)[source]#

Send a message to ActiveMQ to either synchronize the experiment session from the User Portal in ICAT or to create a test experiment session in ICAT.

Parameters:

  • beamline (Optional[str]) – The beamline name of the proposal.

  • proposal (Optional[str]) – The proposal name.

  • start_datetime – The start date of the experiment session, timezone local time. Current date time by default.

  • end_datetime – The end date of the experiment session, timezone local time.

store_dataset(beamline=None, proposal=None, dataset=None, path=None, metadata=None, store_filename=None)[source]#

Request icat to store raw dataset.

Parameters:

  • str (proposal) – beamline name like id01, id15a, bm18…

  • str – proposal name like in1169, blc14795, ihma429…

  • dataset (Optional[str]) – dataset name.

  • path (Optional[str]) – path to the raw dataset to store. Must be a folder.

  • metadata (Optional[dict]) – metadata to associate with the dataset. Must contain keys defined by the appropriate application definition, available at https://icat-esrf-definitions.readthedocs.io.

  • store_filename (Optional[str]) – xml file with metadata to be stored.

  • beamline (Optional[str])

  • proposal (Optional[str])

  • dataset

  • path

  • metadata

  • store_filename

store_dataset_from_file(store_filename=None)[source]#

Send a message to ActiveMQ to store a dataset and the associated metadata from a xml file stored on the disk.

Parameters:

store_filename (Optional[str]) – The XML filename containing all dataset metadata.

store_processed_data(beamline=None, proposal=None, dataset=None, path=None, metadata=None, raw=(), store_filename=None)[source]#

Request icat to store a processed dataset.

Parameters:

  • str (proposal) – beamline name like id01, id15a, bm18…

  • str – proposal name like in1169, blc14795, ihma429…

  • dataset (Optional[str]) – dataset name like sample_XYZ.

  • path (Optional[str]) – path to the processed dataset to store. Can be a file or a folder.

  • metadata (Optional[dict]) – metadata to associate with the dataset. Must contain keys defined by the appropriate application definition, available at https://icat-esrf-definitions.readthedocs.io.

  • raw (Sequence) – Path(s) to the raw dataset(s). Should point to the ‘bliss dataset’ folder(s). If processing relies on multiple datasets, all corresponding folders must be provided.

  • store_filename (Optional[str]) – xml file with metadata to be stored.

  • beamline (Optional[str])

  • proposal (Optional[str])

  • dataset

  • path

  • metadata

  • raw

  • store_filename

update_archive_restore_status(dataset_id=None, type=None, level=ArchiveStatusLevel.INFO, message=None)[source]#

DEPRECATED: This method is deprecated and may be removed in future versions. Update the archiving or restore status of a dataset.

Parameters:

  • dataset_id (Optional[int]) – The ICAT dataset identifier.

  • type (Optional[ArchiveStatusType]) – The type of the status, possible options are {‘archiving’, ‘restoration’}.

  • level (ArchiveStatusLevel) – The level of the status message; possible options are {‘info’, ‘warning’, ‘error’}.

  • message (Optional[str]) – The optional status’ message.

update_metadata(proposal=None, beamline=None, dataset_paths=None, metadata_name=None, metadata_value=None)[source]#

Update or create datasets metadata.

Parameters:

  • proposal (Optional[str]) – The proposal name.

  • beamline (Optional[str]) – The beamline name of the proposal.

  • dataset_paths (Optional[str]) – Comma-separated list of the dataset locations.

  • metadata_name (Optional[str]) – The name of the metadata to update.

  • metadata_value (Optional[str]) – The new value of the metadata.