caosdb.common.models module

missing docstring.

class caosdb.common.models.ACI(realm, username, role, permission)

Bases: object

add_to_element(e)
class caosdb.common.models.ACL(xml=None)

Bases: object

clear()
combine(other)

Combine and return new instance.

deny(username=None, realm=None, role=None, permission=None, priority=False)
get_acl_for_role(role)
get_acl_for_user(username, realm=None)
get_permissions_for_role(role)
get_permissions_for_user(username, realm=None)
global_acl = None
grant(username=None, realm=None, role=None, permission=None, priority=False)
is_empty()
is_permitted(role, permission)
parse_xml(xml)
revoke_denial(username=None, realm=None, role=None, permission=None, priority=False)
revoke_grant(username=None, realm=None, role=None, permission=None, priority=False)
to_xml(xml=None)
class caosdb.common.models.Container

Bases: list

Container is a type safe list for Entities.

It also provides several short-cuts for transactions like retrieval, insertion, update, and deletion which are a applied to all entities in the container or the whole container respectively.

add_message(m)
append(entity)

Append an entity container.

If the parameter is an integer an entity with the corresponding ID is appended. If the parameter is a string an entity with the corresponding name is appended. Raise a TypeError if the entity is not a sub type of the correct class (as defined via the constructor).

@param entity: The entity to be appended.

clear_server_messages()
delete(raise_exception_on_error=True, flags=None, chunk_size=100)

Delete all entities in this container.

Entities are identified via their id if present and via their name otherwise. If any entity has no id and no name a TransactionError will be raised.

Note: If only a name is given this could lead to ambiguities. If this happens, none of them will be deleted. It occurs an error instead.

extend(entities)

Extend this Container by appending all single entities in the given list of entities.

@param entities: list of entities.

static from_xml(xml_str)

Creates a Container from the given xml string.

@return The created Container.

get_all_errors()

Returns a dictionary with all errors from all entities in this container.

The dictionary keys are the ids of those entities having contained an error.

get_all_messages()
get_entity_by_id(id)

Get the first entity which has the given id. Note: If several entities are in this list which have the same id, this method will only return the first and ignore the others.

@param name: The id of the entity to be returned. @return: Entity with the given id.

get_entity_by_name(name, case_sensitive=True)

Get the first entity which has the given name. Note: If several entities are in this list which have the same name, this method will only return the first and ignore the others.

@param name: the name of the entity to be returned. @param case_sensitive (True/False): Do a case-sensitive search for name (or not). @return: Entity with the given name.

get_errors()

Get all error messages of this container.

@return _Messages: Error messages.

get_property_values(*selectors)

Return a list of tuples with values of the given selectors.

I.e. a tabular representation of the container’s content.

If the elements of the selectors parameter are tuples, they will return the properties of the referenced entity, if present. E.g. (“window”, “height”) will return the value of the height property of the referenced window entity.

All tuples of the returned list have the same length as the selectors parameter and the ordering of the tuple’s values correspond to the order of the parameter as well.

The tuple contains None for all values that are not available in the entity. That does not necessarily mean, that the values are not stored in the database (e.g. if a single entity was retrieved without referenced entities).

Parameters

*selectors (str or tuple of str) – Each selector is a list or tuple of property names, e.g. “height”, “width”.

Returns

table – A tabular representation of the container’s content.

Return type

list of tuples

get_warnings()

Get all warning messages of this container.

@return _Messages: Warning messages.

has_errors()

@return True: if and only if this container has any error messages.

has_warnings()

@return True: if and only if this container has any warning messages.

insert(strict=False, raise_exception_on_error=True, unique=True, sync=True, flags=None)

Insert this file entity into CaosDB. A successful insertion will generate a new persistent ID for this entity. This entity can be identified, retrieved, updated, and deleted via this ID until it has been deleted.

If the insertion fails, a CaosDBException will be raised. The server will have returned at least one error-message describing the reason why it failed in that case (call <this_entity>.get_all_messages() in order to get these error-messages).

Some insertions might cause warning-messages on the server-side, but the entities are inserted anyway. Set the flag ‘strict’ to True in order to force the server to take all warnings as errors. This prevents the server from inserting this entity if any warning occurs.

