tox.ini

[tox]
envlist = python
minversion = 3.21.0

[testenv]
deps =
  -rrequirements{/}tests.in
commands_pre =
  {envpython} \
    {[python-cli-options]byteerrors} \
    {[python-cli-options]isolate} \
    -m \
    OpenSSL.debug
commands =
  {envpython} \
    {[python-cli-options]byteerrors} \
    {[python-cli-options]isolate} \
    -m \
    pytest \
    {tty:--color=yes} \
    {posargs:}
install_command =
  {envpython} \
    {[python-cli-options]byteerrors} \
    {[python-cli-options]isolate} \
    {toxinidir}{/}bin{/}pip-wrapper \
    '{envname}' \
    '{toxinidir}{/}requirements{/}' \
    install {opts} {packages}
usedevelop = True

passenv =
  WEBTEST_INTERACTIVE
  CI
  TRAVIS
  TRAVIS_*
  APPVEYOR
  APPVEYOR_*
  CIRCLECI
  CIRCLE_*
  PYTHONDONTWRITEBYTECODE
  PYTHONTRACEMALLOC
  PYTEST_*
  SSH_AUTH_SOCK
  GITHUB_*
  CODECOV_TOKEN
setenv =
  CRYPTOGRAPHY_ALLOW_OPENSSL_102=x
  PYTHONDONTWRITEBYTECODE=x
  WEBTEST_INTERACTIVE=false


[python-cli-options]
byteerrors = -bb
bytewarnings = -b
# isolate = -I
# FIXME: Python 2 shim. Is this equivalent to the above?
isolate = -E -s


[dists]
setenv =
  PIP_CONSTRAINT = {toxinidir}{/}requirements{/}dist-build-constraints.txt
  PEP517_OUT_DIR = {env:PEP517_OUT_DIR:{toxinidir}{/}dist}


[testenv:build-docs]
allowlist_externals =
  git
basepython = python3.10
description = Build The Docs
changedir = docs
commands_pre =
commands =
  # Retrieve possibly missing commits:
  -git fetch --unshallow
  -git fetch --tags

  # Build docs site:
  {envpython} \
    {[python-cli-options]byteerrors} \
    {[python-cli-options]isolate} \
    -m sphinx \
    -j auto \
    -b html \
    {tty:--color} \
    -a \
    -n \
    -W --keep-going \
    -d "{temp_dir}{/}.doctrees" \
    . \
    "{envdir}{/}docs_out"

  # Print out the output docs dir and a way to serve html:
  -{envpython} \
  {[python-cli-options]byteerrors} \
  {[python-cli-options]isolate} \
  -c\
  'import pathlib;\
  docs_dir = pathlib.Path(r"{envdir}") / "docs_out";\
  index_file = docs_dir / "index.html";\
  print(f"\nDocumentation available under \
  `file://\{index_file\}`\n\nTo serve docs, use \
  `python3 -m http.server --directory \
  \N\{QUOTATION MARK\}\{docs_dir\}\N\{QUOTATION MARK\} 0`\n")'
depends =
  make-changelog
deps =
  -rrequirements{/}tox-docs.in
envdir = {toxworkdir}/build-docs

[testenv:doctest-docs]
allowlist_externals =
  {[testenv:build-docs]allowlist_externals}
basepython = {[testenv:build-docs]basepython}
description = Doctest The Docs
changedir = {[testenv:build-docs]changedir}
commands_pre =
commands =
  # Retrieve possibly missing commits:
  -git fetch --unshallow
  -git fetch --tags

  # Doctest docs site:
  {envpython} \
    {[python-cli-options]byteerrors} \
    {[python-cli-options]isolate} \
    -m sphinx \
    -j auto \
    -a -n -W \
    --keep-going \
    -b doctest --color \
    -d "{temp_dir}{/}.doctrees" \
    . "{toxworkdir}{/}docs_out"
deps =
  {[testenv:build-docs]deps}
envdir = {[testenv:build-docs]envdir}

[testenv:linkcheck-docs]
allowlist_externals =
  {[testenv:build-docs]allowlist_externals}
basepython = {[testenv:build-docs]basepython}
description = Linkcheck The Docs
changedir = {[testenv:build-docs]changedir}
commands_pre =
commands =
  # Retrieve possibly missing commits:
  -git fetch --unshallow
  -git fetch --tags

  # Linkcheck docs site:
  {envpython} \
    {[python-cli-options]byteerrors} \
    {[python-cli-options]isolate} \
    -m sphinx \
    -j auto \
    -a -n -W \
    --keep-going \
    -b linkcheck --color \
    -d "{temp_dir}{/}.doctrees" \
    . "{toxworkdir}{/}docs_out"
deps =
  {[testenv:build-docs]deps}
envdir = {[testenv:build-docs]envdir}

[testenv:spellcheck-docs]
allowlist_externals =
  {[testenv:build-docs]allowlist_externals}
basepython = {[testenv:build-docs]basepython}
description = Spellcheck The Docs
changedir = {[testenv:build-docs]changedir}
commands_pre =
commands =
  # Retrieve possibly missing commits:
  -git fetch --unshallow
  -git fetch --tags

  # Spellcheck docs site:
  {envpython} \
    {[python-cli-options]byteerrors} \
    {[python-cli-options]isolate} \
    -m sphinx \
    -j auto \
    -a -n -W \
    --keep-going \
    -b spelling --color \
    -d "{temp_dir}{/}.doctrees" \
    . "{toxworkdir}{/}docs_out"
deps =
  -rrequirements{/}tox-docs-linkcheck.in
envdir = {[testenv:build-docs]envdir}

[testenv:watch]
commands = ptw --runner=pytest

