tox.ini

; tox configuration file for running tests.
;
; The main trial based environments are defined based on a set of factors. Each
; factor will trigger a different behavior. Multiple factors can be set for the
; same environment:
;
; * alldeps - install all possible dependencies.
; * nodeps - avoid installing any dependencies apart from testing tools.
; * withcov - run the tests wrapped using the coverage.
; * nocov - run the tests directly, without using the coverage wrapper.
; * release-prepare - build the sdist and wheel distribution and run tests for them
; * posix - prepare the tests to be run in a Linux/Unix/macOS environment.
; * macos - prepare the tests to be run in a macOS 10.11+ environment (superset of posix)
; * windows - prepare the tests to be executed under Windows.
;
; See README.rst for example tox commands.
;
[tox]
minversion=3.24.1
requires=
    virtualenv>=20.7.2
    tox-wheel>=0.6.0
skip_missing_interpreters=True
envlist=lint, mypy,
    apidocs, narrativedocs, newsfragment,
    release-prepare,
    alldeps-nocov
isolated_build=true


[default]
; Files and directories that contain Python source for linting.
sources = setup.py src/ docs/conch/examples docs/mail/examples docs/names/examples docs/pair/examples docs/web/examples docs/words/examples
; These examples fail lint, see https://twistedmatrix.com/trac/ticket/9952
;   docs/core/examples

[testenv]
# Wheel based testing is required as part of our release process.
# If you remove the wheels from here, then also update the release
# process to generate its own wheels.
wheel = True
parallel_show_output = True
;; dependencies managed by extras in setup.cfg
extras =
    ; The "nodeps" build still depends on PyHamcrest.
    nodeps: test

    ; We also need to include `dev_release` so that we can test our
    ; release helpers or documentation generation, and `conch_nacl` so that
    ; we can test conch fallbacks to PyNaCl without requiring most users to
    ; install it.
    alldeps: all_non_platform, dev_release, conch_nacl

    windows: windows_platform

    alldeps-macos: osx_platform

    gtk: gtk_platform

    serial: serial

    {withcov}: dev

;; dependencies that are not specified as extras
deps =
    lint: pre-commit
    ; bugfix for https://github.com/sphinx-doc/sphinx/pull/9513/ on py310rc1
    alldeps: sphinx @ https://github.com/sphinx-doc/sphinx/archive/514fca7a407f03fae4c788178555a74256936655.tar.gz

; All environment variables are passed.
passenv = *

setenv =
    ; Enable sub-processes coverage reports and store coverage reports in a
    ; known location.
    COVERAGE_PROCESS_START = {toxinidir}/.coveragerc
    COVERAGE_FILE = {toxinidir}/.coverage
    # Help tests know where the base directory is.
    TOX_INI_DIR = {toxinidir}
    ; If serial or windows extras, force serial testing
    {windows,serial}: TWISTED_FORCE_SERIAL_TESTS = 1

skip_install =
    lint: True

commands =
    ;
    ; Display information about Python interpreter
    ; which will be used in subsequent steps
    ;
    python {toxinidir}/admin/dump_all_version_info.py

    posix: python -c "print('Running on POSIX (no special dependencies)')"

    ; Run tests without wrapping them using coverage.
    nocov: python -m twisted.trial --temp-directory={envtmpdir}/_trial_temp --reporter={env:TRIAL_REPORTER:verbose} {env:TRIAL_ARGS:-j8} {posargs:twisted}

    ; Run the tests wrapped using coverage.
    withcov: python {toxinidir}/admin/_copy.py {toxinidir}/admin/zz_coverage.pth {envsitepackagesdir}/zz_coverage.pth
    withcov: coverage erase
    withcov: coverage run -p --rcfile={toxinidir}/.coveragerc -m twisted.trial --temp-directory={envtmpdir}/_trial_temp --reporter={env:TRIAL_REPORTER:verbose} {env:TRIAL_ARGS:-j8} {posargs:twisted}

    lint: pre-commit {posargs:run --all-files --show-diff-on-failure}

    newsfragment: python {toxinidir}/bin/admin/check-newsfragment "{toxinidir}"


[testenv:towncrier]
description = Create the release notes from the current fragment files found in the source tree.

; towncrier needs Twisted install to get the version
; and dev_release requires the towncrier package.
extras =
    dev_release

commands =
    towncrier --yes


#
# `narrativedocs` environment is designed to build the complete documentation HTML files.
#
# It tries to run as close as possible to the Read The Docs environment, as
# that is the environment we use for the release.
#
[testenv:narrativedocs]
description = Build the full documentation (narrative and apidocs).

; Try to speed up the generation of the docs.
wheel = False
usedevelop = True
; Documentation needs Twisted install to get the version.
extras =
    dev_release

setenv =
    # Set this to `True` to run similar to Read The Docs.
    READTHEDOCS=False
    READTHEDOCS_LANGUAGE=en
    READTHEDOCS_VERSION=1.0.0.dev0

commands =
    sphinx-build -aW --keep-going -b html -d {toxinidir}/docs/_build {toxinidir}/docs {toxinidir}/docs/_build/


#
# `apidocs` environment is designed to build only the API doc HTML files.
#
# This is here to help during the development process and debugging.
# It is not used for the release.
#
# API docs build violation are visible to stdout.
#
# The resulting files can be viewed with web browsers from the local `apidocs`
# path.
[testenv:apidocs]
description = Build the API documentation and fail on any errors or warnings.

extras = dev_release
commands =
    # FIXME:https://github.com/twisted/twisted/issues/11590
    # After all the pydoctor errors are fixed, the tox should be updated
    # to fail on any pydoctor errors.
    # Remote the dash from the start of the command.
    - pydoctor src/twisted


[testenv:mypy]
description = run Mypy (static type checker)

extras = mypy
# https://github.com/twisted/incremental/pull/69
deps = incremental @ https://github.com/twisted/incremental/archive/refs/heads/trunk.tar.gz
commands =
    mypy                                       \
        --cache-dir="{toxworkdir}/mypy_cache"  \
        {tty:--pretty:}                        \
        {posargs:src}

;
; Create sdist and wheel packages and run basic tests on them.
; Makes the packages available in root `dist/` directory.
;
[testenv:release-prepare]
deps =
    pep517
    twine
    check-manifest>=0.44
whitelist_externals =
    cp
    rm
commands =
    check-manifest --ignore "docs/_build/**,docs/historic/**,admin/**,bin/admin/**"
    rm -rf {toxinidir}/dist
    cp -r {distdir} {toxinidir}/dist # copy the wheel built by tox-wheel
    {envpython} -m pep517.build --source --out-dir={toxinidir}/dist {toxinidir}
    twine check {toxinidir}/dist/*.*