@param strict=False: Flag for strict mode. @param sync=True: synchronize this container with the response from the server. Otherwise, this method returns a new container with the inserted entities and leaves this container untouched.

is_valid()
remove(entity)

Remove the first entity from this container which is equal to the given entity. Raise a ValueError if there is no such entity.

Alternatively, if the argument is not an entity but an ID, the contained entity with this ID is removed.

@param entity: The entity to be removed.

retrieve(query=None, unique=True, raise_exception_on_error=True, sync=True, flags=None)

Retrieve all entities in this container identified via their id if present and via their name otherwise. Any locally already existing attributes (name, description, …) will be preserved. Any such properties and parents will be synchronized as well. They will not be overridden. This method returns a Container containing the this entity.

If any entity has no id and no name a CaosDBException will be raised.

Note: If only a name is given this could lead to ambiguities. All entities with the name in question will be returned. Therefore, the container could contain more elements after the retrieval than before.

to_xml(add_to_element=None, local_serialization=False)

Get an xml tree representing this Container or append all entities to the given xml element.

@param add_to_element=None: optional element to which all entities of this container is to be appended. @return xml element

update(strict=False, raise_exception_on_error=True, unique=True, sync=True, flags=None)

Update these entites.

class caosdb.common.models.DropOffBox(iterable=(), /)

Bases: list

path = None
sync()
class caosdb.common.models.Entity(name=None, id=None, description=None, datatype=None, value=None, **kwargs)

Bases: object

Entity is a generic CaosDB object.

The majority of all methods of the derived classes (e.g. Record, RecordType, Property …) are defined here, e.g. add_property, add_parent, retrieve … Each entity may have some attributes (id, name, description, …), a set of properties, a set of parent entities and a set of messages which are generated through the processing in the client library or the server, or which can be used by the user to control several server-side plug-ins.

add_message(msg=None, type=None, code=None, description=None, body=None)

Add a message (msg) to this entity. If and only if no msg is given this method will created a new message from the parameters type, code, description, and body.

@param msg: The message to be added to this entity. @param type: The type of the message to be added. @param code: The code of the message to be added. @param description: The description of the message to be added. @param body: The body of the message to be added.

add_parent(parent=None, id=None, name=None, inheritance=None)

Add a parent to this entity.

Parameters
  • parent (Entity or int or str or None) – The parent entity, either specified by the Entity object itself, or its id or its name. Default is None.

  • id (int) – Integer id of the parent entity. Ignored if parent is not None.

  • name (str) – Name of the parent entity. Ignored if parent is not none.

  • inheritance (str) –

    One of obligatory, recommended, suggested, or fix. Specifies the minimum importance which parent properties need to have to be inherited by this entity. If no inheritance is given, no properties will be inherited by the child. This parameter is case-insensitive.

    Note that the behaviour is currently not yet specified when assigning parents to

    Records, it only works for inheritance of RecordTypes (and Properties).

    For more information, it is recommended to look into the data insertion tutorial.

Raises

UserWarning – If neither a parent parameter, nor the id, nor name parameter is passed to this method.

add_property(property=None, value=None, id=None, name=None, description=None, datatype=None, unit=None, importance=None, inheritance=None)

Add a property to this entity.

The first parameter is meant to identify the property entity. So the method expects an instance of Entity, an integer or a string here. The second parameter is the value of the new property. Any other named parameter may be passed by means of the keywwords. Accepted keywords are: id, name, description, importance, inheritance, datatype, and unit. Any other keyword will be ignored right now. But that may change in the future.

Parameters
  • property (int, str, Property, optional) – An identifying parameter, by default None

  • value (int, str, Property, optional) – The value of the new property, by default None

  • id (int, optional) – Id of the property, by default None

  • name (str, optional) – Name of the property, by default None

  • description (str, optional) – Description of the property, by default None

  • datatype (str, optional) – Datatype of the property, by default None

  • unit (str, optional) – Unit of the property, by default None

  • importance (str, optional) – Importance of the property, by default None

  • inheritance (str, optional) – Inheritance of the property, by default None

Returns

Return type

Entity

Raises
  • UserWarning – If the first parameter is None then id or name must be defined and not be None.

  • UserWarning – If the first parameter is an integer then it is interpreted as the id and id must be undefined or None.

  • UserWarning – If the first parameter is not None and neither an instance of Entity nor an integer it is interpreted as the name and name must be undefined or None.

property checksum
clear_server_messages()
property datatype
delete(raise_exception_on_error=True)
deny(realm=None, username=None, role=None, permission=None, priority=False)
property description
property file
get_all_messages()
get_errors()

Get all error messages of this entity.

@return _Messages(list): Error messages.

get_errors_deep(roots=None)

Get all error messages of this entity and all sub-entities / parents / properties.

@return A list of tuples. Tuple index 0 contains the error message

and tuple index 1 contains the tree.

get_importance(property)

Get the importance of a given property regarding this entity.

get_messages()

Get all messages of this entity.

@return: _Messages(list)

get_parent(key)

Return the first parent matching the key or None if no match exists.

Parameters

key (int or Enity or str) – The id, Entity, or name of the parent that should be returned. If an Entity is given, its id or its name is used to find a matching parent.

Returns

parent – The first parent of this entity that matches the given id, entity, or name.

Return type

Entity

get_parents()

Get all parents of this entity.

@return: _Parents(list)

get_parents_recursively()

Get all ancestors of this entity.

@return: list of Entities

get_properties()

Get all properties of this entity.

@return: _Properties(list)

get_property(pattern)

Return the first matching property or None.

Parameters

pattern (str or int or Entity) – The name or id to look for (case-insensitive) or an Entity where the name or id is used to match the properites of this instance.

Returns

property – The first Property of this Entity with a matching name or id.

Return type

Property

get_property_values(*selectors)

Return a tuple with the values described by the given selectors.

This represents an entity’s properties as if it was a row of a table with the given columns.

If the elements of the selectors parameter are tuples, they will return the properties of the referenced entity, if present. E.g. (“window”, “height”) will return the value of the height property of the referenced window entity.

The tuple’s values correspond to the order of selectors parameter.

The tuple contains None for all values that are not available in the entity. That does not necessarily mean, that the values are not stored in the database (e.g. if a single entity was retrieved without referenced entities).

Parameters

*selectors (str or tuple of str) – Each selector is a list or tuple of property names, e.g. “height”, “width”.

Returns

row – A row-like representation of the entity’s properties.

Return type

tuple

get_warnings()

Get all warning messages of this entity.

@return _Messages(list): Warning messages.

grant(realm=None, username=None, role=None, permission=None, priority=False)
has_errors()

@return True: if and only if this entities has any error messages.

has_parent(parent, recursive=True, check_name=True, check_id=False)

Checks if this entity has a given parent.

If ‘check_name’ and ‘check_id’ are both False, test for identity on the Python level. Otherwise use the name and/or ID for the check. Note that, if checked, name or ID should not be None, lest the check fail.

@param parent: Check for this parent. @param recursive: Whether to check recursively. @param check_name: Whether to use the name for ancestry check. @param check_id: Whether to use the ID for ancestry check. @return: True if ‘parent’ is a true parent, False otherwise.

property id
insert(raise_exception_on_error=True, unique=True, sync=True, strict=False, flags=None)

Insert this entity into a CaosDB server. A successful insertion will generate a new persistent ID for this entity. This entity can be identified, retrieved, updated, and deleted via this ID until it has been deleted.

If the insertion fails, a CaosDBException will be raised. The server will have returned at least one error-message describing the reason why it failed in that case (call <this_entity>.get_all_messages() in order to get these error-messages).

Some insertions might cause warning-messages on the server-side, but the entities are inserted anyway. Set the flag ‘strict’ to True in order to force the server to take all warnings as errors. This prevents the server from inserting this entity if any warning occurs.

@param strict=False: Flag for strict mode. @param raise_exception_on_error=True: Flag to raise an

exception when an error occurs.

@param unique=True: Flag to only allow

insertion of elements with unique names.

@param flags: A dictionary of flags to be send with the insertion.

