Copier Modern Machine Learning Template

Copier template with modern Python workflows

Inspired by copier-uv, cookiecutter-data-science, and BestieTemplates.jl.

Packaging Guide

• Check out pyOpenSci Python Package Guide

Features

• Uses uv for project and package management, which includes the following tools:
  • ruff for code formatting and quality analysis
  • mypy for type checking
• Testing is done with pytest and its plugins
• Documentation is built with mkdocs-material and mkdocstrings plugin
• Supports GitHub workflows, including:
  • Automatic release with semantic versioning
  • Auto-generated CHANGELOG.md and release notes using git-cliff
    • Requires Conventional Commits.

How to use it

Install dependencies

• Python 3.12+
• copier >= 9.7.1
• uv >= 0.7.0

Install copier (global)

uv tool install copier

Start new project

uvx --with copier_templates_extensions copier copy --trust gh:appleparan/copier-modern-ml ~/src/PATH/TO/YOUR/PROJECT

Install Python and packages

cd ~/src/PATH/TO/YOUR/PROJECT
uv python install 3.13
uv python pin 3.13
uv sync --group dev --group docs --extra cu126

Initialize git

Finally, initialize git, then install pre-commit hooks. (it takes some time at the first installation)

uv tool install pre-commit
git init
git add .
uvx pre-commit run -a # Try to fix possible pre-commit issues (failures are expected)
git add .
git commit -m "First commit"
uvx pre-commit install # Future commits can't be directly to main unless you use -n

The resulting directory structure

The directory structure of your new project will look something like this (depending on the settings that you choose):

├── LICENSE            <- Open-source license if one is chosen
├── README.md          <- The top-level README for developers using this project.
├── mkdocs.yml         <- mkdocs-material configuration file.
├── pyproject.toml     <- Project configuration file with package metadata for
│                         {{ project_slug }} and configuration for tools like ruff
├── uv.lock            <- The lock file for reproducing the production environment, e.g.
│                         generated with `uv sync`
├── data
│   ├── external       <- Data from third party sources.
│   ├── interim        <- Intermediate data that has been transformed.
│   ├── processed      <- The final, canonical data sets for modeling.
│   └── raw            <- The original, immutable data dump.
├── docs               <- A default mkdocs project; see www.mkdocs.org for details
├── models             <- Trained and serialized models, model predictions, or model summaries
├── notebooks          <- Jupyter notebooks. Naming convention is a number (for ordering),
│                         the creator's initials, and a short `-` delimited description, e.g.
│                         `1.0-jqp-initial-data-exploration`.
├── references         <- Data dictionaries, manuals, and all other explanatory materials.
├── reports            <- Generated analysis as HTML, PDF, LaTeX, etc.
│   └── figures        <- Generated graphics and figures to be used in reporting
├── tests              <- Unit test files.
└── src/{{ project_slug }}   <- Source code for use in this project.
    │
    ├── __init__.py             <- Makes {{ project_slug }} a Python module
    │
    └── cli.py                  <- Default CLI program

Development

Generate package from local template

uvx --with copier_templates_extensions copier copy --vcs-ref HEAD --trust LOCAL_TEMPLATE_PATH PACKAGE_NAME

Check next version

uv run git-cliff --bumped-version

Release

Execute scripts

sh scripts/release.sh

What release.sh do:

1. Set next version to BUMPED_VERSION: This ensures that the git-cliff --bumped-version command produces consistent results.

BUMPED_VERSION=$(uv run git-cliff --bumped-version)

2. Generate CHANGELOG.md and RELEASE.md: The script creates or updates the changelog and release notes using the bumped version:

uv run git-cliff --strip header --tag $BUMPED_VERSION -o CHANGELOG.md
uv run git-cliff --latest --strip header --tag $BUMPED_VERSION --unreleased -o RELEASE.md

3. Commit updated CHANGELOG.md and RELEASE.md then add tags and push: It commits the updated files, creates a tag for the new version, and pushes the changes to the repository:

git add CHANGELOG.md RELEASE.md
git commit -am "docs: Add CHANGELOG.md and RELEASE.md to release $BUMPED_VERSION"
git tag -a $BUMPED_VERSION -m "Release $BUMPED_VERSION"
git push origin tag $BUMPED_VERSION

For dry run:

uv run git-cliff --latest --strip header --tag $(uv run git-cliff --bumped-version) --unreleased

PyTorch Index URL (PyTorch 2.7)

Compute Platform	Linux	Windows	macOS
CPU Only	☐ https://download.pytorch.org/whl/cpu	☐ default	☐ default
CUDA 11.8	☐ https://download.pytorch.org/whl/cu118	☐ https://download.pytorch.org/whl/cu118	❌ Not supported
CUDA 12.6	☐ default	☐ https://download.pytorch.org/whl/cu126	❌ Not supported
CUDA 12.8	☐ https://download.pytorch.org/whl/cu128	☐ https://download.pytorch.org/whl/cu128	❌ Not supported
ROCm 6.3	☐ https://download.pytorch.org/whl/rocm6.3	❌ Not supported	❌ Not supported