Doc updates; Renamed ServerDefinition to Server; renamed pytest opts

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

Makefile

@@ -558,11 +558,11 @@ safety_$(python_pymn_version).done: develop_reqs_$(python_pymn_version).done Mak
 test: develop
 ifeq ($(python_mn_version),3.4)
 	@echo "Makefile: Running unit tests (without coverage)"
-	pytest --color=yes $(pytest_warning_opts) $(pytest_opts) $(test_dir)/unittest -s --es-server-file $(test_dir)/unittest/server.yml --es-vault-file $(test_dir)/unittest/vault.yml
+	pytest --color=yes $(pytest_warning_opts) $(pytest_opts) $(test_dir)/unittest -s --es-file $(test_dir)/unittest/es_server.yml
 	@echo "Makefile: Done running unit tests (without coverage)"
 else
 	@echo "Makefile: Running unit tests (with coverage)"
-	coverage run --source=$(package_name) --rcfile=.coveragerc -m pytest --color=yes $(pytest_warning_opts) $(pytest_opts) $(test_dir)/unittest -s --es-server-file $(test_dir)/unittest/server.yml --es-vault-file $(test_dir)/unittest/vault.yml
+	coverage run --source=$(package_name) --rcfile=.coveragerc -m pytest --color=yes $(pytest_warning_opts) $(pytest_opts) $(test_dir)/unittest -s --es-file $(test_dir)/unittest/es_server.yml
 	coverage report --rcfile=.coveragerc
 	@echo "Makefile: Done running unit tests (with coverage)"
 endif

README.rst

@@ -23,31 +23,25 @@ pytest-easy-server - Pytest plugin for easy testing against servers
 Overview
 --------
 
-The **pytest-easy-server** package is a
-`Pytest <https://docs.pytest.org/en/stable/>`_ plugin that provides a
-:func:`~pytest_easy_server.server_definition` fixture that resolves to the set
-of servers the tests should run against.
+The **pytest-easy-server** package is a `Pytest`_ plugin that provides a
+`Pytest fixture`_ fixture `es_server`_ that resolves
+to the set of servers the tests should run against.
 
-The set of servers is defined in a *server definition file* and the secrets
-to access the servers are defined in a *vault file* in the formats defined
-by the
-`easy-server package <https://easy-server.readthedocs.io/en/stable/>`_.
+The set of servers is defined in a *server file* and the secrets to access the
+servers are defined in a *vault file* that is referenced by the server file,
+in the formats defined by the `easy-server package`_.
 
 The files to use and the server or group nickname to select for the test
 can be specified in pytest options added by the plugin:
 
 .. code-block:: text
 
-    --es-server-file=FILE   Use the specified server definition file.
-                            Default: server.yml in current directory.
-
-    --es-vault-file=FILE    Use the specified vault file.
-                            Default: vault.yml in current directory.
-
-    --es-nickname=NICKNAME  Use the server or server group with this
-                            nickname to test against.
-                            Default: default server or server group
-                            specified in the server definition file.
+    --es-file=FILE
+                            Path name of the easy-server file to be used.
+                            Default: es_server.yml in current directory.
+    --es-nickname=NICKNAME
+                            Nickname of the server or server group to test against.
+                            Default: The default from the server file.
 
 
 .. _`Documentation and change log`:
@@ -70,10 +64,7 @@ The pytest-easy-server project is provided under the
 
 .. _`Pytest`: https://docs.pytest.org/en/stable/
 .. _`Pytest fixture`: https://docs.pytest.org/en/stable/fixture.html