is_permitted(permission, role=None)
property name
property path
property pickup
remove_parent(parent)
remove_property(property)
retrieve(unique=True, raise_exception_on_error=True, flags=None)

Retrieve this entity identified via its id if present and via its name otherwise. Any locally already existing attributes (name, description, …) will be preserved. Any such properties and parents will be synchronized as well. They will not be overridden. This method returns a Container containing the this entity.

Note: If only a name is given this could lead to ambiguities. Usually this would raise a CaosDBException. Set the flag ‘unique’ to False if this Exception should be suppressed. If unique is False this method returns a Container object which carries the returned entities. They are distinct from this one. This entity will no be changed somehow.

@param unique=True: flag to suppress the ambiguity exception.

@return Container with the returned entities or single entity if and only if unique was True and no exception was raised.

retrieve_acl()
revoke_denial(realm=None, username=None, role=None, permission=None, priority=False)
revoke_grant(realm=None, username=None, role=None, permission=None, priority=False)
property role
set_flag(key, value=None)
property size
property thumbnail
to_xml(xml=None, add_properties='ALL', local_serialization=False)

Generate an xml representation of this entity. If the parameter xml is given, all attributes, parents, properties, and messages of this entity will be added to it instead of creating a new element.

Raise an error if xml is not a lxml.etree.Element

@param xml: an xml element to which all attributes, parents,

properties, and messages are to be added.

@return: xml representation of this entity.

property unit
update(strict=False, raise_exception_on_error=True, unique=True, flags=None, sync=True)

Update this entity.

There are two possible work-flows to perform this update: First:

  1. retrieve an entity

  2. do changes

  3. call update method

Second:
  1. construct entity with id

  2. call update method.

For slight changes the second one it is more comfortable. Furthermore, it is possible to stay off-line until calling the update method. The name, description, unit, datatype, path, and value of an entity may be changed. Additionally, properties, parents and messages may be added.

However, the first one is more powerful: It is possible to delete and change properties, parents and attributes, which is not possible via the second one for internal reasons (which are reasons of definiteness).

If the update fails, a CaosDBException will be raised. The server will have returned at least one error message describing the reason why it failed in that case (call <this_entity>.get_all_messages() in order to get these error-messages).

Some updates might cause warning messages on the server-side, but the updates are performed anyway. Set flag ‘strict’ to True in order to force the server to take all warnings as errors. This prevents the server from updating this entity if any warnings occur.

@param strict=False: Flag for strict mode.

update_acl()
property value
property version
class caosdb.common.models.File(name=None, id=None, description=None, path=None, file=None, pickup=None, thumbnail=None, from_location=None)

Bases: caosdb.common.models.Record

This class represents CaosDB’s file entities.

For inserting a new file to the server, path gives the new location, and (exactly?) one of file and pickup should (must?) be given to specify the source of the file.

Symlinking from the “extroot” file system is not supported by this API yet, it can be done manually using the InsertFilesInDir flag. For sample code, look at test_files.py in the Python integration tests of the load_files.py script in the advanced user tools.

@param name: A name for this file record (That’s an entity name - not to be

confused with the last segment of the files path).

@param id: An ID. @param description: A description for this file record. @param path: The complete path, including the file name, of the file in the

server’s “caosroot” file system.

@param file: A local path or python file object. The file designated by

this argument will be uploaded to the server via HTTP.

@param pickup: A file/folder in the DropOffBox (the server will move that

file into its “caosroot” file system).

@param thumbnail: (Local) filename to a thumbnail for this file. @param properties: A list of properties for this file record. @todo is this

implemented?

@param from_location: Deprecated, use pickup instead.

add_property(property=None, id=None, name=None, description=None, datatype=None, value=None, unit=None, importance='FIX', inheritance='FIX')

Add a property to this entity.

The first parameter is meant to identify the property entity. So the method expects an instance of Entity, an integer or a string here. The second parameter is the value of the new property. Any other named parameter may be passed by means of the keywwords. Accepted keywords are: id, name, description, importance, inheritance, datatype, and unit. Any other keyword will be ignored right now. But that may change in the future.

