MAINT: fix test, allow non-interactive crawl, and docs

integrationtests/full_test/test_crawler.py

@@ -18,7 +18,7 @@ class CrawlerTest(unittest.TestCase):
         # vanishing of the property
         # thus an x is used here. Needs to be fixed.
         exp = db.execute_query(
-            "FIND Experiment with date=2019-02-03 and not identifier",
+            "FIND Experiment with date=2019-02-03 and identifier=empty_identifier",
             unique=True)
 
         # There should be a Project with name TestProject which is referenced
@@ -57,7 +57,7 @@ class CrawlerTest(unittest.TestCase):
         # # first analysis # #
         ######################
         ana = db.execute_query(
-            "FIND Analysis with date=2019-02-03 and identifier='x'",
+            "FIND Analysis with date=2019-02-03 and identifier='empty_identifier'",
             unique=True)
 
         # There should be a Project with name TestProject which is referenced

src/caosadvancedtools/cfood.py

@@ -175,7 +175,14 @@ class AbstractCFood(object):
 
     def looking_for(self, crawled_file):
         """
-        should set the instance variable Container with the identifiables
+        returns True if crawled_file can be added this CFood.
+
+        to be overwritten by subclasses.
+        Sometimes files belong to the CFood of created by another file. This
+        function can be used to define what files shall be 'attached'. E.g. the
+        data from an experiment should always contain a labnotes scan. Then a
+        subclass CFood for the experiment could be 'looking_for' this scan
+        using this function.
         """
 
         return False
@@ -412,6 +419,27 @@ def get_ids_for_entities_with_names(entities):
 
 
 class CMeal(object):
+    """
+    CMeal groups equivalent CFoods and allow their collected insertion.
+
+    Sometimes there is no one file that can be used to trigger the creation of
+    some Record. E.g. if a collection of images shall be referenced from one
+    Record that groups them, it is unclear which image should trigger the
+    creation of the Record.
+
+    CMeals are grouped based on the groups in the used regular expression. If,
+    in the above example, all the images reside in one folder, all groups
+    except that for the file name should match. The groups that shall match
+    need to be listed in the matching_groups class property. Subclasses will
+    overwrite this property.
+
+    The cook function of a cfood allows this class to work. Instead of directly
+    instantiating a CFood the cook function is used. If the CFood is also a
+    child of CMeal, it will be checked (using get_suitable_cfood) in the cook
+    function whether a new CFood should be created or if the file match should
+    be added to an existing one. In order to allow this all instances of a
+    CFood class are tracked in the existing_instances class member.
+    """
     existing_instances = []
     matching_groups = []