F retrieve substructure

Summary

This adds a new function in pylib that allows for retrieving connected parts of a data model. This function is needed for feasible conversion of parts of the data model into UML.

This MR also adds some missing docstrings to old functions.

Focus

There is only one function to check that recursively adds substructure starting from a few given entities.

Test Environment

Check out the branch and try this on an instance of your choice:

import caosdb as db
from caosdb.utils.plantuml import to_graphics, retrieve_substructure
rts = retrieve_substructure(db.execute_query("Find RecordType SomeRecordtype"), 2)

Check List for the Author

• All automated tests pass
• Reference related Issues
• Up-to-date CHANGELOG.md
• Annotations in code (Gitlab comments)
  • Intent of new code
  • Problems with old code
  • Why this implementation?

Check List for the Reviewer

• I understand the intent of this MR
• All automated tests pass
• Up-to-date CHANGELOG.md
• The test environment setup works and the intended behavior is reproducible in the test environment
• In-code documentation and comments are up-to-date.
• Check: Are there spezifications? Are they satisfied?

For further good practices have a look at our review guidelines.

src/caosdb/common/datatype.py

@@ -60,10 +60,21 @@ def is_list_datatype(datatype):
 
 
 def is_reference(datatype):
-    """ returns whether the value is a reference
+    """Returns whether the value is a reference
 
     FILE and REFERENCE properties are examples, but also datatypes that are
-    RecordTypes
+    RecordTypes.
+
+    Parameters
+    ----------
+    datatype : str
+               The datatype to check.
+
+    Returns
+    -------
+    bool
+        True if the datatype is a not base datatype or a list of a base datatype.
+        Otherwise False is returned.
     """
 
     if datatype in [DOUBLE, BOOLEAN, INTEGER, TEXT, DATETIME]:
@@ -73,6 +84,39 @@ def is_reference(datatype):
     else:
         return True
 
+def get_referenced_recordtype(datatype):
+    """Return the record type of the referenced datatype.
+
+    Raises
+    ------
+    ValueError
+              In cases where datatype is not a reference, the list does not have
+              a referenced record type or the datatype is a FILE.
+
+    Parameters
+    ----------
+    datatype : str
+               The datatype to check.
+
+    Returns
+    -------
+    str
+       String containing the name of the referenced datatype.
+    """
+
+    if not is_reference(datatype):
+        raise ValueError("datatype must be a reference")
+
+    if is_list_datatype(datatype):
+        datatype = get_list_datatype(datatype)
+        if datatype is None:
+            raise ValueError("list does not have a list datatype")
+
+    if datatype == FILE:
+        raise ValueError("FILE references are not considered references with a record type")
+
+    return datatype
+
 
 def get_id_of_datatype(datatype):
     """ returns the id of a Record Type