Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,28 @@ version breaks generated projects.

## [Unreleased]

## [0.4.0] - 2026-10-29

New questions, all off by default: with the defaults a generated project is byte-for-byte the
same as with 0.3.0 (only `.copier-answers.yml` records the new answers).

### Added
- `include_example` (default yes): answer no to drop the `hello()` example and its tests, keeping
only `__version__`. With the Typer CLI, only the `version` command remains.
- `include_data_science` (default no): numpy, pandas, scikit-learn, `pandas-stubs`, `ipykernel`, a
mypy override for scikit-learn, `notebooks/` excluded from Ruff, `data/` and `artifacts/`
gitignored, notes in CLAUDE.md, and a `brew install libomp` step on macOS CI (LightGBM and
XGBoost wheels need it).
- `protect_project_files` (default no): `copier update` skips `README.md`, `CHANGELOG.md` and the
package `__init__.py` once they exist (`_skip_if_exists`). Existing projects opt in with
`uvx copier update -d protect_project_files=true`.
- `make test` renders two more variants: a bare CLI without the example, and data/ML with
protected files.

### Changed
- `.gitignore` and `.github/workflows/ci.yml` are now rendered (`.jinja`) so the data option can
extend them; the CI file wraps its GitHub expressions in `{% raw %}`.

## [0.3.0] - 2026-10-28

### Fixed
Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
## Testing a change

```bash
make test # test the hooks, render default + CLI variants into .tmp/ and run lint/types/tests
make test # test the hooks, render default, CLI, bare and data variants into .tmp/ and run lint/types/tests
make test-hooks # only the tests for template/.claude/hooks (tests/test_hooks.py)
make render # render default variant into .tmp/default for manual poking
make clean
Expand Down
4 changes: 4 additions & 0 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,12 @@ test-hooks: ## Test the Claude Code hooks shipped in template/.claude/hooks
test: clean test-hooks ## Test the hooks, render all variants and run their checks
$(COPIER) . $(OUT)/default
$(COPIER) -d include_cli=true -d project_name="Cli Demo" -d license=Proprietary . $(OUT)/cli
$(COPIER) -d include_cli=true -d include_example=false -d project_name="Bare Cli" . $(OUT)/bare
$(COPIER) -d include_data_science=true -d include_example=false -d protect_project_files=true -d project_name="Data Demo" . $(OUT)/data
$(call check,$(OUT)/default)
$(call check,$(OUT)/cli)
$(call check,$(OUT)/bare)
$(call check,$(OUT)/data)
$(MAKE) -C $(OUT)/default help clean

clean: ## Remove rendered output
Expand Down
17 changes: 14 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,16 @@ make check
```

Works the same in bash, zsh, PowerShell and cmd. You'll be asked for the project name, package name, Python version, whether to include a
Typer CLI, and a license.
Typer CLI, and a license, plus three options that are off by default:

| Question | Default | What it changes |
| -------- | ------- | --------------- |
| `include_example` | yes | No: drop the example `hello()` function and its tests (and the CLI's `greet`), keeping only `__version__`. |
| `include_data_science` | no | Yes: numpy, pandas and scikit-learn; `pandas-stubs` and a mypy override for scikit-learn so `strict` still passes; `notebooks/` (not linted); `data/` and `artifacts/` gitignored; `brew install libomp` on macOS CI for LightGBM/XGBoost wheels. |
| `protect_project_files` | no | Yes: `copier update` leaves `README.md`, `CHANGELOG.md` and the package `__init__.py` alone once they exist, instead of merging template changes into files the project has rewritten. |

With the defaults, a generated project is identical to the previous template version.
Existing projects can opt in on their next update, e.g. `uvx copier update -d protect_project_files=true`.

### Pull template updates into an existing project

Expand All @@ -78,14 +87,15 @@ Commit or stash your work first (Copier refuses to update a dirty repo). It only
| CI | GitHub Actions on Ubuntu, macOS, Windows (`astral-sh/setup-uv`) |
| Deps updates | Dependabot (uv + Actions) |
| Docs | README, CONTRIBUTING, CHANGELOG, PR + issue templates |
| Optional | Typer CLI, MIT license |
| Optional | Typer CLI, MIT license, data/ML setup, protected project files |

### A generated project

```
my-project/
├── src/my_project/ # your package (py.typed); cli.py if you chose the Typer CLI
├── tests/ # pytest, 80% coverage gate
├── notebooks/ # only with include_data_science (data/, artifacts/ gitignored)
├── pyproject.toml # uv_build, ruff, mypy strict, pytest, coverage
├── uv.lock
├── Makefile # make help: install, check, test, format, build, ...
Expand Down Expand Up @@ -122,7 +132,8 @@ the project alone. Both are tested in this repo (`make test-hooks`). `CLAUDE.loc
## Developing the template

See [CONTRIBUTING.md](CONTRIBUTING.md). TL;DR: `make test` tests the hooks, renders the
template twice (default + CLI variant) and runs the full check suite on each. CI runs it on
template four times (default, CLI, bare CLI without the example, data/ML with protected files)
and runs the full check suite on each. CI runs it on
Ubuntu, macOS and Windows (Git Bash **and** plain `cmd`).

## Releasing a new template version
Expand Down
27 changes: 27 additions & 0 deletions copier.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,14 @@ _subdirectory: template
_templates_suffix: .jinja
_answers_file: .copier-answers.yml

# With protect_project_files, `copier update` leaves these alone once they exist: a project
# rewrites them, so a template diff would only conflict. Copier recreates a skipped file the
# project deleted, so only list files a project keeps. Each pattern renders to "" (no-op) when off.
_skip_if_exists:
- "{% if protect_project_files %}README.md{% endif %}"
- "{% if protect_project_files %}CHANGELOG.md{% endif %}"
- "{% if protect_project_files %}src/{{ package_name }}/__init__.py{% endif %}"

_message_after_copy: |
Project "{{ project_name }}" created at {{ _copier_conf.dst_path }}.

Expand Down Expand Up @@ -73,6 +81,25 @@ include_cli:
help: Include a Typer CLI entry point?
default: false

include_example:
type: bool
help: Include the example hello() function and its tests? (No keeps only __version__.)
default: true

include_data_science:
type: bool
help: >-
Add a data/ML setup? (numpy, pandas, scikit-learn, pandas-stubs, notebooks/, data/ and
artifacts/ gitignored, libomp on macOS CI for LightGBM/XGBoost)
default: false

protect_project_files:
type: bool
help: >-
Should `copier update` leave README.md, CHANGELOG.md and the package __init__.py alone
once they exist?
default: false

license:
type: str
help: License
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
name: CI
{% raw %}name: CI

on:
push:
Expand All @@ -23,8 +23,13 @@ jobs:
with:
enable-cache: true

- name: Install
run: uv sync --all-groups --locked
{% endraw %}{% if include_data_science %} # LightGBM and XGBoost macOS wheels link against Homebrew's OpenMP runtime.
- name: Install libomp (macOS)
if: runner.os == 'macOS'
run: brew install libomp

{% endif %} - name: Install
run: uv sync --all-groups --locked{% raw %}

- name: Lint
run: |
Expand All @@ -36,3 +41,4 @@ jobs:

- name: Test
run: uv run pytest --cov --cov-report=term-missing
{% endraw %}
7 changes: 7 additions & 0 deletions template/.gitignore → template/.gitignore.jinja
Original file line number Diff line number Diff line change
Expand Up @@ -28,3 +28,10 @@ CLAUDE.local.md
.vscode/
.DS_Store
Thumbs.db
{%- if include_data_science %}

# Data and model outputs: never committed
data/
artifacts/
.ipynb_checkpoints/
{%- endif %}
7 changes: 7 additions & 0 deletions template/CLAUDE.md.jinja
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,9 @@
{%- if include_cli %}
- Typer CLI at `src/{{ package_name }}/cli.py` (entry point `{{ project_slug }}`)
{%- endif %}
{%- if include_data_science %}
- numpy, pandas, scikit-learn; `notebooks/` for exploration only
{%- endif %}

## Commands

Expand All @@ -33,6 +36,10 @@ If `make` is unavailable, run the equivalent `uv run ...` line from the `Makefil
- Don't `pip install` or edit `uv.lock` by hand.
- Don't add `# type: ignore` / `# noqa` without a reason comment.
- Don't commit secrets; config comes from environment variables.
{%- if include_data_science %}
- Don't commit data or trained models: `data/` and `artifacts/` are gitignored.
- Don't put pipeline logic in notebooks; it goes in `src/` with tests.
{%- endif %}

## Architecture

Expand Down
16 changes: 15 additions & 1 deletion template/README.md.jinja
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,9 @@
| Git | `brew install git` | `sudo apt install git` | `winget install Git.Git` |
| make | `xcode-select --install` | `sudo apt install make` | `winget install ezwinports.make` |

All `make` targets work in bash, zsh, PowerShell and cmd. Without `make`, run the
{% if include_data_science %}On macOS, also `brew install libomp` if you add LightGBM or XGBoost.

{% endif %}All `make` targets work in bash, zsh, PowerShell and cmd. Without `make`, run the
`uv run ...` line from the [Makefile](Makefile). On Windows, also run
`git config --global core.longpaths true` once.

Expand All @@ -34,7 +36,10 @@ make check # lint + typecheck + tests
## Usage

```bash
{%- if include_example %}
uv run {{ project_slug }} greet --name you
{%- endif %}
uv run {{ project_slug }} version
uv run {{ project_slug }} --help
```
{%- endif %}
Expand Down Expand Up @@ -69,6 +74,10 @@ Add dependencies with `uv add <pkg>` (runtime) or `uv add --dev <pkg>` (tooling)
│ └── hooks/ # Bash guard + auto-format
├── src/{{ package_name }}/
├── tests/
{%- if include_data_science %}
├── notebooks/ # Exploration only (not linted)
├── data/ # Raw data (gitignored)
{%- endif %}
├── Makefile
└── pyproject.toml
```
Expand All @@ -88,6 +97,11 @@ To pull in template improvements:
```bash
uvx copier update
```
{%- if protect_project_files %}

`README.md`, `CHANGELOG.md` and `src/{{ package_name }}/__init__.py` belong to this project:
`copier update` leaves them alone (`protect_project_files` in `.copier-answers.yml`).
{%- endif %}
{%- if license == "MIT" %}

## License
Expand Down
21 changes: 21 additions & 0 deletions template/pyproject.toml.jinja
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,11 @@ license = "MIT"
license-files = ["LICENSE"]
{%- endif %}
dependencies = [
{%- if include_data_science %}
"numpy>=2.2",
"pandas>=2.3",
"scikit-learn>=1.7",
{%- endif %}
{%- if include_cli %}
"typer>=0.16",
{%- endif %}
Expand All @@ -31,7 +36,13 @@ build-backend = "uv_build"

[dependency-groups]
dev = [
{%- if include_data_science %}
"ipykernel>=6.30",
{%- endif %}
"mypy>=1.18",
{%- if include_data_science %}
"pandas-stubs>=2.3",
{%- endif %}
"pre-commit>=4.3",
"pytest>=8.4",
"pytest-cov>=7.0",
Expand All @@ -43,6 +54,9 @@ dev = [
line-length = 100
target-version = "py{{ python_version | replace('.', '') }}"
src = ["src", "tests"]
{%- if include_data_science %}
extend-exclude = ["notebooks"] # exploration only; the pipeline lives in src/
{%- endif %}

[tool.ruff.lint]
select = [
Expand All @@ -66,6 +80,13 @@ select = [
python_version = "{{ python_version }}"
strict = true
files = ["src", "tests"]
{%- if include_data_science %}

[[tool.mypy.overrides]]
# No type stubs published; add other untyped libraries here (lightgbm.*, xgboost.*, shap.*).
module = ["sklearn.*"]
ignore_missing_imports = true
{%- endif %}

# ---------------------------------------------------------------- pytest
[tool.pytest.ini_options]
Expand Down
2 changes: 2 additions & 0 deletions template/src/{{package_name}}/__init__.py.jinja
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,10 @@
from importlib.metadata import version

__version__ = version("{{ project_slug }}")
{%- if include_example %}


def hello(name: str = "world") -> str:
"""Return a friendly greeting."""
return f"Hello, {name}!"
{%- endif %}
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,23 @@

import typer

from {{ package_name }} import __version__, hello
from {{ package_name }} import __version__{% if include_example %}, hello{% endif %}

app = typer.Typer(help="{{ description }}", no_args_is_help=True)
{%- if include_example %}


@app.command()
def greet(name: str = "world") -> None:
"""Print a greeting."""
typer.echo(hello(name))
{%- else %}


@app.callback()
def main() -> None:
"""Keep subcommands even while there is only one."""
{%- endif %}


@app.command()
Expand Down
8 changes: 8 additions & 0 deletions template/tests/test_basic.py.jinja
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
{%- if include_example -%}
from {{ package_name }} import hello


Expand All @@ -7,3 +8,10 @@ def test_hello_default() -> None:

def test_hello_name() -> None:
assert hello("Claude") == "Hello, Claude!"
{%- else -%}
from {{ package_name }} import __version__


def test_version_is_set() -> None:
assert __version__
{%- endif %}
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,14 @@ from {{ package_name }} import __version__
from {{ package_name }}.cli import app

runner = CliRunner()
{%- if include_example %}


def test_greet() -> None:
result = runner.invoke(app, ["greet", "--name", "Claude"])
assert result.exit_code == 0
assert "Hello, Claude!" in result.output
{%- endif %}


def test_version() -> None:
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# Notebooks

Exploration only: plots, data checks, trying ideas. Anything worth keeping moves into
`src/` with tests, and notebooks import it from there. Ruff skips this folder; clear outputs
before committing.

Raw data goes in `data/` and trained models in `artifacts/`; both are gitignored.
Loading