[IMP] Improve documentation & compat with Sphinx

red_october/__init__.py

@@ -2,4 +2,28 @@
 # Copyright 2016 LasLabs Inc.
 # License MIT (https://opensource.org/licenses/MIT).
 
+""" This library allows you to interact with a remote Red October Instance using Python.
+
+Red October is a cryptographically-secure implementation of the two-person rule to
+protect sensitive data. From a technical perspective, Red October is a software-based
+encryption and decryption server. The server can be used to encrypt a payload in such
+a way that no one individual can decrypt it. The encryption of the payload is
+cryptographically tied to the credentials of the authorized users.
+
+Authorized persons can delegate their credentials to the server for a period of time.
+The server can decrypt any previously-encrypted payloads as long as the appropriate number
+of people have delegated their credentials to the server.
+
+This architecture allows Red October to act as a convenient decryption service. Other
+systems, including CloudFlare’s build system, can use it for decryption and users can
+delegate their credentials to the server via a simple web interface. All communication
+with Red October is encrypted with TLS, ensuring that passwords are not sent in the clear.
+
+* `Read more on the CloudFlare blog
+  <https://blog.cloudflare.com/red-october-cloudflares-open-source-implementation-of-the-two-man-rule/>`_.
+* `View the Red October source
+  <https://github.com/cloudflare/redoctober>`_.
+"""
+
+
 from .red_october import RedOctober

red_october/exceptions.py

@@ -8,8 +8,8 @@
 class RedOctoberException(EnvironmentError):
     """ This exception is raised from errors in the RedOctober Library. """
 
-class RedOctoberDecryptException(RedOctoberException):
-    """ This exception  is raised when there are errors decrypting a file. """
-
 class RedOctoberRemoteException(RedOctoberException):
     """ This exception is raised to indicate issues returned from API. """
+
+class RedOctoberDecryptException(RedOctoberRemoteException):
+    """ This exception is raised when there are errors decrypting a file. """

red_october/models/enum_user_role.py

@@ -6,7 +6,14 @@
 
 
 class EnumUserRole(Enum):
-    """ It provides possible user types. """
+    """ It provides possible user roles for Red October.
+
+    Attributes:
+        delete (int): User is deleted or scheduled to be so.
+        revoke (int): Normal user, revoke administrative rights.
+        admin (int): User has administrative rights.
+        user (int): Alias for `revoke`.
+    """
     delete = 1
     revoke = 2
     admin = 3

red_october/models/enum_user_type.py

@@ -6,6 +6,11 @@
 
 
 class EnumUserType(Enum):
-    """ It provides possible user types. """
+    """ It provides possible user encryption types for Red October.
+
+    Attributes:
+        rsa (int): Uses RSA encryption.
+        ecc (int): Uses ECC encruyption.
+    """
     rsa = 1
     ecc = 2

red_october/red_october.py

@@ -24,11 +24,11 @@ def __init__(self, host, port, name, password, ssl=True):
         """ It initializes the RedOctober API using the provided credentials.
 
         Args:
-            host: (str) Host name/IP of Red October server.
-            port: (int) Port number of server.
-            name: (str) Account name for use as login.
-            password: (str) Password for account.
-            ssl: (bool) Is server SSL encrypted?
+            host (str): Host name/IP of Red October server.
+            port (int): Port number of server.
+            name (str): Account name for use as login.
+            password (str): Password for account.
+            ssl (bool): Is server SSL encrypted?
         """
         ssl = 'https' if ssl else 'http'
         self.uri_base = '%s://%s:%d' % (ssl, host, port)
@@ -42,7 +42,7 @@ def create_vault(self):
         It creates an admin account.
 
         Returns:
