diff --git a/src/doc/high_level_api.org b/src/doc/high_level_api.org index 87b39c5787e5d61cca989bd23fc4e7ca2f2bb93d..7df50bb276564fc753731da3599c95251e11c093 100644 --- a/src/doc/high_level_api.org +++ b/src/doc/high_level_api.org @@ -91,3 +91,31 @@ print(str(obj)) * Concepts +As described in the section [[Quickstart]] the two functions "convert_to_python_object" and "convert_to_entity" convert +entities beetween the high level and the standard representation. + +The high level entities are represented using the following classes from the module caosdb.high_level_api: +- CaosDBPythonEntity: Base class of the following entity classes. +- CaosDBPythonRecord +- CaosDBPythonRecordType +- CaosDBPythonProperty +- CaosDBPythonMultiProperty: **WARNING** Not implemented yet. +- CaosDBPythonFile: Used for file entities and provides an additional "download" function for being able to directly retrieve files from CaosDB. + +In addition, there are the following helper structures which are realized as Python data classes: +- CaosDBPropertyMetaData: For storing meta data about properties. +- CaosDBPythonUnresolved: The base class of unresolved "things". +- CaosDBPythonUnresolvedParent: Parents of entities are stored as unresolved parents by default, storing an id or a name of a parent (or both). +- CaosDBPythonUnresolvedReference: An unresolved reference is a reference property with an id which has not (yet) been resolved to an Entity. + +The function "resolve_references" can be used to recursively replace CaosDBPythonUnresolvedReferences into members of type CaosDBPythonRecords +or CaosDBPythonFile. + +Each property stored in a CaosDB record corresponds to: +- a member attribute of CaosDBPythonRecord **and** +- an entry in a dict called "metadata" storing a CaosDBPropertyMetadata object with the following information about proeprties: + - unit + - datatype + - description + - id + - importance