opentemplate

All-in-one Python template. One click. Everything included.

✨ Features 🚀 Quick start 📚 Documentation 🤝 Contribute 👍 Adopters 📜 Legal

---

Features

opentemplate is a Python template which is:

• Truly open source: no tokens, no fees, no premium plans, open source software only
• Easy to use: clone templated repo, run uv run poe setup and focus on your code
• State of the art: best checkers for Python, YAML, Markdown, prose, and more unified
• Secure: SLSA Build L3, SBOMs, attestations, secured egress, OSSF Best Practices
• Consistent: package metadata is static in pyproject.toml, while uv resolves dependencies into uv.lock
• Performant: parallel checks, builds, minimally-sized caches and checkouts

Important

An example repository using opentemplate

Caution

All files in this repo will be copied to your project, using the title and description you provide.

Code quality (Python focused)

Important

Adjust package metadata and tool configuration in pyproject.toml.

• Package manager: uv (with poe tasks) and a single uv run poe setup manages everything! (see why uv)
• Testing: pytest (with coverage, and hypothesis for fuzzing, doctests, and mutmut for mutation testing); testing across all Python versions done WITHOUT tox or nox(managed directly by uv!)
• Documentation: mkdocs - document once, have it everywhere (unified look on GitHub and hosted docs), semantically versioned (via mike), autogenerated from coverage, deadlink and spell-checked docstrings, automatically deployed after each GitHub release with clean material design look
• Code formatting and linting: ruff (checks hand-picked for best quality and ease of use; most are enabled), pyrefly for type checking
• Each file is copyrighted with your git information - copyrights added automatically by prek, see REUSE and SPDX Licensing for more information
• Dependency license compliance: distributed Python dependencies are checked by Trivy (per Python version and OS), GitHub Actions and other dependencies checked by dependency-review-action, both against a single list of allowed licenses (as defined in .trivy.yaml)
• Automated Python version updates: pyproject.toml (and GitHub Actions pipelines where necessary) are automatically updated to always use 3 latest Python versions (via cogeol) according to Scientific Python SPEC0 deprecation and end-of-life policies
• Other code linting: checks for YAML, Markdown, INI, JSON, prose, all config files, shell, GitHub Actions - all grouped as check-<group> and fix-<group> poe tasks
• Release to PyPI and GitHub: done by making a GitHub release, each release is attested and immutably versioned via commition
• prek: all checks and fixers are run before commit, no need to remember them! (prek is also setup after running a single uv run poe setup command!)

Security

Important

Everything below is already provided out of the box, one-click only!

• Hardening: during setup, an automated issue is created to guide you step by step through enabling rulesets, branch protection, mandatory reviewers, necessary signatures etc. (see here for an example). Best part? harden.yml workflow, which does that automatically (if you follow the instructions in the issue)!
• SLSA Build L3 provenance: wheel and source distributions are built in a reusable workflow which runs no project code, their digests are attested in a separate job and the signed bundle is attached to each release (public repositories or GitHub Enterprise Cloud, once harden.yml pins the reusable workflows)
• SLSA Verification Summary Attestation (VSA): the build provenance of the distributions is verified and the achieved SLSA Build level is attested for them
• Software Bills of Materials (SBOMs): generated per-Python, per-OS, per-dependency group - each attested, and attached to the release
• Static security analysis tooling: uv audit checks against OSV database, semgrep monitors code quality and security, guarddog detects malicious runtime dependencies and actions, zizmor and CodeQL verify workflows, while trufflehog looks for leaked secrets
• Reusable workflows: OpenTemplate tests its own workflow changes through local references. The harden.yml workflow converts those references to open-nudge/opentemplate/.github/workflows/<workflow>.yml@<commit-SHA> calls using the latest OpenTemplate main commit, so generated repositories receive pinned pipeline updates.
• Pinned dependencies: all dependencies are pinned to specific versions (GitHub Actions, prek and uv.lock), with weekly Dependabot pull requests (one per ecosystem)
• Monitored egress in GitHub Actions: harden-runner with a whitelisted minimal set of domains necessary to run the workflows
• Security documentation: SECURITY.md, SECURITY-INSIGHTS.yml, SECURITY-SELF-ASSESSMENT.md (only security file to update manually before release), and SECURITY-DEPENDENCY.md define high quality security policies

Tip

See this example release for all security artifacts described above.

Note

Although there is around 100 workflows helping you maintain high quality, most of them reuse the same workflow, which makes them maintainable and extendable.

GitHub

