open-nudge/opentemplate

一体化 Python 模板。一键启动。应有尽有。

✨ 功能特性 🚀 快速开始 📚 文档 🤝 贡献 👍 采用者 📜 法律信息

## 功能特性 __opentemplate__ 是一个 Python 模板，具有以下特点： - [__真正的开源__](https://open-nudge.github.io/opentemplate/template/about/philosophy)： 无令牌、无费用、无高级计划，纯开源软件 - [__易于使用__](https://open-nudge.github.io/opentemplate/template/quickstart/usage)： 克隆模板仓库，运行 `pdm setup`，然后__专注于你的代码__ - [__业界领先__](https://open-nudge.github.io/opentemplate/template/details)： 最佳检查工具，涵盖 Python、YAML、Markdown、散文等，统一配置 - [__安全可靠__](https://open-nudge.github.io/opentemplate/template/details/security)： [SLSA 3 级](https://slsa.dev/spec/v1.0-rc1/levels)、[SBOM](https://www.cisa.gov/sbom)、 [证明文件](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations/using-artifact-attestations-to-establish-provenance-for-builds)、 [安全出口](https://github.com/step-security/harden-runner)、 [OSSF 最佳实践](https://github.com/ossf/scorecard) - [__一致性强__](https://open-nudge.github.io/opentemplate/template/configuration/basic)： 所有流水线（`GitHub Actions`、`prek`） 共享同一份 `pyproject.toml` 配置 - [__性能优异__](https://open-nudge.github.io/opentemplate/template/details/github-actions)： 并行检查、构建，最小化的缓存和检出 ### 代码质量（以 Python 为重点） - __包管理器：__ [`pdm`](https://pdm-project.org/en/latest/) 只需一个 `pdm setup` 即可管理一切！ （参见 [为什么选择 pdm](https://open-nudge.github.io/opentemplate/latest/template/about/faq/#why-use-pdm-instead-of-uv)） - __测试：__ [`pytest`](https://docs.pytest.org/en/stable/) （配合 [`coverage`](https://coverage.readthedocs.io/en/7.9.1/) 和 [`hypothesis`](https://hypothesis.readthedocs.io/en/latest/) 进行模糊测试）；__跨所有 Python 版本测试 无需使用 [`tox`](https://tox.wiki/en/4.27.0/) 或 [`nox`](https://nox.thea.codes/en/stable/)__（由 `pdm` 直接管理！） - __文档：__ [`mkdocs`](https://www.mkdocs.org/) - __一次编写，到处可用（GitHub 和托管文档统一外观）__， [语义化版本控制](https://semver.org/) （通过 [`mike`](https://github.com/jimporter/mike)）， 自动从 [覆盖率](https://github.com/econchick/interrogate)、 [死链检查](https://github.com/AlexanderDokuchaev/md-dead-link-check) 和[拼写检查](https://github.com/codespell-project/codespell) 的文档字符串生成， 每次 GitHub 发布后自动部署，采用简洁的 [Material Design 外观](https://github.com/squidfunk/mkdocs-material) - __代码格式化和检查：__ [`ruff`](https://github.com/astral-sh/ruff) （精心挑选的检查规则，确保最佳质量和易用性；大部分已启用）， [`basedpyright`](https://github.com/DetachHead/basedpyright) 用于类型检查，[`FawltyDeps`](https://github.com/tweag/FawltyDeps) 用于静态依赖分析 - __每个文件都包含你的 git 信息作为版权声明__ - 版权信息由 `prek` 自动添加， 参见 [REUSE](https://reuse.readthedocs.io/en/stable/) 和 [SPDX 许可](https://spdx.dev/learn/handling-license-info/) 了解更多信息 - __自动更新 Python 版本__：`pyproject.toml` （以及必要的 GitHub Actions 流水线） 会自动更新以始终使用__最新的 3 个 Python 版本__（通过 [`cogeol`](https://pypi.org/project/cogeol/)） 遵循 [Scientific Python SPEC0](https://scientific-python.org/specs/spec-0000/) 弃用和生命周期结束策略 - __其他代码检查__：检查 `YAML`、`Markdown`、`INI`、`JSON`、散文、 所有配置文件、`shell`、`GitHub Actions` - __全部归类为 `check-` 和 `fix-` 的 `pdm` 命令__ - __发布到 `PyPI` 和 `GitHub`__：通过创建 [GitHub release](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases) 完成，每次发布都经过证明并通过 [`commition`](https://pypi.org/project/commition/) 进行不可变版本控制 - [__`prek`__](https://prek.j178.dev/)：__所有检查和修复工具在提交前运行， 无需记忆！ （运行单个 `pdm setup` 命令后 `prek` 也会自动配置！） ### 安全性 - [__加固__](https://open-nudge.github.io/opentemplate/latest/template/quickstart/installation/#hardening)： 在设置期间，会自动创建一个 issue 逐步引导你 启用规则集、分支保护、强制审查者、 必要签名等。 （[参见示例](https://github.com/open-nudge/opentemplate/issues/1)）。 最棒的是什么？__`harden.yml` 工作流会自动完成这些__ （如果你按照 issue 中的说明操作）！ - [__SLSA 合规__](https://slsa.dev/spec/v1.0-rc1/levels)： 公共/企业仓库达到 3 级以上 私人仓库通过 [slsa-github-generator](https://github.com/slsa-framework/slsa-github-generator) 达到 2 级 - __[软件物料清单](https://www.cisa.gov/sbom)（SBOM）__： 按 Python、操作系统、依赖组生成 - __每个都经过[证明](https://github.com/actions/attest)__， 并附加到发布版本中 - __静态安全分析工具__：[`osv-scanner`](https://github.com/google/osv-scanner) 检查 [OSV 数据库](https://osv.dev/)， [`semgrep`](https://semgrep.dev/) 监控代码质量和安全， [`zizmor`](https://github.com/zizmorcore/zizmor) 验证工作流， 而 [`trufflehog`](https://github.com/trufflesecurity/trufflehog) 寻找泄露的密钥 - __可复用工作流__：大多数工作流是[可复用的](https://docs.github.com/en/actions/sharing-automations/reusing-workflows) （指向 `opentemplate` 工作流）以提高安全性 并__获取自动流水线更新__ - 你可以通过 运行 `.github/reusability/localize.sh` 脚本使其本地化。 __无需管理/更新你自己的工作流！__ - __固定的依赖项__：所有依赖项都固定到特定版本 （GitHub Actions、`prek` 和 `pdm.lock`） - __GitHub Actions 中的出口监控__：[`harden-runner`](https://github.com/step-security/harden-runner) 使用__最小化的域名白名单__来运行工作流 - __安全文档__：`SECURITY.md`、`SECURITY-INSIGHTS.yml`、 `SECURITY-SELF-ASSESSMENT.md`（发布前唯一需要手动更新的安全文件） 和 `SECURITY-DEPENDENCY.md` 定义了高质量的安全策略 ### GitHub - __GitHub Actions 缓存__ - 每次合并到 `main` 分后， 依赖项按__组和操作系统__缓存，以获得最佳性能 - __最小化检出和触发__ - 每个工作流基于 适当的路径__触发__，并在可能的情况下执行 [`sparse-checkout`](https://github.blog/open-source/git/bring-your-monorepo-down-to-size-with-sparse-checkout/) 以最小化传输的数据量； __非常适合拥有大量文件和大历史的大型仓库__ - __模板__：包含所有可能的模板（讨论、 issues、pull requests - 均有详细描述） - __预定义标签__ - 每个 pull request 将根据更改的文件 自动标记（在设置期间创建了超过 `20` 个标签！） （例如 `docs`、`tests`、`deps`、`config` 等）。 __无需再指定 commit 的 [semver](https://semver.org/) `scope`！__ - __开源文档__：`CODE_OF_CONDUCT.md`、 `CONTRIBUTING.md`、`ROADMAP.md`、`CHANGELOG.md`、`CODEOWNERS`、`DCO`， 以及更多 - 所有这些都会自动添加并链接到你的 开箱即用的 Python 文档中 - __发布变更日志__：[`git-cliff`](https://git-cliff.org/) - commit 根据 `labels`、`types`、人工/机器人作者自动分类， 并链接到相应的 issues 和 pull requests - __配置文件__：[editorconfig](https://editorconfig.org/)、`.gitattributes`、 始终使用最新的 Python `.gitignore` 等 - __提交检查__：验证签名、提交信息、 DCO 签名、禁止直接提交到 main 分支的策略 （通过 [conform](https://github.com/siderolabs/conform)） ## 对比 - 范围比其他 [`cookiecutter`](https://github.com/cookiecutter/cookiecutter) 模板更广（例如一键和一命令设置、安全、 GitHub Actions、全面文档、规则集、弃用策略、 自动版权声明等）。 在[这里](https://github.com/fpgmaas/cookiecutter-uv) 或[这里](https://github.com/audreyfeldroy/cookiecutter-pypackage)查看对比。 - 与商业产品如 [`snyk`](https://snyk.io/) 或 [`jit.io`](.txt` （__无需手动更新 `pyproject.toml`！__） 3. 在 `/src/` 中编写代码，在 `/tests` 中编写测试 4. 使用 `git add`、`git commit` 和 `git push` 提交你的更改 5. `prek` 将引导你完成整个过程 ### 示例

