From d8a7a022df815d8254c4a9674ef1143f50caa277 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= <hugo@lysator.liu.se>
Date: Mon, 28 Nov 2022 19:34:35 +0100
Subject: Documentation.

---
 mu.py | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 57 insertions(+), 1 deletion(-)

(limited to 'mu.py')

diff --git a/mu.py b/mu.py
index 93816f4..9337747 100644
--- a/mu.py
+++ b/mu.py
@@ -1,3 +1,7 @@
+"""
+Wrapper for the `mu` command line.
+"""
+
 import email.message
 import email.policy
 from email.parser import BytesParser
@@ -6,16 +10,29 @@ from subprocess import PIPE
 import xml.dom.minidom
 import xml.dom
 
+from typing import (
+    Literal,
+    Union,
+)
 
 parser = BytesParser(policy=email.policy.default)
 
 
 def get_mail(id: str) -> email.message.Message:
+    """
+    Lookup email by Message-ID.
+
+    [Raises]
+        MuError
+    """
     cmd = subprocess.run(['mu', 'find', '-u', f'i:{id}',
                           '--fields', 'l'],
                          stdout=PIPE)
     filename = cmd.stdout.decode('UTF-8').strip()
 
+    if cmd.returncode != 0:
+        raise MuError(cmd.returncode)
+
     with open(filename, "rb") as f:
         mail = parser.parse(f)
     return mail
@@ -36,7 +53,46 @@ class MuError(Exception):
         return f'MuError({self.returncode}, "{self.msg}")'
 
 
-def mu_search(query, sortfield='subject', reverse=False):
+Sortfield = Union[Literal['cc'],
+                  Literal['c'],
+                  Literal['bcc'],
+                  Literal['h'],
+                  Literal['date'],
+                  Literal['d'],
+                  Literal['from'],
+                  Literal['f'],
+                  Literal['maildir'],
+                  Literal['m'],
+                  Literal['msgid'],
+                  Literal['i'],
+                  Literal['prio'],
+                  Literal['p'],
+                  Literal['subject'],
+                  Literal['s'],
+                  Literal['to'],
+                  Literal['t'],
+                  Literal['list'],
+                  Literal['v']]
+
+
+
+def mu_search(query, sortfield: Sortfield = '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'
+         }
+    """
+
     if not query:
         raise ValueError('Query required for mu_search')
     cmdline = ['mu', 'find',
-- 
cgit v1.2.3