https://github.com/superlinear-ai/substrate
🌱 Substrate is a modern Copier template for scaffolding Python packages and apps
https://github.com/superlinear-ai/substrate
copier-template devcontainer project-template python ruff scaffolding template ty uv
Last synced: 23 days ago
JSON representation
🌱 Substrate is a modern Copier template for scaffolding Python packages and apps
- Host: GitHub
- URL: https://github.com/superlinear-ai/substrate
- Owner: superlinear-ai
- License: mit
- Created: 2022-01-05T16:20:19.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2025-12-24T11:04:04.000Z (3 months ago)
- Last Synced: 2026-02-10T06:56:40.328Z (about 1 month ago)
- Topics: copier-template, devcontainer, project-template, python, ruff, scaffolding, template, ty, uv
- Language: Jinja
- Homepage:
- Size: 418 KB
- Stars: 349
- Watchers: 10
- Forks: 54
- Open Issues: 16
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/superlinear-ai/substrate) [](https://github.com/codespaces/new/superlinear-ai/substrate) [](https://github.com/copier-org/copier)
# 🌱 Substrate
A modern [Copier template](https://github.com/copier-org/copier) for scaffolding Python packages and apps.
## 🎁 Features
- 🧑💻 One-click development environments with [Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers) and [GitHub Codespaces](https://github.com/features/codespaces)
- 🌈 Cross-platform support for Linux, macOS, and Windows
- 🐚 Modern shell prompt with [Starship](https://github.com/starship/starship)
- 📦 Packaging and dependency management with [uv](https://github.com/astral-sh/uv)
- 🚚 Installing from and publishing to [PyPI](https://pypi.org/)
- ⚡️ Task running with [Poe the Poet](https://github.com/nat-n/poethepoet)
- 💅 Code formatting with [ruff](https://github.com/astral-sh/ruff)
- ✅ Code linting with [pre-commit](https://pre-commit.com/), [ruff](https://github.com/astral-sh/ruff), and [ty](https://github.com/astral-sh/ty)
- 🏷 Optionally follow the [Conventional Commits](https://www.conventionalcommits.org/) standard
- 🚦 Release new versions with [Semantic Versioning](https://semver.org/) and [Keep A Changelog](https://keepachangelog.com/) using [Commitizen](https://github.com/commitizen-tools)
- 💌 Verified commits with [GPG](https://gnupg.org/)
- ♻️ Continuous integration with [GitHub Actions](https://docs.github.com/en/actions) or [GitLab CI/CD](https://docs.gitlab.com/ee/ci/)
- 🧪 Test coverage with [Coverage.py](https://github.com/nedbat/coveragepy)
- 🧰 Dependency updates with [Dependabot](https://docs.github.com/en/code-security/getting-started/dependabot-quickstart-guide)
- 📚 Documentation with [MkDocs](https://github.com/mkdocs/mkdocs)
## ✨ Using
> [!TIP]
> You should first [install uv](https://docs.astral.sh/uv/getting-started/installation/) to be able to run the commands below.
### Create a new Python project
To create a new Python project with this template, run:
```sh
uvx copier copy gh:superlinear-ai/substrate path/to/local/repository
```
### Update your Python project
To update your Python project to the latest template version, run:
```sh
uvx copier update --exclude src/ --exclude tests/
```
### Release a new version of your Python project
If you have enabled [Conventional Commits](https://www.conventionalcommits.org/), you can create a new version tag and update `CHANGELOG.md` based on your commit messages with:
```sh
git checkout main
cz bump
git push origin main --tags
```
### Build and publish your Python project's docs
To build and serve your Python project's docs, run:
```sh
poe docs --serve
```
If your project is on GitHub, your docs will be published automatically to GitHub Pages every time you update the default branch. You can view the docs by clicking on the  badge in your project's README.
> [!TIP]
> Make sure to [configure the source of your project's GitHub Pages as GitHub Actions in your project settings](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow) to allow the GitHub Actions workflow to publish your docs.
## Contributing
Prerequisites
1. [Generate an SSH key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#generating-a-new-ssh-key) and [add the SSH key to your GitHub account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account).
2. Configure SSH to automatically load your SSH keys:
```sh
cat << EOF >> ~/.ssh/config
Host *
AddKeysToAgent yes
IgnoreUnknown UseKeychain
UseKeychain yes
ForwardAgent yes
EOF
```
3. [Install Docker Desktop](https://www.docker.com/get-started).
4. [Install VS Code](https://code.visualstudio.com/) and [VS Code's Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers). Alternatively, install [PyCharm](https://www.jetbrains.com/pycharm/download/).
5. _Optional:_ install a [Nerd Font](https://www.nerdfonts.com/font-downloads) such as [FiraCode Nerd Font](https://github.com/ryanoasis/nerd-fonts/tree/master/patched-fonts/FiraCode) and [configure VS Code](https://github.com/tonsky/FiraCode/wiki/VS-Code-Instructions) or [PyCharm](https://github.com/tonsky/FiraCode/wiki/Intellij-products-instructions) to use it.
Development environments
The following development environments are supported:
1. ⭐️ _GitHub Codespaces_: click on [Open in GitHub Codespaces](https://github.com/codespaces/new/superlinear-ai/substrate) to start developing in your browser.
2. ⭐️ _VS Code Dev Container (with container volume)_: click on [Open in Dev Containers](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/superlinear-ai/substrate) to clone this repository in a container volume and create a Dev Container with VS Code.
3. ⭐️ _uv_: clone this repository and run the following from root of the repository:
```sh
# Create and install a virtual environment
uv sync
# Activate the virtual environment
source .venv/bin/activate
# Install the pre-commit hooks
pre-commit install --install-hooks
```
4. _VS Code Dev Container_: clone this repository, open it with VS Code, and run Ctrl/⌘ + ⇧ + P → _Dev Containers: Reopen in Container_.
5. _PyCharm Dev Container_: clone this repository, open it with PyCharm, [create a Dev Container with Mount Sources](https://www.jetbrains.com/help/pycharm/start-dev-container-inside-ide.html), and [configure an existing Python interpreter](https://www.jetbrains.com/help/pycharm/configuring-python-interpreter.html#widget) at `/opt/venv/bin/python`.
Developing
- This project follows the [Conventional Commits](https://www.conventionalcommits.org/) standard to automate [Semantic Versioning](https://semver.org/) and [Keep A Changelog](https://keepachangelog.com/) with [Commitizen](https://github.com/commitizen-tools/commitizen).
- Run `cz bump` to bump Substrate's version, update the `CHANGELOG.md`, and create a git tag. Then push the changes and the git tag with `git push origin main --tags`.