[testenv:pre-commit]
deps =
  -rrequirements{/}tox-pre-commit.in
commands_pre =
commands = pre-commit run --all-files --show-diff-on-failure {posargs}


[testenv:check-changelog]
basepython = {[testenv:make-changelog]basepython}
description =
  Check Towncrier change notes
commands_pre =
commands =
  {envpython} \
    {[python-cli-options]byteerrors} \
    {[python-cli-options]isolate} \
    -m towncrier.check \
    --compare-with origin/devel {posargs:}
deps =
  {[testenv:make-changelog]deps}
envdir = {[testenv:make-changelog]envdir}
isolated_build = {[testenv:make-changelog]isolated_build}
skip_install = {[testenv:make-changelog]skip_install}


[testenv:make-changelog]
basepython = python3
depends =
  check-changelog
description =
  Generate a changelog from fragments using Towncrier. Getting an
  unreleased changelog preview does not require extra arguments.
  When invoking to update the changelog, pass the desired version as an
  argument after `--`. For example, `tox -e {envname} -- 1.3.2`.
envdir = {[testenv:build-docs]envdir}
commands_pre =
commands =
  {envpython} \
    {[python-cli-options]byteerrors} \
    {[python-cli-options]isolate} \
    -m towncrier.build \
    --version \
    {posargs:'[UNRELEASED DRAFT]' --draft}
deps =
  {[testenv:build-docs]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
  # towncrier
  # -r{toxinidir}/docs/requirements.in
  # -c{toxinidir}/docs/requirements.txt
isolated_build = true
skip_install = true


[testenv:draft-changelog]
allowlist_externals =
  sh
basepython = {[testenv:make-changelog]basepython}
description =
  Print out the Towncrier-managed change notes
  draft for the next release to stdout
commands_pre =
commands =
  # NOTE: `sh` invocation is required to suppress stderr from
  # NOTE: towncrier since it does not have own CLI flags for
  # NOTE: doing this.
  sh -c "2>/dev/null \
    {envpython} \
    {[python-cli-options]byteerrors} \
    {[python-cli-options]isolate} \
    -m towncrier.build \
    --version '[UNRELEASED DRAFT]' \
    --draft"
envdir = {[testenv:make-changelog]envdir}
deps =
  {[testenv:make-changelog]deps}
isolated_build = {[testenv:make-changelog]isolated_build}
skip_install = {[testenv:make-changelog]skip_install}


[testenv:cleanup-dists]
description =
  Wipe the the dist{/} folder
usedevelop = false
skip_install = true
deps =
setenv =
  {[dists]setenv}
commands_pre =
commands =
  {envpython} \
  {[python-cli-options]byteerrors} \
  {[python-cli-options]isolate} \
  -c \
    'import os, shutil, sys; dists_dir = os.getenv("PEP517_OUT_DIR"); shutil.rmtree(dists_dir, ignore_errors=True); sys.exit(os.path.exists(dists_dir))'


[testenv:build-dists]
allowlist_externals =
  env
description =
  Build dists and put them into
  the `{env:PEP517_OUT_DIR}{/}` folder
depends =
  cleanup-dists
platform = darwin|linux
# NOTE: The custom command is here to allow resetting the global
# NOTE: pip constraints env var.
install_command =
  env PIP_CONSTRAINT= \
    {envpython} \
    {[python-cli-options]byteerrors} \
    {[python-cli-options]isolate} \
    {toxinidir}{/}bin{/}pip-wrapper \
    '{envname}' \
    '{toxinidir}{/}requirements{/}' \
    install {opts} {packages}
isolated_build = true
# `usedevelop = true` overrides `skip_install` instruction, it's unwanted
usedevelop = false
skip_install = true
deps =
  -rrequirements{/}tox-build-dists.in
passenv =
  PEP517_BUILD_ARGS
setenv =
  {[dists]setenv}
commands_pre =
commands =
  # Starting with build v0.5.0, it builds wheel from sdist
  # if no format arguments are passed. This makes sure that
  # wheels are not dependent on the Git repo or anything
  # external what may be missing from sdist.
  {envpython} \
    {[python-cli-options]byteerrors} \
    {[python-cli-options]isolate} \
    -m build \
    --outdir '{env:PEP517_OUT_DIR}{/}' \
    {posargs:{env:PEP517_BUILD_ARGS:}} \
    '{toxinidir}'


[testenv:metadata-validation]
description =
  Verify that dists under the `{env:PEP517_OUT_DIR}{/}` dir
  have valid metadata
depends =
  build-dists
deps =
  setuptools-scm
  twine
usedevelop = false
skip_install = true
commands_pre =
  {envpython} \
    {[python-cli-options]byteerrors} \
    {[python-cli-options]isolate} \
    -m setuptools_scm ls
setenv =
  {[dists]setenv}
commands =
  {envpython} \
    {[python-cli-options]byteerrors} \
    {[python-cli-options]isolate} \
    -m twine check \
    --strict \
    {env:PEP517_OUT_DIR}{/}*

[testenv:release]
skip_install = True
deps =
  pep517>=0.5
  twine>=1.13
  path.py
passenv =
  TWINE_PASSWORD
setenv =
  TWINE_USERNAME = {env:TWINE_USERNAME:__token__}
commands_pre =
commands =
  {envpython} \
    {[python-cli-options]byteerrors} \
    {[python-cli-options]isolate} \
    -c "import path; path.Path('dist').rmtree_p()"
  {envpython} \
    {[python-cli-options]byteerrors} \
    {[python-cli-options]isolate} -m pep517.build .
  {envpython} \
    {[python-cli-options]byteerrors} \
    {[python-cli-options]isolate} -m twine upload dist{/}*