Document classes, methods, modules.

4 files changed, 102 insertions, 37 deletions

diff --git a/src/mailman_pgp/pgp/inline.py b/src/mailman_pgp/pgp/inline.py
index 646d13a..d87b3da 100644
--- a/src/mailman_pgp/pgp/inline.py
+++ b/src/mailman_pgp/pgp/inline.py
@@ -16,16 +16,23 @@
 # this program.  If not, see <http://www.gnu.org/licenses/>.
 
 """Strict inline PGP message wrapper."""
-from email.message import Message
 
-from pgpy import PGPKey, PGPMessage
+from pgpy import PGPMessage
 from pgpy.types import Armorable
 from public import public
 
 
 @public
 class InlineWrapper:
-    def __init__(self, msg: Message):
+    """Inline PGP wrapper."""
+
+    def __init__(self, msg):
+        """
+        Wrap the given message.
+
+        :param msg: The message to wrap.
+        :type msg: mailman.email.message.Message
+        """
         self.msg = msg
 
     def _is_inline(self):
@@ -45,32 +52,50 @@ class InlineWrapper:
 
     def is_signed(self):
         """
+        Whether the message is inline signed (cleartext).
 
-        :return:
+        :return: If the message is inline signed.
+        :rtype: bool
         """
+        # XXX: This doesnt handle non-cleartext signatures (gpg -s -a)
         return self._is_inline() and self._has_armor('SIGNATURE')
 
     def is_encrypted(self):
         """
+        Whether the message is inline encrypted.
 
-        :return:
+        :return: If the message is inline encrypted.
+        :rtype: bool
         """
+        # XXX: This mistakes non-cleartext signature as encrypted.
         return self._is_inline() and self._has_armor('MESSAGE')
 
-    def verify(self, key: PGPKey):
+    def verify(self, key):
         """
+        Verify the signature of this message with key.
 
-        :param key:
-        :return:
+        :param key: The key to verify with.
+        :type key: pgpy.PGPKey
+        :return: The verified signature.
+        :rtype: pgpy.types.SignatureVerification
         """
         message = PGPMessage.from_blob(self._as_string())
         return key.verify(message)
 
-    def decrypt(self, key: PGPKey):
+    def sign(self):
+        pass
+
+    def decrypt(self, key):
         """
+        Decrypt this message with key.
 
-        :param key:
-        :return:
+        :param key: The key to decrypt with.
+        :type key: pgpy.PGPKey
+        :return: The decrypted message.
+        :rtype: PGPMessage
         """
         message = PGPMessage.from_blob(self._as_string())
         return key.decrypt(message)
+
+    def encrypt(self):
+        pass
diff --git a/src/mailman_pgp/pgp/keygen.py b/src/mailman_pgp/pgp/keygen.py
index bff5450..06ca22b 100644
--- a/src/mailman_pgp/pgp/keygen.py
+++ b/src/mailman_pgp/pgp/keygen.py
@@ -28,22 +28,20 @@ from pgpy.constants import (
 
 
 class ListKeyGenerator(mp.Process):
-    """"""
+    """A multiprocessing list key generator."""
 
     def __init__(self, keypair_config, display_name, posting_address,
                  request_address, key_path):
         super().__init__(
             target=self.generate,
-            args=(
-                keypair_config, display_name, posting_address, request_address,
-                key_path),
-            daemon=True)
+            args=(keypair_config, display_name, posting_address,
+                  request_address, key_path))
 
     def generate(self, keypair_config, display_name, posting_address,
                  request_address, key_path):
         """
-        Generates the list keypair and saves it to key_path, if it does not
-        exist.
+        Generate the list keypair and save it, if it does not exist.
+
         :param keypair_config:
         :param display_name:
         :param posting_address:
@@ -59,8 +57,9 @@ class ListKeyGenerator(mp.Process):
 
     def _create(self, config, display_name, posting_address, request_address):
         """
-        Generates the list `PGPKey` keypair, with posting and request UIDs.
-        Uses a Sign+Certify main key and Encrypt subkey.
+        Generate the list `PGPKey` keypair, with posting and request UIDs.
+
+        Use a Sign+Certify main key and Encrypt subkey.
         :param config:
         :param display_name:
         :param posting_address:
@@ -105,6 +104,7 @@ class ListKeyGenerator(mp.Process):
     def _save(self, key, key_path):
         """
         Save the generated key.
+
         :param key:
         :param key_path:
         """
diff --git a/src/mailman_pgp/pgp/mime.py b/src/mailman_pgp/pgp/mime.py
index b8ab882..fde9d49 100644
--- a/src/mailman_pgp/pgp/mime.py
+++ b/src/mailman_pgp/pgp/mime.py
@@ -16,19 +16,27 @@
 # this program.  If not, see <http://www.gnu.org/licenses/>.
 
 """RFC1847 and RFC3156 compliant message wrapped."""
