icat
index
/home/fisher/workspace/icat.client/src/main/python/icat.py

 
Modules
       
json
requests

 
Classes
       
__builtin__.object
ICAT
Session
exceptions.Exception(exceptions.BaseException)
IcatException

 
class ICAT(__builtin__.object)
     Methods defined here:
__init__(self, uri, cert=None)
Create a RESTful ICAT instance connected to the server at the specified
URI.
 
A cert may be specified for self signed certificates - it must be 
in DER format. If the certificate has a value of False then 
certificate checking is disabled.
getVersion(self)
Returns the version of the ICAT server
isLoggedIn(self, userName)
Return true if the specified user has at least one session else 
false. 
 
The userName passed in must match that returned by
getUserName and so must include the authenticator mnemomic if 
the authenticator was configured to include it - which should
generally be the case.
login(self, plugin, cmap)
Login and return a session
 
The plugin argument is the mnemonic of the authenticator and cmap is a
map of credential keys to credential values

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class IcatException(exceptions.Exception)
    Thrown by the code to indicate problems.
 
 
Method resolution order:
IcatException
exceptions.Exception
exceptions.BaseException
__builtin__.object

Methods defined here:
__init__(self, code, message, offset=-1)
Not expected to be called by most users
__str__(self)
getMessage(self)
Return a human readable message
getOffset(self)
Return the offset or -1 if not applicable
getType(self)
Return the type of the exception as a string

Data descriptors defined here:
__weakref__
list of weak references to the object (if defined)

Data and other attributes defined here:
BAD_PARAMETER = 'BAD_PARAMETER'
INSUFFICIENT_PRIVILEGES = 'INSUFFICIENT_PRIVILEGES'
INTERNAL = 'INTERNAL'
NOT_IMPLEMENTED = 'NOT_IMPLEMENTED'
NO_SUCH_OBJECT_FOUND = 'NO_SUCH_OBJECT_FOUND'
OBJECT_ALREADY_EXISTS = 'OBJECT_ALREADY_EXISTS'
SESSION = 'SESSION'
VALIDATION = 'VALIDATION'

Data and other attributes inherited from exceptions.Exception:
__new__ = <built-in method __new__ of type object>
T.__new__(S, ...) -> a new object with type S, a subtype of T

Methods inherited from exceptions.BaseException:
__delattr__(...)
x.__delattr__('name') <==> del x.name
__getattribute__(...)
x.__getattribute__('name') <==> x.name
__getitem__(...)
x.__getitem__(y) <==> x[y]
__getslice__(...)
x.__getslice__(i, j) <==> x[i:j]
 
Use of negative indices is not supported.
__reduce__(...)
__repr__(...)
x.__repr__() <==> repr(x)
__setattr__(...)
x.__setattr__('name', value) <==> x.name = value
__setstate__(...)
__unicode__(...)

Data descriptors inherited from exceptions.BaseException:
__dict__
args
message

 
class Session(__builtin__.object)
     Methods defined here:
__init__(self, icat, sessionId)
Not expected to be called by most users. A Session object
is normally generated by a login call to an ICAT object.
cloneEntity(self, name, idValue, keys)
Clone an entity and return the id of the clone
 
name is the name of the type of entity and idValue is the id value of the entity to be cloned
 
keys is a dict with mappings from field names to values to be different in the clone
 
the id of the clone is returned
delete(self, entities)
Delete ICAT entities from nested lists and dicts.
 
If there are multiple top level entities to be deleted then the argument
passed in must be a list. Each top level entity is represented by a dict
with a key of the entity name and a value which is a dict where the keys
are the attribute names and the values are the entity field values.
The only permitted key is the id - which is also required.
 
For example to delete an Investigation:
 
entity = {"Investigation" : {"id" : invid}}
self.session.delete(entity)
 
Remember that all to-many relationships will be followed so, in this case,
all the Datasets of the Investigation will be deleted recursively. DELETE 
permission is required for every entity in the tree.
exportMetaData(self, query=None, attributes=None)
get(self, query, idValue)
Carry out an ICAT get of the entity with the specified idValue and return the result.
 
