Add docstrings to new core

heracles/core.py

@@ -16,14 +16,23 @@
 #
 # You should have received a copy of the GNU Lesser General Public
 # License along with Heracles. If not, see <https://www.gnu.org/licenses/>.
-"""module for common core functionality"""
+"""module for common core functionality."""
 
 from collections import UserDict
 from collections.abc import Mapping, Sequence
 
 
 def toc_match(key, include=None, exclude=None):
-    """return whether a tocdict entry matches include/exclude criteria"""
+    """Return whether a tocdict entry matches include/exclude criteria.
+
+    Args:
+        key: _description_
+        include: _description_
+        exclude: _description_
+
+    Returns:
+        _description_
+    """
     if include is not None:
         for pattern in include:
             if all(p is Ellipsis or p == k for p, k in zip(pattern, key)):
@@ -38,7 +47,19 @@ def toc_match(key, include=None, exclude=None):
 
 
 def toc_filter(obj, include=None, exclude=None):
-    """return a filtered toc dict ``d``"""
+    """Return a filtered toc dict ``d``.
+
+    Args:
+        obj: _description_
+        include: _description_
+        exclude: _description_
+
+    Raises:
+        TypeError: _description_
+
+    Returns:
+        _description_
+    """
     if isinstance(obj, Sequence):
         return [toc_filter(item, include, exclude) for item in obj]
     if isinstance(obj, Mapping):
@@ -50,10 +71,24 @@ def toc_filter(obj, include=None, exclude=None):
 # subclassing UserDict here since that returns the correct type from methods
 # such as __copy__(), __or__(), etc.
 class TocDict(UserDict):
-    """Table-of-contents dictionary with pattern-based lookup"""
+    """Table-of-contents dictionary with pattern-based lookup.
+
+    Args:
+        UserDict: _description_
+    """
 
     def __getitem__(self, pattern):
-        """look up one or many keys in dict"""
+        """Look up one or many keys in dict.
+
+        Args:
+            pattern: _description_
+
+        Raises:
+            KeyError: _description_
+
+        Returns:
+            _description_
+        """
         # first, see if pattern is a valid entry in the dict
         # might fail with KeyError (no such entry) or TypeError (not hashable)
         try: