DOC: added some type hints and documentation

src/caosdb/high_level_api.py

@@ -36,12 +36,19 @@ import caosdb as db
 
 from .apiutils import get_type_of_entity_with
 
+from typing import Any, Optional
 
 class CaosDBPythonEntity(object):
 
     _last_id = 0
 
     def __init__(self):
+        """
+        Initialize a new CaosDBPythonEntity for the high level python api.
+
+        The new entity is initialized with a new negative ID using _get_id (static).
+        """
+        
         # Save a copy of the dry state
         # of this object in order to be
         # able to detect conflicts.
@@ -63,40 +70,82 @@ class CaosDBPythonEntity(object):
 
     @staticmethod
     def _get_id():
+        """
+        Get a new negative ID for a CaosDB Entity.
+
+        The first ID is -1 and decremented with each call of this function.
+        """
         CaosDBPythonEntity._last_id -= 1
 
         return CaosDBPythonEntity._last_id
 
     def _set_property_from_entity(self, ent: db.Entity):
+        """
+        Set a new property using an entity from the normal python API.
+
+        ent : db.Entity
+              The entity to be set.
+        """
+        
         name = ent.name
         val = ent.value
         pr = ent.datatype
         val, reference = self._type_converted_value(val, pr)
         self.set_property(name, val, reference, datatype=pr)
 
-    def set_property(self, name, value, is_reference=False,
-                     overwrite=False, datatype=None):
+    def set_property(self,
+                     name: str,
+                     value: Any,
+                     is_reference: bool = False,
+                     overwrite: bool = False,
+                     datatype: Optional[str] = None):
         """
-        overwrite: Use this if you definitely only want one property with that name (set to True).
+        Set a property for this entity with a name and a value.
+
+        If this property is already set convert the value into a list and append the value.
+        This behavior can be overwritten using the overwrite flag, which will just overwrite
+        the existing value.
+
+        name: str
+              Name of the property.
+        
+        value: Any
+               Value of the property.
+
+        is_reference: bool
+        
+        overwrite: bool
+                   Use this if you definitely only want one property with
+                   that name (set to True).
+
+        datatype: Optional[str]
         """
+
+        # Store the datatype (if given) in a hidden field
+        # The datatypes will be stored in name, value pairs.
+        # TODO: check whether handling of lists is correct.
         self._datatypes[name] = datatype
 
         if isinstance(name, db.Entity):
+            # TODO: check, whether this is reasonable?
             name = name.name
+            raise NotImplementedError()
 
         if name in self._forbidden:
             raise RuntimeError("Entity cannot be converted to a corresponding "
                                "Python representation. Name of property " +
                                name + " is forbidden!")
+        
         already_exists = (name in dir(self))
 
         if already_exists and not overwrite:
-            # each call to _set_property checks first if it already exists
+            # each call to set_property checks first if it already exists
             #        if yes: Turn the attribute into a list and
             #                place all the elements into that list.
             att = self.__getattribute__(name)
 
             if isinstance(att, list):
+                # just append, see below
                 pass
             else:
                 old_att = self.__getattribute__(name)
@@ -120,7 +169,13 @@ class CaosDBPythonEntity(object):
 
     add_property = set_property
 
-    def set_id(self, idx):
+    def set_id(self, idx: int):
+        """
+        Explicitely set the id of this entity.
+
+        idx: int
+             The new ID for this entity.
+        """
         self._id = idx
 
     def _type_converted_list(self, val, pr):