Updated usage chapter, examples; fixed error

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

README.rst

@@ -21,30 +21,39 @@ secure-server-access - Secure Server Access
 Overview
 --------
 
-The **secure-server-access** package is a library for retrieving the information
-needed for accessing servers (or service), such as IP address, logon credentials,
-or informal information such as contact name or which network to use.
-
-The information for accessing the servers is divided into an open part that is
-defined in a *server definition file*, and a protected part containing the
-secrets for the actual access that is defined in a *vault file*. The vault file
-can be encrypted and decrypted using the ``easy-vault`` command provided by the
+The **secure-server-access** package is a Python library for securely defining
+sensitive information for accessing servers (or services), such as IP address,
+logon credentials.
+
+The information for accessing the servers is divided into an general portion
+that is defined in an openly accessible *server definition file*, and
+a sensitive portion that is defined in an encrypted *vault file*.
+
+The vault file must be an "easy-vault" file and can be encrypted and decrypted
+using the ``easy-vault`` command provided by the
 `easy-vault <https://easy-vault.readthedocs.io/en/latest/>`_ package.
+The vault file defines the secrets needed to access the servers, such as
+passwords or API keys. The "easy-vault" files remain encrypted in the file
+system while their content is used to access the servers.
+
+The server definition file defines general information about the servers, such
+as a short description, contact name, or a reminder which network to use for
+accessing them.
 
-The server definition file defines nicknames for the servers and allows grouping
-them into groups that also have nicknames.
+The link between the server items defined in the server definition file and
+the vault file are user-defined nicknames for the servers. These nicknames
+can also used by users as a convenient way to identify servers in commands.
 
-The **secure-server-access** package is not used by end users, but by programs
-that integrate with it, such as test programs or command line clients that
-access servers or services. The users of these programs can then access
-servers or services by means of the server and group nicknames that are defined.
+The server definition files support the definition of server groups that
+also have a nickname.
 
-The secrets needed to access the servers remain in the vault file which remains
-encrypted in teh file system while the server is accessed.
+Typical use cases for the **secure-server-access** package are test programs
+running end-to-end tests against real servers, or command line clients that
+access servers or services.
 
-This provides a convenient, flexible and secure way how your Python programs
-can retrieve the secrets needed for accessing servers or services, while
-protecting these secrets in a secure way.
+This provides a convenient, flexible and secure way how Python programs can
+retrieve the secrets needed for accessing servers or services, while protecting
+these secrets in a secure way.
 
 
 .. _`Documentation and change log`:

docs/api.rst

@@ -16,19 +16,13 @@
 API Reference
 =============
 
-This section describes the API of the **secure-server-access** package.
+This section describes the Python API of the **secure-server-access** package.
+The API is kept stable using the compatibility rules defined for
+`semantic versioning <https://semver.org/>`_. An exception to this rule
+are fixes for security issues.
 
-
-.. _`VaultFile class`:
-
-VaultFile class
----------------
-
-.. autoclass:: secure_server_access.VaultFile
-    :members:
-    :autosummary:
-    :autosummary-inherited-members:
-    :special-members: __str__
+Any functions not described in this section are considered internal and may
+change incompatibly without warning.
 
 
 .. _`ServerDefinitionFile class`:
@@ -55,36 +49,48 @@ ServerDefinition class
     :special-members: __str__
 
 
+.. _`VaultFile class`:
+
+VaultFile class
+---------------
+
+.. autoclass:: secure_server_access.VaultFile
+    :members:
+    :autosummary:
+    :autosummary-inherited-members:
+    :special-members: __str__
+
+
 .. _`Exception classes`:
 
 Exception classes
 -----------------
 
-.. autoclass:: secure_server_access.VaultFileException
+.. autoclass:: secure_server_access.ServerDefinitionFileException
     :members:
     :special-members: __str__
 
-.. autoclass:: secure_server_access.VaultFileOpenError
+.. autoclass:: secure_server_access.ServerDefinitionFileOpenError
     :members:
     :special-members: __str__
 
-.. autoclass:: secure_server_access.VaultFileDecryptError
+.. autoclass:: secure_server_access.ServerDefinitionFileFormatError
     :members:
     :special-members: __str__
 
-.. autoclass:: secure_server_access.VaultFileFormatError
+.. autoclass:: secure_server_access.VaultFileException
     :members:
     :special-members: __str__
 
-.. autoclass:: secure_server_access.ServerDefinitionFileException
+.. autoclass:: secure_server_access.VaultFileOpenError
     :members:
     :special-members: __str__
 
-.. autoclass:: secure_server_access.ServerDefinitionFileOpenError
+.. autoclass:: secure_server_access.VaultFileDecryptError
     :members:
     :special-members: __str__
 
