Add documentation

webservice/lib/utils/emails.py

@@ -8,15 +8,30 @@ from django.conf import settings
 
 # Source: https://djangosnippets.org/snippets/2215/
 class EmailMultiRelated(EmailMultiAlternatives):
-    """
-    A version of EmailMessage that makes it easy to send multipart/related
+    """A version of EmailMessage that makes it easy to send multipart/related
     messages. For example, including text and HTML versions with inline images.
+
+    Returns:
+        EmailMultiAlternatives: EmailMultiAlternatives class
     """
+    
     related_subtype = 'related'
 
     def __init__(self, subject='', body='', from_email=None, to=None, bcc=None,
             connection=None, attachments=None, headers=None, alternatives=None):
-        # self.related_ids = []
+        """Create a new email object that can holds text and HTML content. 
+
+        Args:
+            subject (str, optional): The subject of the email. Defaults to ''.
+            body (str, optional): The body of the email. Defaults to ''.
+            from_email (str, optional): [description]. Defaults to None.
+            to ([type], optional): [description]. Defaults to None.
+            bcc ([type], optional): [description]. Defaults to None.
+            connection ([type], optional): [description]. Defaults to None.
+            attachments ([type], optional): [description]. Defaults to None.
+            headers ([type], optional): [description]. Defaults to None.
+            alternatives ([type], optional): [description]. Defaults to None.
+        """
         self.related_attachments = []
         super(EmailMultiRelated, self).__init__(subject, body, from_email, to, bcc, connection, attachments, headers, alternatives)
 
@@ -27,7 +42,13 @@ class EmailMultiRelated(EmailMultiAlternatives):
 
         If the first parameter is a MIMEBase subclass it is inserted directly
         into the resulting message attachments.
+
+        Args:
+            filename ([type], optional): [description]. Defaults to None.
+            content ([type], optional): [description]. Defaults to None.
+            mimetype ([type], optional): [description]. Defaults to None.
         """
+        
         if isinstance(filename, MIMEBase):
             assert content == mimetype == None
             self.related_attachments.append(filename)

webservice/lib/utils/general.py

@@ -2,25 +2,67 @@ import re
 import random
 import string
 
-def remove_html_tags(text):
-    """Remove html tags from a string"""
-    clean = re.compile('<.*?>')
-    return re.sub(clean, '', text)
-
-def get_random_int_value(length = 6):
-    return ''.join(list(map(lambda x: str(random.randint(1,9)), list(range(length)))))
-
-def get_random_string(length = 8):
-    return ''.join(random.choices(string.ascii_uppercase + string.digits + string.ascii_lowercase, k=length))
-
 def generate_encryption_key(length = 32):
+    """Generate a new encryption key of `length` chars. This is done by using the :func:`get_random_string` function with a default of 32 chars.
+
+    Args:
+        length (int, optional): The length in chars of the encryption key. Defaults to 32.
+
+    Returns:
+        str: A string of `length` chars.
+    """
     return get_random_string(length)
 
 def get_ip_address(request):
-    """ use requestobject to fetch client machine's IP Address """
+    """Get the IP address of the requesting viewer. This is done by looking into the following variables in the headers.
+
+     1. HTTP_X_FORWARDED_FOR
+     2. REMOTE_ADDR
+
+    Args:
+        request (BaseRequest): The Django request.
+
+    Returns:
+        str: IP address of the request
+    """
     x_forwarded_for = request.META.get('HTTP_X_FORWARDED_FOR', None)
     if x_forwarded_for:
         ip = x_forwarded_for.split(',')[0]
     else:
         ip = request.META.get('REMOTE_ADDR')    ### Real IP address of client Machine
-    return ip
+    return ip
+
+def get_random_int_value(length = 6):
+    """Generate a random number of `length` length numbers.
+
+    Args:
+        length (int, optional): The length of the random number in amount of numbers. Defaults to 6.
+
+    Returns:
+        int: Returns a random number of 'length' numbers.
+    """
+    return int(''.join(list(map(lambda x: str(random.randint(1,9)), list(range(length))))))
+
+def get_random_string(length = 8):
+    """Generate a random string of `length` length characters.
+
+    Args:
+        length (int, optional): The length of the random string in amount of characters. Defaults to 8.
+
+    Returns:
+        str: Returns a random string of 'length' characters.
+    """
+    return ''.join(random.choices(string.ascii_uppercase + string.digits + string.ascii_lowercase, k=length))
+
+def remove_html_tags(text):
+    """Remove HTML tags and code from the input text
+
+    Args:
+        text (str): Input text to be cleaned from HTML
+
+    Returns:
+        str: Cleaned HTML.
+    """
+
+    clean = re.compile('<.*?>')
+    return re.sub(clean, '', text)