开发和测试工具¶

毒理¶

tox 是一个受欢迎的包，大量的Python项目使用它作为测试和linting的标准入口点。

Sage将TOX作为标准包包含在内，并将其用于三个目的：

用于Sage发行版的可移植性测试，如我们在在多个平台上测试。这是在文件中配置的 SAGE_ROOT/tox.ini 。
用于测试Sage库的模块化发行版。这是在中配置的 tox.ini 的子目录中的文件 SAGE_ROOT/pkgs/ ，例如 SAGE_ROOT/pkgs/sagemath-standard/tox.ini 。每个发行版的配置定义了用于测试发行版的TOX环境，这些环境使用不同的Python版本和提供依赖项的不同方式。我们在中对此进行了解释打包Sage库以供分发。
作为测试和整理Sage库的入口点，如下所述。这是在文件中配置的 SAGE_ROOT/src/tox.ini 。

毒物检测结果 SAGE_ROOT/src/tox.ini 可以通过使用以下命令调用 ./sage --tox 。(如果 tox 在您的系统安装中可用，您只需键入 tox 相反。)

这种配置为各种测试/衬布方法提供了一个入口点，称为“毒素环境”。我们可以打字 ./sage --advanced 要查看可用的内容，请执行以下操作：

$ ./sage --advanced
SageMath version 9.2
...
Testing files:
...
--tox [options] <files|dirs> -- general entry point for testing
                                and linting of the Sage library
   -e <envlist>     -- run specific test environments; default:
                       doctest,coverage,startuptime,pycodestyle-minimal,relint,codespell,rst
      doctest                -- run the Sage doctester
                                (same as "sage -t")
      coverage               -- give information about doctest coverage of files
                                (same as "sage --coverage[all]")
      startuptime            -- display how long each component of Sage takes to start up
                                (same as "sage --startuptime")
      pycodestyle-minimal    -- check against Sage's minimal style conventions
      relint                 -- check whether some forbidden patterns appear
                                (includes all patchbot pattern-exclusion plugins)
      codespell              -- check for misspelled words in source code
      rst                    -- validate Python docstrings markup as reStructuredText
      coverage.py            -- run the Sage doctester with Coverage.py
      coverage.py-html       -- run the Sage doctester with Coverage.py, generate HTML report
      pyright                -- run the static typing checker pyright
      pycodestyle            -- check against the Python style conventions of PEP8
      cython-lint            -- check Cython files for code style
   -p auto          -- run test environments in parallel
   --help           -- show tox help

Doctest¶

该命令 ./sage -tox -e doctest 运行Sage文档测试器。这相当于使用命令 ./sage -t ；请参阅运行Sage‘s Doctest 。

备注

doctest 是一个特殊的毒性环境，它要求已经构建了Sage。虚拟环境是由tox创建的，但是在普通的Sage环境中调用Sage。

使用Coverage.py进行Doctest¶

该命令 ./sage -tox -e coverage.py 运行Sage文档测试器 (运行Sage‘s Doctest )在正常的Sage环境中，但在 Coverage.py 用于代码覆盖率分析。

如果被调用为 ./sage -tox -e coverage.py-html 此外，还会生成详细的HTML报告。

Configuration: [coverage:run] 阻止进入 SAGE_ROOT/src/tox.ini

Documentation: https://coverage.readthedocs.io

备注

coverage.py 是一个特殊的毒性环境，它要求已经构建了Sage。虚拟环境是由毒素创建的，但 coverage 将包安装到正常的Sage环境中，并从那里调用Sage。

覆盖范围¶

该命令 ./sage -tox -e coverage 检查每个函数是否至少有一个doctest(通常在 EXAMPLES 或 TESTS 块，请参见函数的文档字符串：Content )。

如果没有其他参数，此命令等同于使用命令 ./sage --coverageall 并为Sage库的每个模块提供了一份简短的报告，其中包含一行摘要。

如果使用参数调用，例如 ./sage -tox -e coverage -- src/sage/geometry src/sage/combinat/tableau.py ，它相当于使用命令 ./sage --coverage ，它包括给定文件或目录中模块的详细信息。

备注

coverage 是一个特殊的毒性环境，它要求已经构建了Sage。虚拟环境是由tox创建的，但是在普通的Sage环境中调用Sage。

启动时间¶

该命令 ./sage -tox -e startuptime 测量在Sage的启动阶段导入的每个模块的加载时间。它相当于使用命令 ./sage --startuptime 。

在没有其他参数的情况下，该命令会给出一个简短的报告，其中列出了对总启动时间贡献最长的模块，并按时间排序。

如果使用参数调用，例如 sage -tox -e startuptime -- sage.rings src/sage/geometry/polyhedron ，它提供有关给定模块、包、源文件或目录的详细信息。

备注

startuptime 是一个特殊的毒性环境，它要求已经构建了Sage。虚拟环境是由tox创建的，但是在普通的Sage环境中调用Sage。

Pycodestyle¶

Pycodestyle (以前称为Pep8)根据样式约定检查Python代码 PEP 8 。在第一次使用时，Tox会自动在单独的虚拟环境中安装pycodestyle。

Sage为pycodestyle定义了两种配置。该命令 ./sage -tox -e pycodestyle-minimal 在最低配置中使用pycodestyle。从Sage 9.5开始，整个Sage库符合以下配置：

$ ./sage -tox -e pycodestyle-minimal -- src/sage/
pycodestyle-minimal installed: pycodestyle==2.8.0
pycodestyle-minimal run-test-pre: PYTHONHASHSEED='28778046'
pycodestyle-minimal run-test: commands[0] | pycodestyle --select E401,E70,W605,E711,E712,E721 sage
___________ summary ____________
  pycodestyle-minimal: commands succeeded
  congratulations :)

在为SAGE票证准备分支机构时，开发人员应验证 ./sage -tox -e pycodestyle-minimal 传球。当Sage Patchbot在票据上运行时，它将执行类似的编码样式检查；但在本地运行检查将周转时间从几个小时减少到几秒钟。

第二个配置与命令一起使用 ./sage -tox -e pycodestyle 并运行更全面的检查：

$ ./sage -tox -e pycodestyle -- src/sage/quadratic_forms/quadratic_form.py
pycodestyle installed: pycodestyle==2.8.0
pycodestyle run-test-pre: PYTHONHASHSEED='2520226550'
pycodestyle run-test: commands[0] | pycodestyle sage/quadratic_forms/quadratic_form.py
sage/quadratic_forms/quadratic_form.py:135:9: E225 missing whitespace around operator
sage/quadratic_forms/quadratic_form.py:163:64: E225 missing whitespace around operator
sage/quadratic_forms/quadratic_form.py:165:52: E225 missing whitespace around operator
sage/quadratic_forms/quadratic_form.py:173:42: E228 missing whitespace around modulo operator
...
sage/quadratic_forms/quadratic_form.py:1620:9: E266 too many leading '#' for block comment
sage/quadratic_forms/quadratic_form.py:1621:9: E266 too many leading '#' for block comment
25      E111 indentation is not a multiple of 4
2       E117 over-indented
129     E127 continuation line over-indented for visual indent
1       E128 continuation line under-indented for visual indent
4       E201 whitespace after '['
4       E202 whitespace before ']'
2       E222 multiple spaces after operator
7       E225 missing whitespace around operator
1       E228 missing whitespace around modulo operator
25      E231 missing whitespace after ','
1       E262 inline comment should start with '# '
3       E265 block comment should start with '# '
62      E266 too many leading '#' for block comment
2       E272 multiple spaces before keyword
2       E301 expected 1 blank line, found 0
17      E303 too many blank lines (2)
ERROR: InvocationError for command .../pycodestyle sage/quadratic_forms/quadratic_form.py (exited with code 1)
___________ summary ____________
ERROR:   pycodestyle: commands failed

在为添加新代码的PR准备分支时，开发人员应该验证 ./sage -tox -e pycodestyle 不会对添加的代码发出警告。这将避免后来清理PR，因为Sage代码库正在朝着完全符合PEP8的方向发展。

另一方面，通常不建议在同一公关上将编码风格的修复与生产性更改混合在一起，因为这会使评审者更难评估更改。

通过传递选项 --count -qq 我们可以减少输出，使其只显示样式冲突警告的数量。这有助于规划侧重于一个或几个相关问题的编码式清理PR的工作：

