1 files changed, 40 insertions, 23 deletions

diff --git a/mu4web/mu.py b/mu4web/mu.py
index 8efbd38..2d2d5ac 100644
--- a/mu4web/mu.py
+++ b/mu4web/mu.py
@@ -1,6 +1,4 @@
-"""
-Wrapper for the `mu` command line.
-"""
+"""Wrapper for the `mu` command line."""
 
 import email.message
 import email.policy
@@ -24,7 +22,20 @@ from typing import (
 parser = BytesParser(policy=email.policy.default)
 
 
-def find_file(id: str) -> Optional[PathLike]:
+def find_file(id: str) -> Optional[PathLike[str]]:
+    """
+    Find the file system location for mail with given id.
+
+    :param id:
+        A normalized message id.
+
+    :returns:
+        Either the file system path for a message with that id, or
+        None if no matches were found.
+
+    :raises MuError:
+        On all other failure modes.
+    """
     cmd = subprocess.run(['mu', 'find', '-u', f'i:{id}',
                           '--fields', 'l'],
                          stdout=PIPE)
@@ -41,8 +52,7 @@ def get_mail(id: str) -> email.message.Message:
     """
     Lookup email by Message-ID.
 
-    [Raises]
-        MuError
+    :raises MuError:
     """
     filename = find_file(id)
     if not filename:
@@ -54,6 +64,8 @@ def get_mail(id: str) -> email.message.Message:
 
 
 class MuError(Exception):
+    """One of the errors which mu can return."""
+
     codes = {
         1: 'General Error',
         2: 'No Matches',
@@ -75,21 +87,24 @@ def search(query: str,
            sortfield: Optional[str] = 'subject',
            reverse: bool = False) -> list[dict[str, str]]:
     """
-    [Parameters]
-        query     - Search query as per mu-find(1).
-        sortfield - Field to sort the values by
-        reverse   - If the sort should be reversed
-
-    [Returns]
-    >>> {'from': 'Hugo Hörnquist <hugo@example.com>',
-         'date': '1585678375',
-         'size': '377',
-         'msgid': 'SAMPLE-ID@localhost',
-         'path': '/home/hugo/.local/var/mail/INBOX/cur/filename',
-         'maildir': '/INBOX'
-         }
+    Search the mu database for messages.
+
+    :param query:
+        Search query as per mu-find(1).
+    :param sortfield:
+        Field to sort the values by
+    :param reverse:
+        If the sort should be reversed
+
+    :returns:
+        >>> {'from': 'Hugo Hörnquist <hugo@example.com>',
+             'date': '1585678375',
+             'size': '377',
+             'msgid': 'SAMPLE-ID@localhost',
+             'path': '/home/hugo/.local/var/mail/INBOX/cur/filename',
+             'maildir': '/INBOX'
+             }
     """
-
     if not query:
         raise ValueError('Query required for mu_search')
     cmdline = ['mu', 'find',
@@ -125,9 +140,9 @@ def search(query: str,
     return message_list
 
 
-def base_directory() -> PathLike:
+def base_directory() -> PathLike[str]:
     """
-    Returns where where mu stores its files.
+    Return where where mu stores its files.
 
     Defaults to $XDG_CACHE_HOME/mu, but can be changed through the
     environment variable MUHOME.
@@ -138,6 +153,8 @@ def base_directory() -> PathLike:
 
 
 class MuInfo(TypedDict):
+    """Metadata about the mu database."""
+
     database_path: str
     changed: datetime
     created: datetime
@@ -148,7 +165,7 @@ class MuInfo(TypedDict):
 
 
 def info() -> MuInfo:
-
+    """Collect metadata about the mu database."""
     db = os.path.join(base_directory(), "xapian")
 
     def f(key: str) -> datetime: