From bee82d3cc4828a26ca1cbf07df30ad572eb359a4 Mon Sep 17 00:00:00 2001 From: Alexander Schlemmer <alexander@mail-schlemmer.de> Date: Thu, 17 Mar 2022 14:52:49 +0100 Subject: [PATCH] DOC: added more documentation for the high level API --- src/doc/high_level_api.org | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/src/doc/high_level_api.org b/src/doc/high_level_api.org index 87b39c57..7df50bb2 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 -- GitLab