tox.ini

[tox]

# --------------------------------------------------------------------
#
# NOTE(kgriffs,vytas): Python 3.8 or 3.10 are required when checking
# combined coverage. To check coverage:
#
#   $ tox
#
# You can then drill down into coverage details by opening the HTML
# report at ".coverage_html/index.html".
#
# --------------------------------------------------------------------

envlist = cleanup,
          ruff,
          pep8,
          mypy,
          mypy_tests,
          mintest,
          pytest,
          coverage,
          towncrier

[testenv]
# NOTE(vytas): Other Falcon-specific environment variables for automatic
#   wrapping of coroutines are set in tests/conftest.py.
setenv =
    PIP_CONFIG_FILE={toxinidir}/pip.conf
    PYTHONASYNCIODEBUG=1
    FALCON_DISABLE_CYTHON=Y
deps = -r{toxinidir}/requirements/tests
commands = python "{toxinidir}/tools/clean.py" "{toxinidir}/falcon"
           pytest tests []

# --------------------------------------------------------------------
# Miscellaneous tasks
# --------------------------------------------------------------------

[testenv:cleanup]
deps = {[testenv]deps}
commands = python "{toxinidir}/tools/clean.py" "{toxinidir}/falcon"
           coverage erase

[testenv:coverage]
deps = {[testenv]deps}
commands = coverage combine
           coverage html -d {toxinidir}/.coverage_html
           coverage report --fail-under 100

# --------------------------------------------------------------------
# ASGI servers
# --------------------------------------------------------------------

[testenv:daphne]
deps = {[testenv]deps}
       daphne

[testenv:hypercorn]
# TODO(vytas): Unpin Hypercorn once the buggy versions are yanked upstream.
deps = {[testenv]deps}
       hypercorn != 0.14.0, != 0.14.1

# --------------------------------------------------------------------
# Test without optional packages
# --------------------------------------------------------------------

[testenv:no_optional_packages]
deps = {[testenv]deps}
commands = python "{toxinidir}/tools/clean.py" "{toxinidir}/falcon"
           pip uninstall --yes python-rapidjson daphne orjson
           pytest tests []

# --------------------------------------------------------------------
# Coverage
# --------------------------------------------------------------------

[with-coverage]
commands = python "{toxinidir}/tools/clean.py" "{toxinidir}/falcon"
           coverage run -m pytest tests []

[testenv:mintest]
setenv =
    PIP_CONFIG_FILE={toxinidir}/pip.conf
    PYTHONASYNCIODEBUG=0
    FALCON_DISABLE_CYTHON=Y
deps = -r{toxinidir}/requirements/mintest
commands = coverage run -m pytest tests -k 'not slow' []

[testenv:pytest]
deps = {[testenv]deps}
       pytest-randomly
       jsonschema
commands = coverage run -m pytest tests []

[testenv:pytest_sans_msgpack]
deps = {[testenv]deps}
commands = pip uninstall --yes msgpack
           coverage run -m pytest tests -k "test_ws and test_msgpack_missing"

[testenv:py312]
basepython = python3.12
deps = {[testenv]deps}
       pytest-randomly
       jsonschema
commands = {[with-coverage]commands}

[testenv:py312_sans_msgpack]
basepython = python3.12
deps = {[testenv]deps}
commands = pip uninstall --yes msgpack
           coverage run -m pytest tests -k "test_ws and test_msgpack_missing"

[testenv:py312_nocover]
basepython = python3.12
deps = {[testenv]deps}
       pytest-randomly
       jsonschema
commands = pytest tests []

# --------------------------------------------------------------------
# Additional test suite environments
# --------------------------------------------------------------------

[testenv:pypy3]
basepython = pypy3

# --------------------------------------------------------------------
# Debugging
# --------------------------------------------------------------------

[with-debug-tools]
deps = -r{toxinidir}/requirements/tests
       pdbpp

[testenv:py3_debug]
basepython = python3.10
deps = {[with-debug-tools]deps}
       uvicorn
       jsonschema

# --------------------------------------------------------------------
# mypy
# --------------------------------------------------------------------

[testenv:mypy]
skipsdist = True
skip_install = True
deps = mypy
       types-jsonschema
commands = python {toxinidir}/tools/clean.py "{toxinidir}/falcon"
           mypy falcon

[testenv:mypy_tests]
deps = {[testenv]deps}
       mypy
       types-requests
       types-PyYAML
       types-ujson
       types-waitress
       types-aiofiles
       types-jsonschema
commands = python "{toxinidir}/tools/clean.py" "{toxinidir}/falcon"
           mypy e2e-tests/server
           mypy tests --allow-untyped-defs

# --------------------------------------------------------------------
# Cython
# --------------------------------------------------------------------

[with-cython]
# NOTE(vytas): Specify Cython dep for tests/test_cython.py as PEP 517 build
#   does not require it (although Tox seems to inject it in the current impl).
deps = -r{toxinidir}/requirements/tests
       Cython
