icat.entity — Provide the Entity class

class icat.entity.Entity(client, instance, **kwargs)

Bases: object

The base of the classes representing the entities in the ICAT schema.

Entity is the abstract base for a hierarchy of classes representing the entities in the ICAT schema. It implements the basic behavior of these classes.

Each Entity object is connected to an instance of suds.sudsobject.Object, named instance in the following. Instances are created by Suds based on the ICAT WSDL schema. Entity objects mimic the behavior of the corresponding instance. Attribute accesses are proxied to the instance. A transparent conversion between Entity objects and Suds instances is performed where appropriate.

BeanName = None

Name of the entity in the ICAT schema, None for abstract classes.

Constraint = ('id',)

Attribute or relation names that form a uniqueness constraint.

SelfAttr = frozenset({'client', 'instance', 'validate'})

Attributes stored in the Entity object itself.

InstAttr = frozenset({'id'})

Attributes of the entity in the ICAT schema, stored in the instance.

MetaAttr = frozenset({'createId', 'createTime', 'modId', 'modTime'})

Readonly meta attributes, retrieved from the instance.

InstRel = frozenset({})

Many to one relationships in the ICAT schema.

InstMRel = frozenset({})

One to many relationships in the ICAT schema.

AttrAlias = {}

Map of alias names for attributes and relationships.

SortAttrs = None

List of attributes used for sorting. Uses Constraint if None.

validate = None

Hook to add a pre create validation method.

This may be set to a function that expects one argument, the entity object. It will then be called before creating the object at the ICAT server. The function is expected to raise an exception (preferably ValueError) in case of validation errors.

classmethod getInstanceName()

Get the name of this class in the ICAT WSDL.

New in version 1.0.0.

classmethod getInstance(obj)

Get the corresponding instance from an object.

classmethod getInstances(objs)

Translate a list of objects into the list of corresponding instances.

classmethod getAttrInfo(client, attr)

Get information on an attribute.

Query the EntityInfo of the entity from the ICAT server and retrieve information on one of the attributes from it.

Parameters:
Returns:

information on the attribute.

Raises:

ValueError – if this is an abstract entity class or if no attribute by that name is found.

classmethod getNaturalOrder(client)

Return a natural order for this class.

The order is a list of attributes suitable to be used in a ORDER BY clause in an ICAT search expression. The natural order is the one that is as close as possible to sorting the objects by the __sortkey__(). It is based on Constraint or the SortAttrs, if the latter are defined. In any case, one to many relationships and nullable many to one relationships are removed from the list.

copy()

Return a shallow copy of this entity object.

Create a new object that has all attributes set to a copy of the corresponding values of this object. The relations are copied by reference, i.e. the original and the copy refer to the same related object.

>>> inv = client.new("Investigation", name="Investigation A")
>>> ds = client.new("Dataset", investigation=inv, name="Dataset X")
>>> cds = ds.copy()
>>> cds.name
'Dataset X'
>>> cds.investigation.name
'Investigation A'
>>> cds.name = "Dataset Y"
>>> cds.investigation.name = "Investigation B"
>>> ds.name
'Dataset X'
>>> ds.investigation.name
'Investigation B'
__sortkey__()

Return a key for sorting.

This is suitable to be passed as key to the list.sort() method. E.g. if l is a list of Entity objects, you can sort it using:

>>> l.sort(key=icat.entity.Entity.__sortkey__)
as_dict()

Return a dict with the object’s attributes.

getAttrType(attr)

Get the type of an attribute.

Query this object’s EntityInfo from the ICAT server and retrieve the type of one of the attributes from it. In the case of a relation attribute, this yields the BeanName of the related object.

Parameters:

attr (str) – name of the attribute.

Returns:

name of the attribute type.

Return type:

str

Raises:

ValueError – if no attribute by that name is found.

truncateRelations(keepInstRel=False)

Delete all relationships.

Delete all attributes having relationships to other objects from this object. Note that this is a local operation on the object in the client only. It does not affect the corresponding object at the ICAT server. This is useful if you only need to keep the object’s attributes but not the (possibly large) tree of related objects in local memory.

Parameters:

keepInstRel (bool) – if True, delete only the one to many, but keep the many to one relationships. This is particularly useful if you want to call update() for this object later on, because in this case, you’d definitely need to keep the many to one relationships, but you may want to avoid transmitting a large tree of objects in one to many relationships to the ICAT server in the call, as they’d be essentially useless then.

Changed in version 1.1.0: add the keepInstRel argument.

getUniqueKey(keyindex=None)

Return a unique key.

The key is a string that is guaranteed to be unique for all entities in the ICAT. All attributes that form the uniqueness constraint must be set. A icat.client.Client.search() or icat.client.Client.get() with the appropriate include clause may be required before calling this method.

if keyindex is not None, it is used as a cache of previously generated keys. It must be a dict that maps entity ids to the keys returned by previous calls of getUniqueKey() on other entity objects. The newly generated key will be added to this index.

Parameters:

keyindex (dict) – cache of generated keys.

Returns:

a unique key.

Return type:

str

Raises:

DataConsistencyError – if a relation required in a constraint is not set.

create()

Call icat.client.Client.create() to create the object in the ICAT.

update()

Call icat.client.Client.update() to update the object in the ICAT.

get(query=None)

Call icat.client.Client.get() to get the object from the ICAT.