cookiecutter-python

juftin's personal Copier template for Python projects.

uvx copier copy gh:juftin/cookiecutter-python my-project

Features

• uv for managing the project's Python dependencies
• task for task running and automation
• ruff for code formatting and linting
• mypy for type checking
• pre-commit for managing git hooks
• GitHub Actions for CI/CD
• MkDocs and mkdocs-material for documentation
• GitHub Pages for hosting documentation
• semantic-release and gitmoji for automated releases
• Publishes to PyPI and Docker Hub

Quickstart Guide

Requirements

• Install uv

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

• Install task

  sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d

Creating a project

Copier

Generate a Python project:

uvx copier copy gh:juftin/cookiecutter-python my-project

Updating from the template

From a clean, committed Git worktree, projects generated with Copier can receive later template releases:

uvx copier update --answers-file .github/.copier-answers.yaml

Commit .github/.copier-answers.yaml when creating the project; Copier uses it to locate the template and preserve the original answers. See the migration guide for the update workflow and guidance for existing Cookiecutter projects.

Git Init

Change to the root directory of your new project, create a Git repository, and install pre-commit

git init
task lock
task install
git add .
pre-commit run --all-files
git add .
git commit

Secrets Init

This project uses GitHub Actions to deploy releases, documentation, and to publish artifacts to PyPI / Docker Hub. You will need to create secrets in your GitHub repository to enable these features.

• PERSONAL_ACCESS_TOKEN: A GitHub Personal Access Token with repo permissions
• DOCKER_USERNAME: Your Docker Hub username (optional)
• DOCKER_TOKEN: Your Docker Hub token (optional)

A .env file is provided in the project root for local development, to sync your secrets to GitHub, run the following command with the GitHub CLI:

gh secret set --env-file .env

Docs Init

Enabling GitHub Pages to host your documentation requires going to your repository's settings, navigating to the "Pages" section, and selecting GitHub Actions as the source.

Developing

This project generates its own documentation for how to use the project's tools. To view the documentation locally, run:

task docs

Once the server is running, you can view the documentation at localhost:8080/contributing or see a preview at juftin.com/cookiecutter-python/contributing.