MAINT: docs and user warning

src/caosdb/high_level_api.py

@@ -38,6 +38,7 @@ from caosdb.common.datatype import (BOOLEAN, DATETIME, DOUBLE, FILE, INTEGER,
 import caosdb as db
 
 from .apiutils import get_type_of_entity_with, create_flat_list
+import warnings
 
 from typing import Any, Optional, List, Union, Dict
 
@@ -47,6 +48,10 @@ from dataclasses import dataclass, fields
 from datetime import datetime
 from dateutil import parser
 
+warnings.warn("""EXPERIMENTAL! The high_level_api module is experimental and may be changed or
+removed in future. Its purpose is to give an impression on how the Python client user interface
+might be changed.""")
+
 
 def standard_type_for_high_level_type(high_level_record: "CaosDBPythonEntity",
                                       return_string: bool = False):

src/doc/future_caosdb.md

+# The future of the CaosDB Python Client
+
+The current Python client has done us great services but its structure and the 
+way it is used sometimes feels outdated and clumsy. In this document we sketch
+how it might look different in future and invite everyone to comment or
+contribute to this development.
+
+At several locations in this document there will be links to discussion issues.
+If you want to discuss something new, you can create a new issue
+[here](https://gitlab.com/caosdb/caosdb-pylib/-/issues/new).
+
+## Overview
+Let's get a general impression before discussing single aspects.
+
+``` python
+import caosdb as db
+experiments = db.query("FIND Experiment")
+# print name and date for each `Experiment`
+for exp in experiments:
+   print(exp.name, exp.date)
+
+# suppose `Experiments` reference `Projects` which have a `Funding` Property
+one_exp = experiments[0]
+print(one_exp.Project.Funding)
+
+new_one = db.create_record("Experiment")
+new_one.date = "2022-01-01"
+new_one.name = "Needle Measurement"
+new_one.insert()
+```
+Related discussions:
+- [recursive retrieve in query](https://gitlab.com/caosdb/caosdb-pylib/-/issues/57)
+- [create_record function](https://gitlab.com/caosdb/caosdb-pylib/-/issues/58)
+- [data model utility](https://gitlab.com/caosdb/caosdb-pylib/-/issues/59)
+
+## Quickstart
+Note that you can try out one possible implementation using the 
+`caosdb.high_level_api` module. It is experimental and might be removed in 
+future!
+
+A `resolve_references` function allows to retrieve the referenced entities of 
+an entity, container or a query result set (which is a container).
+It has the following parameters which can also be supplied to the `query` 
+function:
+
+-   `deep`: Whether to use recursive retrieval
+-   `depth`: Maximum recursion depth
+-   `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.
+
+In order to allow a quick look at the object structures an easily readable 
+serialization is provided by the `to_dict` function. It has the following 
+argument:
+-   `without_metadata`: Set this to True if you don\'t want to see
+    property metadata like \"unit\" or \"importance\".
+
+This function creates a simple dictionary containing a representation of
+the entity, which can be stored to disk and completely deserialized
+using the function `from_dict`.
+
+Furthermore, the `__str__` function uses this to display objects in yaml 
+format by default statement
+
+## Design Decisions
+
+### Dot Notation
+Analogue, to what Pandas does. Provide bracket notation 
+`rec.properties["test"]` for Properties with names that are in conflict with 
+default attributes or contain spaces (or other forbidden characters).
+
+- Raise Exception if attribute does not exist but is accessed?
+- How to deal with lists? b has a list as value: `a.b[0].c = 5`
+
+[Discussion](https://gitlab.com/caosdb/caosdb-pylib/-/issues/60)
+
+### Serialization
+What information needs to be contained in (meta)data? How compatible is it with 
+GRPC json serialization?
+
+
+### Recursive Retrieval
+I can resolve later and end up with the same result:
+`recs =db.query("FIND Experiment", depth=2)`  equals `recs = db.query("FIND Experiment"); recs = resolve_references(recs, depth=2)`
+
+[Discussion](https://gitlab.com/caosdb/caosdb-pylib/-/issues/57)
+
+### In-Place operations
+Default behavior is to return new objects instead of modifying them in-place.
+This can be changed with the argument `inplace=True`.
+Especially the following functions operate by default NOT in-place:
+- update
+- insert
+- retrieve
+- resolve_references
+[Discussion](https://gitlab.com/caosdb/caosdb-pylib/-/issues/61)
+
+## Extend Example
+``` python
+import caosdb as db
+
+dm = db.get_data_model()
+
+new_one = db.create_record(dm.Experiment)
+new_one.date = "2022-01-01"
+new_one.name = "Needle Measurement"
+new_one.dataset = db.create_record(dm.Dataset)
+new_one.dataset.voltage = (5, "V")
+new_one.dataset.pulses = [5, 5.3]
+inserted = new_one.insert()
+print("The new record has the ID:", inserted.id)
+```