Merge remote-tracking branch 'origin/docs' into dev

Author: dragly

exdir/core/group.py

@@ -62,7 +62,9 @@ def __init__(self, root_directory, parent_path, object_name, io_mode=None,
     def create_dataset(self, name, shape=None, dtype=None,
                        data=None, fillvalue=None):
         """
-        Create a dataset.
+        Create a dataset. This will create a folder on the filesystem with the given
+        name, an exdir.yaml file that identifies the folder as an Exdir Dataset,
+        and a data.npy file that contains the data.
 
         Parameters
         ----------
@@ -86,13 +88,16 @@ def create_dataset(self, name, shape=None, dtype=None,
 
         Returns
         -------
-        A reference to the newly created dataset.
+        The newly created Dataset.
 
         Raises
         ------
         FileExistsError
             If an object with the same `name` already exists.
 
+        See also
+        --------
+        require_dataset
         """
         exob._assert_valid_name(name, self)
 
@@ -134,8 +139,9 @@ def create_dataset(self, name, shape=None, dtype=None,
 
     def create_group(self, name):
         """
-        Create a subgroup with the given name.
-        This will create a subfolder on the file system.
+        Create a group. This will create a folder on the filesystem with the
+        given name and an exdir.yaml file that identifies the folder as a
+        group. A group can contain multiple groups and datasets.
 
         Parameters
         ----------
@@ -149,7 +155,11 @@ def create_group(self, name):
 
         Returns
         -------
-        A reference to the newly created group.
+        The newly created Group.
+
+        See also
+        --------
+        require_group
         """
         if self.io_mode == self.OpenMode.READ_ONLY:
             raise IOError("Cannot write data to file in read only ("r") mode")
@@ -193,7 +203,11 @@ def require_group(self, name):
 
         Returns
         -------
-        A reference to the newly created group.
+        The existing or created group.
+
+        See also
+        --------
+        create_group
         """
         path = utils.path.name_to_asserted_group_path(name)
         if len(path.parts) > 1:
@@ -305,6 +319,14 @@ def require_dataset(self, name, shape=None, dtype=None, exact=False,
         return current_object
 
     def __contains__(self, name):
+        """
+        Checks the existence of an object with the given name in the group.
+
+        Parameters
+        ----------
+        name: str
+            the case-sensitive name of the object
+        """
         if name == ".":
             return True
         if name == "":
@@ -314,6 +336,19 @@ def __contains__(self, name):
         return exob.is_exdir_object(directory)
 
     def __getitem__(self, name):
+        """
+        Retrieves the object with the given name if it exists in the group.
+
+        Parameters
+        ----------
+        name: str
+            the case-sensitive name of the object to retrieve
+
+        Raises
+        ------
+        KeyError:
+            if the name does not correspond to an exdir object in the group
+        """
         path = utils.path.name_to_asserted_group_path(name)
         if len(path.parts) > 1:
             top_directory = path.parts[0]
@@ -365,6 +400,17 @@ def _dataset(self, name):
         )
 
     def __setitem__(self, name, value):
+        """
+        Set or create a dataset with the given name from the given value.
+
+        Parameters
+        ----------
+        name: str
+            name of the existing or new dataset
+        value: object
+            value that will be used to create a new or set
+            the contents of an existing dataset
+        """
         path = utils.path.name_to_asserted_group_path(name)
         if len(path.parts) > 1:
             self[path.parent][path.name] = value
@@ -409,6 +455,9 @@ def values(self):
         return abc.ValuesView(self)
 
     def __iter__(self):
+        """
+        Iterate over all the objects in the group.
+        """
         # NOTE os.walk is way faster than os.listdir + os.path.isdir
         directories = next(os.walk(str(self.directory)))[1]
         for name in sorted(directories):