From f1bc07da6eeef0dd1a989d17a9af20883baf032a Mon Sep 17 00:00:00 2001
From: Alexander Schlemmer <alexander@mail-schlemmer.de>
Date: Thu, 17 Mar 2022 15:06:50 +0100
Subject: [PATCH] added some corrections
---
src/doc/high_level_api.rst | 87 +++++++++++++++++++-------------------
1 file changed, 44 insertions(+), 43 deletions(-)
diff --git a/src/doc/high_level_api.rst b/src/doc/high_level_api.rst
index 9e52968a..603052b1 100644
--- a/src/doc/high_level_api.rst
+++ b/src/doc/high_level_api.rst
@@ -28,30 +28,30 @@ Quickstart
----------
The module, needed for the high level API is called:
-caosdb.high\ :sub:`levelapi`
+``caosdb.high_level_api``
There are two functions converting entities between the two
representation (old API and new API):
-- convert\ :sub:`topythonobject`: Convert entities from **old** into
+- ``convert_to_python_object``: Convert entities from **old** into
**new** representation.
-- convert\ :sub:`toentity`: Convert entities from **new** into **old**
+- ``convert_to_entity``: Convert entities from **new** into **old**
representation.
Furthermore there are a few utility functions which expose very
practical shorthands:
-- new\ :sub:`highlevelentity`: Retrieve a record type and create a new
+- ``new_high_level_entity``: Retrieve a record type and create a new
high level entity which contains properties of a certain importance
level preset.
-- create\ :sub:`record`: Create a new high level entity using the name
- of a record type and a list of key value pairs as properties.
-- load\ :sub:`externalrecord`: Retrieve a record with a specific name
- and return it as high level entity.
-- create\ :sub:`entitycontainer`: Convert a high level entity into a
+- ``create_record``: Create a new high level entity using the name of a
+ record type and a list of key value pairs as properties.
+- ``load_external_record``: Retrieve a record with a specific name and
+ return it as high level entity.
+- ``create_entity_container``: Convert a high level entity into a
standard entity including all sub entities.
-- query: Do a CaosDB query and return the result as a container of high
- level objects.
+- ``query``: Do a CaosDB query and return the result as a container of
+ high level objects.
So as a first example, you could retrieve any record from CaosDB and use
it using its high level representation:
@@ -86,25 +86,26 @@ series of commands to achieve the same result:
print(output_file.path)
Resolving subproperties makes use of the "resolve\ :sub:`reference`"
-function provided by the high level entity class (CaosDBPythonEntity),
-with the following parameters:
+function provided by the high level entity class
+(``CaosDBPythonEntity``), with the following parameters:
-- deep: Whether to use recursive retrieval
-- references: Whether to use the supplied db.Container to resolve
+- ``deep``: Whether to use recursive retrieval
+- ``references``: Whether to use the supplied db.Container to resolve
references. This allows offline usage. Set it to None if you want to
automatically retrieve entities from the current CaosDB connection.
-- visited: Needed for recursion, set this to None.
+- ``visited``: Needed for recursion, set this to None.
Objects in the high level representation can be serialized to a simple
-yaml form using the function "serialize" with the following parameters:
+yaml form using the function ``serialize`` with the following
+parameters:
-- without\ :sub:`metadata`: Set this to True if you don't want to see
+- ``without_metadata``: Set this to True if you don't want to see
property metadata like "unit" or "importance".
-- visited: Needed for recursion, set this to None.
+- ``visited``: Needed for recursion, set this to None.
This function creates a simple dictionary containing a representation of
the entity, which can be stored to disk and completely deserialized
-using the function "deserialize".
+using the function ``deserialize``.
Furthermore the "*str*" function is overloaded, so that you can use
print to directly inspect high level objects using the following
@@ -118,45 +119,45 @@ Concepts
--------
As described in the section Quickstart the two functions
-"convert\ :sub:`topythonobject`" and "convert\ :sub:`toentity`" convert
-entities beetween the high level and the standard representation.
+``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\ :sub:`levelapi`:
+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.
+- ``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
+- ``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
+- ``CaosDBPythonUnresolvedReference``: An unresolved reference is a
reference property with an id which has not (yet) been resolved to an
Entity.
The function "resolve\ :sub:`references`" can be used to recursively
-replace CaosDBPythonUnresolvedReferences into members of type
-CaosDBPythonRecords or CaosDBPythonFile.
+replace ``CaosDBPythonUnresolvedReferences`` into members of type
+``CaosDBPythonRecords`` or ``CaosDBPythonFile``.
Each property stored in a CaosDB record corresponds to:
-- a member attribute of CaosDBPythonRecord **and**
+- 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
+ - ``unit``
+ - ``datatype``
+ - ``description``
+ - ``id``
+ - ``importance``
--
GitLab