-from email.message import Message
+
 from email.utils import collapse_rfc2231_value
 
-from pgpy import PGPKey, PGPMessage, PGPSignature
+from pgpy import PGPMessage, PGPSignature
 from public import public
 
 
 @public
 class MIMEWrapper:
+    """PGP/MIME (RFC1847 + RFC3156) compliant wrapper."""
+
     _signed_subtype = 'application/pgp-signature'
     _encrypted_subtype = 'application/pgp-encrypted'
 
-    def __init__(self, msg: Message):
+    def __init__(self, msg):
+        """
+        Wrap the given message.
+
+        :param msg: The message to wrap.
+        :type msg: mailman.email.message.Message
+        """
         self.msg = msg
 
     def _is_mime(self):
@@ -40,7 +48,9 @@ class MIMEWrapper:
     def is_signed(self):
         """
         Whether the whole message is MIME signed as per RFC3156 section 5.
-        :return:
+
+        :return: If the message is MIME signed.
+        :rtype: bool
         """
         if not self._is_mime():
             return False
@@ -56,7 +66,9 @@ class MIMEWrapper:
     def is_encrypted(self):
         """
         Whether the whole message is MIME encrypted as per RFC3156 section 4.
-        :return:
+
+        :return: If the message is MIME encrypted.
+        :rtype: bool
         """
         if not self._is_mime():
             return False
@@ -73,11 +85,14 @@ class MIMEWrapper:
             content_subtype == 'encrypted' and \
             protocol_param == MIMEWrapper._encrypted_subtype
 
-    def verify(self, key: PGPKey):
+    def verify(self, key):
         """
+        Verify the signature of this message with key.
 
-        :param key:
-        :return:
+        :param key: The key to verify with.
+        :type key: pgpy.PGPKey
+        :return: The verified signature.
+        :rtype: pgpy.types.SignatureVerification
         """
         clear_text = self.msg.get_payload(0).as_string()
         sig_text = self.msg.get_payload(1).get_payload()
@@ -87,11 +102,14 @@ class MIMEWrapper:
     def sign(self):
         pass
 
-    def decrypt(self, key: PGPKey):
+    def decrypt(self, key):
         """
+        Decrypt this message with key.
 
-        :param key:
-        :return:
+        :param key: The key to decrypt with.
+        :type key: pgpy.PGPKey
+        :return: The decrypted message.
+        :rtype: PGPMessage
         """
         msg_text = self.msg.get_payload(1).get_payload()
         msg = PGPMessage.from_blob(msg_text)
diff --git a/src/mailman_pgp/pgp/wrapper.py b/src/mailman_pgp/pgp/wrapper.py
index 5d8bf41..9a004c4 100644
--- a/src/mailman_pgp/pgp/wrapper.py
+++ b/src/mailman_pgp/pgp/wrapper.py
@@ -14,10 +14,8 @@
 # You should have received a copy of the GNU General Public License along with
 # this program.  If not, see <http://www.gnu.org/licenses/>.
 
-""""""
-from email.message import Message
+"""A combined PGP/MIME + inline PGP wrapper."""
 
-from pgpy import PGPKey
 from public import public
 
 from mailman_pgp.pgp.inline import InlineWrapper
@@ -26,7 +24,15 @@ from mailman_pgp.pgp.mime import MIMEWrapper
 
 @public
 class PGPWrapper():
-    def __init__(self, msg: Message):
+    """A combined PGP/MIME + inline PGP wrapper."""
+
+    def __init__(self, msg):
+        """
+        Wrap the given message.
+
+        :param msg: The message to wrap.
+        :type msg: mailman.email.message.Message
+        """
         self.msg = msg
         self.mime = MIMEWrapper(msg)
         self.inline = InlineWrapper(msg)
@@ -40,7 +46,15 @@ class PGPWrapper():
     def is_signed(self):
         return self.is_mime_signed() or self.is_inline_signed()
 
-    def verify(self, key: PGPKey):
+    def verify(self, key):
+        """
+        Verify the signature of this message with key.
+
+        :param key: The key to verify with.
+        :type key: pgpy.PGPKey
+        :return: The verified signature.
+        :rtype: pgpy.types.SignatureVerification
+        """
         if self.is_mime_signed():
             return self.mime.verify(key)
         else:
@@ -55,7 +69,15 @@ class PGPWrapper():
     def is_encrypted(self):
         return self.is_mime_encrypted() or self.is_inline_encrypted()
 
-    def decrypt(self, key: PGPKey):
+    def decrypt(self, key):
+        """
+        Decrypt this message with key.
+
+        :param key: The key to decrypt with.
+        :type key: pgpy.PGPKey
+        :return: The decrypted message.
+        :rtype: PGPMessage
+        """
         if self.is_mime_encrypted():
             return self.mime.decrypt(key)
         else: