Add the --version-spec cli argument, that allows you to specify the

pep440 specifier that limit's what version of the template can be used
to copy or update.

Author: ddejong-therp

copier/_cli.py

@@ -239,6 +239,13 @@ class CopierCopySubApp(_Subcommand):
         ["-w", "--overwrite"],
         help="Overwrite files that already exist, without asking.",
     )
+    version_spec = cli.SwitchAttr(
+        ["-V", "--version-spec"],
+        str,
+        default=None,
+        help="Prevent copying from a version of the template that does not adhere to "
+            "the version specification.",
+    )
 
     def main(self, template_src: str, destination_path: str) -> int:
         """Call [run_copy][copier.run_copy].
@@ -270,6 +277,7 @@ def inner() -> None:
                 quiet=self.quiet,
                 unsafe=self.unsafe,
                 skip_tasks=self.skip_tasks,
+                version_spec=self.version_spec,
             )
 
         return _handle_exceptions(inner)
@@ -318,6 +326,13 @@ class CopierRecopySubApp(_Subcommand):
         default=False,
         help="Skip questions that have already been answered",
     )
+    version_spec = cli.SwitchAttr(
+        ["-V", "--version-spec"],
+        str,
+        default=None,
+        help="Prevent copying from a version of the template that does not adhere to "
+            "the version specification.",
+    )
 
     def main(self, destination_path: cli.ExistingDirectory = ".") -> int:
         """Call [run_recopy][copier.run_recopy].
@@ -347,6 +362,7 @@ def inner() -> None:
                 unsafe=self.unsafe,
                 skip_answered=self.skip_answered,
                 skip_tasks=self.skip_tasks,
+                version_spec=self.version_spec,
             )
 
         return _handle_exceptions(inner)
@@ -401,6 +417,13 @@ class CopierUpdateSubApp(_Subcommand):
         default=False,
         help="Skip questions that have already been answered",
     )
+    version_spec = cli.SwitchAttr(
+        ["-V", "--version-spec"],
+        str,
+        default=None,
+        help="Prevent updates to any version that does not adhere to the version "
+            "specification.",
+    )
 
     def main(self, destination_path: cli.ExistingDirectory = ".") -> int:
         """Call [run_update][copier.run_update].
@@ -432,6 +455,7 @@ def inner() -> None:
                 unsafe=self.unsafe,
                 skip_answered=self.skip_answered,
                 skip_tasks=self.skip_tasks,
+                version_spec=self.version_spec,
             )
 
         return _handle_exceptions(inner)

copier/_main.py

@@ -15,6 +15,7 @@
 from filecmp import dircmp
 from functools import cached_property, partial, wraps
 from itertools import chain
+from packaging.specifiers import SpecifierSet
 from pathlib import Path, PurePath, PurePosixPath, PureWindowsPath
 from shutil import rmtree
 from tempfile import TemporaryDirectory
@@ -249,6 +250,7 @@ class Worker:
     unsafe: bool = False
     skip_answered: bool = False
     skip_tasks: bool = False
+    version_spec: str | None = None
 
     answers: AnswersMap = field(default_factory=AnswersMap, init=False)
     _cleanup_hooks: list[Callable[[], None]] = field(default_factory=list, init=False)
@@ -1065,7 +1067,12 @@ def template(self) -> Template:
                 raise TypeError("Template not found")
             url = str(self.subproject.template.url)
         ref = self.resolved_vcs_ref
-        result = Template(url=url, ref=ref, use_prereleases=self.use_prereleases)
+        result = Template(
+            url=url,
+            ref=ref,
+            use_prereleases=self.use_prereleases,
+            version_spec=self.version_spec
+        )
         self._cleanup_hooks.append(result._cleanup)
         return result
 
@@ -1195,6 +1202,12 @@ def run_update(self) -> None:
             # We might have switched operation context, ensure the cached property
             # is regenerated to re-render templates.
             del self.match_exclude
+        if self.version_spec:
+            if not SpecifierSet(self.version_spec).contains(self.template.version):
+                raise UserMessageError(
+                    f"Cannot update: new version {self.template.version}, as it does "
+                    f"not adhere to specification \"{self.version_spec}\"."
+                )
 
         self._apply_update()
         self._print_message(self.template.message_after_update)
@@ -1544,6 +1557,7 @@ def run_copy(
     quiet: bool = False,
     unsafe: bool = False,
     skip_tasks: bool = False,
+    version_spec: SpecifierSet | None = None,
 ) -> Worker:
     """Copy a template to a destination, from zero."""
     with Worker(
@@ -1572,6 +1586,7 @@ def run_copy(
         quiet=quiet,
         unsafe=unsafe,
         skip_tasks=skip_tasks,
+        version_spec=version_spec,
     ) as worker:
         worker.run_copy()
     return worker
@@ -1596,6 +1611,7 @@ def run_recopy(
     unsafe: bool = False,
     skip_answered: bool = False,
     skip_tasks: bool = False,
+    version_spec: SpecifierSet | None = None,
 ) -> Worker:
     """Update a subproject from its template, discarding subproject evolution."""
     with Worker(
@@ -1624,6 +1640,7 @@ def run_recopy(
         unsafe=unsafe,
         skip_answered=skip_answered,
         skip_tasks=skip_tasks,
+        version_spec=version_spec,
     ) as worker:
         worker.run_recopy()
     return worker
@@ -1650,6 +1667,7 @@ def run_update(
     unsafe: bool = False,
     skip_answered: bool = False,
     skip_tasks: bool = False,
+    version_spec: SpecifierSet | None = None,
 ) -> Worker:
     """Update a subproject, from its template."""
     with Worker(
@@ -1680,6 +1698,7 @@ def run_update(
         unsafe=unsafe,
         skip_answered=skip_answered,
         skip_tasks=skip_tasks,
+        version_spec=version_spec,
     ) as worker:
         worker.run_update()
     return worker

copier/_template.py

@@ -19,6 +19,7 @@
 import yaml
 from funcy import lflatten
 from packaging.version import Version, parse
+from packaging.specifiers import SpecifierSet
 from plumbum.machines import local
 from pydantic.dataclasses import dataclass
 
@@ -219,6 +220,7 @@ class Template:
     url: str
     ref: str | None = None
     use_prereleases: bool = False
+    version_spec: str | None = None
 
     def _cleanup(self) -> None:
         if temp_clone := self._temp_clone():
@@ -566,11 +568,16 @@ def local_abspath(self) -> Path:
         Dirty changes for local VCS-tracked templates will be copied.
         """
         result = Path(self.url)
