后端CLI【免费下载链接】appriseApprise - Push Notifications that work with just about every platform!项目地址https://gitcode.com/gh_mirrors/ap/apprise点击查看免费下载本文以仓库根目录下的 bin/README.mdApprise Development Guide为骨架结合 tox.ini、bin/ 目录下的脚本与 docker-compose.yml 等仓库资源系统梳理 Apprise 贡献者在本地环境完成环境搭建、单元测试、代码规范校验、CLI 调试、Docker 多版本模拟与 RPM 打包的完整工作流。读完本文你将掌握一套从git clone到PR 可合并的标准化开发链路并理解每个环节背后的实现原理。Apprise 是一个支持几乎所有推送平台的通知库与 CLI 工具其插件生态非常庞大仓库 apprise/plugins/ 下已有数十个服务插件。正因如此项目维护者将本地开发流程高度标准化用 Tox 统一管理依赖、测试与构建用 Ruff 统一代码风格用 Docker 模拟多版本 Python 与 RPM 打包环境。下面我们逐一展开。 环境准备用 Tox 接管一切原文档给出的第一步非常简单python -m pip install tox安装完成后不需要手动安装requirements-dev.txt——Tox 会根据 pyproject.toml 中声明的依赖dev、all-plugins等 extra自动创建虚拟环境并安装。这一点在 tox.ini 中有直接体现isolated_build True每个环境都基于隔离构建避免环境污染usedevelop true以开发模式editable安装 Apprise源码改动即时生效minversion 4.0、requires virtualenv20.0.0规定了 Tox 的最低版本要求。Tox 默认的环境清单envlist包括clean、validate、i18n、compile、minimal、release等覆盖了从清理构建产物到发布前的全部环节后续各小节会逐个介绍常用的几个。 运行测试qa / minimal / test 三个环境全量测试含插件与覆盖率tox -e qaqa环境是 Apprise 的全家桶测试入口。对照 tox.ini 中[testenv:qa]的定义它实际执行pip install --no-cache-dir -e .[dev,all-plugins]—— 安装全部插件依赖与开发依赖coverage erasecoverage run --sourceapprise -m pytest tests—— 以apprise为覆盖源运行 tests/ 下的全部用例coverage report -m与coverage xml -o coverage.xml—— 输出终端报告并生成 XML供 Codecov 等使用。覆盖率配置统一由 pyproject.toml 中的COVERAGE_RCFILE提供。聚焦特定测试tox -e qa -- -k email--之后的所有参数会作为posargs原样透传给 pytest-k email表示只运行名称匹配 email 的用例。这在开发某个插件例如邮箱相关时非常有用可以大幅缩短单次测试时间。仓库中对应的测试文件如 tests/test_plugin_email.py 即可用此方式单独验证。最小依赖集测试tox -e minimalminimal环境只安装devextras不带all-plugins用于验证核心库在最小依赖下依然工作。它同样执行覆盖率采集与报告但覆盖范围更聚焦。此外还有一个更轻量的tox -e test环境只运行pytest --tbshort -q不做覆盖率统计适合快速冒烟。 代码规范Ruff 负责 Lint 与 FormatApprise 使用 Ruff 作为唯一的 Python 风格工具其全部规则配置集中在 pyproject.toml 的[tool.ruff]段落含 lint 规则与 format 配置无需额外的.ruff.toml。只读检查linttox -e lint对应 tox.ini 的[testenv:lint]deps ruff0.15.8 commands ruff check . {posargs} ruff format --check .注意它同时做了两件事ruff check静态检查 ruff format --check验证格式是否符合规范只检查不修改。自动修复formattox -e format对应[testenv:format]commands ruff check . --fix {posargs} ruff format .它会自动修复可自动修复的 lint 问题并重新格式化代码。这两步都不需要你手动安装 ruffTox 会在环境内完成依赖安装。原文档特别提醒所有触碰 Python 文件的 PR 都会在 GitHub Actions 中自动运行 lint一旦出现违规构建会直接失败。因此建议在提交前至少跑一次tox -e lint。✅ 提交前自检lint qa 组合拳原文档推荐在推送或创建 PR 之前执行tox -e lint,qa一行命令串起风格检查 全量测试两个环境。如果两个环境都通过你的改动基本就具备了 PR-ready 的状态。仓库还提供了一个更完整的捷径tox -e checkdone对应 tox.ini 的[testenv:checkdone]它把提交前检查做成了一条流水线安装dev,all-plugins依赖ruff check .静态检查ruff format --check .格式校验coverage run --sourceapprise -m pytest tests全量测试coverage report输出覆盖率汇总。它与qa的区别在于多了一步格式校验且不生成coverage.xml。从脚本层面看bin/checkdone.sh 是它的 bash 等价物稍后介绍 Docker 环境时会再次遇到。 CLI 本地调试bin/apprise 与 tox -e apprise开发推送插件时最直接的验证方式就是真实调用一次 CLI看通知是否成功发出。原文档提供了三种途径。方式一仓库根目录直接执行# 从仓库根目录 ./bin/apprise -t Title -b Body mailto://user:passexample.com这里的关键在于 bin/apprise 这个 Python 脚本注意它不是已安装的命令而是仓库自带的开发工具。打开脚本可以看到它的原理非常朴素# 将仓库根目录脚本的上级目录插入 sys.path 最前 sys.path.insert(0, join(dirname(dirname(abspath(__file__))))) # 从 apprise.cli 导入 main 入口 from apprise.cli import main也就是说它直接复用你当前 checkout 的源码而不是 pip 安装的版本改一行代码、保存、再执行即可立即生效完全不需要重装或python setup.py develop。脚本还支持被拷贝到仓库上级目录使用会尝试把脚本所在目录也加入路径非常灵活。CLI 的真实入口定义在 apprise/cli.py 的main()函数中。常用参数均与-t/-b配合使用参数说明-t/--title通知标题-b/--body通知正文-v/--verbose增加输出详细度可叠加如-vvvv-D/--debug时最低强制为 3 级--dry-run/-d试运行模式只打印将要触发的服务不会真正发送-e/--interpret-escapes解释反斜杠转义序列-j/--interpret-emojis解释:emoji:表情定义-l/--details打印当前 Apprise 支持的所有服务详情-V/--version打印版本号后退出这些选项的完整定义见 apprise/cli.py 的 click 装饰器段约 L700–L820。方式二通过 tox 环境# 语法tox -e apprise -- [options] tox -e apprise -- -vv -b test body -t test title mailto://credentialstox.ini 的[testenv:apprise]安装了all-pluginsextras 后直接执行apprise {posargs}。好处是环境隔离、插件齐全与生产安装形态最接近。方式三直接调用 bin/apprise 传参bin/apprise -vv -b test body -t test title schema把schema换成你正在开发的插件 URL 格式如json://、xml://、form://即可针对单一 schema 做快速验证。-vv会输出 INFO 级别日志帮助你观察请求构造与响应情况。 RPM 打包在 Docker 中构建与验证Apprise 同时支持 Fedora 与 RHEL 系的 RPM 打包。为了不在宿主机污染环境项目用 Docker Compose 隔离了构建环境。原文档给出的三个命令# Build RPM for EL9 (RHEL 9 / Rocky / Alma 等) docker-compose run --rm rpmbuild.el9 /apprise/bin/build-rpm.sh # Build RPM for EL10 docker-compose run --rm rpmbuild.el10 /apprise/bin/build-rpm.sh # Build RPM for Fedora 44 docker-compose run --rm rpmbuild.f44 /apprise/bin/build-rpm.sh这些服务定义在仓库根目录的 docker-compose.yml 中分别对应 tests/docker/Dockerfile.el9、tests/docker/Dockerfile.el10、tests/docker/Dockerfile.f44构建上下文为仓库根目录工作目录/apprise并把仓库挂载为卷./:/apprise。此外还预留了rpmbuild.rawhideFedora Rawhide 滚动版服务。进入容器后bin/build-rpm.sh 会按以下顺序完成打包流水线清理tox -e clean --notest清理构建产物spec 校验rpmlint packaging/redhat/python-apprise.spec检查 RPM 规格文件 packaging/redhat/python-apprise.spec生成 man page用ronn --roff把 packaging/man/apprise.md 编译为 man 手册页翻译提取与编译tox -e i18n与tox -e compile产出apprise/i18n/下的.po/.mo文件构建 sdisttox -e build-sdist生成源码包dist/apprise-version.tar.gzrpmbuild通过rpmbuild --define ... -ba同时产出 source RPM 与 binary RPM最终产物输出到dist/rpm/。如果你不想手敲docker-compose命令tox.ini 里也定义了对应的快捷环境tox -e build-el9-rpm、tox -e build-el10-rpm、tox -e build-f44-rpm以及build-rawhide-rpm它们内部执行的就是同样的docker compose run --rm ...命令。 多版本 Python 模拟环境如果你需要在特定 Python 版本下验证兼容性例如你的改动依赖了某个新语法可以直接进入 Docker 容器交互# Python v3.9 Testing docker-compose run --rm test.py39 bash # Python v3.10 Testing docker-compose run --rm test.py310 bash # Python v3.11 Testing docker-compose run --rm test.py311 bash # Python v3.12 Testing docker-compose run --rm test.py312 bash对应服务同样定义在 docker-compose.yml 中镜像来自 tests/docker/Dockerfile.py39 至 tests/docker/Dockerfile.py312。容器内工作目录为挂载的仓库根因此你可以直接使用仓库自带的脚本容器内命令等价于bin/test.shtox -e qa的简化版——直接跑 pytest 全量用例但不做覆盖率见 bin/test.shbin/checkdone.shtox -e qa的完整版——先ruff check再带覆盖率跑 pytest最后coverage combine/xml/report --show-missing见 bin/checkdone.shbin/apprisetox -e apprise用本地源码启动 CLIruff check . --fixtox -e format自动格式化ruff check .tox -e lint仅静态检查coverage run --sourceapprise -m pytest tests手动带覆盖率的测试执行原文档也给出了选择建议走 Docker 这条路的唯一优势是省掉了每次tox调用的环境启动开销响应更快如果你不介意这层开销直接用tox命令往往更省心。另外bin/test.sh 还支持传关键词过滤例如bin/test.sh email只跑与 email 相关的用例。 GitHub ActionsPR 门禁原文档明确说明Apprise 的 GitHub Actions 流水线会执行✅ 全量测试套件含覆盖率✅ Ruff 代码风格检查✅ 打包与产物校验。其中lint 必须通过PR 才能被合并。这与前面 tox.ini 中lint环境read-only的设计是一致的——风格问题在本地就能被拦截CI 只是最后一道防线。仓库 .github/ 目录下保存了这些工作流的定义贡献者提交 PR 前跑一遍tox -e lint,qa或tox -e checkdone即可对齐 CI 的验收标准。 开发者提示插件开发的三条铁律原文档最后给出了三条对插件贡献者至关重要的经验结合仓库源码可以进一步理解其含义新增插件请参考官方插件库示例。仓库内已实现的 apprise/plugins/ 下的各个插件如json、xml、form对应的 custom_json.py、custom_xml.py、custom_form.py都是很好的起点它们展示了AppriseAttachment/NotifyBase子类的标准写法。多目标插件必须为每次成功调用mark_delivered()。这是 Apprise 投递跟踪机制的核心要求只有标记为已投递的目标重试retry时才会被跳过避免同一目标被重复通知。相关机制可参见 apprise/manager_plugins.py 与 apprise/plugins/base.py 中的投递状态管理。在tests/下使用AppriseURLTester模式编写单元测试。仓库中几乎每个插件都有一个对应的tests/test_plugin_*.py例如 tests/test_plugin_custom_json.py、tests/test_plugin_email.py。这些测试通过构造 URL、断言返回码的方式来验证插件的 URL 解析与发送逻辑。最后一条硬性要求所有新插件必须包含测试覆盖并通过 lint 检查。也就是说一个合格的插件 PR 至少包含三样东西——插件源码、对应的tests/test_plugin_name.py测试文件、以及通过tox -e lint的代码风格。小结一套完整的贡献者工作流把原文档的各个环节串起来一个标准化的 Apprise 贡献流程是这样的# 1. 准备环境 python -m pip install tox # 2. 开发期快速验证任选其一 ./bin/apprise -t Title -b Body schema tox -e apprise -- -vv -b test body -t test title schema # 3. 本地全量回归 tox -e qa # 4. 风格与格式 tox -e lint tox -e format # 5. 提交前终检 tox -e lint,qa # 或一步到位 tox -e checkdone # 6. 需要时做多版本/Docker 验证或 RPM 打包 docker-compose run --rm test.py312 bash docker-compose run --rm rpmbuild.el9 /apprise/bin/build-rpm.sh这套流程的价值在于所有环节都有 Tox / Docker 环境隔离依赖不污染宿主机所有环节都有对应的脚本与 CI 兜底tox.ini 中的lint/qa/checkdone、bin/ 下的开发脚本、GitHub Actions 的 PR 门禁。对新手贡献者来说照着上述命令走一遍就能安全地把第一个插件 PR 推到合并队列里。赞分享后端CLI【免费下载链接】appriseApprise - Push Notifications that work with just about every platform!项目地址https://gitcode.com/gh_mirrors/ap/apprise点击查看免费下载相关推荐Webamp NPM 包开发指南本地开发、构建产物、测试与版本发布全流程Webamp NPM 包开发指南本地开发、构建产物、测试与版本发布全流程 Webamp 是一个用 HTML5、TypeScript 与 React 重新实现前端音视频formik-native 本地开发指南基于 TSDX 的开发、构建与测试工作流formik native 本地开发指南基于 TSDX 的开发、构建与测试工作流 packages/formik native 是 Formik 面向 Reapipreqs 贡献指南基于 Poetry、flake8、tox 的本地开发与 Pull Request 完整工作流pipreqs 贡献指南基于 Poetry、flake8、tox 的本地开发与 Pull Request 完整工作流 本文是 pipreqs 项目官方贡献指南开发工具CLI上一篇从零开始掌握Dify工作流3个核心技巧让你快速构建AI应用下一篇零基础玩转Sulphur-2-Base-GGUF10分钟上手AI视频创作 创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考