-.. autoclass:: secure_server_access.ServerDefinitionFileFormatError
+.. autoclass:: secure_server_access.VaultFileFormatError
     :members:
     :special-members: __str__
 

docs/appendix.rst

@@ -36,32 +36,6 @@ Glossary
        :class:`py3:bytes` in Python 3). Unless otherwise
        indicated, byte strings in this project are always UTF-8 encoded.
 
-    number
-       one of the number types :class:`py:int`, :class:`py2:long` (Python 2
-       only), or :class:`py:float`.
-
-    integer
-       one of the integer types :class:`py:int` or :class:`py2:long` (Python 2
-       only).
-
-    callable
-       a callable object; for example a function, a class (calling it returns a
-       new object of the class), or an object with a :meth:`~py:object.__call__`
-       method.
-
-    hashable
-       a hashable object. Hashability requires an object not only to be able to
-       produce a hash value with the :func:`py:hash` function, but in addition
-       that objects that are equal (as per the ``==`` operator) produce equal
-       hash values, and that the produced hash value remains unchanged across
-       the lifetime of the object. See `term "hashable"
-       <https://docs.python.org/3/glossary.html#term-hashable>`_
-       in the Python glossary, although the definition there is not very crisp.
-       A more exhaustive discussion of these requirements is in
-       `"What happens when you mess with hashing in Python"
-       <https://www.asmeurer.com/blog/posts/what-happens-when-you-mess-with-hashing-in-python/>`_
-       by Aaron Meurer.
-
 
 .. _`References`:
 
@@ -70,12 +44,6 @@ References
 
 .. glossary::
 
-    Pytest
-      `Pytest <https://docs.pytest.org/en/stable/>`_
-
-    Pytest fixtures
-      `Pytest Fixtures <https://docs.pytest.org/en/stable/fixture.html>`_
-
     Python glossary
       * `Python 2.7 Glossary <https://docs.python.org/2.7/glossary.html>`_
-      * `Python 3.4 Glossary <https://docs.python.org/3.4/glossary.html>`_
+      * `Python 3.9 Glossary <https://docs.python.org/3.9/glossary.html>`_

docs/index.rst

@@ -14,30 +14,39 @@
 secure-server-access - Secure Server Access
 *******************************************
 
-The **secure-server-access** package is a library for retrieving the information
-needed for accessing servers (or service), such as IP address, logon credentials,
-or informal information such as contact name or which network to use.
-
-The information for accessing the servers is divided into an open part that is
-defined in a *server definition file*, and a protected part containing the
-secrets for the actual access that is defined in a *vault file*. The vault file
-can be encrypted and decrypted using the ``easy-vault`` command provided by the
+The **secure-server-access** package is a Python library for securely defining
+sensitive information for accessing servers (or services), such as IP address,
+logon credentials.
+
+The information for accessing the servers is divided into an general portion
+that is defined in an openly accessible *server definition file*, and
+a sensitive portion that is defined in an encrypted *vault file*.
+
+The vault file must be an "easy-vault" file and can be encrypted and decrypted
+using the ``easy-vault`` command provided by the
 `easy-vault <https://easy-vault.readthedocs.io/en/latest/>`_ package.
+The vault file defines the secrets needed to access the servers, such as
+passwords or API keys. The "easy-vault" files remain encrypted in the file
+system while their content is used to access the servers.
+
+The server definition file defines general information about the servers, such
+as a short description, contact name, or a reminder which network to use for
+accessing them.
 
-The server definition file defines nicknames for the servers and allows grouping
-them into groups that also have nicknames.
+The link between the server items defined in the server definition file and
+the vault file are user-defined nicknames for the servers. These nicknames
+can also used by users as a convenient way to identify servers in commands.
 
-The **secure-server-access** package is not used by end users, but by programs
-that integrate with it, such as test programs or command line clients that
-access servers or services. The users of these programs can then access
-servers or services by means of the server and group nicknames that are defined.
+The server definition files support the definition of server groups that
+also have a nickname.
 
-The secrets needed to access the servers remain in the vault file which remains
-encrypted in teh file system while the server is accessed.
+Typical use cases for the **secure-server-access** package are test programs
+running end-to-end tests against real servers, or command line clients that
+access servers or services.
 
-This provides a convenient, flexible and secure way how your Python programs
-can retrieve the secrets needed for accessing servers or services, while
-protecting these secrets in a secure way.
+This provides a convenient, flexible and secure way how Python programs can
+retrieve the secrets needed for accessing servers or services, while protecting
+these secrets in a secure way.
 
 .. toctree::
    :maxdepth: 2