Unifying plugin models (#107)

.vscode/launch.json

@@ -8,9 +8,10 @@
             "name": "Python: nait",
             "type": "python",
             "request": "launch",
-            "program": "${workspaceFolder}/src/nait",
+            "program": "${workspaceFolder}/.tox/local/bin/nait",
             "cwd": "${workspaceFolder}",
-            "args": ["--version"]
+            "args": ["nanaimo_bar"],
+            "justMyCode": false
         },
         {
             "name": "Pytest: current test",
@@ -19,7 +20,8 @@
             "module": "pytest",
             "args": ["${file}"],
             "console": "internalConsole",
-            "cwd": "${workspaceFolder}"
+            "cwd": "${workspaceFolder}",
+            "justMyCode": false
         },
         {
             "name": "Pytest: all tests",
@@ -28,15 +30,19 @@
             "module": "pytest",
             "args": ["--log-cli-level=INFO"],
             "console": "internalConsole",
-            "cwd": "${workspaceFolder}"
+            "cwd": "${workspaceFolder}",
+            "justMyCode": false
         },
         {
-            "name": "Pytest: all tests",
+            "name": "Pytest: stepwise",
             "type": "python",
             "request": "launch",
             "module": "pytest",
             "console": "internalConsole",
-            "cwd": "${workspaceFolder}"
+            "cwd": "${workspaceFolder}",
+            "args": ["--stepwise",
+                     "--log-cli-level=INFO"],
+            "justMyCode": false
         },
     ]
 }

.vscode/settings.json

@@ -49,14 +49,19 @@
         "chdir",
         "classmethod",
         "cleandir",
+        "cmdline",
         "conftest",
         "ctypes",
         "datefmt",
+        "docstring",
         "flexural",
         "fnmatch",
+        "fspath",
+        "funcmanage",
         "functools",
         "functors",
         "getcwd",
+        "getfixturedefs",
         "globbing",
         "gtest",
         "imgmath",

README.rst

@@ -5,10 +5,14 @@ Nanaimo: Hardware-In-the-Loop Unit Testing
 |badge_docs|_ |badge_build|_ |badge_github_license|_ |badge_pypi_support|_ |badge_pypi_version|_ \
 |badge_sonarcloud_quality|_ |badge_sonarcloud_coverage|_ |badge_sonarcloud_bugs|_
 
-.. Warning::
-    Nanaimo is evolving rapidly right now. We will signal its readiness for alpha integrations by
-    bumping the version number to 0.1.x. For now we provide this repo to let you follow along and
-    comment but we suggest you hold off relying on any version < 0.1.x.
+.. note::
+    Nanaimo is alpha software and will remain so until we bump its version to 1.0.0 or greater.
+    We will not knowingly break compatibility within a minor revision but we will break compatibility
+    a few more times between minor revisions until beta is declared. Because of this you should depend
+    on a minor version explicitly. For example ::
+
+        nanaimo ~= 0.1
+
 
 .. figure:: https://thirtytwobits.github.io/nanaimo/static/images/nanaimo.png
    :alt: A delicious Nanaimo bar

conf.py

@@ -46,7 +46,6 @@
     'sphinx.ext.viewcode',
     'sphinx.ext.githubpages',
     'sphinx.ext.intersphinx',
-    'sphinxarg.ext'
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/fixtures.rst

@@ -9,84 +9,160 @@ This page provides a reference for the available fixtures in Nanaimo. While the
 own fixtures. This page provides a more concise reference when writing tests using
 only Nanaimo's built-in fixtures and pytest plugins.
 
-Builtin Fixtures |nanaimo logo|
+
+Builtin Pytest Fixtures
 -------------------------------------------------
 
-.. autoclass:: nanaimo.builtin.nanaimo_gather.Fixture
-    :members:
-    :show-inheritance:
+A set of pytest fixtures that come with nanaimo.
+
+|pytest logo| nanaimo_arguments
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autofunction:: nanaimo.pytest.plugin.nanaimo_arguments
     :noindex:
 
-.. autoclass:: nanaimo.builtin.nanaimo_serial_watch.Fixture
-    :members:
-    :show-inheritance:
+|pytest logo| nanaimo_log
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autofunction:: nanaimo.pytest.plugin.nanaimo_log
     :noindex:
 
-.. autoclass:: nanaimo.instruments.bkprecision.Series1900BUart
+|pytest logo| nanaimo_fixture_manager
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autofunction:: nanaimo.pytest.plugin.nanaimo_fixture_manager
+    :noindex:
+
+Builtin Nanaimo Fixtures
+-------------------------------------------------
+
+A set of predefined :class:`nanaimo.fixtures.Fixture` types that come with nanaimo.
+
+
+|pytest logo| nanaimo_gather (gather)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. invisible-code-block: python
+
+    import nanaimo.builtin.nanaimo_gather as gather
+
+    assert gather.pytest_nanaimo_fixture_type().get_canonical_name() == "nanaimo_gather"
+    assert gather.pytest_nanaimo_fixture_type().get_argument_prefix() == "gather"
+
+.. autoclass:: nanaimo.builtin.nanaimo_gather.Fixture
     :members:
     :show-inheritance:
     :noindex:
 
