[tox]
requires =
    tox >= 4
envlist =
    linting
    py310
    py311
    py312
    py313
    py314
    pypy3
    py310-{pexpect,xdist,twisted24,twisted25,asynctest,numpy,pluggymain,pylib}
    doctesting
    doctesting-coverage
    plugins
    py310-freeze
    docs
    docs-checklinks

    # checks that 3.11 native ExceptionGroup works with exceptiongroup
    # not included in CI.
    py311-exceptiongroup



[pkgenv]
# NOTE: This section tweaks how Tox manages the PEP 517 build
# NOTE: environment where it assembles wheels (editable and regular)
# NOTE: for further installing them into regular testenvs.
#
# NOTE: `[testenv:.pkg]` does not work due to a regression in tox v4.14.1
# NOTE: so `[pkgenv]` is being used in place of it.
# Refs:
# * https://github.com/tox-dev/tox/pull/3237
# * https://github.com/tox-dev/tox/issues/3238
# * https://github.com/tox-dev/tox/issues/3292
# * https://hynek.me/articles/turbo-charge-tox/
#
# NOTE: The `SETUPTOOLS_SCM_PRETEND_VERSION_FOR_PYTEST` environment
# NOTE: variable allows enforcing a pre-determined version for use in
# NOTE: the wheel being installed into usual testenvs.
pass_env =
  SETUPTOOLS_SCM_PRETEND_VERSION_FOR_PYTEST


[testenv]
description =
    run the tests
    coverage: collecting coverage
    exceptiongroup: against `exceptiongroup`
    nobyte: in no-bytecode mode
    lsof: with `--lsof` pytest CLI option
    numpy: against `numpy`
    pexpect: against `pexpect`
    pluggymain: against the bleeding edge `pluggy` from Git
    pylib: against `py` lib
    twisted24: against the unit test extras with twisted prior to 24.0
    twisted25: against the unit test extras with twisted 25.0 or later
    asynctest: against the unit test extras with asynctest
    xdist: with pytest in parallel mode
    under `{basepython}`
    doctesting: including doctests
commands =
    {env:_PYTEST_TOX_COVERAGE_RUN:} pytest {posargs:{env:_PYTEST_TOX_DEFAULT_POSARGS:}}
    doctesting: {env:_PYTEST_TOX_COVERAGE_RUN:} pytest --doctest-modules --pyargs _pytest
    coverage: coverage combine
    coverage: coverage report -m
passenv =
    COVERAGE_*
    PYTEST_ADDOPTS
    TERM
    CI
setenv =
    _PYTEST_TOX_DEFAULT_POSARGS={env:_PYTEST_TOX_POSARGS_DOCTESTING:} {env:_PYTEST_TOX_POSARGS_LSOF:} {env:_PYTEST_TOX_POSARGS_XDIST:} {env:_PYTEST_FILES:}

    # See https://docs.python.org/3/library/io.html#io-encoding-warning
    # If we don't enable this, neither can any of our downstream users!
    # pylib is not PYTHONWARNDEFAULTENCODING clean, so don't set for it.
    !pylib: PYTHONWARNDEFAULTENCODING=1

    # Configuration to run with coverage similar to CI, e.g.
    # "tox -e py313-coverage".
    coverage: _PYTEST_TOX_COVERAGE_RUN=coverage run -m
    coverage: _PYTEST_TOX_EXTRA_DEP=coverage-enable-subprocess
    coverage: COVERAGE_FILE={toxinidir}/.coverage
    coverage: COVERAGE_PROCESS_START={toxinidir}/.coveragerc

    doctesting: _PYTEST_TOX_POSARGS_DOCTESTING=doc/en

    # The configurations below are related only to standard unittest support.
    # Run only tests from test_unittest.py.
    asynctest: _PYTEST_FILES=testing/test_unittest.py
    twisted24: _PYTEST_FILES=testing/test_unittest.py
    twisted25: _PYTEST_FILES=testing/test_unittest.py

    nobyte: PYTHONDONTWRITEBYTECODE=1

    lsof: _PYTEST_TOX_POSARGS_LSOF=--lsof

    xdist: _PYTEST_TOX_POSARGS_XDIST=-n auto