setenv =
    PIP_CONFIG_FILE={toxinidir}/pip.conf
    FALCON_DISABLE_CYTHON=
    FALCON_ASGI_WRAP_NON_COROUTINES=Y
    FALCON_TESTING_SESSION=Y
    PYTHONASYNCIODEBUG=1
commands = pytest tests []

[testenv:py38_cython]
basepython = python3.8
deps = {[with-cython]deps}
setenv = {[with-cython]setenv}
commands = {[with-cython]commands}

[testenv:py39_cython]
basepython = python3.9
deps = {[with-cython]deps}
setenv = {[with-cython]setenv}
commands = {[with-cython]commands}

[testenv:py310_cython]
basepython = python3.10
deps = {[with-cython]deps}
setenv = {[with-cython]setenv}
commands = {[with-cython]commands}

[testenv:py311_cython]
basepython = python3.11
deps = {[with-cython]deps}
setenv = {[with-cython]setenv}
commands = {[with-cython]commands}

[testenv:py312_cython]
basepython = python3.12
# NOTE(vytas): pyximport relies on distutils.extension
deps = {[with-cython]deps}
       setuptools
setenv = {[with-cython]setenv}
commands = {[with-cython]commands}

[testenv:py313_cython]
basepython = python3.13
# NOTE(vytas): pyximport relies on distutils.extension
deps = {[with-cython]deps}
       setuptools
setenv = {[with-cython]setenv}
commands = {[with-cython]commands}

# --------------------------------------------------------------------
# WSGI servers (Cythonized Falcon)
# --------------------------------------------------------------------

[testenv:wsgi_servers]
setenv = {[with-cython]setenv}
deps = {[with-cython]deps}
       gunicorn
       # NOTE(caselit): meinheld requires greenlet<0.5 that's not compatible with py3.10
       meinheld
       uwsgi
       waitress
commands = pytest -v tests/test_wsgi_servers.py

# --------------------------------------------------------------------
# Smoke testing with a sample app
# --------------------------------------------------------------------

[smoke-test]
# NOTE(vytas): Work around pprofile's reliance on the removed use_2to3 option:
#   https://github.com/vpelletier/pprofile/issues/41
commands = pip install "setuptools < 58.0"
           pip install -r {toxinidir}/requirements/bench
           python -c "import falcon.asgi; falcon.asgi.App()"
           falcon-bench -t 1 -b falcon-ext

[testenv:py38_smoke]
# NOTE(caselit): vmprof requires python 3.8 https://github.com/vmprof/vmprof-python/issues/240
basepython = python3.8
deps =
commands = {[smoke-test]commands}

[testenv:py38_smoke_cython]
# NOTE(caselit): vmprof requires python 3.8 https://github.com/vmprof/vmprof-python/issues/240
basepython = python3.8
deps = cython
setenv = {[with-cython]setenv}
commands = {[smoke-test]commands}

# --------------------------------------------------------------------
# Lint
# --------------------------------------------------------------------

[testenv:pep8]
deps = ruff
commands = ruff check []

[testenv:ruff]
deps = ruff>=0.3.7
skip_install = True
commands = ruff format --check . []

[testenv:reformat]
deps = ruff>=0.3.7
skip_install = True
commands = ruff format . []

[testenv:pep8-docstrings]
deps = ruff
commands = ruff check \
             --exclude=.ecosystem,.eggs,.git,.tox,.venv,build,dist,docs,examples,tests,falcon/vendor,falcon/bench/nuts \
             --select=D205,D212,D400,D401,D403,D404 \
             []

[testenv:pep8-examples]
deps = ruff
commands = ruff check examples []

# --------------------------------------------------------------------
# For viewing environ dicts generated by various WSGI servers
# --------------------------------------------------------------------

[testenv:py310_dump_gunicorn]
basepython = python3.10
deps = gunicorn
commands = gunicorn -b localhost:8000 tests.dump_wsgi

[testenv:py310_dump_waitress]
basepython = python3.10
deps = waitress
commands = waitress-serve --listen=localhost:8000 tests.dump_wsgi:application

[testenv:py310_dump_wsgiref]
basepython = python3.10
commands = python tests/dump_wsgi.py

# --------------------------------------------------------------------
# Benchmarking
# --------------------------------------------------------------------

[testenv:py310_bench]
basepython = python3.10
deps = -r{toxinidir}/requirements/bench
commands = falcon-bench []

[testenv:py310_bench_cython]
basepython = python3.10
deps = -r{toxinidir}/requirements/bench
       cython
commands = falcon-bench []

[testenv:py38_bench]
basepython = python3.8
deps = -r{toxinidir}/requirements/bench
commands = falcon-bench []

[testenv:py38_bench_cython]
basepython = python3.8
deps = -r{toxinidir}/requirements/bench
       cython
commands = falcon-bench []

[testenv:pypy_bench]
basepython = pypy
deps = -r{toxinidir}/requirements/bench
commands = falcon-bench []

[testenv:pypy3_bench]
basepython = pypy3
deps = -r{toxinidir}/requirements/bench
commands = falcon-bench []

# --------------------------------------------------------------------
# Check for new versions of vendored packages
# --------------------------------------------------------------------