+        print(result)
         if self.vcs == "git":
             result = Path(
                 clone(
                     self.url_expanded,
-                    self.ref or get_latest_tag(self.url_expanded, self.use_prereleases),
+                    self.ref or get_latest_tag(
+                        self.url_expanded,
+                        self.use_prereleases,
+                        self.version_spec and SpecifierSet(self.version_spec) or None,
+                    ),
                 )
             )
         if not result.is_dir():

copier/_vcs.py

@@ -10,12 +10,13 @@
 from warnings import warn
 
 from packaging import version
+from packaging.specifiers import SpecifierSet
 from packaging.version import InvalidVersion, Version
 from plumbum import TF, ProcessExecutionError, colors, local
 from plumbum.machines import LocalCommand
 
 from ._types import OptBool, OptStrOrPath, StrOrPath
-from .errors import DirtyLocalWarning, ShallowCloneWarning
+from .errors import DirtyLocalWarning, ShallowCloneWarning, UserMessageError
 
 GIT_USER_NAME = "Copier"
 GIT_USER_EMAIL = "copier@copier"
@@ -126,7 +127,7 @@ def get_repo(url: str) -> str | None:
     return None
 
 
-def get_latest_tag(url: str, use_prereleases: OptBool = False) -> str:
+def get_latest_tag(url: str, use_prereleases: OptBool = False, spec: SpecifierSet | None = None) -> str:
     """Get latest git tag, sorted by PEP 440.
 
     Args:
@@ -147,10 +148,14 @@ def get_latest_tag(url: str, use_prereleases: OptBool = False) -> str:
     all_tags = (tag for tag in all_tags if valid_version(tag))
     if not use_prereleases:
         all_tags = (tag for tag in all_tags if not version.parse(tag).is_prerelease)
+    if spec:
+        all_tags = spec.filter(all_tags, use_prereleases)
     sorted_tags = sorted(all_tags, key=version.parse, reverse=True)
     try:
         return str(sorted_tags[0])
-    except IndexError:
+    except IndexError as e:
+        if spec:
+            raise UserMessageError(f"No git tag found that matches version spec {spec}.") from e
         print(
             colors.warn | "No git tags found in template; using HEAD as ref",
             file=sys.stderr,