caosdb.high_level_api module

A high level API for accessing CaosDB entities from within python.

This is refactored from apiutils.

class caosdb.high_level_api.CaosDBMultiProperty

Bases: object

This implements a multi property using a python list.

class caosdb.high_level_api.CaosDBPropertyMetaData(unit: Optional[str] = None, datatype: Optional[str] = None, description: Optional[str] = None, id: Optional[int] = None, importance: Optional[str] = None)

Bases: object

datatype: Optional[str] = None
description: Optional[str] = None
id: Optional[int] = None
importance: Optional[str] = None
unit: Optional[str] = None
class caosdb.high_level_api.CaosDBPythonEntity

Bases: object

add_parent(parent: Union[caosdb.high_level_api.CaosDBPythonUnresolvedParent, caosdb.high_level_api.CaosDBPythonRecordType, str])

Add a parent to this entity. Either using an unresolved parent or using a real record type.

Strings as argument for parent will automatically be converted to an unresolved parent. Likewise, integers as argument will be automatically converted to unresolved parents with just an id.

attribute_as_list(name: str)

This is a workaround for the problem that lists containing only one element are indistinguishable from simple types in this representation.

TODO: still relevant? seems to be only a problem if LIST types are not used.

property description

Getter for the description.

static deserialize(serialization: dict)

Deserialize a yaml representation of an entity in high level API form.

property file

Getter for the file.

get_parents()

Returns all parents of this entity.

Use has_parent for checking for existence of parents and add_parent for adding parents to this entity.

get_properties()

Return the names of all properties.

get_property(name: str)

Return the value of the property with name name.

Raise an exception if the property does not exist.

get_property_metadata(prop_name: str)caosdb.high_level_api.CaosDBPropertyMetaData

Retrieve the property metadata for the property with name prop_name.

If the property with the given name does not exist or is forbidden, raise an exception. Else return the metadata associated with this property.

If no metadata does exist yet for the given property, a new object will be created and returned.

prop_name: str

Name of the property to retrieve metadata for.

has_parent(parent: Union[caosdb.high_level_api.CaosDBPythonUnresolvedParent, caosdb.high_level_api.CaosDBPythonRecordType])

Check whether this parent already exists for this entity.

Strings as argument for parent will automatically be converted to an unresolved parent. Likewise, integers as argument will be automatically converted to unresolved parents with just an id.

property id

Getter for the id.

property name

Getter for the name.

property path

Getter for the path.

property_exists(prop_name: str)

Check whether a property exists already.

resolve_references(deep: bool, references: caosdb.common.models.Container, visited: Optional[Dict[Union[str, int], caosdb.high_level_api.CaosDBPythonEntity]] = None)

Resolve this entity’s references. This affects unresolved properties as well as unresolved parents.

deep: bool

If True recursively resolve references also for all resolved references.

references: Optional[db.Container]

A container with references that might be resolved. If None is passed as the container, this function tries to resolve entities from a running CaosDB instance directly.

serialize(without_metadata: bool = False, visited: Optional[dict] = None)

Serialize necessary information into a dict.

without_metadata: bool

If True don’t set the metadata field in order to increase readability. Not recommended if deserialization is needed.

set_property(name: str, value: Any, overwrite: bool = False, datatype: Optional[str] = None)

Set a property for this entity with a name and a value.

If this property is already set convert the value into a list and append the value. This behavior can be overwritten using the overwrite flag, which will just overwrite the existing value.

name: str

Name of the property.

value: Any

Value of the property.

overwrite: bool

Use this if you definitely only want one property with that name (set to True).

use_parameter(name, value)
property version

Getter for the version.

class caosdb.high_level_api.CaosDBPythonFile

Bases: caosdb.high_level_api.CaosDBPythonEntity

download(target=None)
class caosdb.high_level_api.CaosDBPythonProperty

Bases: caosdb.high_level_api.CaosDBPythonEntity

class caosdb.high_level_api.CaosDBPythonRecord

Bases: caosdb.high_level_api.CaosDBPythonEntity

class caosdb.high_level_api.CaosDBPythonRecordType

Bases: caosdb.high_level_api.CaosDBPythonEntity

class caosdb.high_level_api.CaosDBPythonUnresolved

Bases: object

class caosdb.high_level_api.CaosDBPythonUnresolvedParent(id: Optional[int] = None, name: Optional[str] = None)

Bases: caosdb.high_level_api.CaosDBPythonUnresolved

Parents can be either given by name or by ID.

When resolved, both fields should be set.

id: Optional[int] = None
name: Optional[str] = None
class caosdb.high_level_api.CaosDBPythonUnresolvedReference(id=None)

Bases: caosdb.high_level_api.CaosDBPythonUnresolved

caosdb.high_level_api.convert_to_entity(python_object)
caosdb.high_level_api.convert_to_python_object(entity: Union[caosdb.common.models.Container, caosdb.common.models.Entity], references: Optional[caosdb.common.models.Container] = None)

Convert either a container of CaosDB entities or a single CaosDB entity into the high level representation.

The optional second parameter can be used to resolve references that occur in the converted entities and resolve them to their correct representations. (Entities that are not found remain as CaosDBPythonUnresolvedReferences.)

caosdb.high_level_api.create_entity_container(record: caosdb.high_level_api.CaosDBPythonEntity)

Convert this record into an entity container in standard format that can be used to insert or update entities in a running CaosDB instance.

caosdb.high_level_api.create_record(rtname: str, name: Optional[str] = None, **kwargs)

Create a new record based on the name of a record type. The new record is returned.

rtname: str

The name of the record type.

name: str

This is optional. A name for the new record.

kwargs:

Additional arguments are used to set attributes of the new record.

caosdb.high_level_api.high_level_type_for_role(role: str)
caosdb.high_level_api.high_level_type_for_standard_type(standard_record: caosdb.common.models.Entity)
caosdb.high_level_api.load_external_record(record_name: str)

Retrieve a record by name and convert it to the high level API format.

caosdb.high_level_api.new_high_level_entity(entity: caosdb.common.models.RecordType, importance_level: str, name: Optional[str] = None)

Create an new record in high level format based on a record type in standard format.

entity: db.RecordType

The record type to initialize the new record from.

importance_level: str

None, obligatory, recommended or suggested Initialize new properties up to this level. Properties in the record type with no importance will be added regardless of the importance_level.

name: str

Name of the new record.

caosdb.high_level_api.query(query: str, resolve_references: bool = True, references: Optional[caosdb.common.models.Container] = None)
caosdb.high_level_api.standard_type_for_high_level_type(high_level_record: caosdb.high_level_api.CaosDBPythonEntity, return_string: bool = False)

For a given CaosDBPythonEntity either return the corresponding class in the standard CaosDB API or - if return_string is True - return the role as a string.