tox.ini

[tox]
envlist =
    # NOTE: keep this in sync with the env list in .github/workflows/ci.yml.
    py{39,310,311,312,313,314,314t,py3}-pip{supported,lowest,latest,main}-coverage
    pip{supported,lowest,latest,main}-coverage
    pip{supported,lowest,latest,main}
    checkqa
    readme
skip_missing_interpreters = True

[python-cli-options]
byte-warnings = -b
byte-errors = -bb
max-isolation = -E -s -I
# some-isolation = -I
# FIXME: Python 2 shim. Is this equivalent to the above?
some-isolation = -E -s
warnings-to-errors = -Werror


[testenv]
description = run the tests with pytest
extras =
    testing
    coverage: coverage
deps =
    pipsupported: pip == 26.0
    pipsupported: setuptools <= 80.0

    piplowest: pip == 22.2.* ; python_version < "3.12"
    piplowest: pip == 23.2.* ; python_version >= "3.12" and python_version < "3.14"
    piplowest: pip == 25.2.* ; python_version >= "3.14"

    piplatest: pip
    pipmain: https://github.com/pypa/pip/archive/main.zip
setenv =
    coverage: PYTEST_ADDOPTS=--strict-markers --doctest-modules --cov --cov-report=term-missing --cov-report=xml {env:PYTEST_ADDOPTS:}
commands_pre =
    piplatest: python -m pip install -U pip
    pip --version
commands = pytest {posargs}
passenv =
    CI
    FORCE_COLOR
    GITHUB_ACTIONS
    MYPY_FORCE_COLOR
    PRE_COMMIT_COLOR
    PY_COLORS
pip_pre=True

[testenv:checkqa]
description = format the code base and check its quality
skip_install = True
deps = pre-commit
commands_pre =
commands = pre-commit run --all-files --show-diff-on-failure

[testenv:readme]
description = check whether the long description will render correctly on PyPI
deps =
    build
    twine
commands_pre =
commands =
    python -m build --outdir {envtmpdir} --sdist {toxinidir}
    twine check --strict {envtmpdir}{/}*
skip_install = true

[testenv:pip-compile-docs]
description = compile requirements for the documentation
commands_pre =
# compile requirements.in + pyproject.toml to get pip-tools install requirements in
# addition to doc tooling requirements *but without* putting `pip-tools` itself
# into the output
commands =
  python -m piptools compile \
    --strip-extras \
    --allow-unsafe \
    --quiet \
    docs/requirements.in \
    './pyproject.toml' \
    -o docs/requirements.txt \
    {posargs}

[testenv:build-docs]
description = build the documentation
deps =
  -r{toxinidir}/docs/requirements.txt
  # FIXME: re-enable the "-r" + "-c" paradigm once the pip bug is fixed.
  # Ref: https://github.com/pypa/pip/issues/9243
  # -r{toxinidir}/docs/requirements.in
  # -c{toxinidir}/docs/requirements.txt
commands_pre =
  # Retrieve possibly missing commits:
  -git fetch --unshallow
  -git fetch --tags
commands =
  # Build the html docs with Sphinx:
  {envpython} -m sphinx \
    -j auto \
    -b html \
    {tty:--color} \
    -a \
    -n -W --keep-going \
    -d "{temp_dir}/.doctrees" \
    . \
    {posargs:{envdir}/docs_out}
# Print out the output docs dir and a way to serve html after the build
commands_post =
  {envpython} -c \
    'import pathlib;\
    docs_dir = pathlib.Path(r"{envdir}") / "docs_out";\
    index_file = docs_dir / "index.html";\
    print("\n" + "=" * 120 +\
    f"\n\nDocumentation available under:\n\n\
    \tfile://\{index_file\}\n\nTo serve docs, use\n\n\
    \t$ python3 -m http.server --directory \
    \N\{QUOTATION MARK\}\{docs_dir\}\N\{QUOTATION MARK\} 0\n\n" +\
    "=" * 120)'
