icat.client — Provide the Client class

class icat.client.Client(url, **kwargs)

Bases: suds.client.Client

A client accessing an ICAT service.

Client is a subclass of suds.client.Client and inherits most of its behavior. It adds methods for the instantiation of ICAT entities and implementations of the ICAT API methods.

Instance attributes:

Client.apiversion

Version of the ICAT server this client connects to.

Client.autoLogout

Flag whether the client should logout automatically on exit.

Client.ids

The icat.ids.IDSClient instance used for IDS calls.

Client.sessionId

The session id as returned from icat.client.Client.login().

Client.sslContext

The ssl.SSLContext instance that has been used to establish the HTTPS conection to the ICAT and IDS server. This is None for old Python versions that do not have the ssl.SSLContext class.

Client.typemap

A dict that maps type names from the ICAT WSDL schema to the corresponding classes in the icat.entity.Entity hierarchy.

Client.url

The URL to the web service description of the ICAT server.

Class and instance methods:

classmethod Client.cleanupall()

Cleanup all class instances.

Call icat.client.Client.cleanup() on all registered class instances, e.g. on all clients that have not yet been cleaned up.

Client.cleanup()

Release resources allocated by the client.

Logout from the active ICAT session (if self.autoLogout is True). The client should not be used any more after calling this method.

Client.add_ids(url, proxy=None)

Add the URL to an ICAT Data Service.

Client.new(obj, **kwargs)

Instantiate a new icat.entity.Entity object.

If obj is a string, take it as the name of an instance type. Create a new instance object of this type and lookup the class for the object in the self.typemap using this type name. If obj is an instance object, look up its class name in the typemap to determine the class. If obj is None, do nothing and return None.

Parameters:

• obj (suds.sudsobject.Object or str) – either a Suds instance object, a name of an instance type, or None.
• kwargs – attributes passed to the constructor of icat.entity.Entity.

Returns:

the new entity object or None.

Return type:

icat.entity.Entity

Raises TypeError:  

if obj is neither a valid instance object, nor a valid name of an entity type, nor None.

Client.getEntityClass(name)

Return the Entity class corresponding to a BeanName.

Client.getEntity(obj)

Get the corresponding icat.entity.Entity for an object.

If obj is a Suds instance object, create a new object with icat.client.Client.new(). Otherwise do nothing and return obj unchanged.

Parameters:obj (suds.sudsobject.Object or any type) – either a Suds instance object or anything. Returns:the new entity object or obj. Return type:icat.entity.Entity or any type

ICAT API methods

These methods implement the ICAT API calls. Please refer to the ICAT Java Client documentation for details.

Client.login(auth, credentials)

Client.logout()

Client.create(bean)

Client.createMany(beans)

Client.delete(bean)

Client.deleteMany(beans)

Client.get(query, primaryKey)

Client.getApiVersion()

Client.getEntityInfo(beanName)

Client.getEntityNames()

Client.getProperties()

Client.getRemainingMinutes()

Client.getUserName()

Client.isAccessAllowed(bean, accessType)

Client.refresh()

Client.search(query)

Client.update(bean)

Custom API methods

Client.assertedSearch(query, assertmin=1, assertmax=1)

Search with an assertion on the result.

Perform a search and verify that the number of items found lies within the bounds of assertmin and assertmax. Raise an error if this assertion fails.

Parameters:

• query (icat.query.Query or str) – the search query.
• assertmin (int) – minimum number of expected results.
• assertmax (int) – maximum number of expected results. A value of None is treated as infinity.

Returns:

search result.

Return type:

list

Raises:

• ValueError – in case of inconsistent arguments.
• SearchAssertionError – if the assertion on the number of results fails.
• ICATError – in case of exceptions raised by the ICAT server.

Client.searchChunked(query, skip=0, count=None, chunksize=100)

Search the ICAT server.

Call the ICAT icat.client.Client.search() API method, limiting the number of results in each call and repeat the call as often as needed to retrieve all the results.

