Improve python helpers documentation.

1 files changed, 36 insertions, 14 deletions

diff --git a/hs/mail.py b/hs/mail.py
index 03a423b..34b9ef3 100755
--- a/hs/mail.py
+++ b/hs/mail.py
@@ -1,13 +1,18 @@
 #!/usr/bin/env python3
 
-"""
-./main <msg-id>
-> LEN "\n" json-data
-on input:
-> LEN "\n" bytes
+r"""
+Helper script for reading mail from Haskell.
+
+Usage:
+------
+
+    ./main <msg-id>
+    > LEN "\n" json-data
+    on input:
+    > LEN "\n" bytes
 """
 
-from email.message import EmailMessage
+# from email.message import EmailMessage
 from email.parser import BytesParser
 from uuid import uuid4
 import email.policy
@@ -20,8 +25,20 @@ import email.contentmanager
 
 import mu
 
+
 def build_part_tree(part, part_map):
-    result = []
+    """
+    Build a "tree" of all components in mail.
+
+    :param part:
+        A "part" of an email, as per the email library.
+        Each part maps to one node of the tree, and the parts children
+        maps to children in the resulting tree.
+    :param part_map:
+        Dictionary which will be populated with an unique ID for each part.
+        Id's are arbitrary, and change between runs. It's up to the
+        caller if they want to use these for anything.
+    """
     id = str(uuid4())
     part_map[id] = part
     return {
@@ -33,21 +50,25 @@ def build_part_tree(part, part_map):
         'charset': part.get_content_charset(),
     }
 
+
 tmpdir = f'/tmp/.vimwiki-scripts-{os.getuid()}'
 
+
 os.umask(0o077)
 try:
     os.mkdir(tmpdir)
 except FileExistsError:
     os.chmod(tmpdir, 0o700)
 
+
 content_manager = email.contentmanager.raw_data_manager
-content_manager.add_get_handler('text', email.contentmanager.get_non_text_content)
+content_manager.add_get_handler(
+        'text', email.contentmanager.get_non_text_content)
 
-def main():
 
+def __main():
     if len(sys.argv) == 1:
-        print(f'Usage: {sys.argv[0]} message-id')
+        print(f'Usage: {sys.argv[0]} message-id', file=sys.stderr)
         return
 
     id = sys.argv[1]
@@ -60,9 +81,8 @@ def main():
     with open(filename, 'rb') as f:
         mail = parser.parse(f)
 
-
     part_map = {}
-    bytes = json.dumps(build_part_tree(mail, part_map), 
+    bytes = json.dumps(build_part_tree(mail, part_map),
                        ensure_ascii=True).encode('ASCII')
     sys.stdout.buffer.write(b'%i\n' % len(bytes))
     sys.stdout.buffer.write(bytes)
@@ -88,7 +108,8 @@ def main():
                 bytes = s
                 digest = hashlib.sha256(bytes).hexdigest()
                 filename = os.path.join(tmpdir, digest) \
-                         + mimetypes.guess_extension(part.get_content_type())
+                    + mimetypes.guess_extension(part.get_content_type())
+
                 # Write could be skiped, but then we would
                 # probably want to ensure the correct content,
                 # meaning checksuming the existing file, which
@@ -105,5 +126,6 @@ def main():
     except EOFError:
         pass
 
+
 if __name__ == '__main__':
-    main()
+    __main()