changedir = {toxinidir}/docs
isolated_build = true
passenv =
  READTHEDOCS
  READTHEDOCS_VERSION_TYPE
  SSH_AUTH_SOCK
skip_install = false
allowlist_externals =
  git


[testenv:preview-docs]
description = preview the docs
deps =
  sphinx-autobuild
  {[testenv:build-docs]deps}
commands_pre =
commands =
  # Retrieve possibly missing commits:
  -git fetch --unshallow
  -git fetch --tags

  # Build the html docs with sphinx-autobuild:
  {envpython} -m sphinx_autobuild \
    -j auto \
    -b html \
    -n \
    -W \
    -d "{temp_dir}/.doctrees" \
    . \
    --watch ../README.md \
    --watch ../CHANGELOG.md \
    "{envdir}/docs_out"

changedir = {[testenv:build-docs]changedir}
isolated_build = {[testenv:build-docs]isolated_build}
passenv = {[testenv:build-docs]passenv}
skip_install = {[testenv:build-docs]skip_install}
allowlist_externals = {[testenv:build-docs]allowlist_externals}


[testenv:linkcheck-docs]
description = check links in the documentation
deps =
  -r{toxinidir}/docs/requirements.txt
  # FIXME: re-enable the "-r" + "-c" paradigm once the pip bug is fixed.
  # Ref: https://github.com/pypa/pip/issues/9243
  # -r{toxinidir}/docs/requirements.in
  # -c{toxinidir}/docs/requirements.txt
commands_pre =
commands =
  # Retrieve possibly missing commits:
  -git fetch --unshallow
  -git fetch --tags

  # Build the html docs with Sphinx:
  {envpython} -m sphinx \
    -j auto \
    -b linkcheck \
    {tty:--color} \
    -a \
    -n -W --keep-going \
    -d "{temp_dir}/.doctrees" \
    . \
    "{envdir}/docs_out"
changedir = {toxinidir}/docs
isolated_build = true
passenv =
  SSH_AUTH_SOCK
skip_install = false
allowlist_externals =
  git

[testenv:changelog-draft]
deps =
  towncrier
  -c{toxinidir}/docs/requirements.txt
commands_pre =
  towncrier --version
# wrap the invocation of `towncrier build --version main --draft` to discard stderr
# unfortunately, stderr gets interleaved with stdout, often mixing towncrier's draft build output
# with user messaging about the invocation
commands =
  {envpython} -bb -I -Werror \
    -c 'import sys, subprocess; subprocess.run([sys.executable, "-bb", "-I", "-Werror", "-m", "towncrier", "build", "--version", "DRAFT_VERSION", "--draft", *sys.argv[1:]], stderr=subprocess.DEVNULL)' {posargs}


[testenv:cleanup-dists]
description =
  Wipe the dist{/} folder
deps =
commands_pre =
commands =
  {envpython} \
    {[python-cli-options]byte-errors} \
    {[python-cli-options]max-isolation} \
    {[python-cli-options]warnings-to-errors} \
    -c \
      'import os, shutil, sys; \
      dists_dir = "{toxinidir}{/}dist{/}"; \
      shutil.rmtree(dists_dir, ignore_errors=True); \
      sys.exit(os.path.exists(dists_dir))'
commands_post =
package = skip


[testenv:build-dists]
allowlist_externals =
  env
description =
  Build dists with {basepython} and put them into the dist{/} folder
depends =
  cleanup-dists
deps =
  build
commands_pre =
commands =
  {envpython} \
    {[python-cli-options]byte-errors} \
    {[python-cli-options]max-isolation} \
    {[python-cli-options]warnings-to-errors} \
    -m build \
      {posargs:}
commands_post =
package = skip


[testenv:metadata-validation]
description =
  Verify that dists under the `dist{/}` dir
  have valid metadata
depends =
  build-dists
deps =
  twine
commands =
  {envpython} \
    {[python-cli-options]byte-errors} \
    {[python-cli-options]max-isolation} \
    {[python-cli-options]warnings-to-errors} \
    -m twine \
      check \
      --strict \
      dist{/}*
commands_post =
package = skip