tox.ini

# Tox (https://tox.readthedocs.io) is a tool for running tests
# in multiple virtualenvs.  This configuration file will run the tornado
# test suite on all supported python versions.  To use it, "pip install tox"
# and then run "tox" from this directory.
#
# This configuration requires tox 1.8 or higher.
#
# Installation tips:
# When building pycurl on my macports-based setup, I need to either set the
# environment variable ARCHFLAGS='-arch x86_64' or use
# 'port install curl +universal' to get both 32- and 64-bit versions of
# libcurl.
[tox]
envlist =
        # Basic configurations: Run the tests for each python version.
        py38-full,py39-full,py310-full,py311-full,py312-full,pypy3-full

        # Build and test the docs with sphinx.
        docs

        # Run the linters.
        lint

[testenv]
basepython =
           py3: python3
           py38: python3.8
           py39: python3.9
           py310: python3.10
           py311: python3.11
           py312: python3.12
           py313: python3.13
           pypy3: pypy3
           # In theory, it doesn't matter which python version is used here.
           # In practice, things like changes to the ast module can alter
           # the outputs of the tools (especially where exactly the
           # linter warning-suppression comments go), so we specify a
           # python version for these builds.
           # These versions must be synced with the versions in .github/workflows/test.yml
           docs: python3.11
           lint: python3.11

deps =
     full: pycurl
     full: twisted
     full: pycares
     docs: -r{toxinidir}/requirements.txt
     lint: -r{toxinidir}/requirements.txt

setenv =
       # Treat the extension as mandatory in testing (but not on pypy)
       {py3,py38,py39,py310,py311,py312,py313}: TORNADO_EXTENSION=1
       # CI workers are often overloaded and can cause our tests to exceed
       # the default timeout of 5s.
       ASYNC_TEST_TIMEOUT=25
       # Treat warnings as errors by default. We have a whitelist of
       # allowed warnings in runtests.py, but we want to be strict
       # about any import-time warnings before that setup code is
       # reached. Note that syntax warnings are only reported in
       # -opt builds because regular builds reuse pycs created
       # during sdist installation (and it doesn't seem to be
       # possible to set environment variables during that phase of
       # tox).
       {py3,py38,py39,py310,py311,py312,py313,pypy3}: PYTHONWARNINGS=error:::tornado
       # Warn if we try to open a file with an unspecified encoding.
       # (New in python 3.10, becomes obsolete when utf8 becomes the
       # default in 3.15)
       PYTHONWARNDEFAULTENCODING=1

# Allow shell commands in tests
allowlist_externals = sh, env


# Tox filters line-by-line based on the environment name.
commands =
         # py3*: -b turns on an extra warning when calling
         # str(bytes), and -bb makes it an error.
         python -bb -m tornado.test {posargs:}
         # Python's optimized mode disables the assert statement, so
         # run the tests in this mode to ensure we haven't fallen into
         # the trap of relying on an assertion's side effects or using
         # them for things that should be runtime errors.
         full: python -O -m tornado.test
         # Note that httpclient_test is always run with both client
         # implementations; this flag controls which client all the
         # other tests use.
         full: python -m tornado.test --httpclient=tornado.curl_httpclient.CurlAsyncHTTPClient
         full: python -m tornado.test --resolver=tornado.platform.caresresolver.CaresResolver

# python will import relative to the current working directory by default,
# so cd into the tox working directory to avoid picking up the working
# copy of the files (especially important for the speedups module).
changedir = {toxworkdir}

[testenv:docs]
changedir = docs
# For some reason the extension fails to load in this configuration,
# but it's not really needed for docs anyway.
setenv = TORNADO_EXTENSION=0
commands =
    # Build the docs
    sphinx-build -q -E -n -W -b html . {envtmpdir}/html
    # Ensure that everything is either documented or ignored in conf.py
    sphinx-build -q -E -n -W -b coverage . {envtmpdir}/coverage
    # Run the doctests
    sphinx-build -q -E -n -W -b doctest . {envtmpdir}/doctest

[testenv:lint]
commands =
         flake8 {posargs:}
         black --check --diff {posargs:tornado demos}
         # Many syscalls are defined differently on linux and windows,
         # so we have to typecheck both.
         # Mypy currently uses the default encoding so we must unset the warning variable
         # here (must be completely unset, not just set to zero/empty). Remove this
         # (and the allowlist_externals for env) when mypy sets the encoding explicitly.
         env -u PYTHONWARNDEFAULTENCODING mypy --platform linux {posargs:tornado}
         env -u PYTHONWARNDEFAULTENCODING mypy --platform windows {posargs:tornado}
         # We mainly lint on the oldest version of Python we support, since
         # we're more likely to catch problems of accidentally depending on
         # something new than of depending on something old and deprecated.
         # But sometimes something we depend on gets removed so we should also
         # test the newest version.
         env -u PYTHONWARNDEFAULTENCODING mypy --platform linux --python-version 3.13 {posargs:tornado}
changedir = {toxinidir}