$ ./sage -tox -e pycodestyle -- --count -qq src/sage
pycodestyle installed: pycodestyle==2.8.0
pycodestyle run-test-pre: PYTHONHASHSEED='3166223974'
pycodestyle run-test: commands[0] | pycodestyle --count -qq sage
557     E111 indentation is not a multiple of 4
1       E112 expected an indented block
194     E114 indentation is not a multiple of 4 (comment)
...
7       E743 ambiguous function definition 'l'
335     W291 trailing whitespace
4       W292 no newline at end of file
229     W293 blank line contains whitespace
459     W391 blank line at end of file
97797
ERROR: InvocationError for command .../pycodestyle --count -qq sage (exited with code 1)
___________ summary ____________
ERROR:   pycodestyle: commands failed

Installation: (手动使用：) pip install -U pycodestyle --user

Usage:

对毒素：见上文。
手册：运行 pycodestyle path/to/the/file.py 。
VS代码：默认情况下激活最低版本的pycodestyle SAGE_ROOT/.vscode/settings.json (the corresponding setting is "python.linting.pycodestyleEnabled": true). Note that the settings.json file is not ignored by Git so be aware to keep it in sync with the Sage repo on GitHub. For further details, see the official VS Code documentation 。

Configuration: [pycodestyle] 阻止进入 SAGE_ROOT/src/tox.ini

Documentation: https://pycodestyle.pycqa.org/en/latest/index.html

天鹅绒¶

Cython-lint 检查Cython源文件的编码样式。

拉夫¶

Ruff 是一个功能强大、速度快的PYTHON代码链接程序，用Rust编写。

它提供了大量可能的检查选择，并具有修复其发出的一些警告的能力。

Relint¶

Relint 检查所有源文件中是否有正则表达式指定的禁用文本模式。

我们的relint配置标记了一些过时的Python构造、可用的等效LaTeX命令时的普通TeX命令、文档标记中的常见错误以及模块化反模式。

Configuration: SAGE_ROOT/src/.relint.yml

Documentation: https://pypi.org/project/relint/

科德塞尔¶

Codespell 使用词典检查源代码中拼写错误的单词。

SAGE为Codesell：：定义了配置

$ ./sage -tox -e codespell -- src/sage/homology/
codespell installed: codespell==2.1.0
codespell run-test-pre: PYTHONHASHSEED='1285169064'
codespell run-test: commands[0] | codespell '--skip=*.png,*.jpg,*.JPG,*.inv,*.dia,*.pdf,*.ico,*#*,*~*,*.bak,*.orig,*.log,*.sobj,*.tar,*.gz,*.pyc,*.o,*.sws,*.so,*.a,.DS_Store' --skip=doc/ca,doc/de,doc/es,doc/hu,doc/ja,doc/ru,doc/fr,doc/it,doc/pt,doc/tr --skip=src/doc/ca,src/doc/de,src/doc/es,src/doc/hu,src/doc/ja,src/doc/ru,src/doc/fr,src/doc/it,src/doc/pt,src/doc/tr '--skip=.git,.tox,worktree*,dist,upstream,logs,local,cythonized,scripts-3,autom4te.cache,tmp,lib.*,*.egg-info' --dictionary=- --dictionary=/Users/mkoeppe/s/sage/sage-rebasing/src/.codespell-dictionary.txt --ignore-words=/Users/mkoeppe/s/sage/sage-rebasing/src/.codespell-ignore.txt sage/homology
sage/homology/hochschild_complex.py:271: mone ==> mono, money, none
sage/homology/hochschild_complex.py:277: mone ==> mono, money, none
sage/homology/hochschild_complex.py:280: mone ==> mono, money, none
sage/homology/chain_complex.py:2185: mor ==> more
sage/homology/chain_complex.py:2204: mor ==> more
sage/homology/chain_complex.py:2210: mor ==> more
sage/homology/chain_complex.py:2211: mor ==> more
sage/homology/chain_complex.py:2214: mor ==> more
sage/homology/chain_complex.py:2215: mor ==> more
ERROR: InvocationError for command .../codespell '--skip=*.png,...' --dictionary=- --dictionary=/Users/mkoeppe/s/sage/sage-rebasing/src/.codespell-dictionary.txt --ignore-words=/Users/mkoeppe/s/sage/sage-rebasing/src/.codespell-ignore.txt sage/homology (exited with code 65)
___________ summary ____________
ERROR:   codespell: commands failed

Configuration:

[testenv:codespell] block in SAGE_ROOT/src/tox.ini
SAGE_ROOT/src/.codespell-dictionary.txt and SAGE_ROOT/src/.codespell-ignore.txt

