icat.ids — Provide the IDSClient class

This module defines the IDSClient class that connects to an ICAT Data Service (IDS) as a client.

class icat.ids.DataSelection(objs=None)

Bases: object

A set of data to be processed by the ICAT Data Service.

This can be passed as the selection argument to icat.ids.IDSClient method calls. The objs argument is passed to the extend() method.

extend(objs)

Add objs to the DataSelection.

Parameters:objs (dict, list of icat.entity.Entity, or DataSelection) – either a dict having some of the keys investigationIds, datasetIds, and datafileIds with a list of object ids as value respectively, or a list of entity objects, or another data selection.
class icat.ids.IDSClient(url, sessionId=None, sslContext=None, proxy=None)

Bases: object

A client accessing an ICAT Data Service.

The attribute sessionId must be set to a valid ICAT session id from the ICAT client.

ping()

Check that the server is alive and is an IDS server.

getApiVersion()

Get the version of the IDS server.

Note: the getApiVersion call has been added in IDS server version 1.3.0. For older servers, try to guess the server version from features visible in the API. Obviously this cannot always be accurate as we cannot distinguish server version with no visible API changes. In particular, versions older then 1.2.0 will always reported as 1.0.0. Nevertheless, the result of the guess should be fair enough for most use cases.

version()

Get the version of the IDS server.

Note: the version call has been added in IDS server version 1.8.0, deprecating getApiVersion at the same time. For older servers, we fall back to getApiVersion to emulate this call. Note furthermore that version returns a dict, while getApiVersion returns the plain version number as a string.

getIcatUrl()

Get the URL of the ICAT server connected to this IDS.

isReadOnly()

See if the server is configured to be readonly.

isTwoLevel()

See if the server is configured to use both main and archive storage.

getServiceStatus()

Return information about what the IDS is doing.

If all lists are empty it is quiet. To use this call, the user represented by the sessionId must be in the set of rootUserNames defined in the IDS configuration.

getSize(selection)

Return the total size of the datafiles.

getStatus(selection)

Return the status of data.

archive(selection)

Archive data.

restore(selection)

Restore data.

write(selection)

Write data.

reset(selection)

Reset data so that they can be queried again.

resetPrepared(preparedId)

Reset prepared data so that they can be queried again.

Deprecated since version 0.17.0: Call reset() instead.

prepareData(selection, compressFlag=False, zipFlag=False)

Prepare data for a subsequent getData() call.

isPrepared(preparedId)

Check if data is ready.

Returns true if the data identified by the preparedId returned by a call to prepareData() is ready.

getDatafileIds(selection)

Get the list of data file id corresponding to the selection.

getPreparedDatafileIds(preparedId)

Get the list of data file id corresponding to the prepared Id.

Deprecated since version 0.17.0: Call getDatafileIds() instead.

getData(selection, compressFlag=False, zipFlag=False, outname=None, offset=0)

Stream the requested data.

getDataUrl(selection, compressFlag=False, zipFlag=False, outname=None)

Get the URL to retrieve the requested data.

getPreparedData(preparedId, outname=None, offset=0)

Get prepared data.

Get the data using the preparedId returned by a call to prepareData().

Deprecated since version 0.17.0: Call getData() instead.

getPreparedDataUrl(preparedId, outname=None)

Get the URL to retrieve prepared data.

Get the URL to retrieve data using the preparedId returned by a call to prepareData().

Deprecated since version 0.17.0: Call getDataUrl() instead.

Return a hard link to a data file.

This is only useful in those cases where the user has direct access to the file system where the IDS is storing data. The caller is only granted read access to the file.

put(inputStream, name, datasetId, datafileFormatId, description=None, doi=None, datafileCreateTime=None, datafileModTime=None)

Put data into IDS.

Put the data in the inputStream into a data file and catalogue it. The client generates a checksum which is compared to that produced by the server to detect any transmission errors.

delete(selection)

Delete data.