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, ruff-minimal
# When adding environments above, also update the delegations in SAGE_ROOT/tox.ini
skipsdist = true

requires =
    # For the renamed "allowlist_externals" keyword, need >= 3.18
    # Because of https://github.com/tox-dev/tox/issues/3238, need <4.14.1
    tox>=3.18
    tox<4.14.1

[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.py-xml]
# https://coverage.readthedocs.io/en/latest/index.html
description =
    run the Sage doctester with Coverage.py, generate XML 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 xml -o "{envdir}/coverage.xml"

[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]
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,E275,E302,E303,E305,E306,E401,E502,E701,E702,E703,E71,E72,W291,W293,W391,W605 {posargs:{toxinidir}/sage/}
       pycodestyle --select E111,E271,E301,E302,E303,E305,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/}

[testenv:ruff]
description =
    check against Python style conventions
deps = ruff
passenv = RUFF_OUTPUT_FORMAT
commands = ruff check {posargs:{toxinidir}/sage/}

[testenv:ruff-minimal]
description =
    check against Sage's minimal style conventions
deps = ruff
# https://github.com/ChartBoost/ruff-action/issues/7#issuecomment-1887780308
passenv = RUFF_OUTPUT_FORMAT
# Output of currently failing, from "./sage -tox -e ruff -- --statistics":
#
#   3579        PLR2004 [ ] Magic value used in comparison, consider replacing `- 0.5` with a constant variable
#   3498        I001    [*] Import block is un-sorted or un-formatted
#   2146        F401    [*] `.PyPolyBoRi.Monomial` imported but unused
#   1964        E741    [ ] Ambiguous variable name: `I`
#   1676        F821    [ ] Undefined name `AA`
#   1513        PLR0912 [ ] Too many branches (102 > 12)
#   1159        PLR0913 [ ] Too many arguments in function definition (10 > 5)
#    815        E402    [ ] Module level import not at top of file
#    671        PLR0915 [ ] Too many statements (100 > 50)
#    483        PLW2901 [ ] Outer `for` loop variable `ext` overwritten by inner `for` loop target
#    433        PLR5501 [*] Use `elif` instead of `else` then `if`, to reduce indentation
#    428        PLR0911 [ ] Too many return statements (10 > 6)
#    404        E731    [*] Do not assign a `lambda` expression, use a `def`
#    351        F405    [ ] `ComplexField` may be undefined, or defined from star imports
#    306        PLR1714 [*] Consider merging multiple comparisons. Use a `set` if the elements are hashable.
#    236        F403    [ ] `from .abelian_gps.all import *` used; unable to detect undefined names
#    116        PLR0402 [*] Use `from matplotlib import cm` in lieu of alias
#    111        PLW0603 [ ] Using the global statement to update `AA_0` is discouraged
#     78        F841    [*] Local variable `B` is assigned to but never used
#     48        PLW0602 [ ] Using global for `D` but no assignment is done
#     33        PLR1711 [*] Useless `return` statement at end of function
#     24        E714    [*] Test for object identity should be `is not`
#     20        PLR1701 [*] Merge `isinstance` calls
#     17        PLW3301 [ ] Nested `max` calls can be flattened
#     16        PLW1510 [*] `subprocess.run` without explicit `check` argument
#     14        E721    [ ] Do not compare types, use `isinstance()`
#     14        PLW0120 [*] `else` clause on loop without a `break` statement; remove the `else` and dedent its contents
#     12        F811    [*] Redefinition of unused `CompleteDiscreteValuationRings` from line 49
#      8        PLC0414 [*] Import alias does not rename original package
#      7        E743    [ ] Ambiguous function name: `I`
#      7        PLR0124 [ ] Name compared with itself, consider replacing `a == a`
#      5        PLW0127 [ ] Self-assignment of variable `a`
#      4        F541    [*] f-string without any placeholders
#      4        PLW1508 [ ] Invalid type for environment variable default; expected `str` or `None`
#      3        PLC3002 [ ] Lambda expression called directly. Execute the expression inline instead.
#      2        E742    [ ] Ambiguous class name: `I`
#      2        PLE0302 [ ] The special method `__len__` expects 1 parameter, 3 were given
#      2        PLW0129 [ ] Asserting on a non-empty string literal will always pass
#      1        F402    [ ] Import `factor` from line 259 shadowed by loop variable
#      1        PLC0208 [*] Use a sequence type instead of a `set` when iterating over values
#
commands = ruff check --ignore E402,E721,E731,E741,E742,E743,F401,F402,F403,F405,F541,F811,F821,F841,I001,PLC0206,PLC0208,PLC0414,PLC2401,PLC3002,PLE0302,PLR0124,PLR0402,PLR0911,PLR0912,PLR0913,PLR0915,PLR1704,PLR1711,PLR1714,PLR1736,PLR2004,PLR5501,PLW0120,PLW0127,PLW0129,PLW0211,PLW0602,PLW0603,PLW0642,PLW1508,PLW1510,PLW2901,PLW3301 {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 builddir pkgs .git src/doc src/bin tools
addopts = --import-mode importlib
doctest_optionflags = NORMALIZE_WHITESPACE ELLIPSIS
# https://docs.pytest.org/en/stable/reference/reference.html#confval-consider_namespace_packages
consider_namespace_packages = True

[coverage:run]
source = sage
concurrency = multiprocessing,thread
data_file = .coverage/.coverage
disable_warnings = 
    no-data-collected
    module-not-measured

[coverage:report]
ignore_errors = True
skip_empty = True