DOC: Changed docstring of remove_value_from_property(): new behavior

Now do not delete the property in any case, if it was empty (None) before.

src/caosdb/common/models.py

@@ -458,38 +458,39 @@ class Entity:
 
         Do nothing if this entity does not have a property of this
         ``property_name`` or if the property value is different of the given
-        ``value``. By default, the property is removed form this entity if it is
-        empty (i.e., value=None) after removal of the value. This behavior can
-        be changed by setting ``remove_if_empty_afterwards`` to ``False`` in which
-        case the property remains.
+        ``value``. By default, the property is removed from this entity if it
+        becomes empty (i.e., value=None) through removal of the value. This
+        behavior can be changed by setting ``remove_if_empty_afterwards`` to
+        ``False`` in which case the property remains.
 
         Notes
         -----
         If the property value is a list and the value to be removed occurs more
-        than once in this list, only it's first occurrance is deleted (similar
+        than once in this list, only its first occurrance is deleted (similar
         to the behavior of Python's ``list.remove()``.)
 
-        If the property is already empty and a value != None is to be removed,
-        the property is not removed afterwards even if
-        ``remove_if_empty_afterwards`` is set to ``True`` (since it hasn't been
-        emptied **because** this function was called but rather didn't have a
-        value in the first place). This changes if the value to be removed is
-        set to ``None`` explicitly.
+        If the property was empty (prop.value == None) before, the property is
+        not removed afterwards even if ``remove_if_empty_afterwards`` is set to
+        ``True``.  Rationale: the property being empty is not an effect of
+        calling this function.
 
         Parameters
         ----------
         property_name : str
             Name of the property from which the ``value`` will be removed.
+
         value
             Value that is to be removed.
+
         remove_if_empty_afterwards : bool, optional
-            Whether the property is to be removed from this entity if it is
+            Whether the property shall be removed from this entity if it is
             emptied by removing the ``value``. Default is ``True``.
 
         Returns
         -------
         self
             This entity.
+
         """
 
         if self.get_property(property_name) is None:

unittests/test_property.py

@@ -205,8 +205,9 @@ def test_remove_value_from_property():
     assert rec.get_property("testEmptyProp").value is None
     assert rec.get_property("testEmptyProp").datatype == db.REFERENCE
 
-    # Corner case of corner case: remove with `value=None` explicitly and
-    # `remove_if_empty_afterwards=True` leads to the removal of an empty
-    # property.
+    # Corner case of corner case: remove with `value=None` and
+    # `remove_if_empty_afterwards=True` keeps the empty property.
     rec.remove_value_from_property("testEmptyProp", None, remove_if_empty_afterwards=True)
-    assert rec.get_property("testEmptyProp") is None
+    assert rec.get_property("testEmptyProp") is not None
+    assert rec.get_property("testEmptyProp").value is None
+    assert rec.get_property("testEmptyProp").datatype == db.REFERENCE