icat.client
— Provide the Client class¶
The icat.client
defines the Client
class
that manages the interaction with an ICAT service as a client.
-
class
icat.client.
Client
(url, idsurl=None, checkCert=True, caFile=None, caPath=None, sslContext=None, proxy=None, **kwargs)¶ Bases:
suds.client.Client
A client accessing an ICAT service.
This 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.Parameters: - url (
str
) – The URL pointing to the WSDL of the ICAT service. If the URL does not contain a path, e.g. contains only a URL scheme and network location part, a default path is assumend. - idsurl (
str
) – The URL pointing to the IDS service. If set, anicat.ids.IDSClient
instance will be created. - checkCert (
bool
) – Flag whether the server’s SSL certificate should be verified if connecting ICAT with HTTPS. - caFile (
str
) – Path to a file of concatenated trusted CA certificates. If neither caFile nor caPath is set, the system’s default certificates will be used. - caPath (
str
) – Path to a directory containing trusted CA certificates. If neither caFile nor caPath is set, the system’s default certificates will be used. - sslContext (
ssl.SSLContext
) – A SSL context describing various SSL options to be used in HTTPS connections. If set, this will override checkCert, caFile, and caPath. - proxy (
dict
) – HTTP proxy settings. A map with the keys http_proxy and https_proxy and the URL of the respective proxy to use as values. - kwargs – additional keyword arguments that will be passed to
suds.client.Client
, seesuds.options.Options
for details.
Class attributes
-
Register
¶ The register of all active clients.
-
AutoRefreshRemain
¶ Number of minutes to leave in the session before automatic refresh should be called.
Instance attributes
-
url
¶ The URL to the web service description of the ICAT server.
-
kwargs
¶ A copy of the kwargs used in the constructor.
-
apiversion
¶ Version of the ICAT server this client connects to.
-
autoLogout
¶ Flag whether the client should logout automatically on exit.
-
ids
¶ The
icat.ids.IDSClient
instance used for IDS calls.
-
sslContext
¶ The
ssl.SSLContext
instance that has been used to establish the HTTPS conection to the ICAT and IDS server. This isNone
for old Python versions that do not have thessl.SSLContext
class.
-
typemap
¶ A
dict
that maps type names from the ICAT WSDL schema to the corresponding classes in theicat.entity.Entity
hierarchy.
Class and instance methods
-
classmethod
cleanupall
()¶ Cleanup all class instances.
Call
cleanup()
on all registered class instances, e.g. on all clients that have not yet been cleaned up.
-
cleanup
()¶ Release resources allocated by the client.
Logout from the active ICAT session (if
autoLogout
isTrue
). The client should not be used any more after calling this method.
-
add_ids
(url, proxy=None)¶ Add the URL to an ICAT Data Service.
-
clone
()¶ Create a clone.
Return a clone of the
Client
object. That is, a client that connects to the same ICAT server and has been created with the same kwargs. The clone will be in the state as returned from the constructor. In particular, it does not share the same session if this client object is logged in.Returns: a clone of the client object. Return type: 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
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 isNone
, do nothing and returnNone
.Parameters: - obj (
suds.sudsobject.Object
orstr
) – either a Suds instance object, a name of an instance type, orNone
. - kwargs – attributes passed to the constructor of
icat.entity.Entity
.
Returns: the new entity object or
None
.Return type: Raises: EntityTypeError – if obj is neither a valid instance object, nor a valid name of an entity type, nor None.
- obj (
-
getEntityClass
(name)¶ Return the Entity class corresponding to a BeanName.
-
getEntity
(obj)¶ Get the corresponding
icat.entity.Entity
for an object.if obj is a fieldSet, return a tuple of the fields. If obj is any other Suds instance object, create a new entity object with
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: tuple
oricat.entity.Entity
or any typeChanged in version 0.18.0: add support of fieldSet.
ICAT API methods
These methods implement the low level API calls of the ICAT server. See the documentation in the ICAT SOAP Manual. (Note: the Python examples in that manual are based on plain Suds, not on python-icat.)
-
login
(auth, credentials)¶
-
logout
()¶
-
create
(bean)¶
-
createMany
(beans)¶
-
delete
(bean)¶
-
deleteMany
(beans)¶
-
get
(query, primaryKey)¶
-
getApiVersion
()¶
-
getAuthenticatorInfo
()¶
-
getEntityInfo
(beanName)¶
-
getEntityNames
()¶
-
getProperties
()¶
-
getRemainingMinutes
()¶
-
getUserName
()¶
-
getVersion
()¶
-
isAccessAllowed
(bean, accessType)¶
-
refresh
()¶
-
search
(query)¶
-
update
(bean)¶
Custom API methods
These higher level methods build on top of the ICAT API methods.
-
autoRefresh
()¶ Call
refresh()
only if needed.Call
refresh()
if less thenAutoRefreshRemain
minutes remain in the current session. Do not make any client calls if not. This method is supposed to be very cheap if enough time remains in the session so that it may be called often in a loop without causing too much needless load.
-
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
orstr
) – the search query. - assertmin (
int
) – minimum number of expected results. - assertmax (
int
) – maximum number of expected results. A value ofNone
is treated as infinity.
Returns: search result.
Return type: 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.
- query (
-
searchChunked
(query, skip=0, count=None, chunksize=100)¶ Search the ICAT server.
Call the ICAT
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 a generator yielding successively 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 generator.
Note
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. It is a common mistake when looping over items returned from this method to have code with side effects on the search result in the body of the loop. Example:
# Mark all datasets as complete # This will *not* work as expected! query = Query(client, "Dataset", conditions={ "complete": "= False" }, includes="1", order=["id"]) for ds in client.searchChunked(query): ds.complete = True ds.update()
This should rather be formulated as:
# Mark all datasets as complete # This version works! query = Query(client, "Dataset", includes="1", order=["id"]) for ds in client.searchChunked(query): if not ds.complete: continue ds.complete = True ds.update()
Parameters: - query (
icat.query.Query
orstr
) – the search query. - skip (
int
) – offset from within the full list of available results. - count (
int
) – maximum number of items to return. A value ofNone
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 successively yields the items in the search result.
Return type: generator
- query (
-
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.Parameters: Returns: the object corresponding to the key.
Return type: Raises: - SearchResultError – if the object has not been found.
- ValueError – if the key is not well formed.
-
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 172383
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. Seeicat.query.Query.addIncludes()
for details.
Returns: the corresponding object.
Return type: 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.
- obj (
-
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 isFalse
or no user is found, create a new user.Parameters: Returns: the user.
Return type:
-
createGroup
(name, users=())¶ Create a group and add users to it.
Parameters: - name (
str
) – the name of the group. - users (
list
oficat.entity.Entity
) – a list of users.
Returns: the group.
Return type: - name (
-
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 oricat.query.Query
objects. - group (
icat.entity.Entity
) – the group that should be granted access orNone
for everybody.
Returns: list of the ids of the created rules.
Return type: - crudFlags (
Custom IDS methods
These methods provide the most commonly needed IDS functionality and build on top of the low level IDS API methods provided by
icat.ids.IDSClient
.-
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 name 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
orstr
) – 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: - infile (
-
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
oficat.entity.Entity
,icat.ids.DataSelection
, orstr
) – 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, or an id returned byprepareData()
. - 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
urllib.request.OpenerDirector.open()
.- objs (
-
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
oficat.entity.Entity
,icat.ids.DataSelection
, orstr
) – 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, or an id returned byprepareData()
. - 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 the data at the IDS.
Return type: - objs (
-
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
oficat.entity.Entity
, oricat.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
isDataPrepared()
andgetData()
calls.Return type: - objs (
-
isDataPrepared
(preparedId)¶ Check if prepared data is ready at IDS.
Parameters: preparedId ( str
) – the id returned byprepareData()
.Returns: True
if the data is ready, otherwiseFalse
.Return type: bool
-
getPreparedData
(preparedId, outname=None, offset=0)¶ Retrieve prepared data from IDS.
Parameters: - preparedId (
str
) – the id returned byprepareData()
. - 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
urllib.request.OpenerDirector.open()
.Deprecated since version 0.17.0: Call
getData()
instead.- preparedId (
-
getPreparedDataUrl
(preparedId, outname=None)¶ Get the URL to retrieve prepared data from IDS.
Parameters: - preparedId (
str
) – the id returned byprepareData()
. - 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: Deprecated since version 0.17.0: Call
getDataUrl()
instead.- preparedId (
-
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
oficat.entity.Entity
, oricat.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.
- url (