♥️贡献

感谢您的关注！Sanic一直在寻找贡献者。如果您对贡献代码、将文档字符串添加到源文件或帮助 Sanic User Guide 如能提供文档或实现示例，我们将不胜感激！

我们致力于为所有人提供友好、安全和欢迎的环境，无论性别、性取向、残疾、种族、宗教或类似的个人特征。我们的 code of conduct 设定行为标准。

安装

要在Sanic上进行开发(主要是运行测试)，强烈建议从源代码安装。

因此，假设您已经克隆了repo，并且在已设置虚拟环境的工作目录中，然后运行：

pip install -e ".[dev]"

依赖关系更改

Sanic 不使用 requirements*.txt 用于管理与之相关的任何依赖项的文件，以简化管理依赖项所需的工作。请确保您已阅读并理解文档中解释此方法的以下部分 sanic 管理中的依赖项 setup.py 文件。

相关性类型

使用

安装

要求

SANIC运行所需的最小裸依赖项

pip3 install -e .

测试要求/附加要求 [“测试”]

运行单元测试所需的依赖项 sanic

pip3 install -e '.[test]'

extras_require['dev']

增加贡献的额外开发需求

pip3 install -e '.[dev]'

extras_require['docs']

建立和增强SANIC文档所需的依赖性

pip3 install -e '.[docs]'

运行所有测试

为了运行Sanic的测试，建议使用如下毒素：

tox

就这么简单！

tox.ini 包含不同的环境。跑步 tox 如果没有任何参数，将运行所有unittests、执行lint和其他检查。

运行单元测试

tox environment -> [testenv]

要仅执行unittests，请运行 tox 在这样的环境下：

tox -e py37 -v -- tests/test_config.py
# or
tox -e py310 -v -- tests/test_config.py

运行绒布检查

tox environment -> [testenv:lint]

排列 flake8 , black 和 isort 检查。

tox -e lint

运行类型注记检查

tox environment -> [testenv:type-checking]

Permform mypy 支票。

tox -e type-checking

进行其他检查

tox environment -> [testenv:check]

执行其他检查。

tox -e check

运行静态分析

tox environment -> [testenv:security]

执行静态分析安全扫描

tox -e security

运行文档健全性检查

tox environment -> [testenv:docs]

对文档执行健全检查

tox -e docs

代码风格

为了保持代码的一致性，Sanic使用了以下工具。

  1. isort

  2. black

  3. flake8

  4. slotscheck

伊索尔特

isort 对Python导入进行排序。它将导入按字母顺序分为三类。

  1. 内置

  2. 第三方

  3. 特定项目

黑色

black 是一个Python代码格式化程序。

薄片8

flake8 是一个Python风格的指南，它将以下工具打包为一个工具。

  1. PyFlakes

  2. pycodestyle格式

  3. Ned Batchelder的McCabe脚本

时隙检查

slotscheck 确保不会出现任何问题 __slots__ (例如，基类中的重叠或缺少槽)。

isort ， black ， flake8 和 slotscheck 检查在执行期间执行 tox 皮棉支票。

这个 easiest 使您的代码符合的方法是在提交之前运行以下代码。

make pretty

参考 tox 有关详细信息的文档。

拉动请求

所以拉请求审批规则非常简单：

  1. 所有请求都必须通过单元测试。

  2. 所有Pull请求必须至少由Core Developer团队的一名现任成员审查和批准。

  3. 所有请求都必须通过flake8检查。

  4. 所有拉式请求必须匹配 isort 和 black 要求。

  5. 所有拉式请求必须是 PROPERLY 类型批注，除非给予豁免。

  6. 所有请求都必须与现有代码一致。

  7. 如果您决定从任何公共接口中删除/更改任何内容，则应根据我们的 deprecation policy 。

  8. 如果您实现了一个新特性，您应该至少有一个单元测试伴随它。

  9. 示例必须是以下之一：

    • 如何使用Sanic的示例

    • 如何使用Sanic扩展的示例

    • 如何使用Sanic和异步库的示例

文档

Sanic的API文档是使用 sphinx 使用以下命令自动生成模块引用 sphinx-apidoc 。

用户指南位于 sanic-guide 存储库。

要从头生成文档：

sphinx-apidoc -fo docs/_api/ sanic
sphinx-build -b html docs docs/_build

# There is a simple make command provided to ease the work required in generating
# the documentation
make docs

HTML文档将在 docs/_build 文件夹。

您可以运行以下命令来拥有包含API文档的实时开发服务器

make docs-serve

有关如何在其中做出贡献的文档，请参阅用户指南回购。

警告

Sanic的主要目标之一是速度。在可用性、安全性或特性方面没有显著提高的情况下降低Sanic性能的代码可能不会合并。请不要让这吓到你！如果您对某个想法有任何顾虑，请打开一个问题进行讨论并提供帮助。