Parameters
  • property (int, str, Property, optional) – An identifying parameter, by default None

  • value (int, str, Property, optional) – The value of the new property, by default None

  • id (int, optional) – Id of the property, by default None

  • name (str, optional) – Name of the property, by default None

  • description (str, optional) – Description of the property, by default None

  • datatype (str, optional) – Datatype of the property, by default None

  • unit (str, optional) – Unit of the property, by default None

  • importance (str, optional) – Importance of the property, by default None

  • inheritance (str, optional) – Inheritance of the property, by default None

Returns

Return type

Entity

Raises
  • UserWarning – If the first parameter is None then id or name must be defined and not be None.

  • UserWarning – If the first parameter is an integer then it is interpreted as the id and id must be undefined or None.

  • UserWarning – If the first parameter is not None and neither an instance of Entity nor an integer it is interpreted as the name and name must be undefined or None.

download(target=None)

Download this file-entity’s actual file from the file server. It will be stored to the target or will be hold as a temporary file.

@param target: Where to store this file. @return: local path of the downloaded file.

static download_from_path(target_file, path)
to_xml(xml=None, add_properties='ALL', local_serialization=False)

Convert this file to an xml element.

@return: xml element

class caosdb.common.models.Info

Bases: object

sync()
class caosdb.common.models.Message(type, code=None, description=None, body=None)

Bases: object

get_code()
to_xml(xml=None)
class caosdb.common.models.Parent(id=None, name=None, description=None, inheritance=None)

Bases: caosdb.common.models.Entity

The parent entities.

property affiliation
to_xml(xml=None, add_properties=None)

Generate an xml representation of this entity. If the parameter xml is given, all attributes, parents, properties, and messages of this entity will be added to it instead of creating a new element.

Raise an error if xml is not a lxml.etree.Element

@param xml: an xml element to which all attributes, parents,

properties, and messages are to be added.

@return: xml representation of this entity.

class caosdb.common.models.Permission(name, description=None)

Bases: object

class caosdb.common.models.Permissions(xml)

Bases: object

clear()
known_permissions = None
parse_xml(xml)
class caosdb.common.models.Property(name=None, id=None, description=None, datatype=None, value=None, unit=None)

Bases: caosdb.common.models.Entity

CaosDB’s Property object.

add_parent(parent=None, id=None, name=None, inheritance='FIX')

Add a parent Entity to this Property.

Parameters
parentEntity or int or str or None

The parent entity, either specified by the Entity object itself, or its id or its name. Default is None.

idint

Integer id of the parent entity. Ignored if parent is not None.

namestr

Name of the parent entity. Ignored if parent is not none.

inheritancestr, default: FIX

One of obligatory, recommended, suggested, or fix. Specifies the minimum importance which parent properties need to have to be inherited by this entity. If no inheritance is given, no properties will be inherited by the child. This parameter is case-insensitive.

Entity.add_parent

add_property(property=None, value=None, id=None, name=None, description=None, datatype=None, unit=None, importance='FIX', inheritance='FIX')

Add a property to this entity.

The first parameter is meant to identify the property entity. So the method expects an instance of Entity, an integer or a string here. The second parameter is the value of the new property. Any other named parameter may be passed by means of the keywwords. Accepted keywords are: id, name, description, importance, inheritance, datatype, and unit. Any other keyword will be ignored right now. But that may change in the future.

Parameters
  • property (int, str, Property, optional) – An identifying parameter, by default None

  • value (int, str, Property, optional) – The value of the new property, by default None

  • id (int, optional) – Id of the property, by default None

  • name (str, optional) – Name of the property, by default None

  • description (str, optional) – Description of the property, by default None

  • datatype (str, optional) – Datatype of the property, by default None

  • unit (str, optional) – Unit of the property, by default None

  • importance (str, optional) – Importance of the property, by default None

  • inheritance (str, optional) – Inheritance of the property, by default None

Returns

Return type

Entity

Raises
  • UserWarning – If the first parameter is None then id or name must be defined and not be None.

  • UserWarning – If the first parameter is an integer then it is interpreted as the id and id must be undefined or None.

  • UserWarning – If the first parameter is not None and neither an instance of Entity nor an integer it is interpreted as the name and name must be undefined or None.

