Adopt tox

SciTools · Mar 31, 2023 · fd8afb6 · fd8afb6
1 parent 8786962
commit fd8afb6
Show file tree

Hide file tree

Showing 10 changed files with 149 additions and 416 deletions.
diff --git a/.github/workflows/ci-tests.yml b/.github/workflows/ci-tests.yml
@@ -35,20 +35,21 @@ jobs:
       fail-fast: false
       matrix:
         os: ["ubuntu-latest"]
-        python-version: ["3.10"]
-        session: ["doctest", "gallery", "linkcheck"]
+        python-version: ["310"]
+        session: ["docs-tests", "docs-linkcheck", "gallery_tests"]
         include:
           - os: "ubuntu-latest"
-            python-version: "3.10"
+            python-version: "310"
             session: "tests"
-            coverage: "--coverage"
+            posargs: "--cov=lib/iris --cov-report=xml"
           - os: "ubuntu-latest"
-            python-version: "3.9"
+            python-version: "39"
             session: "tests"
           - os: "ubuntu-latest"
-            python-version: "3.8"
+            python-version: "38"
             session: "tests"
 
+
     env:
       IRIS_TEST_DATA_VERSION: "2.19"
       ENV_NAME: "ci-tests"
@@ -63,7 +64,7 @@ jobs:
           CACHE_WEEKS: 2
         run: |
           echo "CACHE_PERIOD=$(date +%Y).$(expr $(date +%U) / ${CACHE_WEEKS})" >> ${GITHUB_ENV}
-          echo "LOCK_FILE=requirements/ci/nox.lock/py$(echo ${{ matrix.python-version }} | tr -d '.')-linux-64.lock" >> ${GITHUB_ENV}
+          echo "LOCK_FILE=requirements/ci/locks/py$(echo ${{ matrix.python-version }})-linux-64.lock" >> ${GITHUB_ENV}
 
       - name: "data cache"
         uses: ./.github/workflows/composite/iris-data-cache
@@ -91,10 +92,10 @@ jobs:
       - name: "conda environment cache"
         uses: ./.github/workflows/composite/conda-env-cache
         with:
-          cache_build: 0
+          cache_build: 1
           cache_period: ${{ env.CACHE_PERIOD }}
           env_name: ${{ env.ENV_NAME }}
-          install_packages: "cartopy nox pip"
+          install_packages: "cartopy tox'<4'"
 
       - name: "conda info"
         run: |
@@ -108,8 +109,8 @@ jobs:
           cache_period: ${{ env.CACHE_PERIOD }}
           env_name: ${{ env.ENV_NAME }}
 
-      - name: "nox cache"
-        uses: ./.github/workflows/composite/nox-cache
+      - name: "tox cache"
+        uses: ./.github/workflows/composite/tox-cache
         with:
           cache_build: 1
           env_name: ${{ env.ENV_NAME }}
@@ -134,11 +135,9 @@ jobs:
           cat ${MPL_RC}
 
       - name: "iris ${{ matrix.session }}"
-        env:
-          PY_VER: ${{ matrix.python-version }}
         run: |
-          nox --session ${{ matrix.session }} -- --verbose ${{ matrix.coverage }}
+            tox -e py${{ matrix.python-version }}-${{ matrix.session }} -- ${{ matrix.posargs }}
 
       - name: Upload coverage report
         uses: codecov/codecov-action@v3
-        if: ${{ matrix.coverage }}
+        if: contains(${{ matrix.posargs }}, "--cov=lib/iris --cov-report=xml")
diff --git a/.github/workflows/ci-wheels.yml b/.github/workflows/ci-wheels.yml
@@ -54,7 +54,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.8", "3.9", "3.10"]
+        python-version: ["38", "39", "310"]
         session: ["wheel"]
     env:
       ENV_NAME: "ci-wheels"
@@ -74,7 +74,7 @@ jobs:
           CACHE_WEEKS: 2
       run: |
         echo "CACHE_PERIOD=$(date +%Y).$(expr $(date +%U) / ${CACHE_WEEKS})" >> ${GITHUB_ENV}
