Sanic 贡献指南从源码安装到测试、代码规范与 PR 流程的完整实践手册【免费下载链接】sanicAccelerate your web app development | Build fast. Run fast.项目地址: https://gitcode.com/gh_mirrors/sa/sanic导读本文基于 Sanic 官方贡献指南仓库内 CONTRIBUTING.md 及其完整版 guide/content/en/organization/contributing.md编写系统讲解如何以源码方式搭建 Sanic 开发环境、理解其依赖管理策略、使用 tox 运行单元测试与各类质量检查以及通过 Pull Request 向 Sanic 提交代码时必须遵守的规范。读完本文你将掌握一套可直接落地执行的 Sanic 本地开发、测试与提交工作流并理解这些流程背后的源码与配置依据。说明仓库根目录的 CONTRIBUTING.md 仅有两行内容并指向官方站点完整贡献指南的实际全文位于 guide/content/en/organization/contributing.md本文以该完整文档为主体展开。参与方式不只是写代码Sanic 社区欢迎各种形式的贡献。官方指南明确指出如果你不习惯提交代码为源码文件补充 docstring、或为 Sanic 用户指南 提供文档与实现示例同样是备受珍视的贡献方式。这意味着贡献门槛被刻意降低——文档编写、示例补充与代码提交在社区中享有同等价值。此外Sanic 承诺为所有参与者提供友好、安全、包容的环境无论其性别、性取向、残障、种族、宗教或个人特征如何。相应的行为标准由 CODE_OF_CONDUCT.md 规定其完整内容同样位于 guide/content/en/organization/code-of-conduct.md涵盖承诺Our Pledge、行为标准Our Standards、维护者职责、适用范围Scope、执行机制Enforcement等条款要求参与者使用包容性语言、尊重不同观点、优雅接受建设性批评并禁止骚扰、贬损性评论、未经许可公开他人隐私等行为。环境准备从源码安装开发版要进行 Sanic 的本地开发尤其是运行测试官方强烈推荐从源码安装。假设你已经克隆了仓库并进入工作目录且已创建好虚拟环境只需执行pip install -e .[dev]-e表示以可编辑editable模式安装源码改动会即时生效无需重复安装.[dev]则安装包含完整开发依赖的 extras。安装完成后sanic命令即来自 setup.py 中注册的入口点sanic sanic.__main__:main。从 setup.py 的源码看Sanic 的最低运行依赖install_requires包括sanic-routing23.12.0、httptools0.0.10、aiofiles、websockets、multidict、html5tagger、tracerite、typing-extensions等其中uvloop与ujson通过环境标记仅安装在 CPython 且非 Windows 平台见 setup.py。环境变量的可选影响安装脚本支持两个可选环境变量来剥离加速依赖见 setup.pySANIC_NO_UJSON1不安装 uJSON同时移除对应的types_ujson类型存根SANIC_NO_UVLOOP1不安装 uvLoop。这两个开关在 tox 的-no-ext测试环境中会被显式设置见 tox.ini用于验证 Sanic 在无这些加速库时的兼容性。依赖管理策略setup.py 而非 requirements*.txtSanic不使用requirements*.txt文件管理任何依赖这是刻意的设计目的是简化依赖维护的复杂度。所有依赖关系都集中在 setup.py 中通过extras_require声明。官方文档给出了清晰的分类表依赖类型用途安装方式requirements基础依赖Sanic 运行所需的最小依赖集pip3 install -e .tests_require / extras_require[test]运行 Sanic 单元测试所需的依赖pip3 install -e .[test]extras_require[dev]参与贡献所需的额外开发依赖pip3 install -e .[dev]extras_require[docs]构建与增强 Sanic 文档所需依赖pip3 install -e .[docs]对照 setup.py 的源码这一结构完全吻合tests_require包含sanic-testing23.6.0、pytest8.2.2、pytest-xdist3.5.0、pytest-cov、coverage、beautifulsoup4、pytest-sanic、pytest-benchmark、chardet3.*、ruff、bandit、mypy、slotscheck0.8.0,1等dev_require tests_require [cryptography, tox, towncrier]——即在测试依赖之上追加 tox测试编排与 towncrierchangelog 生成docs_require则包含sphinx2.1.2、sphinx_rtd_theme、m2r2、enum-tools[sphinx]、mistune、autodocsumm、msgspec、python-frontmatter、docstring-parser、libsass等文档构建工具此外还有extsanic-ext、http3aioquic等额外 extras。由于dev依赖基于tests_require拼接pip install -e .[dev]一次性覆盖了测试与开发所需的全部工具链。用 tox 运行测试与质量检查Sanic 的测试与质量检查全部由 tox.ini 编排官方推荐直接运行tox不传参数时tox 会按envlist依次执行所有环境见 tox.inipy310, py311, py312, py313, py314, pyNightly, pypy310各 Python 版本的测试环境以及对应的-no-ext变体、lint、check、security、docs、type-checking。也就是说一次tox会跑完全部单元测试、代码风格检查及其他校验。tox 的基础测试环境[testenv]配置了extras test, http3并以pytest -n 3 --dist loadgroup {posargs:tests}并行执行测试见 tox.ini。下面按官方文档逐一说明各专用环境。运行单元测试对应 tox 环境[testenv]及各 Python 版本专属环境如py310等。tox -e py37 -v -- tests/test_config.py # 或 tox -e py310 -v -- tests/test_config.py其中-v输出详细信息--之后的参数会透传给 pytest因此可以指定单个测试文件甚至单个用例来快速迭代。注意当前仓库 setup.py 声明python_requires 3.10tox 的envlist也是py310起的版本矩阵因此实际可用的环境以本机已安装的 Python 版本为准如py310、py311等。运行 lint 检查对应 tox 环境[testenv:lint]。官方文档说明 lint 执行flake8、black与isort检查命令为tox -e lint对照 tox.ini 的当前实现lint 环境实际执行的命令是ruff check sanic、ruff format sanic --check与slotscheck --verbose -m sanic——即风格检查已统一迁移到 ruff、sanic/base/meta.py、sanic/blueprints.py、sanic/middleware.py、sanic/response/types.py、sanic/server/async_server.py 等文件均包含__slots__声明。运行类型注解检查对应 tox 环境[testenv:type-checking]执行mypy检查见 tox.initox -e type-checkingSanic 对类型注解要求严格——PR 规范中明确要求代码正确地进行类型注解这正是mypy sanic检查的意义所在。运行其他检查对应 tox 环境[testenv:check]执行打包元数据校验见 tox.initox -e check其实际命令为python setup.py check -r -s即检查setup.py中声明的依赖-r与元数据-s是否完整合法。运行静态安全分析对应 tox 环境[testenv:security]执行 bandit 安全扫描见 tox.initox -e security命令为bandit --recursive sanic -b ./bandit.baseline其中-b ./bandit.baseline指定基线文件允许已确认的已知告警不再重复报告从而让新引入的安全问题更容易被暴露。基线文件位于仓库根目录 bandit.baseline。运行文档健全性检查对应 tox 环境[testenv:docs]对文档做健全性检查见 tox.initox -e docs该环境仅限 Linux/macOS 平台安装docs, http3extras 后执行make docs-test。仓库 Makefile 中docs-test目标会先执行docs-clean再在docs目录下执行make dummy以验证文档可被正确构建且无引用错误。代码风格四件套与 make pretty为保持代码一致性Sanic 使用以下工具isort对 Python import 排序将导入分为内置built-in、第三方third-party、项目内project-specific三类各类内部按字母序排列blackPython 代码格式化器统一代码排版flake8Python 风格检查器聚合了 PyFlakes、pycodestyle 与 Ned Batchelder 的 McCabe 脚本复杂度检查slotscheck确保__slots__定义没有问题例如槽位重叠、基类缺失槽位等。需要强调的是isort、black、flake8、slotscheck 这四项检查都会在tox -e lint中执行。虽然当前仓库的 lint 命令已用ruff统一取代 isort/black/flake8 的调用见 tox.ini但检查目标完全一致——导入排序、代码格式化与风格合规。提交前的捷径make pretty官方文档给出的最简单方式是在提交前运行make pretty查看仓库 Makefile 可知pretty目标实际由两部分组成fix: ruff check ${RUFF_FORMATTED_FOLDERS} --fix format: ruff format ${RUFF_FORMATTED_FOLDERS} pretty: format fix其中RUFF_FORMATTED_FOLDERS sanic examples scripts tests guide docs见 Makefile即make pretty会对源码、示例、脚本、测试、文档等全部目录先执行ruff format再执行ruff check --fix自动修复大部分格式与风格问题。与之配套的还有make fix仅修复 lint、make format仅格式化等目标。Pull Request 提交规则官方文档给出了清晰的 PR 批准规则共 9 条所有 PR 必须通过单元测试所有 PR 必须经过至少一位当前 Core Developer 团队成员审阅并批准所有 PR 必须通过 flake8 检查当前对应 tox.ini 中lint环境的ruff check sanic所有 PR 必须满足 isort 与 black 要求当前对应ruff format sanic --check所有 PR 必须正确地进行类型注解除非获得豁免所有 PR 必须与现有代码保持一致若要从任何公共接口删除/更改内容必须依据弃用政策附上弃用消息deprecation message若实现新功能必须至少附带一个单元测试示例必须属于以下类别之一展示如何使用 Sanic展示如何使用 Sanic 扩展展示如何将 Sanic 与异步库结合使用。仓库中 examples 目录正是第 9 条的直观体现——例如 examples/hello_world.pySanic 基础用法、examples/authorized_sanic.py 与 examples/logdna_example.py扩展集成、examples/limit_concurrency.py异步并发场景等。弃用消息的源码实现第 7 条提到的弃用机制在源码层有对应实现。Sanic 在 sanic/logging/deprecation.py 提供deprecation(message, version)工具函数其 docstring 明确要求当功能即将被移除时version参数至少应为下一个版本号 2函数会以[DEPRECATION vX.Y]前缀的格式输出告警信息并触发DeprecationWarning颜色化输出见源码中Colors.RED/Colors.YELLOW的应用。而弃用政策进一步规定在功能被弃用或引入破坏性 API 变更之前必须对外公开并通过两个发布周期持续显示弃用警告LTS 版本中不得进行任何弃用。仅当绝对必要例如为遏制重大安全问题时别无替代方案才可绕过该流程。文档与示例贡献官方指南中Documentation一节目前标注为Check back. We are reworking our documentation so this will change.文档正在重构中此部分将有所变化表明 Sanic 团队正在重新整理文档体系。当前仓库的文档主要由两部分构成docs 目录基于 Sphinx 的 API 文档docs/conf.py涵盖 app、blueprints、router、server 等 API 参考guide 目录用户指南内容覆盖入门、基础、进阶、部署、插件等主题例如 guide/content/en/guide/getting-started.md、guide/content/en/guide/basics/app.md 等。通过 Makefile 的make docs、make docs-test、make docs-serve目标可以分别构建文档、做健全性测试、或启动本地文档预览服务sphinx-autobuild docs docs/_build/html --port 9999 --watch ./见 Makefile。若你选择以文档或示例的方式参与贡献这些命令就是你的主要工具。一站式贡献工作流总结综合全文一次完整的 Sanic 贡献流程可以归纳为准备环境克隆仓库、创建虚拟环境执行pip install -e .[dev]安装全部开发依赖编写/修改代码遵循 Sanic 的代码风格为新功能补充单元测试必要时添加符合弃用政策的弃用消息本地自检运行make pretty自动格式化与修复风格问题运行tox -e py310 -v -- tests/xxx.py聚焦验证改动相关的测试运行tox -e lint、tox -e type-checking确认风格与类型检查通过全量验证提交 PR 前运行tox跑完全部环境的单元测试与质量检查必要时单独执行tox -e security与tox -e docs提交 PR确保改动通过全部单元测试、获得至少一位 Core Developer 审阅批准、通过风格与类型检查、与新功能配套的单元测试齐备且代码与现有实现保持一致。通过这一流程你的贡献既能被 Sanic 团队顺利合入也最大程度降低了后续维护成本。【免费下载链接】sanicAccelerate your web app development | Build fast. Run fast.项目地址: https://gitcode.com/gh_mirrors/sa/sanic创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考