-.. _`Format of server definition file`: https://pytest-easy-server.readthedocs.io/en/latest/usage.html#format-of-server-definition-file
-.. _`Protecting secrets`: https://pytest-easy-server.readthedocs.io/en/latest/usage.html#protecting-secrets
-.. _`Derived Pytest fixtures`: https://pytest-easy-server.readthedocs.io/en/latest/usage.html#derived-pytest-fixtures
-.. _`server_definition`: https://pytest-easy-server.readthedocs.io/en/latest/api.html#server-definition-fixture
-.. _`ServerDefinition`: https://pytest-easy-server.readthedocs.io/en/latest/api.html#serverdefinition-class
-.. _`Documentation`: https://pytest-easy-server.readthedocs.io/en/latest/
-.. _`Change log`: https://pytest-easy-server.readthedocs.io/en/latest/changes.html
+.. _`easy-server package`: https://easy-server.readthedocs.io/en/stable/
+.. _`es_server`: https://pytest-easy-server.readthedocs.io/en/stable/api.html#es-server-fixture
+.. _`Documentation`: https://pytest-easy-server.readthedocs.io/en/stable/
+.. _`Change log`: https://pytest-easy-server.readthedocs.io/en/stable/changes.html

docs/api.rst

@@ -25,12 +25,12 @@ Any functions not described in this section are considered internal and may
 change incompatibly without warning.
 
 
-.. _`server_definition fixture`:
+.. _`es_server fixture`:
 
-server_definition fixture
--------------------------
+es_server fixture
+-----------------
 
-.. autofunction:: pytest_easy_server.server_definition
+.. autofunction:: pytest_easy_server.es_server
 
 
 .. _`Package version`:

docs/conf.py

@@ -493,7 +493,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
   'easy_vault': ('https://easy-vault.readthedocs.io/en/stable/', None),

docs/index.rst

@@ -14,31 +14,25 @@
 pytest-easy-server - Pytest plugin for easy testing against servers
 *******************************************************************
 
-The **pytest-easy-server** package is a
-`Pytest <https://docs.pytest.org/en/stable/>`_ plugin that provides a
-:func:`~pytest_easy_server.server_definition` fixture that resolves to the set
-of servers the tests should run against.
+The **pytest-easy-server** package is a `Pytest`_ plugin that provides a
+`Pytest fixture`_ fixture :func:`~pytest_easy_server.es_server` that resolves
+to the set of servers the tests should run against.
 
-The set of servers is defined in a *server definition file* and the secrets
-to access the servers are defined in a *vault file* in the formats defined
-by the
-`easy-server package <https://easy-server.readthedocs.io/en/stable/>`_.
+The set of servers is defined in a *server file* and the secrets to access the
+servers are defined in a *vault file* that is referenced by the server file,
+in the formats defined by the `easy-server package`_.
 
 The files to use and the server or group nickname to select for the test
 can be specified in pytest options added by the plugin:
 
 .. code-block:: text
 
-    --es-server-file=FILE   Use the specified server definition file.
-                            Default: server.yml in current directory.
-
-    --es-vault-file=FILE    Use the specified vault file.
-                            Default: vault.yml in current directory.
-
-    --es-nickname=NICKNAME  Use the server or server group with this
-                            nickname to test against.
-                            Default: default server or server group
-                            specified in the server definition file.
+    --es-file=FILE
+                            Path name of the easy-server file to be used.
+                            Default: es_server.yml in current directory.
+    --es-nickname=NICKNAME
+                            Nickname of the server or server group to test against.
+                            Default: The default from the server file.
 
 
 .. toctree::
@@ -50,3 +44,10 @@ can be specified in pytest options added by the plugin:
    development.rst
    appendix.rst
    changes.rst
+
+
+.. # Links to documentation:
+
+.. _`Pytest`: https://docs.pytest.org/en/stable/
+.. _`Pytest fixture`: https://docs.pytest.org/en/stable/fixture.html
+.. _`easy-server package`: https://easy-server.readthedocs.io/en/stable/

docs/usage.rst

@@ -50,14 +50,14 @@ its version, e.g.:
     plugins: easy-server-0.5.0
 
 
-.. _`Server definition file and vault file`:
+.. _`Server file and vault file`:
 
