Improve H5Store docs (#775)

* Improve H5Store docs.

* Add H5Store related errors to the public API and docs.

* Doc revisions.

* Update changelog.

* Improve wording.

* Tiny grammar fix

Co-authored-by: Corwin Kerr <cbkerr@umich.edu>

changelog.txt

@@ -10,6 +10,10 @@ Version 2
 [2.0.0] -- 2021-xx-xx
 ---------------------
 
+Added
++++++
+ - ``H5Store`` related errors are now included in the public API (#775).
+
 Changed
 +++++++
 

doc/api.rst

@@ -109,7 +109,7 @@ The Job class
 The JSONDict
 ============
 
-This class implements the interface for the job's :attr:`~signac.contrib.job.Job.statepoint` and :attr:`~signac.contrib.job.Job.document` attributes, but can also be used stand-alone:
+This class implements the interface for the job's :attr:`~signac.contrib.job.Job.statepoint` and :attr:`~signac.contrib.job.Job.document` attributes, but can also be used on its own.
 
 .. autoclass:: JSONDict
     :members:
@@ -119,7 +119,7 @@ This class implements the interface for the job's :attr:`~signac.contrib.job.Job
 The H5Store
 ===========
 
-This class implements the interface to the job's :attr:`~signac.contrib.job.Job.data` attribute, but can also be used stand-alone:
+This class implements the interface to the job's :attr:`~signac.contrib.job.Job.data` attribute, but can also be used on its own.
 
 .. autoclass:: H5Store
     :members:
@@ -129,7 +129,7 @@ This class implements the interface to the job's :attr:`~signac.contrib.job.Job.
 The H5StoreManager
 ==================
 
-This class implements the interface to the job's :attr:`~signac.contrib.job.Job.stores` attribute, but can also be used stand-alone:
+This class implements the interface to the job's :attr:`~signac.contrib.job.Job.stores` attribute, but can also be used on its own.
 
 .. autoclass:: H5StoreManager
     :members:

signac/contrib/project.py

@@ -354,10 +354,10 @@ def doc(self, new_doc):
 
     @property
     def stores(self):
-        """Get HDF5-stores associated with this project.
+        """Get HDF5 stores associated with this project.
 
         Use this property to access an HDF5 file within the project
-        directory using the H5Store dict-like interface.
+        directory using the :py:class:`~.H5Store` dict-like interface.
 
         This is an example for accessing an HDF5 file called ``'my_data.h5'``
         within the project directory:
@@ -382,7 +382,7 @@ def stores(self):
         Returns
         -------
         :class:`~signac.H5StoreManager`
-            The HDF5-Store manager for this project.
+            The HDF5 store manager for this project.
 
         """
         with self._lock:

signac/core/errors.py

@@ -8,3 +8,11 @@ class Error(Exception):
     """Base class used for signac Errors."""
 
     pass
+
+
+class H5StoreClosedError(Error, RuntimeError):
+    """Raised when trying to access a closed HDF5 file."""
+
+
+class H5StoreAlreadyOpenError(Error, OSError):
+    """Indicates that the underlying HDF5 file is already open."""

signac/core/h5store.py

@@ -10,7 +10,7 @@
 from collections.abc import Mapping, MutableMapping
 from threading import RLock
 
-from ..errors import InvalidKeyError
+from ..errors import H5StoreAlreadyOpenError, H5StoreClosedError, InvalidKeyError
 from .dict_manager import DictManager
 from .utility import _safe_relpath
 
@@ -64,14 +64,6 @@ def _requires_tables():
 logger = logging.getLogger(__name__)
 
 
-class H5StoreClosedError(RuntimeError):
-    """Raised when trying to access a closed store."""
-
-
-class H5StoreAlreadyOpenError(OSError):
-    """Indicates that the underlying HDF5 file is already openend."""
-
-
 def _h5set(store, grp, key, value, path=None):
     """Set a key in an h5py container.
 
@@ -297,28 +289,25 @@ class H5Store(MutableMapping):
     ...     assert 'foo' in h5s
     ...     assert h5s.foo == 'bar'
     ...     assert h5s['foo'] == 'bar'
-    >>>
 
     The H5Store can be used as a context manager to ensure that the underlying
     file is opened, however most built-in types (excluding arrays) can be read
-    and stored without the need to _explicitly_ open the file. **To
+    and stored without the need to *explicitly* open the file. **To
     access arrays (reading or writing), the file must always be opened!**
 
     To open a file in read-only mode, use the :py:meth:`.open` method with ``mode='r'``:
 
     >>> with H5Store('file.h5').open(mode='r') as h5s:
     ...     pass
-    >>>
 
     Parameters
     ----------
     filename : str
         The filename of the underlying HDF5 file.
     \*\*kwargs
-        Additional keyword arguments to be forwarded to the ``h5py.File``
-        constructor. See the documentation for the `h5py.File constructor
-        <https://docs.h5py.org/en/latest/high/file.html#File>`_ for more
-        information.
+        Additional keyword arguments to be forwarded to the
+        :py:class:`h5py.File` constructor. See the :py:class:`h5py.File`
+        documentation for more information.
 
     """
     __slots__ = ["_filename", "_file", "_kwargs"]
@@ -382,9 +371,14 @@ def _open(self, **kwargs):
     def open(self, mode=None):
         """Open the underlying HDF5 file.
 
-        :param mode:
+        Parameters
+        ----------
+        mode : str
             The file open mode to use. Defaults to 'a' (append).
-        :returns:
+
+        Returns
+        -------
+        H5Store
             This H5Store instance.
         """
         if mode is None:
@@ -409,21 +403,25 @@ def close(self):
 
     @property
     def file(self):
-        """Access the underlying instance of h5py.File.
+        """Access the underlying instance of :py:class:`h5py.File`.
 
-        This property exposes the underlying ``h5py.File`` object enabling
-        use of functions such as ``create_dataset()`` or ``requires_dataset()``.
+        This property exposes the underlying :py:class:`h5py.File` object, enabling
+        use of functions such as :py:meth:`h5py.Group.create_dataset` or
+        :py:meth:`h5py.Group.require_dataset`.
 
         .. note::
 
             The store must be open to access this property!
 
-        :returns:
-            The ``h5py`` file-object that this store is operating on.
-        :rtype:
-            ``h5py.File``
-        :raises H5StoreClosedError:
-            When the store is closed at the time of accessing this property.
+        Returns
+        -------
+        h5py.File
+            The :py:class:`h5py.File` object that this store is operating on.
+
+        Raises
+        ------
+        H5StoreClosedError
+            If the store is closed.
         """
         if self._file is None:
             raise H5StoreClosedError(self.filename)

signac/errors.py

@@ -15,7 +15,7 @@
     StatepointParsingError,
     WorkspaceError,
 )
-from .core.errors import Error
+from .core.errors import Error, H5StoreAlreadyOpenError, H5StoreClosedError
 from .synced_collections.errors import InvalidKeyError, KeyTypeError
 
 
@@ -64,6 +64,8 @@ def __str__(self):
     "DocumentSyncConflict",
     "Error",
     "FileSyncConflict",
+    "H5StoreAlreadyOpenError",
+    "H5StoreClosedError",
     "IncompatibleSchemaVersion",
     "InvalidKeyError",
     "JobsCorruptedError",