[frontend] dataset docstrings, improved searching

fishbook/frontend/frontend_classes.py

@@ -80,9 +80,11 @@ class Cell:
 
 
 class Dataset:
-    """The Dataset class represents an entry in the "datasets" table in the database. In the relacs context a Dataset represents all that has been recorded between pressing enter. For example all that is stored in the folder 2020-01-01-aa.
-
+    """ The Dataset class represents an entry in the "datasets" table in the database. In the relacs 
+        context a Dataset represents all that has been recorded between pressing enter. For example 
+        all that is stored in the folder 2020-01-01-aa.
 
+        Dataset contains several basic properties and allows access to associated cells and subjects.
     """
     def __init__(self, dataset_id=None, tuple=None):
         """Constructor of a Dataset entity.
@@ -133,71 +135,125 @@ class Dataset:
 
     @property
     def recording_duration(self):
+        """Recording duration.
+
+        Returns:
+            float: recprding duration given in seconds.
+        """
         return self.__tuple["duration"]
 
     @property
     def quality(self):
+        """The quality assessment as assigned by the experimenter.
+
+        Returns:
+            str: the quality
+        """
         return self.__tuple["quality"]
 
     @property
     def has_nix(self):
+        """Whether or not a nix file was recorded.
+
+        Returns:
+            bool: true or false
+        """
         return self.__tuple["has_nix"]
 
     @property
     def comment(self):
+        """The comment entered by the experimenter.
+
+        Returns:
+            str: the comment
+        """
         return self.__tuple["comment"]
 
     @property
     def data_source(self):
+        """Where the data is stored (at least at the time of import).
+
+        Returns:
+            str: the path to the data. 
+        """
         return self.__tuple["data_source"]
 
     @property
     def setup(self):
+        """The recording setup.
+
+        Returns:
+            str: the setup
+        """
         return self.__tuple["setup"]
 
     @property
     def cells(self):
+        """The list of cells that are associated with this dataset.
+
+        Returns:
+            list of fishbook.Cell: the cells.
+        """
+
         cell_list = (Cells * (CellDatasetMap & self.__tuple))
         return [Cell(tuple=c) for c in cell_list]
 
     @property
     def subjects(self):
+        """The subjects that are associated with this dataset.
+
+        Returns:
+            list of fishbook.Subject: list of subjects
+        """
         subject_list = (Subjects * (SubjectDatasetMap & self.__tuple))
         return [Subject(tuple=s) for s in subject_list]
 
     @property
     def samplerate(self):
+        """Get the samplerate of the data.
+
+        Returns:
+            float: the sample rate
+        """
         return self.__samplerate
 
     @staticmethod
-    def totalDatasetCount():
+    def datasetCount():
         """Returns the total number of datasets defined in the database.
 
         Returns:
             int: the count
         """
-        return len(Datasets)
+        return len(Datasets())
 
     @staticmethod
-    def find(min_duration=None, experimenter=None, quality=None):
+    def find(min_duration=None, experimenter=None, quality=None, test=False):
         """Find dataset entries in the database. You may restrict the search by providing the following arguments.
 
         Args:
             min_duration (float, optional): minimum duration of the recording session, if not given, any length datasets will be returned. Defaults to None.
             experimenter (str, optional): the name of the one who did the recording. The name does not need to be the full name. Defaults to None.
             quality (str, optional): the quality assigned to the dataset during recording (e.g. good, fair, poor). Defaults to None.
-
+            test (bool, optional): defines whether this is a test run and thus whether or not the search results should be fetched, which can take a while. Defaults to False.
         Returns:
-            list: list of Dataset object matching the search criteria.
+            list: list of Dataset object matching the search criteria, empty if test==True
+            int: Count of matching results
         """
-        dataset_list = Datasets
+        dataset_list = Datasets()
         if min_duration:
             dataset_list = dataset_list & "duration > %.2f" % min_duration
         if experimenter:
             dataset_list = dataset_list & "experimenter like '%{0:s}%'".format(experimenter)
         if quality:
             dataset_list = dataset_list & "quality like '{0:s}'".format(quality)
-        return [Dataset(tuple=d) for d in dataset_list]
+        
+        results = []
+        total = len(dataset_list)
+        if not test:
+            for i, d in enumerate(dataset_list):
+                progress(i+1, total, "fetching data")
+                results.append(Dataset(tuple=d))
+        return results, total
 
     def __find_samplerate(self, trace_name="V-1"):
         if self.has_nix and os.path.exists(os.path.join(self.data_source, self.id, '.nix')):
@@ -229,6 +285,13 @@ class Dataset:
     def _tuple(self):
         return self.__tuple.copy()
 
+    def __str__(self):
+        str = "id: %s\n" % self.id
+        str += "recorded: %s \t by:%s\n" % (self.recording_date, self.experimenter)
+        str += "duration: %ss \t quality:%s\n" % (self.recording_duration, self.quality)
+        str += "comment: %s" % self.comment
+        return str
+
 
 class RePro:
     def __init__(self, repro_id=None, tuple=None):