-Server definition file and vault file
--------------------------------------
+Server file and vault file
+--------------------------
 
-The server definition file define the servers, server groups and a default
+The server file define the servers, server groups and a default
 server or group. It is described in the "easy-server" documentation in section
-`Server definition files <https://easy-server.readthedocs.io/en/stable/usage.html#server-definition-files>`_.
+`Server files <https://easy-server.readthedocs.io/en/stable/usage.html#server-files>`_.
 
 The vault file defines the secrets needed to access the servers and can stay
 encrypted in the file system while being used. It is described in the
@@ -67,61 +67,61 @@ encrypted in the file system while being used. It is described in the
 The servers and groups are identified with user-defined nicknames.
 
 
-.. _`Using the server_definition fixture`:
+.. _`Using the es_server fixture`:
 
-Using the server_definition fixture
------------------------------------
+Using the es_server fixture
+----------------------------------
 
-If your pytest test function uses the :func:`~pytest_easy_server.server_definition`
+If your pytest test function uses the :func:`~pytest_easy_server.es_server`
 fixture, the test function will be invoked for the server specified in the
 ``--es-nickname`` command line option, or the set of servers if the specified
 nickname is that of a server group.
 
 From a perspective of the test function that is invoked, the fixture resolves
-to a single server definition.
+to a single server item.
 
 The following example shows a test function using this fixture and how it gets
 to the details for accessing the server:
 
 .. code-block:: python
 
-    from pytest_easy_server import server_definition
+    from pytest_easy_server import es_server
 
-    def test_sample(server_definition):
+    def test_sample(es_server):
         """
         Example Pytest test function that tests something.
 
         Parameters:
-          server_definition (ServerDefinition): Server to be used for the test
+          es_server (Server): Server to be used for the test
         """
 
-        # Standard properties from the server definition file:
-        nickname = server_definition.nickname
-        description = server_definition.description
+        # Standard properties from the server file:
+        nickname = es_server.nickname
+        description = es_server.description
 
-        # User-defined additional properties from the server definition file:
-        stuff = server_definition.user_defined['stuff']
+        # User-defined additional properties from the server file:
+        stuff = es_server.user_defined['stuff']
 
         # User-defined secrets from the vault file:
-        host = server_definition.secrets['host']
-        username = server_definition.secrets['username']
-        password = server_definition.secrets['password']
+        host = es_server.secrets['host']
+        username = es_server.secrets['username']
+        password = es_server.secrets['password']
 
         # Log on to the host and perform some test
         . . .
 
 The example shows how to access the standard and user-defined properties
-from the server definition file for demonstration purposes. The data structure
-of the user-defined properties in the server definition file and of the secrets
+from the server file for demonstration purposes. The data structure
+of the user-defined properties in the server file and of the secrets
 in the vault file is completely up to you, so you could decide to have the host
-and userid in user-defined properties in the server definition file, and have
+and userid in user-defined properties in the server file, and have
 only the password in the vault file.
 
-The ``server_definition`` parameter of the test function is a
-:class:`easy_server:easy_server.ServerDefinition` object that represents a
-server definition from the file for test of a single server.
+The ``es_server`` parameter of the test function is a
+:class:`easy_server:easy_server.Server` object that represents a
+server item from the server file for testing against a single server.
 
-An example server definition file that provides the user-defined properties
+An example server file that provides the user-defined properties
 used in the test function shown above would be:
 
 .. code-block:: yaml
@@ -177,22 +177,18 @@ Controlling which servers to test against
 
 When pytest loads the pytest-easy-server plugin, its set of command line options
 gets extended by those contributed by the plugin. These options allow
-controlling which server definition file is used and wich server or server
+controlling which server file is used and wich server or server
 group is used to test against. These options are optional and have sensible
 defaults:
 
 .. code-block:: text
 