is_reference(server_retrieval=False)

Returns whether this Property is a reference

Parameters

server_retrieval (bool, optional) – If True and the datatype is not set, the Property is retrieved from the server, by default False

Returns

Returns whether this Property is a reference or None if a server call is needed to check correctly, but server_retrieval is set to False.

Return type

bool, NoneType

to_xml(xml=None, add_properties='ALL')

Generate an xml representation of this entity. If the parameter xml is given, all attributes, parents, properties, and messages of this entity will be added to it instead of creating a new element.

Raise an error if xml is not a lxml.etree.Element

@param xml: an xml element to which all attributes, parents,

properties, and messages are to be added.

@return: xml representation of this entity.

class caosdb.common.models.Query(q)

Bases: object

q

The query string.

Type

str

flags

A dictionary of flags to be send with the query request.

Type

dict of str

messages

A container of messages included in the last query response.

Type

_Messages()

cached

indicates whether the server used the query cache for the execution of this query.

Type

bool

results

The number of results (when this was a count query) or the container with the resulting entities.

Type

int or Container

execute(unique=False, raise_exception_on_error=True, cache=True)

Execute a query (via a server-requests) and return the results.

Parameters
  • unique (bool) – Whether the query is expected to have only one entity as result. Defaults to False.

  • raise_exception_on_error (bool) – Whether an exception should be raises when there are errors in the resulting entities. Defaults to True.

  • cache (bool) – Whether to use the query cache (equivalent to adding a “cache” flag) to the Query object. Defaults to True.

Returns

results – Returns an integer when it was a COUNT query. Otherwise, returns a Container with the resulting entities.

Return type

Container or integer

getFlag(key)
putFlag(key, value=None)
removeFlag(key)
class caosdb.common.models.QueryTemplate(id=None, name=None, query=None, description=None)

Bases: object

clear_server_messages()
delete(raise_exception_on_error=True)
get_errors()
get_messages()
get_parents()
get_properties()
has_errors()
has_id()
insert(strict=True, raise_exception_on_error=True, unique=True, sync=True, flags=None)
retrieve(raise_exception_on_error=True, unique=True, sync=True, flags=None)
to_xml(xml=None)
update(strict=True, raise_exception_on_error=True, unique=True, sync=True, flags=None)
class caosdb.common.models.Record(name=None, id=None, description=None)

Bases: caosdb.common.models.Entity

This class represents CaosDB’s Record entities.

add_property(property=None, value=None, id=None, name=None, description=None, datatype=None, unit=None, importance='FIX', inheritance='FIX')

Add a property to this entity.

The first parameter is meant to identify the property entity. So the method expects an instance of Entity, an integer or a string here. The second parameter is the value of the new property. Any other named parameter may be passed by means of the keywwords. Accepted keywords are: id, name, description, importance, inheritance, datatype, and unit. Any other keyword will be ignored right now. But that may change in the future.

Parameters
  • property (int, str, Property, optional) – An identifying parameter, by default None

  • value (int, str, Property, optional) – The value of the new property, by default None

  • id (int, optional) – Id of the property, by default None

  • name (str, optional) – Name of the property, by default None

  • description (str, optional) – Description of the property, by default None

  • datatype (str, optional) – Datatype of the property, by default None

  • unit (str, optional) – Unit of the property, by default None

  • importance (str, optional) – Importance of the property, by default None

  • inheritance (str, optional) – Inheritance of the property, by default None

Returns

Return type

Entity

Raises
  • UserWarning – If the first parameter is None then id or name must be defined and not be None.

  • UserWarning – If the first parameter is an integer then it is interpreted as the id and id must be undefined or None.

  • UserWarning – If the first parameter is not None and neither an instance of Entity nor an integer it is interpreted as the name and name must be undefined or None.

to_xml(xml=None, add_properties='ALL')

Generate an xml representation of this entity. If the parameter xml is given, all attributes, parents, properties, and messages of this entity will be added to it instead of creating a new element.

Raise an error if xml is not a lxml.etree.Element

@param xml: an xml element to which all attributes, parents,

properties, and messages are to be added.

@return: xml representation of this entity.

