Skip to content

Commit

Permalink
Adopt tox
Browse files Browse the repository at this point in the history
  • Loading branch information
lbdreyer committed Mar 31, 2023
1 parent 8786962 commit fd8afb6
Show file tree
Hide file tree
Showing 10 changed files with 149 additions and 416 deletions.
29 changes: 14 additions & 15 deletions .github/workflows/ci-tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -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
Expand Down Expand Up @@ -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: |
Expand All @@ -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 }}
Expand All @@ -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")
18 changes: 8 additions & 10 deletions .github/workflows/ci-wheels.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -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
Expand All @@ -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
Expand Down
Original file line number Diff line number Diff line change
@@ -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:
Expand All @@ -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) }}
24 changes: 13 additions & 11 deletions benchmarks/bm_runner.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down Expand Up @@ -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()

Expand Down Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions docs/src/common_links.inc
Original file line number Diff line number Diff line change
Expand Up @@ -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/
Expand Down
103 changes: 45 additions & 58 deletions docs/src/developers_guide/contributing_running_tests.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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/
7 changes: 5 additions & 2 deletions docs/src/whatsnew/latest.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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`)
Expand All @@ -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,
Expand Down
Loading

0 comments on commit fd8afb6

Please sign in to comment.