最高测试¶

Pytest 是一个测试框架。它作为可选程序包包含在Sage发行版中。

目前，Sage只使用非常有限的pytest来测试包 sage.numerical.backends 和中的一些模块 sage.manifolds 。

Installation:

./sage -i pytest pytest_xdist 。

Usage:

托克斯，Sage Doctester：在 ./sage -t (或 ./sage --tox -e doctest )，则自动调用PYTEST。
手册：运行 ./sage -pytest path/to/the/test_file.py 或 ./sage -pytest 来运行所有测试。另一个论点是 -n 可用于跨多个CPU分布测试，以加快测试执行速度。例如, ./sage -pytest -n 4 将并行运行4个测试，而 ./sage -pytest -n auto 将产生与可用CPU数量相等的工作进程数量。
VS代码：安装 Python extension and follow the offical VS Code documentation 。

Configuration: SAGE_ROOT/src/conftest.py

Documentation: https://docs.pytest.org/en/stable/index.html

皮赖特¶

Pyright 是静态类型检查器。

Installation:

(手动使用：) npm install -g pyright, see documentation 了解更多细节。

Usage:

毒物：跑步 ./sage -tox -e pyright path/to/the/file.py
手册：运行 pyright path/to/the/file.py 。如果要检查整个Sage库，很可能是默认设置的内存不足。您可以使用以下命令检查整个库：
```
NODE_OPTIONS="--max-old-space-size=8192" pyright
```
VS代码：安装 Pylance 分机。

Configuration: SAGE_ROOT/pyrightconfig.json

Documentation: Https://github.com/microsoft/pyright#documentation

火焰片¶

Pyflakes 检查常见的编码错误。

行动¶

act 是一个用Go编写的工具，使用Docker在本地运行GitHub操作；特别是，它加快了操作的开发速度。我们建议您使用 gh extension 要安装的设施 act 。**

[alice@localhost sage]$ gh extension install https://github.com/nektos/gh-act

有关将Docker配置为在本地运行操作所需的额外步骤，请访问 act's GitHub

在这里，我们给出一个非常短的样本 act 的功能。如果您安装了单机版 act ，则它应作为 act ，而不是 gh act 。在设置之后，例如可以列出所有可用的植绒动作：

[alice@localhost sage]$ gh act -l | grep lint
0      lint-pycodestyle        Code style check with pycodestyle                          Lint                                               lint.yml                push,pull_request
0      lint-relint             Code style check with relint                               Lint                                               lint.yml                push,pull_request
0      lint-rst                Validate docstring markup as RST                           Lint                                               lint.yml                push,pull_request
[alice@localhost sage]$

运行特定操作 lint-rst **

[alice@localhost sage]$ gh act -j lint-rst
...

诸若此类。

默认情况下， act 从下一个提取所需的所有数据，但它也可以缓存这些数据，从而大大加快了重复运行的速度。以下代码重复运行 lint-rst 使用缓存数据：：

[alice@localhost sage]$ gh act -p false -r -j lint-rst
[Lint/Validate docstring markup as RST]   Start image=catthehacker/ubuntu:act-latest
...
| rst: commands[0] /home/alice/work/software/sage/src> flake8 --select=RST
|   rst: OK (472.60=setup[0.09]+cmd[472.51] seconds)
|   congratulations :) (474.10 seconds)
...
[Lint/Validate docstring markup as RST]     Success - Main Lint using tox -e rst
[Lint/Validate docstring markup as RST]  Run Post Set up Python
[Lint/Validate docstring markup as RST]     docker exec cmd=[node /var/run/act/actions/actions-setup-python@v4/dist/cache-save/index.js] user= workdir=
[Lint/Validate docstring markup as RST]     Success - Post Set up Python
[Lint/Validate docstring markup as RST]   Job succeeded

这里 -p false 意味着使用已经拉出的Docker图像，以及 -r 意味着在使用Docker映像的成功运行后不要删除它们。可以通过运行以下命令找到这一点以及更多细节 gh act -h ，以及阅读 act 的文档。

开发和测试工具¶

毒理¶

Doctest¶

使用Coverage.py进行Doctest¶

覆盖范围¶

启动时间¶

Pycodestyle¶

天鹅绒¶

拉夫¶

Relint¶

科德塞尔¶

最高测试¶

皮赖特¶

火焰片¶

行动¶

目录

上一主题

下一主题