Add type hints to models.py

Summary

Introduce type hints in models.py. #144 (closed)

Focus

This MR adds many type hints to models.py, but is not complete. Also, probaby not all type hints are fully correct and will have to be checked, in particular whether really all Optional arguments are actually optional, i.e. are allowed to be None.

Test Environment

Regular test environment.

Check List for the Author

Please, prepare your MR for a review. Be sure to write a summary and a focus and create gitlab comments for the reviewer. They should guide the reviewer through the changes, explain your changes and also point out open questions. For further good practices have a look at our review guidelines

• All automated tests pass
• Reference related issues
• Up-to-date CHANGELOG.md (or not necessary)
• 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 (or not necessary)
• 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 specifications? Are they satisfied?

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

src/caosdb/common/models.py

@@ -587,18 +587,24 @@ class Entity(object):
 
         return name_result and id_result
 
-    def get_parents(self):
+    def get_parents(self) -> list:
         """Get all parents of this entity.
 
-        @return: _Parents(list)
+        Returns
+        -------
+       list
+            Parents
         """
 
         return self.parents
 
-    def get_parents_recursively(self):
+    def get_parents_recursively(self) -> list:
         """Get all ancestors of this entity.
 
-        @return: list of Entities
+        Returns
+        -------
+        list
+            list of Entities
         """
 
         all_parents = _Parents()
@@ -606,15 +612,16 @@ class Entity(object):
 
         return all_parents
 
-    def _get_parent_recursively(self, all_parents):
+    def _get_parent_recursively(self, all_parents: list) -> None:
         """Get all ancestors with a little helper.
 
-        As a side effect of this method, the ancestors are added to
-        all_parents.
-
-        @param all_parents: The added parents so far.
+        Important: As a side effect of this method, the ancestors are 
+        added to all_parents.
 
-        @return: None, but see side effects.
+        Parameters
+        ----------
+        all_parents : list
+            The added parents so far
         """
 
         for parent in self.parents:
@@ -624,22 +631,21 @@ class Entity(object):
                 all_parents.append(w_parent)
                 w_parent._get_parent_recursively(all_parents)
 
-    def get_parent(self, key):
+    def get_parent(self, key: Union[Entity, int, str]) -> Optional[Entity]:
         """Return the first parent matching the key or None if no match exists.
 
         Parameters
-        ---------
-        key : int or Enity or str
+        ----------
+        key : Entity, int, str
             The id, Entity, or name of the parent that should be
             returned. If an Entity is given, its id or its name is
             used to find a matching parent.
 
         Returns
         -------
-        parent : Entity
+        Entity
             The first parent of this entity that matches the given id,
             entity, or name.
-
         """
 
         if isinstance(key, int):
@@ -665,41 +671,51 @@ class Entity(object):
 
         return None
 
-    def get_properties(self):
+    def get_properties(self) -> list:
         """Get all properties of this entity.
 
-        @return: _Properties(list)
+        Returns
+        -------
+        list
+            _Properties(list)
         """
-
         return self.properties
 
-    def get_property(self, pattern):
-        """ Return the first matching property or None.
+    def get_property(self, pattern: Union[Entity, str, int]) -> Optional[Property]:
+        """Return the first matching property or None.
 
         Parameters
         ----------
-        pattern : str or int or Entity
+        pattern : Entity, str, int
             The name or id to look for (case-insensitive) or an Entity where
             the name or id is used to match the properites of this instance.
 
         Returns
         -------
-        property : Property
+        Property
             The first Property of this Entity with a matching name or id.
 
+        Raises
+        ------
+        ValueError
+            Wrong input type.
         """
+
         # entity given
 
-        if (hasattr(pattern, "name") or hasattr(pattern, "id")):
+         # entity given
+        pattern_name = getattr(pattern, "name", None)
+        pattern_id = getattr(pattern, "id", None)
+        if pattern_name or pattern_id:
             # only return if a result was found, otherwise use id
 
-            if (hasattr(pattern, "name") and pattern.name is not None
-                    and self.get_property(pattern.name) is not None):
+            if (pattern_name is not None
+                    and self.get_property(pattern_name) is not None):
 
-                return self.get_property(pattern.name)
+                return self.get_property(pattern_name)
 
-            if hasattr(pattern, "id") and pattern.id is not None:
-                return self.get_property(pattern.id)
+            if pattern_id is not None:
+                return self.get_property(pattern_id)
 
         # int given
         elif isinstance(pattern, int):
@@ -718,15 +734,24 @@ class Entity(object):
 
         return None
 
-    def _get_value_for_selector(self, selector):
-        """return the value described by the selector
+    def _get_value_for_selector(self, selector: Union[tuple, list, str]) -> Any:
+        """Return the value described by the selector
+
+        Parameters
+        ----------
+        selector : tuple, list, str
+            A selector is a list or a tuple of strings describing a path in an
+            entity tree with self as root. The last selector may be a special one
+            like unit or name.
 
-        A selector is a list or a tuple of strings describing a path in an
-        entity tree with self as root. The last selector may be a special one
-        like unit or name.
+        Returns
+        -------
+        Any
+            The value described by the selector.
 
         See also get_property_values()
         """
+        
         SPECIAL_SELECTORS = ["unit", "value", "description", "id", "name"]
 
         if not isinstance(selector, (tuple, list)):