extras = dev
deps =
    doctesting: PyYAML
    exceptiongroup: exceptiongroup>=1.0.0rc8
    numpy: numpy>=1.19.4
    pexpect: pexpect>=4.8.0
    pluggymain: pluggy @ git+https://github.com/pytest-dev/pluggy.git
    pylib: py>=1.8.2
    twisted24: twisted<25
    twisted25: twisted>=25
    asynctest: asynctest
    xdist: pytest-xdist>=2.1.0
    xdist: -e .
    {env:_PYTEST_TOX_EXTRA_DEP:}
# Can use the same wheel for all environments.
package = wheel
wheel_build_env = .pkg

[testenv:linting]
description =
    run pre-commit-defined linters under `{basepython}`
skip_install = True
deps = pre-commit>=2.9.3
commands = pre-commit run --all-files --show-diff-on-failure {posargs:}
setenv =
    # pre-commit and tools it launches are not clean of this warning.
    PYTHONWARNDEFAULTENCODING=

[testenv:docs]
description =
    build the documentation site under \
    `{toxinidir}{/}doc{/}en{/}_build{/}html` with `{basepython}`
basepython = python3.13 # Sync with .readthedocs.yaml to get errors.
usedevelop = True
deps =
    -r{toxinidir}/doc/en/requirements.txt
commands =
    sphinx-build \
      -j auto \
      -W --keep-going \
      -b html doc/en doc/en/_build/html \
      {posargs:}
setenv =
    # Sphinx is not clean of this warning.
    PYTHONWARNDEFAULTENCODING=

[testenv:docs-checklinks]
description =
    check the links in the documentation with `{basepython}`
usedevelop = True
changedir = doc/en
deps = -r{toxinidir}/doc/en/requirements.txt
commands =
    sphinx-build -W -q --keep-going -b linkcheck . _build
setenv =
    # Sphinx is not clean of this warning.
    PYTHONWARNDEFAULTENCODING=

[testenv:regen]
description =
    regenerate documentation examples under `{basepython}`
changedir = doc/en
deps =
    PyYAML
    regendoc>=0.8.1
    sphinx
allowlist_externals =
    make
commands =
    make regen
setenv =
    # We don't want this warning to reach regen output.
    PYTHONWARNDEFAULTENCODING=
    # Remove CI markers: pytest auto-detects those and uses more verbose output, which is undesirable
    # for the example documentation.
    CI=
    BUILD_NUMBER=

[testenv:plugins]
description =
    run reverse dependency testing against pytest plugins under `{basepython}`
# use latest versions of all plugins, including pre-releases
pip_pre=true
# use latest pip to get new dependency resolver (#7783)
download=true
install_command=python -m pip install {opts} {packages}
changedir = testing/plugins_integration
deps = -rtesting/plugins_integration/requirements.txt
setenv =
    PYTHONPATH=.
commands =
    pip check
    pytest bdd_wallet.py
    pytest --cov=. simple_integration.py
    pytest --ds=django_settings simple_integration.py
    pytest --html=simple.html simple_integration.py
    pytest --reruns 5 simple_integration.py pytest_rerunfailures_integration.py
    pytest pytest_anyio_integration.py
    pytest pytest_asyncio_integration.py
    pytest pytest_mock_integration.py
    pytest pytest_trio_integration.py
    pytest pytest_twisted_integration.py
    pytest simple_integration.py --force-sugar --flakes

[testenv:py310-freeze]
description =
    test pytest frozen with `pyinstaller` under `{basepython}`
changedir = testing/freeze
deps =
    pyinstaller
commands =
    {envpython} create_executable.py
    {envpython} tox_run.py

[testenv:release]
description = do a release, required posarg of the version number
usedevelop = True
passenv = *
deps =
    colorama
    pre-commit>=2.9.3
    towncrier
commands = python scripts/release.py {posargs}

[testenv:prepare-release-pr]
description = prepare a release PR from a manual trigger in GitHub actions
usedevelop = {[testenv:release]usedevelop}
passenv = {[testenv:release]passenv}
deps = {[testenv:release]deps}
commands = python scripts/prepare-release-pr.py {posargs}

[testenv:generate-gh-release-notes]
description = generate release notes that can be published as GitHub Release
usedevelop = True
deps =
    pypandoc_binary
commands = python scripts/generate-gh-release-notes.py {posargs}

[testenv:update-plugin-list]
description = update the plugin list
skip_install = True
deps =
    packaging
    requests
    tabulate[widechars]
    tqdm
    requests-cache
    platformdirs
commands = python scripts/update-plugin-list.py {posargs}