tox.ini

[tox]
min_version = 4.6
# Set the envlist:
# Defines the environments that tox runs by default (when -e <environment> is not used)
#
# Default order of execution when using `tox` without `-e <environment>`:
#
# 1. pytest using python 3.11 for code coverage with diff-cover and mypy check
# 2. pytype (needs Python 3.10 or newer)
# 3. pylint and pyright checks (any modern Python version is fine)
#
# .github/workflows/main.yml is set up to test with 3.11, 3.12 and 3.13 in parallel.
# Therefore, use three environments: One with 3.11, one with 3.12 and one with 3.13:
#
envlist = py311-covcp-check-pytype-mdreport, py312-cov-docs, py313-cov-lint-pyright
isolated_build = true
skip_missing_interpreters = true
requires =
    tox-gh-actions

[test]
description = Run pytest in this environment with --cov for use in other stages
extras      = test
commands    =
    # https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md
    # https://github.com/actions/toolkit/blob/main/docs/commands.md#problem-matchers
    echo "::add-matcher::.github/workflows/PYTHONWARNINGS-problemMatcher.json"
    echo "::group::pytest"
    pytest --cov -v --new-first -x --show-capture=all -rA --junitxml={envlogdir}/junit.xml -o junit_family=legacy
    echo "::endgroup::"
    sh -c 'if [ -n "{env:PYTEST_MD_REPORT_OUTPUT}" -a -n "{env:GITHUB_STEP_SUMMARY}" ];then    \
      mkdir -p $(dirname "{env:GITHUB_STEP_SUMMARY:.git/sum.md}");                             \
      sed "s/tests\(.*py\)/[&](&)/"                                                            \
      {env:PYTEST_MD_REPORT_OUTPUT} >{env:GITHUB_STEP_SUMMARY:.git/sum.md};fi'

[testenv]
description = Run in a {basepython} virtualenv:
    cov:        {[cov]description}
    covcp:      Copy the generated .converage and coverage.xml to the UPLOAD_DIR dir
    docs:       {[docs]description}
    fox:        {[fox]description}
    lint:       {[lint]description}
    mdreport:   Make a test report (which is shown in the GitHub Actions Summary Page)
    test:       {[test]description}
    # See https://microsoft.github.io/pyright/#/configuration for more in pyright
    pyright:    Run pyright for static analyis
    check:      Run mypy for static analyis
    pytype:     Run pytype for static analyis, intro: https://youtu.be/abvW0mOrDiY
# checkers(mypy) need the pytest dependices as well:
extras =
    check: {[check]extras}
    pytype: {[pytype]extras}
    {lint,test,pyright,mdreport}: {[test]extras}
    {cov,covcp,fox}:              {[cov]extras}
deps =
    mdreport: pytest-md-report
    {cov,covcp,fox}: coverage[toml]
    {cov,covcp,fox}: diff-cover
    {lint,fox}: {[lint]deps}
    docs: {[docs]deps}
    pyright: pyright
allowlist_externals =
    {cov,covcp,fox,check,lint,test,mdreport}: echo
    {cov,covcp,fox,check,lint,test,mdreport}: sh
    {cov,covcp,fox}: cp
    check: cat
    docs: make
    fox: firefox
passenv =
    {pytype,lint,test}: GITHUB_STEP_SUMMARY
    pytype: GITHUB_SERVER_URL
    pytype: GITHUB_REPOSITORY
    pytype: GITHUB_HEAD_REF
    pytype: GITHUB_REF_NAME
    test: PYTEST_ADDOPTS
    test: PYTEST_XDIST_WORKER_COUNT
    cov: TESTS_COVERAGE_MIN
    cov: XCP_COVERAGE_MIN
    cov: DIFF_COVERAGE_MIN
    covcp: UPLOAD_DIR
    covcp: HOME
    check: MYPY_FORCE_COLOR
    check: MYPY_FORCE_TERMINAL_WIDTH
    {fox,check,pytype}: TERM
    fox: DISPLAY
    fox: XAUTHORITY
    fox: DBUS_SESSION_BUS_ADDRESS
setenv =
    LC_ALL=C           # Ensure that xcp is tested without an locale (like XAPI plugins)
    PYLINTHOME={envdir}/.pylinthome
    PYTHONDEVMODE=yes  # Enables development/resource checks: eg unclosed files and more
    PYTHONPATH=stubs
    # Inhibit dev-warnings on pytest plugins, but we enable dev-warnings in conftest.py
    PYTHONWARNINGS=ignore  # for our code, for full warnings except for pytest plugins
    COVERAGE_FILE={envlogdir}/.coverage
    mdreport: PYTEST_MD_REPORT=True
    mdreport: PYTEST_MD_REPORT_VERBOSE=0
    mdreport: PYTEST_MD_REPORT_COLOR=never
    mdreport: PYTEST_MD_REPORT_OUTPUT={envlogdir}/pytest-md-report.md
    mdreport: PYTEST_MD_REPORT_TEE=1
    mdreport: PYTEST_MD_REPORT_ZEROS=empty
    lint: ENVLOGDIR={envlogdir}
    {[cov]setenv}
commands =
    docs: {[docs]commands}
    lint: {[lint]commands}
    pyright: {[pyright]commands}
    check: {[check]commands}
    pytype: {[pytype]commands}
    {cov,covcp,check,fox,test,mdreport}: {[test]commands}
    {cov,covcp}: {[cov]commands}
    covcp: cp -av {envlogdir}/coverage.xml {envlogdir}/coverage.lcov {envlogdir}/.coverage {envlogdir}/junit.xml {env:UPLOAD_DIR:.}
    fox: {[cov]commands}
    fox: {[lint]commands}
    fox: {[fox]commands}

[cov]
description = Generate coverage html reports (incl. diff-cover) for this environment
setenv      = PY3_DIFFCOVER_OPTIONS=--ignore-whitespace --show-uncovered
extras      = coverage
    test
commands    =
    coverage xml  -o {envlogdir}/coverage.xml  --fail-under {env:XCP_COVERAGE_MIN:78}
    coverage lcov -o {envlogdir}/coverage.lcov
    coverage html -d {envlogdir}/htmlcov
    coverage html -d {envlogdir}/htmlcov-tests --fail-under {env:TESTS_COVERAGE_MIN:95} \
                      --include="tests/*"
    diff-cover --compare-branch=origin/master                                         \
      {env:PY3_DIFFCOVER_OPTIONS} --fail-under {env:DIFF_COVERAGE_MIN:92}             \
      --html-report  {envlogdir}/coverage-diff.html                                   \
                     {envlogdir}/coverage.xml


[docs]
description = Build the documentation to check for errors
deps = -r docs/requirements.txt
commands = make -C docs html SPHINXOPTS="--fail-on-warning"


[lint]
description = Run pylint and fail on warnings remaining on lines in the diff to master
deps = pylint
    diff-cover
    pandas
    tabulate
    toml
commands =
    python pylint_runner.py xcp tests
    diff-quality --compare-branch=origin/master --violations=pylint                   \
      --ignore-whitespace --fail-under 100                                            \
      --html-report  {envlogdir}/pylint-diff.html {envlogdir}/pylint.txt

[fox]
description = Generate pylint and coverage html reports and open them in firefox
commands = firefox   {envlogdir}/coverage-diff.html                                   \
                     {envlogdir}/htmlcov/index.html                                   \
                     {envlogdir}/htmlcov-tests/index.html                             \
                     {envlogdir}/pylint-warnings.txt                                  \
                     {envlogdir}/pylint-warnings-on-changed-lines.txt                 \
                     {envlogdir}/pylint-diff.html

# Map the github python versions to fators to run only matching envs from [tox]:envlist
# See https://github.com/ymyzk/tox-gh-actions for details:
# https://github.com/ymyzk/tox-gh-actions#tox-gh-actions-configuration
# The benefit of using tox is that all versions can be run locally and
# the local venvs will be the same as the venvs created by tox on the GitHub runners:
[gh-actions]
python =
    3.6: py36
    3.7: py37
    3.8: py38
    3.9: py39
    3.10: py310
    3.11: py311
    3.12: py312
    3.13: py313

[check]
extras = mypy
commands =
    mypy --txt-report {envlogdir}
    cat {envlogdir}/index.txt

[pycodestyle]
ignore = W191,W293,W504,E101,E126,E127,E201,E202,E203,E221,E222,E226,E227,E241,E251,E261,E262,E265,E301,E302,E303,E305,E722,W391,E401,E402,E741
max-line-length = 129

[pyright]
commands =
    pyright --version
    # To make pyright checks optional, change the next line to '-pyright':
    pyright

[pytype]
extras = pytype
description = Run pytype (note: It fails to find pytest_httpserver on 3.12!)
basepython = py311
commands =
    # Needs python >= 3.10: Needed to parse the newer syntax for "Type2 | Type2"
    pytype --version
    # Runs pytype -j auto -k --config .github/workflows/pytype.cfg and parses the output:
    python3 pytype_runner.py # When switching versions, update .github/workflows/pytype.cfg too!