tox.ini

## Configuration for tox.
## Needs tox installed in the system python.
##
## doctest:  Run the sage doctests.  From the SAGE_ROOT/src directory:
##
##     $ tox
##
##   Arguments are passed on to "sage -t":
##
##     $ tox sage/geometry
##
##   To pass on options to "sage -t", use -- to separate it from tox options:
##
##     $ tox -- --verbose --optional=sage,pynormaliz --long sage/geometry
##
## pycodestyle:
##
##     $ tox -e pycodestyle
##
##   Note that on the first run, tox automatically installs pycodestyle
##   in a virtual environment.
##
[tox]
envlist = doctest, coverage, startuptime, pycodestyle-minimal, relint, codespell, rst
# When adding environments above, also update the delegations in SAGE_ROOT/tox.ini
skipsdist = true

requires =
    # For the renamed "allowlist_externals" keyword
    tox>=3.18

[sagedirect]
# Base for tox environments that bypass the virtual environment set up by tox,
# calling sage directly.
passenv =
    HOME
setenv =
    SAGE={toxinidir}/../sage
envdir={toxworkdir}/sagedirect
allowlist_externals =
    {env:SAGE}

[testenv:doctest]
description =
    run the Sage doctester (same as "sage -t")
## This toxenv bypasses the virtual environment set up by tox.
passenv = {[sagedirect]passenv}
setenv  = {[sagedirect]setenv}
envdir  = {[sagedirect]envdir}
allowlist_externals = {[sagedirect]allowlist_externals}
commands =
    {env:SAGE} -t -p 0 {posargs:--all}

[testenv:coverage.py]
# https://coverage.readthedocs.io/en/latest/index.html
description =
    run the Sage doctester with Coverage.py
## This toxenv bypasses the virtual environment set up by tox.
passenv = {[sagedirect]passenv}
setenv  = {[sagedirect]setenv}
envdir  = {[sagedirect]envdir}
allowlist_externals = {[sagedirect]allowlist_externals}
commands_pre =
    {env:SAGE} -pip install -U coverage
commands =
    {env:SAGE} --python -m coverage run "{toxinidir}/../venv/bin/sage-runtests" -p 0 {posargs:--all}
commands_post =
    {env:SAGE} --python -m coverage combine
    {env:SAGE} --python -m coverage report

[testenv:coverage.py-html]
# https://coverage.readthedocs.io/en/latest/index.html
description =
    run the Sage doctester with Coverage.py, generate HTML report
## This toxenv bypasses the virtual environment set up by tox.
passenv = {[sagedirect]passenv}
setenv  = {[sagedirect]setenv}
envdir  = {[sagedirect]envdir}
allowlist_externals = {[sagedirect]allowlist_externals}
commands_pre =
    {env:SAGE} -pip install -U coverage
commands =
    {env:SAGE} --python -m coverage run "{toxinidir}/../venv/bin/sage-runtests" -p 0 {posargs:--all}
commands_post =
    {env:SAGE} --python -m coverage combine
    {env:SAGE} --python -m coverage report
    {env:SAGE} --python -m coverage html -d "{envdir}"

[testenv:coverage]
description =
    give information about doctest coverage of files
    (same as "sage --coverage[all]")
## This toxenv bypasses the virtual environment set up by tox.
passenv = {[sagedirect]passenv}
setenv  = {[sagedirect]setenv}
envdir  = {[sagedirect]envdir}
allowlist_externals = {[sagedirect]allowlist_externals}
commands =
    {env:SAGE} --coverage {posargs:--all}

[testenv:startuptime]
description =
    display how long each component of Sage takes to start up
    (same as "sage --startuptime")
## This toxenv bypasses the virtual environment set up by tox.
passenv = {[sagedirect]passenv}
setenv  = {[sagedirect]setenv}
envdir  = {[sagedirect]envdir}
allowlist_externals = {[sagedirect]allowlist_externals}
commands =
    {env:SAGE} --startuptime {posargs}

[testenv:pyright]
description =
    run the static typing checker pyright
deps = pyright
setenv =
    {[sagedirect]setenv}
    HOME={envdir}
    # Fix version, see .github/workflows/build.yml
    PYRIGHT_PYTHON_FORCE_VERSION=1.1.232
allowlist_externals = {[sagedirect]allowlist_externals}
## We run pyright from within the sage-env so that SAGE_LOCAL is available.
## pyright is already configured via SAGE_ROOT/pyrightconfig.json to use our venv.
##
## Running pyright on the whole Sage source tree takes very long
## and may run out of memory. When no files/directories are given, just run it
## on the packages that already have typing annotations.
commands =
    {env:SAGE} -sh -c 'pyright {posargs:{toxinidir}/sage/combinat {toxinidir}/sage/manifolds}'

[testenv:pycodestyle]
description =
    check against the Python style conventions of PEP8
deps = pycodestyle
commands = pycodestyle {posargs:{toxinidir}/sage/}

[testenv:pycodestyle-minimal]
## Note that the the pycodestyle linter provided by vscode checks against the
## same minimal conventions as defined below, see the file SAGE_ROOT/.vscode/settings.json.
description =
    check against Sage's minimal style conventions
    # Check for the following issues:
    # E111: indentation is not a multiple of four
    # E211: whitespace before '('
    # E271: multiple spaces after keyword
    # E305: expected 2 blank lines after class or function definition, found 1
    # E306: expected 1 blank line before a nested definition, found 0
    # E401: multiple imports on one line
    # E502 the backslash is redundant between brackets
    # E701: multiple statements on one line (colon)
    # E702: multiple statements on one line (semicolon)
    # E703: statement ends with a semicolon
    # E711: comparison to None should be ‘if cond is None:’
    # E712: comparison to True should be ‘if cond is True:’ or ‘if cond:’
    # E713 test for membership should be ’not in’
    # E721: do not compare types, use isinstance()
    # E722: do not use bare except, specify exception instead
    # W291: trailing whitespace
    # W293: blank line contains whitespace
    # W391: blank line at end of file
    # W605: invalid escape sequence ‘x’
    # See https://pycodestyle.pycqa.org/en/latest/intro.html#error-codes
deps = pycodestyle
commands = pycodestyle --select E111,E21,E221,E222,E225,E227,E228,E25,E271,E303,E305,E306,E401,E502,E701,E702,E703,E71,E72,W291,W293,W391,W605 {posargs:{toxinidir}/sage/}
       pycodestyle --select E111,E271,E301,E306,E401,E502,E703,E712,E713,E714,E72,W29,W391,W605, --filename *.pyx {posargs:{toxinidir}/sage/}

[pycodestyle]
max-line-length = 160
statistics = True

[testenv:relint]
description =
    check whether some forbidden patterns appear
# https://github.com/codingjoe/relint
# The patterns are in .relint.yml
deps = relint
allowlist_externals = find
commands = find {posargs:{toxinidir}/sage/} \
    -name "*\#*" -prune -o \
    -name "*.a" -prune -o \
    -name "*.bak" -prune -o \
    -name "*.bz2" -prune -o \
    -name "*.dia" -prune -o \
    -name "*.gz" -prune -o \
    -name "*.ico" -prune -o \
    -name "*.inv" -prune -o \
    -name "*.JPEG" -prune -o \
    -name "*.jpeg" -prune -o \
    -name "*.JPG" -prune -o \
    -name "*.jpg" -prune -o \
    -name "*.log" -prune -o \
    -name "*.o" -prune -o \
    -name "*.orig" -prune -o \
    -name "*.PDF" -prune -o \
    -name "*.pdf" -prune -o \
    -name "*.PNG" -prune -o \
    -name "*.png" -prune -o \
    -name "*.pyc" -prune -o \
    -name "*.so" -prune -o \
    -name "*.sobj" -prune -o \
    -name "*.sws" -prune -o \
    -name "*.tar" -prune -o \
    -name "*.tgz" -prune -o \
    -name "*.xz" -prune -o \
    -name "*.zip" -prune -o \
    -name "*~*" -prune -o \
    -name ".DS_Store" -prune -o \
    -exec relint -c {toxinidir}/.relint.yml \{\} +

[testenv:codespell]
description =
    check for misspelled words in source code
# https://pypi.org/project/codespell/
deps = codespell
commands = codespell \
    --skip="*\#*,*.a,*.bak,*.bz2,*.dia,*.gz,*.ico,*.inv,*.JPEG,*.jpeg" \
    --skip="*.JPG,*.jpg,*.log,*.o,*.orig,*.PDF,*.pdf,*.PNG,*.png,*.pyc" \
    --skip="*.so,*.sobj,*.sws,*.tar,*.tgz,*.xz,*.zip,*~*,.DS_Store" \
    --skip="doc/ca,doc/de,doc/es,doc/fr,doc/hu,doc/it,doc/ja,doc/pt,doc/ru,doc/tr" \
    --skip="src/doc/ca,src/doc/de,src/doc/es,src/doc/fr,src/doc/hu" \
    --skip="src/doc/it,src/doc/ja,src/doc/pt,src/doc/ru,src/doc/tr" \
    --skip=".git,.tox,autom4te.cache,cythonized,dist,lib.*,local" \
    --skip="logs,scripts-3,tmp,upstream,worktree*,*.egg-info" \
    --dictionary=- \
    --dictionary={toxinidir}/.codespell-dictionary.txt \
    --ignore-words={toxinidir}/.codespell-ignore.txt \
    {posargs:{toxinidir}/sage/}

[testenv:rst]
description =
    validate Python docstrings markup as reStructuredText
deps = flake8-rst-docstrings
commands = flake8 --select=RST {posargs:{toxinidir}/sage/}

[testenv:cython-lint]
description =
    check Cython files for code style
deps = cython-lint
commands = cython-lint --no-pycodestyle {posargs:{toxinidir}/sage/}

[flake8]
rst-roles =
    # Sphinx
    doc,
    file,
    ref,
    # Sphinx - https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#the-standard-domain (selection)
    envvar,
    # Sphinx - https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects
    attr,
    class,
    const,
    data,
    exc,
    func,
    kbd,
    meth,
    mod,
    obj,
    # from src/sage/misc/sagedoc.py
    arxiv,
    doi,
    mathscinet,
    oeis,
    pari,
    python,
    issue,
    wikipedia,
    common_lisp,
    ecl,
    gap,
    gap_package,
    giac_cascmd,
    giac_us,
    maxima,
    meson,
    polymake,
    ppl,
    qepcad,
    scip,
    singular,
    soplex
rst-directives =
    attribute,
    automethod,
    autofunction,
    toctree,
    MODULEAUTHOR,
    ONLY,
    PLOT,
    SEEALSO,
    TODO
extend-ignore =
    # Ignore RST306 Unknown target name -- because of references to the global bibliography
    RST306
exclude =
    # Avoid errors by exclude files with generated docstring portions such as {PLOT_OPTIONS_TABLE}
    sage/combinat/designs/database.py
    sage/graphs/graph_plot.py
    sage/misc/sagedoc.py

[pytest]
python_files = *_test.py
norecursedirs = local prefix venv build pkgs .git src/doc src/bin
addopts = --import-mode importlib
doctest_optionflags = NORMALIZE_WHITESPACE ELLIPSIS

[coverage:run]
source = sage
concurrency = multiprocessing
data_file = .coverage/.coverage
disable_warnings = no-data-collected

[coverage:report]
ignore_errors = True
skip_empty = True