tox.ini

# This is a configuration file for running tests, linters and other
# code-quality checks, using Tox (https://tox.readthedocs.io/), which
# allows configuring and automatically running many different test
# environments and checks, each in a separate Python virtual
# environment (and each potentially using a different version of
# Python).
#
# Using this file requires having tox installed -- "pip install tox"
# or refer to Tox's own documentation -- and a functioning
# installation of at least one targeted Python version. Running "tox"
# with no command-line arguments will attempt to run all environments
# against all targeted Python versions, and will fail if any Python
# versions are missing. To select only certain test environments to
# run, use the "-e" command-line flag and pass either a single
# environment name, or a comma-separated list of environment names. To
# see all available environments with their descriptions, run:
# "tox -v 1 --listenvs"


# Base configuration: list of environments and Python versions.
################################################################################

# Environment matrix.
[tox]
envlist =
  py{37,38,39,310}
  black
  check-description
  check-manifest
  docs
  flake8
  isort
  spelling

# Configuration for running on GitHub Actions via tox-gh-actions.
[gh-actions]
python =
  3.6: py36
  3.7: py37
  3.8: py38
  3.9: py39
  3.10: py310, black, check-description, check-manifest, docs, flake8, isort, spelling


# The base test environment -- runs the unit test suite with coverage.
################################################################################
[testenv]
description = Run tests with coverage report.
allowlist_externals =
  find
  rm
# Python silences deprecation warnings by default, but we want to see
# them during test runs.
setenv =
    PYTHONWARNINGS=once::DeprecationWarning
# Ensure each virtualenv always has latest pip, so output doesn't get
# cluttered with messages about needing to upgrade it. Note that tox's
# 'download=true' option doesn't quite do the same thing: it ensures
# pip/setuptools/wheel get upgraded at virtualenv creation time, but
# will not upgrade them when reusing an already-created virtualenv.
commands_pre =
  {envpython} -m pip install --upgrade pip
# Many test runs will leave behind some type of artifact -- Python
# bytecode, packaging-related files, coverage data -- which should be
# removed before the next run in order to ensure a clean starting
# point. The commands below run after the main test commands of each
# virtualenv, and perform this cleanup.
commands_post =
  find {toxinidir}/tests -type f -name "*.pyc" -delete
  find {toxinidir}/tests -type d -name "__pycache__" -delete
  find {toxinidir}/src -type f -name "*.pyc" -delete
  find {toxinidir}/src -type d -name "__pycache__" -delete
  find {toxinidir}/src -type f -path "*.egg-info*" -delete
  find {toxinidir}/src -type d -path "*.egg-info" -delete
  rm -f {toxinidir}/.coverage
commands =
  {posargs:pytest -vv --ignore=src --cov=akismet --cov-report term-missing}
deps =
  pytest
  pytest-cov
passenv =
  TEST_AKISMET_API_KEY
  TEST_AKISMET_BLOG_URL

# Documentation checks.
################################################################################

# Runs an HTML build of the documentation, and fails if there's an
# error in building it.
[testenv:docs]
description = Check that the documentation can build.
basepython = python3.10
changedir = {toxinidir}/docs
commands =
  sphinx-build -b html -d {envtmpdir}/doctrees . {envtmpdir}/html
deps =
  sphinx
  sphinx_rtd_theme

# Runs a spelling checker over the documentation, and if misspelled
# words are found, fails the build and outputs a list of
# them. Requires the 'enchant' C library preinstalled on the target
# system.
[testenv:spelling]
description = Spell-check documentation.
basepython = python3.10
changedir = {toxinidir}/docs
# This is the only env where we silence deprecation warnings, because
# we'd already catch any from our actual codebase elsewhere and in
# this env we are asking Sphinx to promote warnings to errors in order
# to fail the build on anything caught by the spelling checker.
setenv =
    PYTHONWARNINGS=ignore::DeprecationWarning
commands =
  sphinx-build -W -b spelling -d {envtmpdir}/doctrees . {envtmpdir}/html
deps =
  sphinx
  sphinx_rtd_theme
  pyenchant
  sphinxcontrib-spelling


# Linters.
################################################################################

# Runs the Black code formatter over the entire code base, and fails
# if Black thinks any files need to be reformatted.
[testenv:black]
description = Check code formatting using Black.
basepython = python3.10
changedir = {toxinidir}
deps = black
commands =
  black --line-length 88 --check --diff {toxinidir}/src {toxinidir}/tests {toxinidir}/docs {toxinidir}

# Runs the flake8 linter over the entire code base, and fails if
# flake8 finds any problems.
[testenv:flake8]
description = Lint code with flake8.
basepython = python3.10
changedir = {toxinidir}
deps = flake8
commands =
  flake8 {toxinidir}/src/akismet.py {toxinidir}/tests

# Runs the isort import linter over the entire code base, and fails if
# any problems are found.
[testenv:isort]
description = Lint imports with isort.
basepython = python3.10
changedir = {toxinidir}
deps = isort
commands =
  isort --check-only --diff {toxinidir}/src {toxinidir}/tests


# Packaging checks.
################################################################################

# Builds the package and runs 'twine check' to ensure it will render
# correctly when uploaded to the Python Package Index, or fail if not.
[testenv:check-description]
description = Check that the package description will render on the Python Package Index.
basepython = python3.10
changedir = {toxinidir}
skip_install = true
deps =
  twine
# In this environment we always want latest wheel in addition to
# latest pip.
commands_pre =
  {envpython} -m pip install --upgrade pip setuptools wheel
commands =
  {envpython} -m pip wheel -w {envtmpdir}/build --no-deps .
  twine check {envtmpdir}/build/*

# Runs check-manifest, a tool that builds the package and compares the
# files in the package to the files under version control, and fails
# if any version-controlled files do not end up in the package.
[testenv:check-manifest]
description = Check that the set of packaged files matches the set of version-controlled files.
basepython = python3.10
changedir = {toxinidir}
skip_install = true
deps =
  check-manifest
commands =
  check-manifest --verbose