This can be used as a drop in replacement for the search API method most of the times. It avoids the error if the number of items in the result exceeds the limit imposed by the ICAT server. There are a few subtle differences though: the query must not contain a LIMIT clause (use the skip and count arguments instead) and should contain an ORDER BY clause. The return value is an iterator over the items in the search result rather then a list. The individual search calls are done lazily, e.g. they are not done until needed to yield the next item from the iterator. The result may be defective (omissions, duplicates) if the content in the ICAT server changes between individual search calls in a way that would affect the result.

Parameters:

• query (icat.query.Query or str) – the search query.
• skip (int) – offset from within the full list of available results.
• count (int) – maximum number of items to return. A value of None means no limit.
• chunksize (int) – number of items to query in each search call. This is an internal tuning parameter and does not affect the result.

Returns:

a generator that iterates over the items in the search result.

Return type:

generator

Client.searchUniqueKey(key, objindex=None)

Search the object that belongs to a unique key.

This is in a sense the inverse method to icat.entity.Entity.getUniqueKey(), the key must previously have been generated by it. This method searches the Entity object that the key has been generated for from the server.

if objindex is not None, it is used as a cache of previously retrieved objects. It must be a dict that maps keys to Entity objects. The object retrieved by this method call will be added to this index.

This method uses the JPQL inspired query syntax introduced with ICAT 4.3.0. It won’t work with older ICAT servers.

Parameters:

• key (str) – the unique key of the object to search for.
• objindex (dict) – cache of Entity objects.

Returns:

the object corresponding to the key.

Return type:

icat.entity.Entity

Raises:

• SearchResultError – if the object has not been found.
• ValueError – if the key is not well formed.
• VersionMethodError – if connected to an ICAT server older then 4.3.0.

Client.searchMatching(obj, includes=None)

Search the matching object.

Search the object from the ICAT server that matches the given object in the uniqueness constraint.

>>> dataset = client.new("dataset", investigation=inv, name=dsname)
>>> dataset = client.searchMatching(dataset)
>>> dataset.id
172383L

Parameters:

• obj (icat.entity.Entity) – an entity object having the attrinutes for the uniqueness constraint set accordingly.
• includes (iterable of str) – list of related objects to add to the INCLUDE clause of the search query. See icat.query.Query.addIncludes() for details.

Returns:

the corresponding object.

Return type:

icat.entity.Entity

Raises:

• SearchResultError – if the object has not been found.
• ValueError – if the object’s class does not have a uniqueness constraint or if any attribute needed for the constraint is not set.

Client.createUser(name, search=False, **kwargs)

Search a user by name or Create a new user.

If search is True search a user by the given name. If search is False or no user is found, create a new user.

Parameters:

• name (str) – username.
• search (bool) – flag whether a user should be searched first.
• kwargs – attributes of the user passed to new.

Returns:

the user.

Return type:

icat.entity.Entity

Client.createGroup(name, users=[])

Create a group and add users to it.

Parameters:

• name (str) – the name of the group.
• users (list of icat.entity.Entity) – a list of users.

Returns:

the group.

Return type:

icat.entity.Entity

Client.createRules(crudFlags, what, group=None)

Create access rules.

Parameters:

• crudFlags (str) – access mode.
• what (list) – list of items subject to the rule. The items must be either ICAT search expression strings or icat.query.Query objects.
• group (icat.entity.Entity) – the group that should be granted access or None for everybody.

Returns:

list of the ids of the created rules.

Return type:

list of long

Custom IDS methods

Client.putData(infile, datafile)

Upload a datafile to IDS.

The content of the file to upload is read from infile, either directly if it is an open file, or a file by that named will be opened for reading.

The datafile object must be initialized but not yet created at the ICAT server. It will be created by the IDS. The ids of the Dataset and the DatafileFormat as well as the attributes description, doi, datafileCreateTime, and datafileModTime will be taken from datafile. If datafileModTime is not set, the method will try to os.fstat() infile and use the last modification time from the file system, if available. If datafileCreateTime is not set, it will be set to datafileModTime.