• GitHub Actions cache - after each merge to the main branch, dependencies are cached per-group and per-OS for maximum performance
• Minimal checkouts and triggers - each workflow is triggered based on appropriate path and performs sparse-checkout when possible to minimize the amount of data transferred; great for large repositories with many files and large history
• Templates: every possible template included (discussions, issues, pull requests - each extensively described)
• Predefined labels - each pull request will be automatically labeled (over 20 labels created during setup!) based on changed files (e.g. docs, tests, deps, config etc.). No need to specify semver scope of commit anymore!
• Open source documents: CODE_OF_CONDUCT.md, CONTRIBUTING.md, ROADMAP.md, CHANGELOG.md, CODEOWNERS, DCO, and much more - all automatically added and linked to your Python documentation out of the box
• Release changelog: git-cliff - commits automatically divided based on labels, types, human/bot authors, and linked to appropriate issues and pull requests
• Config files: editorconfig, .gitattributes, always the latest Python .gitignore etc.
• Commit checks: verification of signatures, commit messages, DCO signing, no commit to the main branch policy (via conform)

Comparison

• Broader scope than other cookiecutter templates (e.g. one-click and one-command setup, security, GitHub Actions, comprehensive docs, rulesets. deprecation policies, automated copyrights and more). Check the cookiecutter-uv template or the cookiecutter-pypackage template to compare yourself.
• Truly FOSS (no freemium, no paid plans, no tokens) when compared to commercial offerings like snyk. Additionally Python-centric and sticks with tools widely known by developers (their own environment and GitHub interface).

Tip

See detailed comparison in the documentation

Quick start

Installation

Note

Install uv (if you don't have it already), for Linux/MacOS:

curl -LsSf https://astral.sh/uv/install.sh | sh

1. Create a new GitHub repository using this template (green Use this template button)
2. Name your repo (use underscore _, not hyphens -)
3. Add project description (necessary!)
4. Wait until the setup commit appears (performed by github-actions[bot], it may take a few minutes)
5. Clone the repository
6. Run uv run poe setup command locally to setup development environment

Tip

For more details read the documentation

Usage

1. Create a new branch
2. Optionally adjust package metadata in [project] in pyproject.toml (including dependencies, keywords, or classifiers), prek runs uv lock --upgrade on every commit (releases at least a week old)
3. Write code in /src/<project_name> and tests in /tests
4. Use git add, git commit and git push your changes
5. prek will guide you through the process

Tip

For more details read the documentation

Examples

Caution

Click on each example to see it in action!

Run checkers or fixers manually (click me)

 

> uv run poe check-<group> [FILE1, FILE2, ...] # uv run poe fix-<group>

For example, to check all Python files:

> uv run poe check-python

Or to check /src/__init__.py:

> uv run poe check-python src/__init__.py

To run all checks and fixers at once (via prek):

> uv run poe fix-all

Adjust template (click me)

 

Package metadata is configured directly in the static [project] fields in pyproject.toml.

Common package metadata changes in pyproject.toml:

• Add runtime dependencies in [project].dependencies
• Add package keywords in [project].keywords
• Add package classifiers in [project].classifiers

Advanced tool and development changes still belong in pyproject.toml:

• Add dev dependencies under [dependency-groups] (everything is named dev-<group>)
• Modify [tool.poe.tasks] for custom command (check-<group> or fix-<group>, the latter modifies files)
• Use [tool.<name>] to adjust specific tool configuration

Adjusting these sections will affect prek and GitHub Actions

Disable some prek check (click me)

 

Disabling checks should be done cautiously!

prek checks are defined in prek.toml.

Disable a check using SKIP environment variable:

SKIP="<group1>,<group2>" git commit -m <message>

For example, the following will skip DCO and ini checks and Python fixes (which would modify files):

SKIP="dco,ini,fix-python" git commit -m <message>

For details, refer to the id fields in prek.toml.

Some commands have both <group>-fix and <group>-check for different actions!

Disable GitHub Actions checks (click me)

 

Disabling checks should be done cautiously!

When making a commit you can add one of the following strings to the message:

• [skip ci]
• [ci skip]
• [no ci]
• [skip actions]
• [actions skip]

Note that you can also merge pull requests even if the checks fail.

Contribute

We welcome your contributions! Start here:

• Code of Conduct
• Contributing Guide
• Roadmap
• Changelog
• Report security vulnerabilities
• Open an Issue

Legal

• This project is licensed under the Apache 2.0 License - see the LICENSE file for details.
• This project is copyrighted by open-nudge - the appropriate copyright notice is included in each file.