-    --es-server-file=FILE   Use the specified server definition file.
-                            Default: server.yml in current directory.
-
-    --es-vault-file=FILE    Use the specified vault file.
-                            Default: vault.yml in current directory.
-
-    --es-nickname=NICKNAME  Use the server or server group with this
-                            nickname to test against.
-                            Default: default server or server group
-                            specified in the server definition file.
+    --es-file=FILE
+                            Path name of the easy-server file to be used.
+                            Default: es_server.yml in current directory.
+    --es-nickname=NICKNAME
+                            Nickname of the server or server group to test against.
+                            Default: The default from the server file.
 
 
 .. _`Protecting secrets`:
@@ -210,8 +206,6 @@ the file system. The functionality also works if the vault file is not
 encrypted, but the normal case should be that you keep it encrypted. If you
 store the vault file in a repository, make sure it is encrypted.
 
-**TODO: Add functionality to warn or error out if the vault file is not encrypted.**
-
 The vault password is protected in the following ways:
 
 * For local use on your system, you are prompted for the vault password upon
@@ -234,9 +228,8 @@ on your local system.
 Derived Pytest fixtures
 -----------------------
 
-If using the server definition in your test functions includes the same boiler
-plate code for opening a session with the server, this can be put into a
-second derived fixture.
+If using the es_server fixture in your test functions repeats boiler plate code
+for opening a session with the server, this can be put into a derived fixture.
 
 The following fixture is an example for that. It opens and closes a
 session with a server using a fictitious class ``MySession``:
@@ -246,18 +239,18 @@ In a file ``session_fixture.py``:
 .. code-block:: python
 
     import pytest
-    from pytest_easy_server import server_definition
+    from pytest_easy_server import es_server
 
     @pytest.fixture(scope='module')
-    def my_session(request, server_definition):
+    def my_session(request, es_server):
         """
         Pytest fixture representing the set of MySession objects to use for
         testing against a server.
         """
         session = MySession(
-            host = server_definition.secrets['host']
-            username = server_definition.secrets['username']
-            password = server_definition.secrets['password']
+            host = es_server.secrets['host']
+            username = es_server.secrets['username']
+            password = es_server.secrets['password']
         )
         yield session
         session.close()
@@ -266,7 +259,7 @@ In your test functions, you can now use that fixture:
 
 .. code-block:: python
 
-    from pytest_easy_server import server_definition  # Must still be imported
+    from pytest_easy_server import es_server  # Must still be imported
     from session_fixture import my_session
 
     def test_sample(my_session):

examples/server.yml → examples/es_server.yml

@@ -1,4 +1,6 @@
-# Example server definition file for the pytest-easy-server project
+# Example server file for the pytest-easy-server project
+
+vault_file: es_vault.yml
 
 servers:
 

examples/test_function.py

@@ -2,27 +2,27 @@
 Example pytest test function for pytest-easy-server project.
 """
 
-from pytest_easy_server import server_definition
+from pytest_easy_server import es_server
 
-def test_sample(server_definition):
+def test_sample(es_server):
     """
     Example Pytest test function that tests something.
 
     Parameters:
-      server_definition (easy_server.ServerDefinition): Server to be used.
+      es_server (easy_server.Server): Server to be used.
     """
 
-    # Standard properties from the server definition file:
-    nickname = server_definition.nickname
-    description = server_definition.description
+    # Standard properties from the server file:
+    nickname = es_server.nickname
+    description = es_server.description
 
-    # User-defined additional properties from the server definition file:
-    stuff = server_definition.user_defined['stuff']
+    # User-defined additional properties from the server file:
+    stuff = es_server.user_defined['stuff']
 
     # User-defined secrets from the vault file:
-    host = server_definition.secrets['host']
-    username = server_definition.secrets['username']
-    password = server_definition.secrets['password']
+    host = es_server.secrets['host']
+    username = es_server.secrets['username']
+    password = es_server.secrets['password']
 
     # Log on to the host and perform some test
     # . . .