Note that only the attributes datafileFormat, dataset, description, doi, datafileCreateTime, and datafileModTime of datafile will be taken into account as described above. All other attributes are ignored and the Datafile object created in the ICAT server might end up with different values for those other attribues.

Parameters:

• infile (file or str) – either a file opened for reading or a file name.
• datafile (icat.entity.Entity) – A Datafile object.

Returns:

The Datafile object created by IDS.

Return type:

icat.entity.Entity

Client.getData(objs, compressFlag=False, zipFlag=False, outname=None, offset=0)

Retrieve the requested data from IDS.

The data objects to retrieve are given in objs. This can be any combination of single Datafiles, Datasets, or complete Investigations.

Parameters:

• objs (dict, list of icat.entity.Entity, or icat.ids.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 a data selection.
• compressFlag (bool) – flag whether to use a zip format with an implementation defined compression level, otherwise use no (or minimal) compression.
• zipFlag (bool) – flag whether return a single datafile in zip format. For multiple files zip format is always used.
• outname (str) – the preferred name for the downloaded file to specify in the Content-Disposition header.
• offset (int) – if larger then zero, add Range header to the HTTP request with the indicated bytes offset.

Returns:

a file-like object as returned by urllib2.OpenerDirector.open().

Client.getDataUrl(objs, compressFlag=False, zipFlag=False, outname=None)

Get the URL to retrieve the requested data from IDS.

The data objects to retrieve are given in objs. This can be any combination of single Datafiles, Datasets, or complete Investigations.

Note that the URL contains the session id of the current ICAT session. It will become invalid if the client logs out.

Parameters:

• objs (dict, list of icat.entity.Entity, or icat.ids.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 a data selection.
• compressFlag (bool) – flag whether to use a zip format with an implementation defined compression level, otherwise use no (or minimal) compression.
• zipFlag (bool) – flag whether return a single datafile in zip format. For multiple files zip format is always used.
• outname (str) – the preferred name for the downloaded file to specify in the Content-Disposition header.

Returns:

the URL for tha data at the IDS.

Return type:

str

Client.prepareData(objs, compressFlag=False, zipFlag=False)

Prepare data at IDS to be retrieved in subsequent calls.

The data objects to retrieve are given in objs. This can be any combination of single Datafiles, Datasets, or complete Investigations.

Parameters:

• objs (dict, list of icat.entity.Entity, or icat.ids.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 a data selection.
• compressFlag (bool) – flag whether to use a zip format with an implementation defined compression level, otherwise use no (or minimal) compression.
• zipFlag (bool) – flag whether return a single datafile in zip format. For multiple files zip format is always used.

Returns:

preparedId, an opaque string which may be used as an argument to icat.client.Client.isDataPrepared() and icat.client.Client.getPreparedData() calls.

Return type:

str

Client.isDataPrepared(preparedId)

Check if prepared data is ready at IDS.

Parameters:preparedId (str) – the id returned by icat.client.Client.prepareData(). Returns:True if the data is ready, otherwise False. Return type:bool

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

Retrieve prepared data from IDS.

Parameters:

• preparedId (str) – the id returned by icat.client.Client.prepareData().
• outname (str) – the preferred name for the downloaded file to specify in the Content-Disposition header.
• offset (int) – if larger then zero, add Range header to the HTTP request with the indicated bytes offset.

Returns:

a file-like object as returned by urllib2.OpenerDirector.open().

Client.getPreparedDataUrl(preparedId, outname=None)

Get the URL to retrieve prepared data from IDS.

Parameters:

• preparedId (str) – the id returned by icat.client.Client.prepareData().
• outname (str) – the preferred name for the downloaded file to specify in the Content-Disposition header.

Returns:

the URL for tha data at the IDS.

Return type:

str

Client.deleteData(objs)

Delete data from IDS.

The data objects to delete are given in objs. This can be any combination of single Datafiles, Datasets, or complete Investigations.

Parameters:objs (dict, list of icat.entity.Entity, or icat.ids.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 a data selection.