cookiecutter-python

juftin's personal cookiecutter template for Python projects.

cookiecutter gh:juftin/cookiecutter-python

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

Cookiecutter

Generate a Python project:

uv tool run cookiecutter gh:juftin/cookiecutter-python

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.