-        echo "LOCK_FILE=requirements/ci/nox.lock/py$(echo ${{ matrix.python-version }} | tr -d '.')-linux-64.lock" >> ${GITHUB_ENV}
+        echo "LOCK_FILE=requirements/ci/locks/py$(echo ${{ matrix.python-version }})-linux-64.lock" >> ${GITHUB_ENV}
 
     - name: "conda package cache"
       uses: ./.github/workflows/composite/conda-pkg-cache
@@ -95,23 +95,21 @@ jobs:
     - name: "conda environment cache"
       uses: ./.github/workflows/composite/conda-env-cache
       with:
-        cache_build: 0
+        cache_build: 1
         cache_period: ${{ env.CACHE_PERIOD }}
         env_name: ${{ env.ENV_NAME }}
-        install_packages: "nox pip"
+        install_packages: "tox'<4' pip"
 
-    - name: "nox cache"
-      uses: ./.github/workflows/composite/nox-cache
+    - name: "tox cache"
+      uses: ./.github/workflows/composite/tox-cache
       with:
         cache_build: 0
         env_name: ${{ env.ENV_NAME }}
         lock_file: ${{ env.LOCK_FILE }}
 
-    - name: "nox install and test wheel"
-      env:
-        PY_VER: ${{ matrix.python-version }}
+    - name: "tox install and test wheel"
       run: |
-        nox --session ${{ matrix.session }} -- --verbose
+        tox -e py${{ matrix.python-version }}-${{ matrix.session }}
 
   show-artifacts:
     needs: build

diff --git a/.../workflows/composite/nox-cache/action.yml → .../workflows/composite/tox-cache/action.yml b/.../workflows/composite/nox-cache/action.yml → .../workflows/composite/tox-cache/action.yml
@@ -1,9 +1,9 @@
-name: "nox cache"
-description: "cache the nox test environments"
+name: "tox cache"
+description: "cache the tox test environments"
 
 inputs:
   cache_build:
-    description: "nox cache build number"
+    description: "tox cache build number"
     required: false
     default: "0"
   env_name:
@@ -18,5 +18,5 @@ runs:
   steps:
     - uses: actions/cache@v3
       with:
-        path: ${{ github.workspace }}/.nox
-        key: ${{ runner.os }}-nox-${{ inputs.env_name }}-s${{ matrix.session }}-py${{ matrix.python-version }}-b${{ inputs.cache_build }}-${{ hashFiles(inputs.lock_file) }}
+        path: ${{ github.workspace }}/.tox
+        key: ${{ runner.os }}-tox-${{ inputs.env_name }}-s${{ matrix.session }}-py${{ matrix.python-version }}-b${{ inputs.cache_build }}-${{ hashFiles(inputs.lock_file) }}
diff --git a/benchmarks/bm_runner.py b/benchmarks/bm_runner.py
@@ -48,27 +48,29 @@ def _prep_data_gen_env() -> None:
     """
 
     root_dir = Path(__file__).parents[1]
-    python_version = "3.10"
+    python_version = "310"
     data_gen_var = "DATA_GEN_PYTHON"
     if data_gen_var in environ:
         print("Using existing data generation environment.")
     else:
         print("Setting up the data generation environment ...")
-        # Get Nox to build an environment for the `tests` session, but don't
-        #  run the session. Will re-use a cached environment if appropriate.
+        # Get tox to build an environment. It will re-use a cached environment
+        # if appropriate.
         subprocess.run(
             [
-                "nox",
-                f"--noxfile={root_dir / 'noxfile.py'}",
-                "--session=tests",
-                "--install-only",
-                f"--python={python_version}",
+                "tox",
+                "-c",
+                root_dir,
+                "-e",
+                f"py{python_version}",
             ]
         )
         # Find the environment built above, set it to be the data generation
         #  environment.
         data_gen_python = next(
-            (root_dir / ".nox").rglob(f"tests*/bin/python{python_version}")
+            (root_dir / ".tox").rglob(
+                f"py{python_version}/bin/python{python_version[:1]}.{python_version[1:]}"
+            )
         ).resolve()
         environ[data_gen_var] = str(data_gen_python)
 
@@ -98,7 +100,7 @@ def _prep_data_gen_env() -> None:
 
 def _setup_common() -> None:
     _check_requirements("asv")
-    _check_requirements("nox")
+    _check_requirements("tox")
 
     _prep_data_gen_env()
 
@@ -140,7 +142,7 @@ def _asv_compare(*commits: str, overnight_mode: bool = False) -> None:
 
 
 class _SubParserGenerator(ABC):
-    """Convenience for holding all the necessary argparse info in 1 place."""
+    """Convenience for holding all the necessary argparse info in one place."""
 
     name: str = NotImplemented
     description: str = NotImplemented

diff --git a/docs/src/common_links.inc b/docs/src/common_links.inc
@@ -35,6 +35,7 @@
 .. _scitools-iris: https://pypi.org/project/scitools-iris/
 .. _sphinx: https://www.sphinx-doc.org/en/master/
 .. _test-iris-imagehash: https://github.com/SciTools/test-iris-imagehash
+.. _tox: https://tox.readthedocs.io/en/latest/
 .. _using git: https://docs.github.com/en/github/using-git
 .. _requirements: https://github.com/SciTools/iris/tree/main/requirements
 .. _CF-UGRID: https://ugrid-conventions.github.io/ugrid-conventions/

diff --git a/docs/src/developers_guide/contributing_running_tests.rst b/docs/src/developers_guide/contributing_running_tests.rst
@@ -12,8 +12,8 @@ There are two options for running the tests:
   the tests or use ``python`` interactively to investigate any issues.  See
   :ref:`test manual env`.
 
-* Use ``nox``.  This will automatically generate an environment and run test
-  sessions consistent with our GitHub continuous integration.  See :ref:`using nox`.
+* Use ``tox``.  This will automatically generate an environment and run test
+  sessions consistent with our GitHub continuous integration.  See :ref:`using tox`.
 
 .. _test manual env:
 
@@ -101,97 +101,84 @@ using the commands ``python test_mapping.py -h`` or
 ``python test_mapping.py --help``.
 
 .. tip::  A useful command line option to use is ``-d``.  This will display
-          matplotlib_ figures as the tests are run.  For example::
+          `matplotlib_` figures as the tests are run.  For example::
 
              python test_mapping.py -d
 
-.. _using nox:
+.. _using tox:
 
-Using Nox for Testing Iris
+Using tox for Testing Iris
 ==========================
 
-The `nox`_ tool has for adopted for automated testing on `Iris GitHub Actions`_
+The `tox`_ tool has been adopted for automated testing on `Iris GitHub Actions`_
 and also locally on the command-line for developers.
 
-`nox`_ is similar to `tox`_, but instead leverages the expressiveness and power of a Python
-configuration file rather than an `.ini` style file. As with `tox`_, `nox`_ can use `virtualenv`_
-to create isolated Python environments, but in addition also supports `conda`_ as a testing
-environment backend.
+`tox`_ uses `virtualenv`_ to create isolated Python environments and is
+configured within a tox.ini file.
 
-
-Where is Nox Used?
+Where is tox Used?
 ------------------
 
-Iris uses `nox`_ as a convenience to fully automate the process of executing the Iris tests, but also
-automates the process of:
+Iris uses `tox`_ as a convenience to fully automate the process of:
 
-* building the documentation and executing the doc-tests
-* building the documentation gallery
+* executing the Iris tests,
+* building the documentation,
+* executing the doc-tests,
+* executing the gallery tests, and
 * running the documentation URL link check
 
-You can perform all of these tasks manually yourself, however the onus is on you to first ensure
-that all of the required package dependencies are installed and available in the testing environment.
+You can perform all of these tasks manually yourself, however the onus is on you
+to first ensure that all of the required package dependencies are installed and
+available in the testing environment.
 
-`Nox`_ has been configured to automatically do this for you, and provides a means to easily replicate
-the remote testing behaviour of `Iris GitHub Actions`_ locally for the developer.
+`tox`_ has been configured to automatically do this for you, and provides a
+means to easily replicate the remote testing behaviour of `Iris GitHub Actions`_
+locally for the developer.
 
 
-Installing Nox
+Installing tox
 --------------
 
-We recommend installing `nox`_ using `conda`_. To install `nox`_ in a separate `conda`_ environment::
+We recommend installing `tox`_ using `conda`_. To install `tox`_ in a separate
+`conda`_ environment::
 
-  conda create -n nox -c conda-forge nox
-  conda activate nox
+  conda create -n tox -c conda-forge tox
+  conda activate tox
 
-To install `nox`_ in an existing active `conda`_ environment::
+To install `tox`_ in an existing active `conda`_ environment::
 
-  conda install -c conda-forge nox
+  conda install -c conda-forge tox
 
-The `nox`_ package is also available on PyPI, however `nox`_ has been configured to use the `conda`_
-backend for Iris, so an installation of `conda`_ must always be available.
+The `tox`_ package is also available on PyPI, however `tox`_ has been configured
+to use `conda`_ to create the testing environments and so an installation of
+`conda`_ must always be available.
 
 
-Testing with Nox
+Testing with tox
 ----------------
 
-The `nox`_ configuration file `noxfile.py` is available in the root ``iris`` project directory, and
-defines all the `nox`_ sessions (i.e., tasks) that may be performed. `nox`_ must always be executed
-from the ``iris`` root directory.
-
-To list the configured `nox`_ sessions for Iris::
-
-  nox --list
-
-To run the Iris tests for all configured versions of Python::
+The `tox`_ configuration file `tox.ini` is available in the root ``iris``
+project directory, and defines all the `tox`_ test environments (i.e., tasks)
+that may be performed. `tox`_ must always be executed from the ``iris`` root
+directory.
 
-  nox --session tests
+To list the configured `tox`_ sessions for Iris::
 
-To build the Iris documentation specifically for Python 3.7::
+  tox --listenvs-all
 
-  nox --session doctest-3.7
+To run the Iris tests for Python 3.10::
 
-To run all the Iris `nox`_ sessions::
+  tox -e py310-tests
 
-  nox
+To build the Iris documentation specifically for Python 3.10::
 
-For further `nox`_ command-line options::
-
-  nox --help
-
-.. tip::
-    For `nox`_ sessions that use the `conda`_ backend, you can use the ``-v`` or ``--verbose``
-    flag to display the `nox`_ `conda`_ environment package details and environment info.
-    For example::
+  tox -e py310-docs
 
-        nox --session tests -- --verbose
+For further `tox`_ command-line options::
 
+  tox --help
 
-.. note:: `nox`_ will cache its testing environments in the `.nox` root ``iris`` project directory.
+.. note:: `tox`_ will cache its testing environments in the `.tox` root ``iris`` project directory.
 
 
-.. _setuptools: https://setuptools.readthedocs.io/en/latest/
-.. _tox: https://tox.readthedocs.io/en/latest/
-.. _virtualenv: https://virtualenv.pypa.io/en/latest/
-.. _PyPI: https://pypi.org/project/nox/
-.. _v41.5.0: https://setuptools.readthedocs.io/en/latest/history.html#v41-5-0
+.. _virtualenv: https://virtualenv.pypa.io/en/latest/
diff --git a/docs/src/whatsnew/latest.rst b/docs/src/whatsnew/latest.rst
@@ -136,8 +136,8 @@ This document explains the changes made to Iris for this release
    (:pull:`5101`)
 
 #. `@lbdreyer`_ and `@trexfeathers`_ (reviewer) added coverage testing. This
-   can be enabled by using the "--coverage" flag when running the tests with
-   nox i.e. ``nox --session tests -- --coverage``. (:pull:`4765`)
+   can be enabled when running with tox i.e. ``tox -e py310-tests -- --cov``.
+   (:pull:`4765`)
 
 #. `@lbdreyer`_ and `@trexfeathers`_ (reviewer) removed the ``--coding-tests``
    option from Iris' test runner. (:pull:`4765`)
@@ -155,6 +155,9 @@ This document explains the changes made to Iris for this release
    pin for first use of `dask.array.ma.empty_like`_ and replaced `@tinyendian`_
    workaround. (:pull:`5225`)
 
+# `@lbdreyer`_ replaced nox with tox as the automated test runner.
+  (:pull:`5184`)
+
 
 .. comment
     Whatsnew author names (@github name) in alphabetical order. Note that,