feat: add copier support (#176)

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

Author: henryiii

.github/workflows/reusable-cookie.yml

@@ -120,6 +120,9 @@ jobs:
       - name: Test meson-python
         run: nox -s 'tests(mesonpy)'
 
+      - name: Compare template generation
+        run: nox -s compare
+
   nox:
     name: Check included Noxfile
     runs-on: ubuntu-latest

.pre-commit-config.yaml

@@ -50,7 +50,7 @@ repos:
     rev: v1.3.0
     hooks:
       - id: mypy
-        files: "(src|web|tests)"
+        files: "(src|tests)"
         args: []
         additional_dependencies:
           - click

README.md

@@ -7,20 +7,21 @@
 [![PyPI version][pypi-version]][pypi-link]
 [![PyPI platforms][pypi-platforms]][pypi-link]
 
-A cookiecutter template for new Python projects based on the Scientific Python
-Developer Guide. What makes this different from other cookie cutter templates
-for Python packages?
+A [copier][]/[cookiecutter][] template for new Python projects based on the
+Scientific Python Developer Guide. What makes this different from other
+templates for Python packages?
 
 - Lives with the [Scientific-Python Development Guide][]: Every decision is
-  clearly documented and every tool described.
+  clearly documented and every tool described, and everything is kept in sync.
 - Twelve different backends to choose from for building packages.
 - Template generation tested in GitHub Actions using nox.
-- Includes several compiled backends using pybind11, with wheels produced for
-  all platforms using cibuildwheel.
-- Follows PyPA best practices and regularly updated.
+- Supports generation with both [copier][] and [cookiecutter][].
+- Includes several compiled backends using [pybind11][], with wheels produced
+  for all platforms using [cibuildwheel][].
 - Provides [`sp-repo-review`][pypi-link] to evaluate existing repos against the
   guidelines, with a WebAssembly version integrated with the guide. All checks
   cross-linked.
+- Follows PyPA best practices and regularly updated.
 
 Be sure you have read the [Scientific-Python Development Guide][] first, and
 possibly used them on a project or two. This is _not_ a minimal example or
@@ -33,36 +34,62 @@ During generation you can select from the following backends for your package:
 1. [hatch][]: This uses hatchling, a modern builder with nice file inclusion,
    extendable via plugins, and good error messages. **(Recommended for pure
    Python projects)**
-2. [setuptools][]: The classic build system. Most powerful, but high learning
-   curve and lots of configuration required.
-3. [setuptools621][setuptools]: The classic build system, but with the new
-   standardized configuration. Python 3.7+.
-4. [pybind11][]: This is setuptools but with an C++ extension written in
-   [pybind11][] and wheels generated by [cibuildwheel][].
-5. [scikit-build][]: A scikit-build (CMake) project also using pybind11, using
-   scikit-build-core. **(Recommended for C++ projects)**
-6. [meson-python][]: A Meson project also using pybind11.
-7. [poetry][]: An all-in-one solution to pure Python projects. Replaces
-   setuptools, venv/pipenv, pip, wheel, and twine. Higher learning curve, but is
-   all-in-one. Makes some bad default assumptions for libraries.
-8. [flit][]: A modern, lightweight [PEP 621][] build system for pure Python
+2. [flit][]: A modern, lightweight [PEP 621][] build system for pure Python
    projects. Replaces setuptools, no MANIFEST.in, setup.py, or setup.cfg. Low
    learning curve. Easy to bootstrap into new distributions. Difficult to get
    the right files included, little dynamic metadata support.
-9. [pdm][]: A modern, less opinionated all-in-one solution to pure Python
+3. [pdm][]: A modern, less opinionated all-in-one solution to pure Python
    projects supporting standards. Replaces setuptools, venv/pipenv, pip, wheel,
    and twine. Supports [PEP 621][].
-10. [trampolim][]: A modern [PEP 621][] builder with support for tasks, allowing
-    arbitrary Python to run during the build process if needed.
-11. [whey][]: A modern [PEP 621][] builder with some automation options for
-    Trove classifiers. Development seems to be stalled, possibly.
+4. [trampolim][]: A modern [PEP 621][] builder with support for tasks, allowing
+   arbitrary Python to run during the build process if needed.
+5. [whey][]: A modern [PEP 621][] builder with some automation options for Trove
+   classifiers. Development seems to be stalled, possibly.
+6. [poetry][]: An all-in-one solution to pure Python projects. Replaces
+   setuptools, venv/pipenv, pip, wheel, and twine. Higher learning curve, but is
+   all-in-one. Makes some bad default assumptions for libraries. The only one
+   with a non-standard pyproject.toml config.
+7. [setuptools621][setuptools]: The classic build system, but with the new
+   standardized configuration. Python 3.7+.
+8. [setuptools][]: The classic build system. Most powerful, but high learning
+   curve and lots of configuration required.
+9. [pybind11][]: This is setuptools but with an C++ extension written in
+   [pybind11][] and wheels generated by [cibuildwheel][].
+10. [scikit-build][]: A scikit-build (CMake) project also using pybind11, using
+    scikit-build-core. **(Recommended for C++ projects)**
+11. [meson-python][]: A Meson project also using pybind11.
 12. [maturin][]: A [PEP 621][] builder for Rust binary extensions.
     **(Recommended for Rust projects)**
 
 Currently, the best choice is probably hatch for pure Python projects, and
 setuptools (such as the pybind11 choice) for binary projects.
 
-#### To use:
+#### To use (modern copier version)
+
+Install `copier` and `copier-templates-extensions`. Using [pipx][], that's:
+
+```bash
+pipx install copier
+pipx inject copier copier-templates-extensions
+```
+
+Now, run copier to generate your project:
+
+```bash
+copier copy gh:scientific-python/cookie <pkg> --UNSAFE --vcs-ref=HEAD
+```
+
+(`<pkg>` is the path to put the new project.)
+
+You will get a much, much nicer CLI experience with helpful descriptions and
+answer validation. You will also get a `.copier-answers.yml` file, which will
+allow you to perform updates in the future.
+
+> Note: Add `--vcs-ref=HEAD` to get the latest version instead of the last
+> tagged version; this is required until there's a tagged version, and still
+> recommended after that.
+
+#### To use (classic cookiecutter version)
 
 Install cookiecutter, ideally with `brew install cookiecutter` if you use brew,
 otherwise with `pipx install cookiecutter` (or prepend `pipx run` to the command
@@ -72,8 +99,6 @@ below, and skip installation). Then run:
 cookiecutter gh:scientific-python/cookie
 ```
 
-You can also use `pipx run cookiecutter` without installing.
-
 Check the key setup files, `pyproject.toml`, and possibly `setup.cfg` and
 `setup.py` (pybind11 example). Update README.md. Also update and add docs to
 `docs/`.
@@ -125,9 +150,6 @@ You can test locally with [nox][]:
 # See all commands
 nox -l
 
-# Run all tests and checks (takes several minutes)
-nox
-
 # Run a specific check
 nox -s "lint(setuptools)"
 
@@ -160,7 +182,9 @@ NSLS-II guide during the 2023 Scientific-Python Developers Summit.
 
 [actions-badge]: https://github.com/scikit-hep/cookie/workflows/CI/badge.svg
 [actions-link]: https://github.com/scikit-hep/cookie/actions
-[cibuildwheel]: https://cibuildwheel.readthedocs.io/en/stable/
+[cibuildwheel]: https://cibuildwheel.readthedocs.io
+[cookiecutter]: https://cookiecutter.readthedocs.io
+[copier]: https://copier.readthedocs.io
 [flit]: https://flit.readthedocs.io/en/latest/
 [github-discussions-badge]: https://img.shields.io/static/v1?label=Discussions&message=Ask&color=blue&logo=github
 [github-discussions-link]: https://github.com/scikit-hep/cookie/discussions
@@ -173,16 +197,16 @@ NSLS-II guide during the 2023 Scientific-Python Developers Summit.
 [pep 621]: https://www.python.org/dev/peps/pep-0621
 [pipx]: https://pypa.github.io/pipx/
 [poetry]: https://python-poetry.org
-[pybind11]: https://pybind11.readthedocs.io/en/stable/
+[pybind11]: https://pybind11.readthedocs.io
 [pypi-link]: https://pypi.org/project/sp-repo-review/
 [pypi-platforms]: https://img.shields.io/pypi/pyversions/sp-repo-review
 [pypi-version]: https://badge.fury.io/py/sp-repo-review.svg
 [rtd-badge]: https://readthedocs.org/projects/scientific-python-cookie/badge/?version=latest
 [rtd-link]: https://scientific-python-cookie.readthedocs.io/en/latest/?badge=latest
 [scientific-python development guide]: https://learn.scientific-python.org/development
-[scikit-build]: https://scikit-build.readthedocs.io/en/latest/
-[setuptools]: https://setuptools.readthedocs.io/en/latest/
-[trampolim]: https://trampolim.readthedocs.io/en/latest/
-[whey]: https://whey.readthedocs.io/en/latest/
+[scikit-build]: https://scikit-build.readthedocs.io
+[setuptools]: https://setuptools.readthedocs.io
+[trampolim]: https://trampolim.readthedocs.io
+[whey]: https://whey.readthedocs.io
 
 <!-- prettier-ignore-end -->

cookiecutter.json

@@ -8,20 +8,21 @@
   "license": ["BSD", "Apache", "MIT"],
   "backend": [
     "hatch",
-    "setuptools",
-    "setuptools621",
-    "pybind11",
-    "skbuild",
-    "mesonpy",
-    "poetry",
     "flit",
     "pdm",
     "trampolim",
     "whey",
+    "poetry",
+    "setuptools621",
+    "setuptools",
+    "pybind11",
+    "skbuild",
+    "mesonpy",
     "maturin"
   ],
   "_extensions": ["jinja2_time.TimeExtension"],
   "__year": "{% now 'utc', '%Y' %}",
   "__project_slug": "{{ cookiecutter.project_name | lower | replace('-', '_') | replace('.', '_') }}",
-  "__type": "{{ 'compiled' if cookiecutter.backend in ['pybind11', 'skbuild', 'mesonpy', 'maturin'] else 'pure' }}"
+  "__type": "{{ 'compiled' if cookiecutter.backend in ['pybind11', 'skbuild', 'mesonpy', 'maturin'] else 'pure' }}",
+  "__answers": ""
 }

copier.yml

@@ -0,0 +1,70 @@
+project_name:
+  type: str
+  help: The name of your project
+  validator: >-
+    {% if not project_name %} You must provide a name for the project. {% endif
+    %}
+
+org:
+  type: str
+  help: The name of your (GitHub?) org
+  validator: >-
+    {% if not project_name %} You must provide a org for the project. It might
+    just be your user name on the site (like GitHub) you are targeting. {% endif
+    %}
+
+url:
+  type: str
+  help: The URL for your repository
+  default: "https://github.com/{{ org }}/{{ project_name }}"
+
+full_name:
+  type: str
+  help: Your name
+  placeholder: My Name
+  validator: >-
+    {% if not full_name %} You must provide a name (possibly yours) to place in
+    your config files. {% endif %}
+
+email:
+  type: str
+  help: Your email
+  placeholder: me@email.com
+  validator: >-
+    {% if not email %} You must provide an email (possibly yours) to place in
+    your config files, as required by PyPI. {% endif %}
+
+project_short_description:
+  type: str
+  default: A great package.
+
+license:
+  help: Select a license
+  choices:
+    - BSD
+    - Apache
+    - MIT
+
+backend:
+  help: Choose a build backend
+  choices:
+    "Hatchling                      - Pure Python (recommended)": hatch
+    "Flit-core                      - Pure Python (minimal)": flit
+    "PDM-backend                    - Pure Python": pdm
+    "Trampolim                      - Pure Python": trampolim
+    "Whey                           - Pure Python": whey
+    "Poetry                         - Pure Python": poetry
+    "Setuptools with pyproject.toml - Pure Python": setuptools621
+    "Setuptools with setup.py       - Pure Python": setuptools
+    "Setuptools and pybind11        - Compiled C++": pybind11
+    "Scikit-build-core              - Compiled C++ (recommended)": skbuild
+    "Meson-python                   - Compiled C++ (also good)": mesonpy
+    "Maturin                        - Compiled Rust (recommended)": maturin
+
+_templates_suffix: ""
+
+_subdirectory: "{% raw %}{{cookiecutter.project_name}}{% endraw %}"
+
+_jinja_extensions:
+  - copier_templates_extensions.TemplateExtensionLoader
+  - extensions.py:CookiecutterNamespace

docs/README.md

@@ -4,7 +4,9 @@ This is maintained by the scientific Python community for the benefit of fellow
 scientists and research software engineers. The repository contains:
 
 - A guide
-- A cookiecutter that generates a template for a scientific Python library
+- A copier/cookiecutter template that generates a template for a scientific
+  Python library
+- sp-repo-review, a plugin for [repo-review](https://repo-review.readthedocs.io)
 
 ## Contributing to the documentation
 

docs/pages/guides/index.md

@@ -24,9 +24,9 @@ choices for using CI to distribute your package, on for [pure Python][gha_pure],
 and one for [compiled extensions][gha_wheels]. You can read about setting up
 good tests on the [pytest page][pytest].
 
-Once you have completed the guidelines, there is a [cookiecutter][] project,
-[scientific-python/cookie][], that implements these guidelines and lets you
-setup a new package from a template in less than 60 seconds!
+Once you have completed the guidelines, there is a [copier][]/[cookiecutter][]
+project, [scientific-python/cookie][], that implements these guidelines and lets
+you setup a new package from a template in less than 60 seconds!
 
 You can also evaluate your repository against the guidelines by using
 [scientific-python-repo-review][]!
@@ -45,6 +45,7 @@ You can also evaluate your repository against the guidelines by using
 [scientific-python-repo-review]: {% link pages/guides/repo_review.md %}
 
 [cookiecutter]: https://cookiecutter.readthedocs.io
+[copier]: https://copier.readthedocs.io
 [scientific-python/cookie]: https://github.com/scientific-python/cookie
 
 <!-- prettier-ignore-end -->

docs/pages/index.md

@@ -20,9 +20,10 @@ maintainable, reusable, and shareable form? Start at the
 guides]({% link pages/guides/index.md %}) provide task-based instruction on
 topics that scientists and research software engineers may encounter as their
 projects evolve and grow. This covers everything from writing and building
-documentation to modern Python packaging. This comes with a cookiecutter for
-making new repos, [scientific-python/cookie][], and [sp-repo-review][], a tool
-for comparing your repository with the guidelines, runnable in WebAssembly.
+documentation to modern Python packaging. This comes with a
+[copier][]/[cookiecutter][] template for making new repos,
+[scientific-python/cookie][], and [sp-repo-review][], a tool for comparing your
+repository with the guidelines, runnable in WebAssembly.
 
 **Learn to write better research code.** A high-level document on
 [principles]({% link pages/principles/index.md %}) provides advice based on the
@@ -46,4 +47,6 @@ basic facility with git to use these tools successfully. We recommend the
 <!-- prettier-ignore-start -->
 [scientific-python/cookie]: https://github.com/scientific-python/cookie
 [sp-repo-review]: {% link pages/guides/repo_review.md %}
+[copier]: https://copier.readthedocs.io
+[cookiecutter]: https://cookiecutter.readthedocs.io
 <!-- prettier-ignore-end -->

docs/pages/patterns/data_files.md

@@ -40,9 +40,9 @@ Alternatives:
   need to download large datasets for their examples and tests.
 
 If you use one these alternatives, add the names of the generated or downloaded
-files to the project's `.gitignore` file, which was provided by the cookiecutter
-template. This helps protect you against accidentally committing the file to
-git.
+files to the project's `.gitignore` file, which is provided by the
+[copier][]/[cookiecutter][] template. This helps protect you against
+accidentally committing the file to git.
 
 If the file in question is a text file and not very large (\< 100 kB) than it's
 reasonable to just bundle it with the package. If not, see the recommendation at
@@ -201,7 +201,11 @@ file_path = pooch.retrieve(
 On repeated runs of this command, the locally cached filename would be used
 instead of downloading the data again.
 
+<!-- prettier-ignore-start -->
 [importlib_resources]: https://importlib-resources.readthedocs.io/en/latest/
 [osf.io]: https://osf.io/
 [pooch]: https://www.fatiando.org/pooch/latest/
 [zenodo]: https://zenodo.org/
+[copier]: https://copier.readthedocs.io
+[cookiecutter]: https://cookiecutter.readthedocs.io
+<!-- prettier-ignore-end -->

extensions.py

@@ -0,0 +1,18 @@
+import datetime
+
+from copier_templates_extensions import ContextHook
+
+
+class CookiecutterNamespace(ContextHook):
+    def hook(self, context):
+        context["__year"] = str(datetime.datetime.today().year)
+        context["__project_slug"] = (
+            context["project_name"].lower().replace("-", "_").replace(".", "_")
+        )
+        context["__type"] = (
+            "compiled"
+            if context["backend"] in ["pybind11", "skbuild", "mesonpy", "maturin"]
+            else "pure"
+        )
+        context["__answers"] = context["_copier_conf"]["answers_file"]
+        return {"cookiecutter": context}