-            (bool) Status of vault creation
+            bool: Status of vault creation
         """
         return self.call('create')
 
@@ -55,11 +55,11 @@ def delegate(self, time=None, uses=None):
         Any new delegation overrides the previous delegation.
 
         Args:
-            time: (datetime.timedelta) Period of time that delegation is valid
+            time (datetime.timedelta): Period of time that delegation is valid
                 for.
-            uses: (int) Number of times that delegation can be used.
+            uses (int): Number of times that delegation can be used.
         Returns:
-            (bool) Status of delegation creation.
+            bool: Status of delegation creation.
         """
         data = self._clean_mapping({
             'Time': time and '%ds' % time.total_seconds() or None,
@@ -75,10 +75,10 @@ def create_user(self, user_type='rsa'):
         and if none is provided will default to ``rsa``.
 
         Args:
-            user_type: (str) Controls how the record is encrypted. This can have
+            user_type (str): Controls how the record is encrypted. This can have
                 a value of either ``ecc`` or ``rsa``.
         Returns:
-            (bool) Status of user creation.
+            bool: Status of user creation.
         """
         data = self._clean_mapping({
             'UserType': EnumUserType[user_type].name.upper(),
@@ -89,7 +89,7 @@ def get_summary(self):
         """ It provides a list of keys and delegations for the server.
 
         Returns:
-            (dict) A mapping containing keys on the system, and users who have
+            dict: A mapping containing keys on the system, and users who have
                 currently delegated their key to the server. Example:
 
                 .. code-block:: python
@@ -122,13 +122,13 @@ def encrypt(self, minimum, owners, data):
         """ It allows a user to encrypt a piece of data.
 
         Args:
-            minimum: (int) Minimum number of users from ``owners`` set that
+            minimum (int): Minimum number of users from ``owners`` set that
                 must have delegated their keys to the server.
-            owners: (iter) Iterator of strings indicating users that may
+            owners (iter): Iterator of strings indicating users that may
                 decrypt the document.
-            data: (str) Data to encrypt.
+            data (str): Data to encrypt.
         Returns:
-            (str) Base64 encoded string representing the encrypted string.
+            str: Base64 encoded string representing the encrypted string.
         """
         data = self._clean_mapping({
             'Minimum': minimum,
@@ -141,14 +141,14 @@ def decrypt(self, data):
         """ It allows a user to decrypt a piece of data.
 
         Args:
-            data: (str) Base64 encoded string representing the encrypted
+            data (str): Base64 encoded string representing the encrypted
                 string.
         Raises:
             RedOctoberDecryptException: If not enough ``minimum`` users from
                 the set of ``owners`` have delegated their keys to the server,
                 or if the decryption credentials are incorrect.
         Returns:
-            (str) Decrypted string
+            str: Decrypted string
         """
         data = self._clean_mapping({
             'Data': data,
@@ -162,13 +162,13 @@ def get_owners(self, data):
         """ It provides the delegates required to decrypt a piece of data.
 
         Args:
-            data: (str) Base64 encoded string representing the encrypted
+            data (str): Base64 encoded string representing the encrypted
                 string.
         Raises:
             RedOctoberDecryptException: If incorrect decryption credentials
                 are provided.
         Returns:
-            (list) List of strings representing users that are able to decrypt
+            list: List of strings representing users that are able to decrypt
                 the data.
         """
         data = self._clean_mapping({
@@ -183,11 +183,11 @@ def change_password(self, new_password):
         """ It allows users to change their password.
 
         Args:
-            name: (str) Name of account.
-            password: (str) Password for account.
-            new_password: (str) New password for account.
+            name (str): Name of account.
+            password (str): Password for account.
+            new_password (str): New password for account.
         Returns:
-            (bool) Password change status.
+            bool: Password change status.
         """
         data = self._clean_mapping({
             'NewPassword': new_password,
@@ -198,13 +198,13 @@ def modify_user_role(self, modify_name, command='revoke'):
         """ It allows for administration of user roles.
 
         Args:
-            modify_name: (str) Name of account to modify.
-            command: (str) Command to apply to user:
+            modify_name (str): Name of account to modify.
+            command (str): Command to apply to user:
                 ``admin``: Promote user to administrator.
                 ``revoke``: Revoke administrator rights.
                 ``delete``: Delete user.
         Returns:
-            (bool) Role modfication status.
+            bool: Role modfication status.
         """
         data = self._clean_mapping({
             'ToModify': modify_name,
@@ -216,21 +216,21 @@ def purge_delegates(self):
         """ It deletes all delegates for an encryption key.
 
         Returns:
-            (bool) Purge status.
+            bool: Purge status.
         """
         return self.call('purge')
 
     def create_order(self, labels, duration, uses, data):
         """ It creates lets others users know delegations are needed.
 
         Args:
-            labels: (iter) Iterator of strings to label order with.
-            duration: (datetime.timedelta) Proposed duration of delegation.
-            uses: (int) Proposed delegation use amounts.
-            data: (str) Base64 encoded string representing the encrypted
+            labels (iter): Iterator of strings to label order with.
+            duration (datetime.timedelta): Proposed duration of delegation.
+            uses (int): Proposed delegation use amounts.
+            data (str): Base64 encoded string representing the encrypted
                 string.
         Returns:
-            (dict) Mapping representing the newly created order. Example:
+            dict: Mapping representing the newly created order. Example:
 
             .. code-block:: python
 
@@ -263,7 +263,7 @@ def get_orders_outstanding(self):
         """ It returns a mapping of current orders.
 
         Returns:
-            (dict) Mapping representing the currently open orders. Example:
+            dict: Mapping representing the currently open orders. Example:
 
             .. code-block:: python
 
@@ -286,9 +286,9 @@ def get_order_information(self, order_num):
         """ It gets information for a specified order.
 
         Args:
-            order_num: (str) Order number to get.
+            order_num (str): Order number to get.
         Returns:
-            (dict) Mapping representing the order information. Example:
+            dict: Mapping representing the order information. Example:
 
             .. code-block:: python
 
@@ -318,9 +318,9 @@ def cancel_order(self, order_num):
         """ It cancels an order by number.
 
         Args:
-            order_num: (str) Order number to get.
+            order_num (str): Order number to get.
         Returns:
-            (bool) Status of order cancellation.
+            bool: Status of order cancellation.
         """
         data = self._clean_mapping({
             'OrderNum': order_num,
@@ -331,19 +331,19 @@ def call(self, endpoint, method='POST', params=None, data=None):
         """ It calls the remote endpoint and returns the result, if success.
 
         Args:
-            endpoint: (str) RedOctober endpoint to call (e.g. ``newcert``).
-            method: (str) HTTP method to utilize for the Request.
+            endpoint (str): RedOctober endpoint to call (e.g. ``newcert``).
+            method (str): HTTP method to utilize for the Request.
             params: (dict|bytes) Data to be sent in the query string
                 for the Request.
             data: (dict|bytes|file) Data to send in the body of the
                 Request.
-        Returns:
-            (mixed) Data contained in ``result`` key of the API response, or
-                ``True`` if there was no response data, but the call was a
-                success.
         Raises:
             RedOctoberRemoteException: In the event of a ``False`` in the
                 ``success`` key of the API response.
+        Returns:
+            mixed: Data contained in ``result`` key of the API response, or
+                ``True`` if there was no response data, but the call was a
+                success.
         """
         endpoint = '%s/%s' % (self.uri_base, endpoint)
         if data:
@@ -371,5 +371,11 @@ def call(self, endpoint, method='POST', params=None, data=None):
             return True
 
     def _clean_mapping(self, mapping):
-        """ It removes false entries from mapping """
+        """ It removes false entries from mapping.
+
+        Args:
+            mapping (dict): Mapping to remove values from.
+        Returns:
+            dict: Mapping with no values evaluating to False.
+        """
         return {k:v for k, v in mapping.iteritems() if v}