手动运行检查器或修复工具（点击我）

  ``` > pdm check- [FILE1, FILE2, ...] # pdm fix- ``` 例如，检查__所有 Python 文件__： ``` > pdm check-python ``` 或者检查 `/src/__init__.py`： ``` > pdm check-python src/__init__.py ``` 请注意，所有 `check` 和 `fix` 命令都为你方便分组了： ``` > pdm check-all # pdm fix-all ```

调整模板（点击我）

  对 `pyproject.toml` 的常见更改： - 在 `[dependency-groups]` 下添加开发依赖 （所有依赖都命名为 `dev-`） - 修改 `[tool.pdm.scripts]` 以自定义命令 （`check-` 或 `fix-`，后者会修改文件） - 使用 `[tool.]` 调整特定工具的配置

禁用某些 prek 检查（点击我）

  `prek` 检查定义在 `prek.toml` 中。 使用 `SKIP` 环境变量禁用检查： ``` SKIP="," git commit -m ``` 例如，以下将跳过 `DCO` 和 `ini` 检查 以及 Python 修复（会修改文件）： ``` SKIP="dco,ini,fix-python" git commit -m ``` 详情请参阅 `prek.toml` 中的 `id` 字段。

禁用 GitHub Actions 检查（点击我）

  提交时可以添加以下字符串之一到提交信息中： - `[skip ci]` - `[ci skip]` - `[no ci]` - `[skip actions]` - `[actions skip]`

## 法律信息 - 本项目基于 _Apache 2.0 许可证_ - 详见 [LICENSE](/LICENSE.md) 文件。 - 本项目由 _open-nudge_ 拥有版权 - 每个文件都包含相应的版权声明。

标签：Python开发, Python模板, Python项目, SOC Prime, 一站式解决方案, 二进制发布, 代码模板, 安全规则引擎, 开发工具, 开发框架, 开源工具, 快速启动, 数据管道, 脚手架工具, 软件工程, 逆向工具, 项目生成器, 项目脚手架