The query might be just the name of the entity type. For example the query
 
"Facility" will return the facility specified by the idValue
 
The INCLUDE keyword can also be used as in "Dataset ds INCLUDE ds.datafiles"
getRemainingMinutes(self)
Return the time remaining in the session in minutes
getUserName(self)
Return the user name corresponding to the session.
importMetaData(self, data, duplicate=None, attributes=None)
logout(self)
Logout of the session after which the session cannot be re-used
refresh(self)
Refresh the session by resetting the time remaining
search(self, query)
Carry out an ICAT search and return the results
 
The query takes the form of JPQL. For example the query
 
SELECT f.id, f.name from Facility f
 
returns a list of lists which in this case might be:
 
[[17, "abcd"], [18, "efgh"]]
 
If only one attribute is requested then it returns simply a list of values so that
 
"SELECT f.name from Facility f" would return ["abcd", "efgh"]
 
Functions such as COUNT are not treated as special cases so the query 
"SELECT COUNT(f) FROM Facility f" would in this case return [2] which is a list
of length 1 
 
The old query syntax is also supported but is not recommended as it is 
better adapted to SOAP calls.
write(self, entities)
Write (create or update) ICAT entities from nested lists and dicts.
 
If there are multiple top level entities to be handled then the argument
passed in must be a list. Each top level entity is represented by a dict with a 
key of the entity name and a value which is a dict where the keys are the 
attribute names and the values are the entity field values.
 
A list of the ids of the top level entities created is returned.
 
A simple example which will create a single Facility and return its id is:
 
facility = {}
facility["name"] = "Test Facility"
entity = {"Facility":facility}
fid = session.write(entity)[0]
 
or in one line:
 
fid = session.write({"Facility":{"name":Test Facility}})
 
If the attribute is a many to one relationship then the value is a dict and if it 
is a one to many relationship then the value is a list of dicts.
 
For example to create a dataset referencing the already existing Investigation 
with id of invid and DatasetType with id of dstid and creating two new datafiles:
 
dataset = {"name" : "ds1", "investigation" : { "id" : invid}, "type": {"id":dstid}}
dataset["datafiles"] = [{"name" : "df1"}, {"name":"df2"}]
entity = {"Dataset" : dataset}
dsid = self.session.write(entity)[0]
 
In all cases many to one relationships must already exist and so must 
be specified by their id value while one to many relationships cannot exist
prior to the call and so the id value is omitted.
 
For updating pass in the id of top level entity and the attributes you specify 
will be updated. In the case of a one to many relationship any new entities 
will be appended. So to add a Datafile to a Dataset one could write and at
the same time updating the description field:
 
dataset["id"] = dsid
dataset["datafiles"] = [{"name" : "df3"}]
dataset["description"] = "Indescribable"
entity = {"Dataset" : dataset}
self.session.write(entity)
 
This will return an empty list because no new Dataset has been created and so 
this is regarded as an update. The similar operation:
 
datafile = {"name" : "df3", dataset {"id" : dsid}}
entity = {"Datafile" : datafile}
dfid = self.session.write(entity)[0]
 
also results in a Datafile being added to the Dataset but in this case it is
treated as a creation and the id of the Datafile is returned. If it is wished to 
update the dataset description at the same time then one could write:
 
entities = []
datafile = {"name" : "df3", dataset {"id" : dsid}}
entities.append({"Datafile" : datafile})
dataset["id"] = dsid
dataset["description"] = "Indescribable"
entities.append({"Dataset" : dataset})
dfid = self.session.write(entity)[0]
 
where this time as list (an existing Dataset to be updated) and a Datafile to be created
are passed in.

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

Data and other attributes defined here:
ALL = 'ALL'
CHECK = 'CHECK'
IGNORE = 'IGNORE'
OVERWRITE = 'OVERWRITE'
THROW = 'THROW'
USER = 'USER'