class caosdb.common.models.RecordType(name=None, id=None, description=None, datatype=None)

Bases: caosdb.common.models.Entity

This class represents CaosDB’s RecordType entities.

add_parent(parent=None, id=None, name=None, inheritance='OBLIGATORY')

Add a parent to this RecordType

Parameters
  • parent (Entity or int or str or None) – The parent entity, either specified by the Entity object itself, or its id or its name. Default is None.

  • parent – The parent entity, either specified by the Entity object itself, or its id or its name. Default is None.

  • id (int) – Integer id of the parent entity. Ignored if parent is not None.

  • name (str) – Name of the parent entity. Ignored if parent is not none.

  • inheritance (str, default OBLIGATORY) – One of obligatory, recommended, suggested, or fix. Specifies the minimum importance which parent properties need to have to be inherited by this entity. If no inheritance is given, no properties will be inherited by the child. This parameter is case-insensitive.

add_property(property=None, value=None, id=None, name=None, description=None, datatype=None, unit=None, importance='RECOMMENDED', inheritance='FIX')

Add a property to this entity.

The first parameter is meant to identify the property entity. So the method expects an instance of Entity, an integer or a string here. The second parameter is the value of the new property. Any other named parameter may be passed by means of the keywwords. Accepted keywords are: id, name, description, importance, inheritance, datatype, and unit. Any other keyword will be ignored right now. But that may change in the future.

Parameters
  • property (int, str, Property, optional) – An identifying parameter, by default None

  • value (int, str, Property, optional) – The value of the new property, by default None

  • id (int, optional) – Id of the property, by default None

  • name (str, optional) – Name of the property, by default None

  • description (str, optional) – Description of the property, by default None

  • datatype (str, optional) – Datatype of the property, by default None

  • unit (str, optional) – Unit of the property, by default None

  • importance (str, optional) – Importance of the property, by default None

  • inheritance (str, optional) – Inheritance of the property, by default None

Returns

Return type

Entity

Raises
  • UserWarning – If the first parameter is None then id or name must be defined and not be None.

  • UserWarning – If the first parameter is an integer then it is interpreted as the id and id must be undefined or None.

  • UserWarning – If the first parameter is not None and neither an instance of Entity nor an integer it is interpreted as the name and name must be undefined or None.

to_xml(xml=None, add_properties='ALL')

Generate an xml representation of this entity. If the parameter xml is given, all attributes, parents, properties, and messages of this entity will be added to it instead of creating a new element.

Raise an error if xml is not a lxml.etree.Element

@param xml: an xml element to which all attributes, parents,

properties, and messages are to be added.

@return: xml representation of this entity.

class caosdb.common.models.UserInfo(xml)

Bases: object

caosdb.common.models.delete(ids, raise_exception_on_error=True)
caosdb.common.models.execute_query(q, unique=False, raise_exception_on_error=True, cache=True, flags=None)

Execute a query (via a server-requests) and return the results.

Parameters
  • q (str) – The query string.

  • unique (bool) – Whether the query is expected to have only one entity as result. Defaults to False.

  • raise_exception_on_error (bool) – Whether an exception should be raises when there are errors in the resulting entities. Defaults to True.

  • cache (bool) – Whether to use the query cache (equivalent to adding a “cache” flag). Defaults to True.

  • flags (dict of str) – Flags to be added to the request.

Returns

results – Returns an integer when it was a COUNT query. Otherwise, returns a Container with the resulting entities.

Return type

Container or integer

caosdb.common.models.get_global_acl()
caosdb.common.models.get_known_permissions()
caosdb.common.models.parse_xml(xml)

parse a string or tree representation of an xml document to a set of entities (records, recordtypes, properties, or files).

@param xml: a string or tree representation of an xml document. @return: list of entities or single entity.

caosdb.common.models.raise_errors(arg0)

Raise a TransactionError depending on the error code(s) inside Entity, QueryTemplate or Container arg0. More detailed errors may be attached to the TransactionError depending on the contents of arg0.

arg0Entity, QueryTemplate, or Container

CaosDB object whose messages are evaluated according to their error codes

caosdb.common.models.sync_global_acl()