diff --git a/CHANGELOG.md b/CHANGELOG.md index 32f3aad..3aad5b3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8416c82..50d6648 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 diff --git a/Makefile b/Makefile index 5b16b24..3e28b9b 100644 --- a/Makefile +++ b/Makefile @@ -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 diff --git a/README.md b/README.md index 138355d..8c20be4 100644 --- a/README.md +++ b/README.md @@ -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 @@ -78,7 +87,7 @@ 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 @@ -86,6 +95,7 @@ Commit or stash your work first (Copier refuses to update a dirty repo). It only 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, ... @@ -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 diff --git a/copier.yml b/copier.yml index fa03df8..e3fb701 100644 --- a/copier.yml +++ b/copier.yml @@ -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 }}. @@ -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 diff --git a/template/.github/workflows/ci.yml b/template/.github/workflows/ci.yml.jinja similarity index 65% rename from template/.github/workflows/ci.yml rename to template/.github/workflows/ci.yml.jinja index 3b916ed..73b5f22 100644 --- a/template/.github/workflows/ci.yml +++ b/template/.github/workflows/ci.yml.jinja @@ -1,4 +1,4 @@ -name: CI +{% raw %}name: CI on: push: @@ -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: | @@ -36,3 +41,4 @@ jobs: - name: Test run: uv run pytest --cov --cov-report=term-missing +{% endraw %} \ No newline at end of file diff --git a/template/.gitignore b/template/.gitignore.jinja similarity index 72% rename from template/.gitignore rename to template/.gitignore.jinja index aedca8d..3a83f26 100644 --- a/template/.gitignore +++ b/template/.gitignore.jinja @@ -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 %} diff --git a/template/CLAUDE.md.jinja b/template/CLAUDE.md.jinja index e393766..a08236c 100644 --- a/template/CLAUDE.md.jinja +++ b/template/CLAUDE.md.jinja @@ -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 @@ -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 diff --git a/template/README.md.jinja b/template/README.md.jinja index 93da8a0..87dac40 100644 --- a/template/README.md.jinja +++ b/template/README.md.jinja @@ -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. @@ -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 %} @@ -69,6 +74,10 @@ Add dependencies with `uv add ` (runtime) or `uv add --dev ` (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 ``` @@ -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 diff --git a/template/pyproject.toml.jinja b/template/pyproject.toml.jinja index 9b4405b..a1d121e 100644 --- a/template/pyproject.toml.jinja +++ b/template/pyproject.toml.jinja @@ -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 %} @@ -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", @@ -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 = [ @@ -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] diff --git a/template/src/{{package_name}}/__init__.py.jinja b/template/src/{{package_name}}/__init__.py.jinja index e1f7cb3..b6721f2 100644 --- a/template/src/{{package_name}}/__init__.py.jinja +++ b/template/src/{{package_name}}/__init__.py.jinja @@ -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 %} diff --git a/template/src/{{package_name}}/{% if include_cli %}cli.py{% endif %}.jinja b/template/src/{{package_name}}/{% if include_cli %}cli.py{% endif %}.jinja index eb9a819..65acb4d 100644 --- a/template/src/{{package_name}}/{% if include_cli %}cli.py{% endif %}.jinja +++ b/template/src/{{package_name}}/{% if include_cli %}cli.py{% endif %}.jinja @@ -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() diff --git a/template/tests/test_basic.py.jinja b/template/tests/test_basic.py.jinja index c03d079..5cc58dc 100644 --- a/template/tests/test_basic.py.jinja +++ b/template/tests/test_basic.py.jinja @@ -1,3 +1,4 @@ +{%- if include_example -%} from {{ package_name }} import hello @@ -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 %} diff --git a/template/tests/{% if include_cli %}test_cli.py{% endif %}.jinja b/template/tests/{% if include_cli %}test_cli.py{% endif %}.jinja index 67ad670..0941d45 100644 --- a/template/tests/{% if include_cli %}test_cli.py{% endif %}.jinja +++ b/template/tests/{% if include_cli %}test_cli.py{% endif %}.jinja @@ -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: diff --git a/template/{% if include_data_science %}notebooks{% endif %}/README.md b/template/{% if include_data_science %}notebooks{% endif %}/README.md new file mode 100644 index 0000000..6a33de5 --- /dev/null +++ b/template/{% if include_data_science %}notebooks{% endif %}/README.md @@ -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.