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
    tox < 4
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 = 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 pyproject.toml
extras =
    ; The "nodeps" build still depends on PyHamcrest.
    nodeps: test

    ; FIXME:https://github.com/twisted/twisted/issues/11583
    ; Once we no longer have custom `towncrier` check the dev_release deps
    ; can be removed.
    ; We also need to include `dev_release` so that we can test our
    ; release helpers or documentation generation.
    alldeps: all_non_platform, dev_release

    windows: windows_platform

    alldeps-macos: osx_platform

    gtk: gtk_platform

    serial: serial

    {withcov}: dev
    newsfragment: dev

;; dependencies that are not specified as extras
deps =
    lint: pre-commit
    # This runs Twisted with minimum deps.
    # Designed to be used by our CI/CD.
    # You should keep this list in sync with the Twisted package definition.
    # Here you should pin the minimum version declared as supported.
    # IOCP is skipped since our CI is designed for Linux.
    mindeps: zope.interface == 5.0.0
    mindeps: constantly == 15.1
    mindeps: incremental == 24.7.0
    mindeps: Automat == 0.8.0
    mindeps: hyperlink == 17.1.1
    mindeps: attrs == 21.3.0
    mindeps: typing_extensions == 4.2.0
    # TLS
    mindeps: pyopenssl == 21.0.0
    mindeps: service_identity == 18.1.0
    mindeps: idna == 2.4
    # Conch
    mindeps: cryptography == 3.3
    mindeps: appdirs == 1.4.0
    mindeps: bcrypt == 3.1.3
    # HTTP
    mindeps: h2 == 3.0
    mindeps: priority == 1.1.0
    # Tesing minimum deps
    mindeps: cython-test-exception-raiser == 1.0.2
    mindeps: PyHamcrest == 2.0
    mindeps: hypothesis == 6.56

; 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 -m towncrier check --compare-with=origin/trunk


[testenv:benchmark]
description = Run the benchmarks.

deps =
    pytest-benchmark

extras =
    all_non_platform

commands =
    pytest benchmarks/ {posargs}


[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
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
whitelist_externals =
    cp
    rm
commands =
    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/*.*