Updated docs and command messages

Details:

* Switched from terms 'clear text' and 'unencrypted' to 'decrypted' and
  made the language in docstrings and messages mor clear to distinguish
  between states of the file and actions.

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

easy_vault/_easy_vault.py

@@ -75,7 +75,7 @@ class EasyVaultDecryptError(EasyVaultException):
 
 class EasyVaultEncryptError(EasyVaultException):
     """
-    Exception indicating that an unencrypted vault file could not be encrypted.
+    Exception indicating that a decrypted vault file could not be encrypted.
 
     Derived from :exc:`EasyVaultException`.
     """
@@ -107,13 +107,13 @@ class EasyVault(object):
     well suited for handling huge files. It is really meant for vault files:
     Files that keep secrets, but not huge data.
 
-    The password may be provided or not (`None`). If not provided, encryption
-    and decryption of the vault file is going to be rejected and access to the
-    data requires that the vault file is unencrypted. If the password is
-    provided, it is converted to a symmetric key which is then used for
-    encryption and decryption of the vault file and for decrypting the vault
-    file content upon access (the vault file in the file system remains
-    encrypted).
+    The password may be provided or not (`None`).
+    If the password is provided, it is converted to a symmetric key which is
+    then used for encrypting and decrypting the vault file itself and for
+    decrypting the vault file content upon access.
+    If the password is not provided, encryption and decryption of the vault file
+    is rejected and access to the vault file content requires that the vault
+    file is in the decrypted state.
 
     The encryption package used by this class is pluggable. The default
     implementation uses the symmetric key support from the
@@ -138,6 +138,9 @@ def __init__(self, filepath, password):
           password (:term:`unicode string`):
             Password for encrypting and decrypting the vault file, or `None`
             if not provided.
+
+        Raises:
+          TypeError
         """
         self._filepath = filepath
         if password is None:
@@ -206,7 +209,7 @@ def encrypt(self):
         """
         Encrypt the vault file.
 
-        The vault file must be unencrypted (i.e. not encrypted by easy-vault).
+        The vault file must be decrypted (i.e. not encrypted by easy-vault).
 
         This method requires a vault password to be provided.
 
@@ -267,10 +270,11 @@ def decrypt(self):
 
     def _get_bytes_from_encrypted(self):
         """
-        Get the data from an encrypted vault file.
+        Get the content of an encrypted vault file by decrypting the content
+        upon access and leaving the file unchanged.
 
         Returns:
-          :term:`byte string`: Unencrypted data from the vault file.
+          :term:`byte string`: Decrypted content of the vault file.
 
         Raises:
           EasyVaultFileError: I/O error with the vault file
@@ -311,10 +315,10 @@ def _get_bytes_from_encrypted(self):
 
     def _get_bytes_from_clear(self):
         """
-        Get the data from an unencrypted vault file.
+        Get the content of a decrypted vault file.
 
         Returns:
-          :term:`byte string`: Unencrypted data from the vault file.
+          :term:`byte string`: Decrypted content of the vault file.
 
         Raises:
           EasyVaultFileError: I/O error with the vault file
@@ -332,15 +336,16 @@ def _get_bytes_from_clear(self):
 
     def get_bytes(self):
         """
-        Get the unencrypted content of the vault file as a Byte sequence.
+        Get the decrypted content of the vault file as a Byte sequence.
 
-        The vault file may be encrypted or unencrypted.
+        The vault file may be in the encrypted or decrypted state and remains
+        unchanged.
 
-        If the vault file is encrypted, this method requires a vault password
-        to be provided, otherwise it does not.
+        If the vault file is in the encrypted state, the object this method
+        is called on must have been created with a vault password.
 
         Returns:
-          :term:`byte string`: Unencrypted content of the vault file, as a Byte
+          :term:`byte string`: Decrypted content of the vault file, as a Byte
           sequence.
 
         Raises:
@@ -353,15 +358,16 @@ def get_bytes(self):
 
     def get_text(self):
         """
-        Get the unencrypted content of the vault file as a Unicode string.
+        Get the decrypted content of the vault file as a Unicode string.
 
-        The vault file may be encrypted or unencrypted.
+        The vault file may be in the encrypted or decrypted state and remains
+        unchanged.
 
-        If the vault file is encrypted, this method requires a vault password
-        to be provided, otherwise it does not.
+        If the vault file is in the encrypted state, the object this method
+        is called on must have been created with a vault password.
 
         Returns:
-          :term:`unicode string`: Unencrypted content of the vault file, as a
+          :term:`unicode string`: Decrypted content of the vault file, as a
           Unicode string.
 
         Raises:
@@ -374,13 +380,14 @@ def get_text(self):
 
     def get_yaml(self):
         """
-        Get the unencrypted content of a YAML-formatted vault file as a YAML
+        Get the decrypted content of a YAML-formatted vault file as a YAML
         object.
 
-        The vault file may be encrypted or unencrypted.
+        The vault file may be in the encrypted or decrypted state and remains
+        unchanged.
 
-        If the vault file is encrypted, this method requires a vault password
-        to be provided, otherwise it does not.
+        If the vault file is in the encrypted state, the object this method
+        is called on must have been created with a vault password.
 
         Returns:
           dict or list: Top-level object of the YAML-formatted vault file.

easy_vault/_password.py

@@ -71,16 +71,12 @@ def get_password(
         password = keyringlib.get_password(filepath)
         if password is not None:
             if verbose:
-                echo("Using password from keyring service for vault file: {fn}".
-                     format(fn=filepath))
+                echo("Using password from keyring service")
             return password
 
     if use_prompting:
         password = getpass.getpass(
             "Enter password for vault file {fn}:".format(fn=filepath))
-        if verbose:
-            echo("Using prompted password for vault file: {fn}".
-                 format(fn=filepath))
         return password
 
     raise ValueError("use_keyring and use_prompt were both False")
@@ -127,11 +123,9 @@ def set_password(
         current_password = keyringlib.get_password(filepath)
         if current_password is None:
             if verbose:
-                echo("Setting new password in keyring service for vault "
-                     "file: {fn}".format(fn=filepath))
+                echo("Setting new password in keyring service")
             keyringlib.set_password(filepath, password)
         elif password != current_password:
             if verbose:
-                echo("Updating password in keyring service for vault "
-                     "file: {fn}".format(fn=filepath))
+                echo("Updating password in keyring service")
             keyringlib.set_password(filepath, password)

examples/show_vault.py

@@ -26,7 +26,7 @@ def main():
     """Main function"""
 
     if len(sys.argv) < 2:
-        print("Show content of a vault file.")
+        print("Show content of a YAML vault file.")
         print("Usage: {} vaultfile".format(sys.argv[0]))
         sys.exit(2)
 
@@ -40,8 +40,9 @@ def main():
     password = easy_vault.get_password(vault_file)
     vault = easy_vault.EasyVault(vault_file, password)
     try:
-        encrypted = "encrypted" if vault.is_encrypted() else "unencrypted"
-        print("Vault file {fn} is {e}".format(fn=vault_file, e=encrypted))
+        encrypted = "encrypted" if vault.is_encrypted() else "decrypted"
+        print("Vault file {fn} is in {e} state".
+              format(fn=vault_file, e=encrypted))
         vault_obj = vault.get_yaml()
     except easy_vault.EasyVaultException as exc:
         print("Error: {}".format(exc))