-.. autoclass:: nanaimo.instruments.ykush.Fixture
+|pytest logo| nanaimo_serial_watch (lw)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. invisible-code-block: python
+
+    import nanaimo.builtin.nanaimo_serial_watch as lw
+
+    assert lw.pytest_nanaimo_fixture_type().get_canonical_name() == "nanaimo_serial_watch"
+    assert lw.pytest_nanaimo_fixture_type().get_argument_prefix() == "lw"
+
+.. autoclass:: nanaimo.builtin.nanaimo_serial_watch.Fixture
     :members:
     :show-inheritance:
     :noindex:
 
-
-Builtin Subprocess Fixtures
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Fixtures based on :mod:`nanaimo.fixture.SubprocessFixture`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. autoclass:: nanaimo.fixtures.SubprocessFixture
     :members:
     :show-inheritance:
     :noindex:
 
+
+|pytest logo| nanaimo_cmd (cmd)
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+.. invisible-code-block: python
+
+    import nanaimo.builtin.nanaimo_cmd as cmd
+
+    assert cmd.pytest_nanaimo_fixture_type().get_canonical_name() == "nanaimo_cmd"
+    assert cmd.pytest_nanaimo_fixture_type().get_argument_prefix() == "cmd"
+
 .. autoclass:: nanaimo.builtin.nanaimo_cmd.Fixture
     :members:
     :show-inheritance:
     :noindex:
 
+
+|pytest logo| nanaimo_scp (scp)
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+.. invisible-code-block: python
+
+    import nanaimo.builtin.nanaimo_scp as scp
+
+    assert scp.pytest_nanaimo_fixture_type().get_canonical_name() == "nanaimo_scp"
+    assert scp.pytest_nanaimo_fixture_type().get_argument_prefix() == "scp"
+
 .. autoclass:: nanaimo.builtin.nanaimo_scp.Fixture
     :members:
     :show-inheritance:
     :noindex:
 
+|pytest logo| nanaimo_ssh (ssh)
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+.. invisible-code-block: python
+
+    import nanaimo.builtin.nanaimo_ssh as ssh
+
+    assert ssh.pytest_nanaimo_fixture_type().get_canonical_name() == "nanaimo_ssh"
+    assert ssh.pytest_nanaimo_fixture_type().get_argument_prefix() == "ssh"
+
 .. autoclass:: nanaimo.builtin.nanaimo_ssh.Fixture
     :members:
     :show-inheritance:
     :noindex:
 
 
-|pytest logo| Pytest Plugins
+
+Instrument Fixtures
 -------------------------------------------------
 
-.. autofunction:: nanaimo.instruments.bkprecision.nanaimo_instr_bk_precision
-    :noindex:
+Fixtures for popular measurement, control, and test gear.
 
-.. autofunction:: nanaimo.instruments.bkprecision.nanaimo_instr_ykush
-    :noindex:
+|pytest logo| nanaimo_instr_bk_precision (bk)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. autofunction:: nanaimo.builtin.nanaimo_gather.nanaimo_gather
-    :noindex:
+.. invisible-code-block: python
 
-.. autofunction:: nanaimo.builtin.nanaimo_scp.nanaimo_scp
-    :noindex:
+    import nanaimo.instruments.bkprecision as bk
 
-.. autofunction:: nanaimo.builtin.nanaimo_ssh.nanaimo_ssh
-    :noindex:
+    assert bk.pytest_nanaimo_fixture_type().get_canonical_name() == "nanaimo_instr_bk_precision"
+    assert bk.pytest_nanaimo_fixture_type().get_argument_prefix() == "bk"
 
-.. autofunction:: nanaimo.builtin.nanaimo_serial_watch.nanaimo_serial_watch
+.. autoclass:: nanaimo.instruments.bkprecision.Series1900BUart
+    :members:
+    :show-inheritance:
     :noindex:
 
-.. autofunction:: nanaimo.pytest.plugin.nanaimo_arguments
-    :noindex:
 
-.. autofunction:: nanaimo.pytest.plugin.nanaimo_log
-    :noindex:
+|pytest logo| nanaimo_instr_ykush (wk)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. autofunction:: nanaimo.pytest.plugin.nanaimo_fixture_manager
+.. invisible-code-block: python
+
+    import nanaimo.instruments.ykush as yk
+
+    assert yk.pytest_nanaimo_fixture_type().get_canonical_name() == "nanaimo_instr_ykush"
+    assert yk.pytest_nanaimo_fixture_type().get_argument_prefix() == "yku"
+
+.. autoclass:: nanaimo.instruments.ykush.Fixture
+    :members:
+    :show-inheritance:
     :noindex:
 
+
 .. |pytest logo| image:: static/images/pytest1.png
   :width: 100
   :alt: Pytest logo