[testenv:check_vendored]
basepython = python3.10
allowlist_externals = {toxinidir}/tools/check-vendored.sh
deps =
commands = {toxinidir}/tools/check-vendored.sh

# --------------------------------------------------------------------
# Package sanity check with twine
# --------------------------------------------------------------------

[testenv:twine_check]
basepython = python3.10
skipsdist = True
deps = setuptools
       twine
       wheel
commands =
    python {toxinidir}/setup.py bdist_wheel sdist
    twine check {toxinidir}/dist/*

# --------------------------------------------------------------------
# Documentation
# --------------------------------------------------------------------

[testenv:docs]
basepython = python3.10
deps = -r{toxinidir}/requirements/docs
commands =
    sphinx-build -j auto -W -E -b html docs docs/_build/html []

# NOTE(vytas): importlib-resources is wreaking havoc by backporting future
#   removals from 3.13 (3.11 being the current stable at the time of writing);
#   hence we pin it manually here.
[testenv:towncrier]
deps = -r{toxinidir}/requirements/docs
        importlib-resources < 6.0
        toml
        towncrier
commands =
    python "{toxinidir}/tools/towncrier_draft.py" --dry-run

[testenv:changelog_release]
deps = -r{toxinidir}/requirements/docs
        toml
        towncrier
commands =
    python "{toxinidir}/tools/add_contributors.py"
    python "{toxinidir}/tools/towncrier_draft.py"

# NOTE(kgriffs): Renders the changelog to HTML so that the final result
#   can be previewed, but then restores the changelog RST document.
[testenv:changelog_draft]
deps = -r{toxinidir}/requirements/docs
        toml
        towncrier
commands =
    python "{toxinidir}/tools/add_contributors.py" --dry-run
    python "{toxinidir}/tools/towncrier_draft.py" --dry-run

[testenv:dash]
basepython = python3.10
setenv =
    DASHBUILD = True
deps = -r{toxinidir}/requirements/docs
commands =
    sphinx-build -j 4 -W -E -b html docs docs/_build/html []
    {toxinidir}/tools/generate_dash.sh

# --------------------------------------------------------------------
# Tutorial ("look") tests
# --------------------------------------------------------------------

[testenv:look]
deps =
    -r{toxinidir}/examples/look/requirements/test
commands =
    pytest {toxinidir}/examples/look/tests

# --------------------------------------------------------------------
# ASGI tutorial ("asgilook") tests
# --------------------------------------------------------------------

[testenv:asgilook]
basepython = python3.12
deps =
    -r{toxinidir}/examples/asgilook/requirements/asgilook
    -r{toxinidir}/examples/asgilook/requirements/test
commands =
    pytest \
        --cov asgilook \
        --cov-config {toxinidir}/examples/asgilook/.coveragerc \
        --cov-fail-under 100 \
        --cov-report term-missing \
        {toxinidir}/examples/asgilook/tests/

# --------------------------------------------------------------------
# WebSockets tutorial ("ws_tutorial") tests
# --------------------------------------------------------------------

[testenv:ws_tutorial]
basepython = python3.12
deps =
    -r{toxinidir}/examples/ws_tutorial/requirements/app
    -r{toxinidir}/examples/ws_tutorial/requirements/test
commands =
    pytest \
        --cov ws_tutorial \
        --cov-config {toxinidir}/examples/ws_tutorial/.coveragerc \
        --cov-fail-under 100 \
        --cov-report term-missing \
        {toxinidir}/examples/ws_tutorial/tests/

# --------------------------------------------------------------------
# Ecosystem
# --------------------------------------------------------------------

[testenv:hug]
basepython = python3.8
deps = virtualenv
commands =
     {toxinidir}/tools/testing/install_hug.sh
     {toxinidir}/tools/testing/test_hug.sh

# --------------------------------------------------------------------
# E2E tests
# --------------------------------------------------------------------

[testenv:e2e_chrome]
basepython = python3.10
deps =
    -r{toxinidir}/requirements/e2e
commands =
    pytest {toxinidir}/e2e-tests/ --browser=chrome

[testenv:e2e_firefox]
basepython = python3.10
deps =
    -r{toxinidir}/requirements/e2e
commands =
    pytest {toxinidir}/e2e-tests/ --browser=firefox

# --------------------------------------------------------------------
# Wheels stuff
# --------------------------------------------------------------------

[testenv:wheel_check]
basepython = python
skipsdist = True
skip_install = True
deps = setuptools>=44
       pytest
passenv = GITHUB_*
setenv =
    PYTHONASYNCIODEBUG=0
    PYTHONNOUSERSITE=1
    FALCON_ASGI_WRAP_NON_COROUTINES=Y
    FALCON_TESTING_SESSION=Y
    FALCON_DISABLE_CYTHON=Y
commands =
    pip uninstall --yes falcon
    pip install --find-links {toxinidir}/dist --no-index --ignore-installed falcon
    python --version
    python -c "import sys; sys.path.pop(0); from falcon.cyutil import misc, reader, uri"
    python .github/workflows/scripts/verify_tag.py {toxinidir}/dist
    pip install -r{toxinidir}/requirements/tests
    pytest -q tests []