Docs: Improved documentation of exceptions

Signed-off-by: Andreas Maier <andreas.r.maier@gmx.de>

docs/conf.py

@@ -485,7 +485,7 @@ def get_version(version_file):
 #       to datatypes of function parameters can be controlled.
 #
 intersphinx_mapping = {
-  'py': ('https://docs.python.org/2/', None), # agnostic to Python version
+  'py': ('https://docs.python.org/3/', None), # default Python version
   'py2': ('https://docs.python.org/2', None), # specific to Python 2
   'py3': ('https://docs.python.org/3', None), # specific to Python 3
   'keyring': ('https://keyring.readthedocs.io/en/stable', None),

easy_vault/_easy_vault.py

@@ -50,7 +50,7 @@ class EasyVaultException(Exception):
     Base exception for all exceptions raised by the
     :class:`~easy_vault.EasyVault` class.
 
-    Derived from :exc:`py:Exception`.
+    Derived from :exc:`~py:Exception`.
     """
     pass
 
@@ -141,7 +141,8 @@ def __init__(self, filepath, password=None):
             if not provided.
 
         Raises:
-          TypeError
+          TypeError: Type error in arguments or in return of pluggable
+            encryption function.
         """
         self._filepath = filepath
         if password is None:
@@ -187,7 +188,7 @@ def is_encrypted(self):
           easy-vault.
 
         Raises:
-          EasyVaultFileError: I/O error with the vault file
+          :exc:`EasyVaultFileError`: I/O error with the vault file.
         """
         try:
             with open(self._filepath, 'rb') as fp:
@@ -216,8 +217,9 @@ def encrypt(self):
         This method requires a vault password to be provided.
 
         Raises:
-          EasyVaultFileError: I/O error with the vault file or a temporary file
-          EasyVaultEncryptError: Error encrypting the vault file
+          :exc:`EasyVaultFileError`: I/O error with the vault file or a
+            temporary file.
+          :exc:`EasyVaultEncryptError`: Error encrypting the vault file.
         """
         if not self.password_provided:
             raise EasyVaultEncryptError(
@@ -266,8 +268,9 @@ def decrypt(self):
         This method requires a vault password to be provided.
 
         Raises:
-          EasyVaultFileError: I/O error with the vault file or a temporary file
-          EasyVaultDecryptError: Error decrypting the vault file
+          :exc:`EasyVaultFileError`: I/O error with the vault file or a
+            temporary file.
+          :exc:`EasyVaultDecryptError`: Error decrypting the vault file.
         """
         clear_bdata = self._get_bytes_from_encrypted()
         write_file(self._filepath, clear_bdata)
@@ -281,8 +284,8 @@ def _get_bytes_from_encrypted(self):
           :term:`byte string`: Decrypted content of the vault file.
 
         Raises:
-          EasyVaultFileError: I/O error with the vault file
-          EasyVaultDecryptError: Error decrypting the vault file
+          :exc:`EasyVaultFileError`: I/O error with the vault file.
+          :exc:`EasyVaultDecryptError`: Error decrypting the vault file.
         """
         if not self.password_provided:
             raise EasyVaultDecryptError(
@@ -327,7 +330,7 @@ def _get_bytes_from_clear(self):
           :term:`byte string`: Decrypted content of the vault file.
 
         Raises:
-          EasyVaultFileError: I/O error with the vault file
+          :exc:`EasyVaultFileError`: I/O error with the vault file.
         """
         try:
             with open(self._filepath, 'rb') as fp:
@@ -355,8 +358,8 @@ def get_bytes(self):
           sequence.
 
         Raises:
-          EasyVaultFileError: I/O error with the vault file
-          EasyVaultDecryptError: Error decrypting the vault file
+          :exc:`EasyVaultFileError`: I/O error with the vault file.
+          :exc:`EasyVaultDecryptError`: Error decrypting the vault file.
         """
         if self.is_encrypted():
             return self._get_bytes_from_encrypted()
@@ -377,8 +380,8 @@ def get_text(self):
           Unicode string.
 
         Raises:
-          EasyVaultFileError: I/O error with the vault file
-          EasyVaultDecryptError: Error decrypting the vault file
+          :exc:`EasyVaultFileError`: I/O error with the vault file.
+          :exc:`EasyVaultDecryptError`: Error decrypting the vault file.
         """
         bdata = self.get_bytes()
         udata = bdata.decode('utf-8')
@@ -399,9 +402,10 @@ def get_yaml(self):
           dict or list: Top-level object of the YAML-formatted vault file.
 
         Raises:
-          EasyVaultFileError: I/O error with the vault file or a temporary file
-          EasyVaultYamlError: YAML syntax error in the vault file
-          EasyVaultDecryptError: Error decrypting the vault file
+          :exc:`EasyVaultFileError`: I/O error with the vault file or a
+            temporary file.
+          :exc:`EasyVaultYamlError`: YAML syntax error in the vault file.
+          :exc:`EasyVaultDecryptError`: Error decrypting the vault file.
         """
         clear_bdata = self.get_bytes()
         try:
@@ -491,7 +495,7 @@ def decrypt_data(self, encrypted_data, key):
           :term:`byte string`: The clear data.
 
         Raises:
-          EasyVaultDecryptError: Error decrypting the vault file
+          :exc:`EasyVaultDecryptError`: Error decrypting the vault file.
         """
         f = Fernet(key)
         try:
@@ -524,7 +528,7 @@ def write_file(filepath, data):
         The data to be written.
 
     Raises:
-      EasyVaultFileError: I/O error with the file
+      :exc:`EasyVaultFileError`: I/O error with the file.
     """
     assert isinstance(data, six.binary_type), type(data)
     try:

easy_vault/_key_ring_lib.py

@@ -43,7 +43,7 @@ class KeyRingException(Exception):
     Base exception for all exceptions raised by the
     :class:`~easy_vault.KeyRingLib` class.
 
-    Derived from :exc:`py:Exception`.
+    Derived from :exc:`~py:Exception`.
     """
     pass
 
@@ -77,13 +77,6 @@ class KeyRingLib(object):
     The keyring items that are created have a fixed service/app name that
     starts with 'easy_vault'. There is one keyring item for each vault file.
 
-    If no keyring service is available that is recognized by the
-    keyring package, the :exc:`keyring:keyring.errors.NoKeyringError` exception
-    is raised starting with keyring version 22.0, or the standard Python
-    RuntimeError before that keyring version. Other errors with the keyring
-    servive will be raised as exceptions that are derived from the
-    :exc:`keyring:keyring.errors.KeyringError` base exception class.
-
     For details on the keyring service, see section :ref:`Keyring service`.
     """
 

easy_vault/_password.py

@@ -37,14 +37,6 @@ def get_password(
     is disabled and the keyring service did not have an item for the vault file
     stored.
 
-    If the use of the keyring service is enabled, but no keyring service is
-    available that is recognized by the keyring package, the
-    :exc:`keyring:keyring.errors.NoKeyringError` exception is raised starting
-    with keyring version 22.0, or the standard Python RuntimeError before
-    that keyring version. Other errors with the keyring servive will be raised
-    as exceptions that are derived from the
-    :exc:`keyring:keyring.errors.KeyringError` base exception class.
-
     This is a convenience function that uses the password methods of the
     :class:`~easy_vault.KeyRingLib` class.
 
@@ -70,11 +62,10 @@ def get_password(
       :term:`unicode string`: Password for the vault file, or `None`.
 
     Raises:
-      ValueError: use_keyring and use_prompt were both False
-      :exc:`keyring:keyring.errors.NoKeyringError` or RuntimeError:
-        No keyring service available
-      :exc:`keyring:keyring.errors.KeyringError`: Base class for errors with
-        the keyring service
+      ValueError: Use of keyring service and use of password prompting were
+        both disabled.
+      :exc:`KeyRingNotAvailable`: No keyring service available.
+      :exc:`KeyRingError`: An error happend in the keyring service.
     """
     password = None
 
@@ -105,14 +96,6 @@ def set_password(
     For consistency with :func:`get_password`, the use of the keyring service
     can be disabled, in which case the function does nothing.
 
-    If the use of the keyring service is enabled, but no keyring service is
-    available that is recognized by the keyring package, the
-    :exc:`keyring:keyring.errors.NoKeyringError` exception is raised starting
-    with keyring version 22.0, or the standard Python RuntimeError before
-    that keyring version. Other errors with the keyring servive will be raised
-    as exceptions that are derived from the
-    :exc:`keyring:keyring.errors.KeyringError` base exception class.
-
     This is a convenience function that uses the password methods of the
     :class:`~easy_vault.KeyRingLib` class.
 
@@ -136,10 +119,8 @@ def set_password(
         Print function to be used for the additional messages in verbose mode.
 
     Raises:
-      :exc:`keyring:keyring.errors.NoKeyringError` or RuntimeError:
-        No keyring service available
-      :exc:`keyring:keyring.errors.KeyringError`: Base class for errors with
-        the keyring service
+      :exc:`KeyRingNotAvailable`: No keyring service available.
+      :exc:`KeyRingError`: An error happend in the keyring service.
     """
     if use_keyring:
         keyringlib = KeyRingLib()