vcs-versioning 2.2.4__tar.gz → 2.3.0__tar.gz

{vcs_versioning-2.2.4 → vcs_versioning-2.3.0}/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 <!-- towncrier release notes start -->
 
+## 2.3.0 (2026-08-13)
+
+### Added
+
+- Add a ``vcs_versioning.dynamic_metadata`` provider for the [dynamic-metadata](https://github.com/scikit-build/dynamic-metadata) system. ([#1465](https://github.com/pypa/setuptools-scm/issues/1465))
+
+
+### Fixed
+
+- Make the `tag.strict` and `scm.git.describe_command` diagnostics actionable and non-conflicting.
+
+  The `tag.strict` future-default notice is now reported by the git backend rather than at configuration time, and only when the future default would actually select a different tag for the repository -- the message names both the current and the future version string. Projects the change cannot affect are silent, and setting an explicit `describe_command` no longer triggers it at all, so the two warnings can no longer contradict each other.
+
+  The `describe_command` notice is likewise limited to the case where it and an explicit `tag.strict` really disagree, and no longer claims that `tag.prefix` has no effect -- prefix stripping applies regardless of how the tag was selected.
+
+  Both are logged at warning level instead of raised as warnings, so `SETUPTOOLS_SCM_DEBUG=ERROR` silences them. ([#1429](https://github.com/pypa/setuptools-scm/issues/1429))
+- Honour `export-ignore` on directories and submodules again in the git file finder.
+
+  The switch from `git archive` to `git ls-files --recurse-submodules` lost two parts of the archive semantics: `--recurse-submodules` listed every submodule regardless of `export-ignore`, and the `:(exclude,attr:export-ignore)` pathspec only matches files, so an `export-ignore` on a directory no longer excluded the files below it. Projects that kept vendored submodules in an `export-ignore`d directory suddenly shipped them in their sdists.
+
+  The finder now lists a repository without recursion, checks `export-ignore` for directories via `git check-attr` (which is what `git archive` effectively does when it skips a tree), and only then descends into the submodules that survived. Submodule contents are still listed - with their own `.gitattributes` applied - so `export-ignore` in the parent repository now controls exactly which submodules get packaged. Submodules that are not checked out are skipped instead of failing the listing. ([#1469](https://github.com/pypa/setuptools-scm/issues/1469))
+- Honour `tag.strict` on Mercurial changesets that carry tags of their own, and report the coming strict default for Mercurial repositories.
+
+  `tag.strict` was only applied when looking for the latest tag, so a checked-out changeset tagged `event-2024` still produced version `2024` even with `tag.strict = true`, while git rejected the same tag. Strict matching now applies to the tags on the changeset too: a changeset carrying only event-style tags is treated as untagged and versioning continues from the last real version tag, matching `git describe --match`. When several tags sit on one changeset, the version-shaped one is now selected instead of whichever Mercurial happened to list first.
+
+  The `tag.strict` divergence diagnostic added in #1429 now covers Mercurial as well, naming the current and future version whenever the coming default would change them. Both backends share the message, and the git-only helpers moved to `_backends/_scm_workdir.py`.
+
+  Note that the Mercurial backend required a dot in version tags before setuptools-scm 9, so for Mercurial projects the coming strict default restores the historical behavior. ([#1495](https://github.com/pypa/setuptools-scm/issues/1495))
+
 ## 2.2.4 (2026-08-07)
 
 ### Fixed

{vcs_versioning-2.2.4/src/vcs_versioning.egg-info → vcs_versioning-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vcs-versioning
-Version: 2.2.4
+Version: 2.3.0
 Summary: the blessed package to manage your versions by vcs metadata
 Author-email: Ronny Pfannschmidt <opensource@ronnypfannschmidt.de>
 License: MIT

{vcs_versioning-2.2.4 → vcs_versioning-2.3.0}/pyproject.toml

@@ -91,6 +91,9 @@ node-and-timestamp = "vcs_versioning._version_schemes:get_local_node_and_timesta
 "semver-pep440-release-branch" = "vcs_versioning._version_schemes:release_branch_semver_version"
 "towncrier-fragments" = "vcs_versioning._version_schemes._towncrier:version_from_fragments"
 
+[project.entry-points."dynamic_metadata.provider"]
+"vcs_versioning" = "vcs_versioning._dynamic_metadata"
+
 [tool.setuptools.packages.find]
 where = ["src"]
 namespaces = false

{vcs_versioning-2.2.4 → vcs_versioning-2.3.0}/src/vcs_versioning/_backends/_git.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import dataclasses
+import fnmatch
 import logging
 import os
 import re
@@ -23,10 +24,17 @@ from .._run_cmd import CompletedProcess as _CompletedProcess
 from .._run_cmd import require_command as _require_command
 from .._run_cmd import run as _run
 from .._scm_version import ScmVersion, meta, tag_to_version
-from ._scm_workdir import Workdir, get_latest_file_mtime
+from ._scm_workdir import (
+    STRICT_DIAGNOSTIC,
+    Workdir,
+    config_location,
+    get_latest_file_mtime,
+    report_once,
+    version_outcome,
+)
 
 if TYPE_CHECKING:
-    from .._protocols import DescribeCapable
+    from .._protocols import DescribeCapable, GitQueryable
     from . import _hg_git as hg_git
 log = logging.getLogger(__name__)
 
@@ -74,12 +82,14 @@ def run_git(
     *,
     check: bool = False,
     timeout: int | None = None,
+    input: str | None = None,
 ) -> _CompletedProcess:
     return _run(
         ["git", "--git-dir", repo / ".git", *args],
         cwd=repo,
         check=check,
         timeout=timeout,
+        input=input,
     )
 
 
@@ -232,7 +242,10 @@ class GitWorkdir(Workdir):
     def default_describe(self) -> _CompletedProcess:
         match_glob = self.config.tag.describe_match_glob()
         cmd = make_describe_command(match_glob)
-        return self.run_git(cmd[1:])
+        res = self.run_git(cmd[1:])
+        if self.config.tag.strict is None:
+            _warn_if_strict_would_differ(self, self.config, res)
+        return res
 
     def get_scm_version(self) -> ScmVersion | None:
         """Obtain version metadata from this git work directory."""
@@ -264,6 +277,90 @@ class GitWorkdir(Workdir):
         return res.returncode == 0
 
 
+def _describe_tag(output: str) -> str | None:
+    """Extract just the tag name from a ``git describe --long`` output."""
+    if not output.strip():
+        return None
+    return _git_parse_describe(output.strip())[0]
+
+
+def _strict_match_glob(prefix: str) -> str:
+    """The ``--match`` glob ``tag.strict = true`` would produce."""
+    return f"{prefix}*[0-9]*.*[0-9]*"
+
+
+def _describe_outcome(output: str, config: Configuration) -> str:
+    """Render what a ``git describe`` *output* would yield as a version."""
+    if not output.strip():
+        return version_outcome(config, None)
+
+    tag, distance, node, dirty = _git_parse_describe(output.strip())
+    return version_outcome(config, tag, distance=distance, dirty=dirty, node=node)
+
+
+def _warn_if_strict_would_differ(
+    wd: GitQueryable, config: Configuration, permissive: _CompletedProcess
+) -> None:
+    """Report the ``tag.strict`` future default only when it changes the answer.
+
+    ``tag.strict`` is unset, so the permissive glob was used.  Stay silent
+    unless the strict glob would pick a different tag, so that projects the
+    future default cannot affect are never nagged.
+    """
+    permissive_tag = _describe_tag(permissive.stdout)
+    strict_glob = _strict_match_glob(config.tag.prefix)
+
+    if permissive_tag is None:
+        # nothing matched the wider glob, so nothing matches the narrower one
+        return
+    if fnmatch.fnmatchcase(permissive_tag, strict_glob):
+        # the strict glob matches a subset of the permissive one, so a
+        # permissive answer that is itself strict-matching is also the
+        # closest strict-matching tag -- no subprocess needed
+        return
+
+    strict = wd.run_git(make_describe_command(strict_glob)[1:])
+    report_once(
+        f"strict-divergence:{wd.path}:{permissive_tag}:{_describe_tag(strict.stdout)}",
+        STRICT_DIAGNOSTIC,
+        _describe_outcome(permissive.stdout, config),
+        _describe_outcome(strict.stdout, config),
+        config_location(config),
+    )
+
+
+def _warn_if_describe_command_overrides_strict(
+    wd: GitQueryable, config: Configuration, describe_res: _CompletedProcess
+) -> None:
+    """Report that ``describe_command`` beat an explicit ``tag.strict``.
+
+    Only fires when the two actually disagree about which tag to use --
+    setting both is harmless as long as they pick the same tag.  ``tag.prefix``
+    is deliberately not mentioned: it still strips the prefix before version
+    parsing, so combining it with ``describe_command`` is legitimate.
+    """
+    strict_glob = _strict_match_glob(config.tag.prefix)
+    strict = wd.run_git(make_describe_command(strict_glob)[1:])
+    strict_tag = _describe_tag(strict.stdout)
+    describe_tag = _describe_tag(describe_res.stdout)
+    if strict_tag == describe_tag:
+        return
+
+    report_once(
+        f"describe-overrides-strict:{wd.path}:{describe_tag}:{strict_tag}",
+        "scm.git.describe_command takes precedence over tag.strict, and they"
+        " disagree for this repository:\n"
+        "  describe_command gives:      %s\n"
+        "  tag.strict = %s would give: %s\n"
+        "Drop tag.strict, or drop describe_command and let tag.prefix/tag.strict"
+        " build the match pattern, in %s.",
+        _describe_outcome(describe_res.stdout, config),
+        str(config.tag.strict).lower(),
+        _describe_outcome(strict.stdout, config),
+        config_location(config),
+    )
+
+
 def warn_on_shallow(wd: GitWorkdir) -> None:
     """experimental, may change at any time"""
     if wd.is_shallow() and not wd.head_is_exact_tag():
@@ -410,6 +507,8 @@ def version_from_describe(
             describe_res = wd.run_git(cmd_args[1:])
         else:
             describe_res = _run(cmd_args, wd.path, timeout=wd._subprocess_timeout)
+        if config.tag.strict is not None:
+            _warn_if_describe_command_overrides_strict(wd, config, describe_res)
     else:
         describe_res = wd.default_describe()
 

{vcs_versioning-2.2.4 → vcs_versioning-2.3.0}/src/vcs_versioning/_backends/_hg.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import dataclasses
 import datetime
 import logging
 import os
@@ -15,12 +16,92 @@ from .._run_cmd import require_command as _require_command
 from .._run_cmd import run as _run
 from .._scm_version import ScmVersion, meta, tag_to_version
 from .._version_cls import Version
-from ._scm_workdir import Workdir, get_latest_file_mtime
+from .._version_schemes import format_version
+from ._scm_workdir import (
+    STRICT_DIAGNOSTIC,
+    Workdir,
+    config_location,
+    get_latest_file_mtime,
+    report_once,
+)
 
 log = logging.getLogger(__name__)
 
 _HG_PSEUDO_TAGS = frozenset({"tip", "qbase", "qtip", "qparent"})
 
+_KEEP: Any = object()
+"""Sentinel for "use the configured value" -- ``None`` is a real strictness."""
+
+
+def hg_tag_pattern(config: Configuration, strict: bool | None = _KEEP) -> str:
+    """Build the Mercurial regex ``latesttag()`` is given from tag config.
+
+    *strict* overrides ``config.tag.strict``, which the diagnostics use to ask
+    what the other setting would have selected.
+    """
+    if strict is _KEEP:
+        strict = config.tag.strict
+    prefix = re.escape(config.tag.prefix) if config.tag.prefix else ""
+    if strict:
+        # Require at least one dot in the version part
+        return rf"{prefix}\d+\.\d+"
+    else:
+        return rf"{prefix}\d+"
+
+
+def matches_tag_pattern(
+    tag: str, config: Configuration, strict: bool | None = _KEEP
+) -> bool:
+    """Whether *tag* satisfies the configured strictness.
+
+    The pattern is the same one ``latesttag()`` is given on the distance path,
+    so both paths agree about which tags count as version tags.
+    """
+    return re.search(hg_tag_pattern(config, strict), tag) is not None
+
+
+def select_tag(
+    tags: list[str], config: Configuration, strict: bool | None = _KEEP
+) -> str | None:
+    """Pick the version tag to use from the tags on the current changeset.
+
+    Pre-filters with tag_regex so non-version tags are silently skipped
+    without emitting warnings from tag_to_version().
+    Strips tag.prefix before matching when configured.
+
+    Under ``tag.strict = true`` a tag that is not version-shaped is
+    rejected outright rather than falling back to a looser match, so a
+    changeset carrying only event-style tags falls through to the distance
+    path -- the same thing ``git describe --match`` does (#1495).
+    """
+    if strict is _KEEP:
+        strict = config.tag.strict
+    tag_prefix = config.tag.prefix
+    for tag_str in tags:
+        check_str = tag_str
+        if tag_prefix and tag_str.startswith(tag_prefix):
+            check_str = tag_str[len(tag_prefix) :]
+        if not config.tag.regex.match(check_str):
+            log.debug("skipping non-version tag %r", tag_str)
+            continue
+        # only narrow when strictness was asked for, so the permissive
+        # path keeps selecting exactly what it always has
+        if strict and not matches_tag_pattern(tag_str, config, strict):
+            log.debug("skipping tag %r: not version-shaped under tag.strict", tag_str)
+            continue
+        if tag_to_version(tag_str, config) is not None:
+            return tag_str
+    return None
+
+
+def _rendered(version: ScmVersion | None, tag: str | None) -> str:
+    """Render one side of the ``tag.strict`` comparison for the diagnostic."""
+    if version is None:
+        return "no matching tag, falling back to the fallback version"
+    if tag is None:
+        return format_version(version)
+    return f"{format_version(version)} (from tag {tag!r})"
+
 
 def _get_hg_command() -> str:
     """Read the hg command from resolved runtime settings.
@@ -95,12 +176,71 @@ class HgWorkdir(Workdir):
         tags = self._parse_tags(tags_str)
 
         # Try to get version from current tags
+        result: ScmVersion | None
         tag_version = self._get_version_from_tags(tags, config)
         if tag_version:
-            return meta(tag_version, dirty=dirty, branch=branch, config=config)
+            result = meta(tag_version, dirty=dirty, branch=branch, config=config)
+        else:
+            # Fall back to distance-based versioning
+            result = self._get_distance_based_version(
+                config, dirty, branch, node, node_date
+            )
+
+        if config.tag.strict is None:
+            self._report_strict_divergence(config, tags, result)
+        return result
 
-        # Fall back to distance-based versioning
-        return self._get_distance_based_version(config, dirty, branch, node, node_date)
+    def _report_strict_divergence(
+        self, config: Configuration, tags: list[str], result: ScmVersion | None
+    ) -> None:
+        """Report the coming ``tag.strict`` default when it changes the version.
+
+        Mirrors the git backend: stay silent unless strict matching would
+        select a different tag, so repositories the change cannot affect are
+        never nagged (#1495).
+        """
+        permissive_tag = select_tag(tags, config, strict=False)
+        strict_tag = select_tag(tags, config, strict=True)
+
+        if permissive_tag is not None and permissive_tag == strict_tag:
+            # the changeset is tagged with a version-shaped tag either way
+            return
+        if permissive_tag is None and strict_tag is None:
+            # neither takes the exact-tag path, so compare the latest tags
+            permissive_tag = self.get_latest_normalizable_tag(config, strict=False)
+            if permissive_tag is None:
+                return
+            if matches_tag_pattern(permissive_tag, config, strict=True):
+                # the permissive answer is itself version-shaped, and strict
+                # matches a subset, so both paths land on the same tag
+                return
+
+        # whichever side found no tag on this changeset falls through to the
+        # distance path, so name the tag it would count from there
+        if permissive_tag is None:
+            permissive_tag = self.get_latest_normalizable_tag(config, strict=False)
+        if strict_tag is None:
+            strict_tag = self.get_latest_normalizable_tag(config, strict=True)
+
+        strict_config = dataclasses.replace(
+            config, tag=dataclasses.replace(config.tag, strict=True)
+        )
+        strict_result = self.get_meta(strict_config)
+        if (
+            result is not None
+            and strict_result is not None
+            and format_version(result) == format_version(strict_result)
+        ):
+            # different tags, same resulting version -- nothing to act on
+            return
+
+        report_once(
+            f"strict-divergence:{self.path}:{permissive_tag}:{strict_tag}",
+            STRICT_DIAGNOSTIC,
+            _rendered(result, permissive_tag),
+            _rendered(strict_result, strict_tag),
+            config_location(config),
+        )
 
     def _get_node_info(self) -> tuple[str, str, str] | None:
         """Get node, tags, and date information from mercurial log."""
@@ -163,24 +303,11 @@ class HgWorkdir(Workdir):
     def _get_version_from_tags(
         self, tags: list[str], config: Configuration
     ) -> Version | None:
-        """Try to get a version from the current tags.
-
-        Pre-filters with tag_regex so non-version tags are silently skipped
-        without emitting warnings from tag_to_version().
-        Strips tag.prefix before matching when configured.
-        """
-        tag_prefix = config.tag.prefix
-        for tag_str in tags:
-            check_str = tag_str
-            if tag_prefix and tag_str.startswith(tag_prefix):
-                check_str = tag_str[len(tag_prefix) :]
-            if not config.tag.regex.match(check_str):
-                log.debug("skipping non-version tag %r", tag_str)
-                continue
-            version = tag_to_version(tag_str, config)
-            if version is not None:
-                return version
-        return None
+        """Try to get a version from the current tags."""
+        tag_str = select_tag(tags, config)
+        if tag_str is None:
+            return None
+        return tag_to_version(tag_str, config)
 
     def _get_distance_based_version(
         self,
@@ -234,20 +361,11 @@ class HgWorkdir(Workdir):
             check=True,
         ).stdout
 
-    def _hg_tag_pattern(self, config: Configuration) -> str:
-        """Build a Mercurial regex pattern from tag configuration."""
-        prefix = re.escape(config.tag.prefix) if config.tag.prefix else ""
-        if config.tag.strict:
-            # Require at least one dot in the version part
-            return rf"{prefix}\d+\.\d+"
-        else:
-            return rf"{prefix}\d+"
-
     def get_latest_normalizable_tag(
-        self, config: Configuration | None = None
+        self, config: Configuration | None = None, strict: bool | None = _KEEP
     ) -> str | None:
         if config is not None:
-            pattern = self._hg_tag_pattern(config)
+            pattern = hg_tag_pattern(config, strict)
         else:
             pattern = r"\."
         result = self.hg_log(

{vcs_versioning-2.2.4 → vcs_versioning-2.3.0}/src/vcs_versioning/_backends/_scm_workdir.py

@@ -1,11 +1,12 @@
 from __future__ import annotations
 
 import logging
+import warnings
 from dataclasses import dataclass
 from dataclasses import field as dc_field
 from datetime import date, datetime, timezone
 from pathlib import Path
-from typing import TYPE_CHECKING, overload
+from typing import TYPE_CHECKING, Any, overload
 
 from .._scm_version import ScmVersion
 
@@ -77,6 +78,68 @@ def get_latest_file_mtime(changed_files: list[str], base_path: Path) -> date | N
     return None
 
 
+# ---------------------------------------------------------------------------
+# Configuration diagnostics shared by the backends
+#
+# These report settings whose effect can only be judged once the SCM has been
+# consulted -- most of all the coming ``tag.strict`` default, which is only
+# worth mentioning when it changes the version at hand (#1429, #1495).
+# ---------------------------------------------------------------------------
+
+_diagnostics_reported: set[str] = set()
+
+
+def report_once(key: str, message: str, *args: object) -> None:
+    """Log a config diagnostic at most once per process.
+
+    Unlike ``warnings.warn`` the logging module does not deduplicate, and a
+    build constructs the configuration more than once (metadata hook plus
+    build hook), so the guard is explicit.
+    """
+    if key in _diagnostics_reported:
+        return
+    _diagnostics_reported.add(key)
+    log.warning(message, *args)
+
+
+def config_location(config: Configuration) -> str:
+    """Where the user should go to change the setting being reported."""
+    return str(config.relative_to or "your pyproject.toml")
+
+
+def version_outcome(config: Configuration, tag: str | None, **meta_kw: Any) -> str:
+    """Render the version *tag* would produce, for a diagnostic message.
+
+    Shows the resulting version string rather than just the tag, since the
+    version is what the user actually cares about.  Falls back to prose when
+    no tag matched or the tag does not parse as a version.  Never raises and
+    never emits warnings of its own: this describes a path *not* taken.
+    """
+    if tag is None:
+        return "no matching tag, falling back to the fallback version"
+
+    from .._scm_version import meta
+    from .._version_schemes import format_version
+
+    try:
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            version = format_version(meta(tag, config=config, **meta_kw))
+    except (ValueError, TypeError):
+        return f"no usable version -- tag {tag!r} does not parse as a version"
+    return f"{version} (from tag {tag!r})"
+
+
+STRICT_DIAGNOSTIC = (
+    "tag.strict is not set, and the future default changes this"
+    " repository's version:\n"
+    "  now (tag.strict = false):           %s\n"
+    "  future default (tag.strict = true): %s\n"
+    "Set tag.strict explicitly in the [tool.setuptools_scm] table of %s."
+)
+"""Message shared by the backends so their advice reads identically."""
+
+
 @dataclass()
 class ScmWorkdir:
     """Base class for VCS work directories.

{vcs_versioning-2.2.4 → vcs_versioning-2.3.0}/src/vcs_versioning/_config.py

@@ -343,20 +343,9 @@ class Configuration:
                     self.tag, regex=_check_tag_regex(tag_regex)
                 )
 
-        # TODO(#1429): re-introduce these warnings with non-conflicting logic
-        if self.tag.strict is None:
-            log.debug(
-                "tag.strict is not set — defaults to False (permissive tag matching)"
-            )
-
-        if (
-            self.tag.prefix or self.tag.strict is not None
-        ) and self.scm.git.describe_command is not None:
-            log.debug(
-                "Both tag.prefix/tag.strict and scm.git.describe_command are set. "
-                "The explicit describe_command takes precedence; tag.prefix and "
-                "tag.strict will have no effect on the git describe match pattern."
-            )
+        # tag.strict and describe_command diagnostics deliberately do not live
+        # here: they are only actionable once the SCM has been consulted, so the
+        # git backend reports them when they actually change the version (#1429)
 
         self._resolved_paths = resolve_paths(
             relative_to=self.relative_to,

vcs_versioning-2.3.0/src/vcs_versioning/_dynamic_metadata.py

@@ -0,0 +1,49 @@
+"""scikit-build ``dynamic-metadata`` provider for vcs-versioning.
+
+Use this module as a provider for `scikit-build/dynamic-metadata
+<https://github.com/scikit-build/dynamic-metadata>`_ so any backend supporting
+that can fill in a VCS-derived ``version``::
+
+    [[tool.dynamic-metadata]]
+    provider = "vcs_versioning"
+
+Configuration is read from ``[tool.vcs-versioning]``; any keys in the
+``[[tool.dynamic-metadata]]`` table are passed through as overrides.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import vcs_versioning
+import vcs_versioning.overrides
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+__all__ = ["dynamic_metadata"]
+
+
+def __dir__() -> list[str]:
+    return __all__
+
+
+def dynamic_metadata(
+    settings: Mapping[str, Any],
+    project: Mapping[str, Any],
+) -> dict[str, Any]:
+    """Return the ``version`` field for a dynamic-metadata consumer."""
+
+    dist_name = project.get("name")
+    # dynamic-metadata runs hooks with cwd at the project root.
+    with vcs_versioning.overrides.GlobalOverrides.from_env(
+        "VCS_VERSIONING", dist_name=dist_name
+    ):
+        pyproject = vcs_versioning.PyProjectData.from_file("pyproject.toml")
+        version = vcs_versioning.infer_version_string(
+            dist_name=dist_name,
+            pyproject_data=pyproject,
+            overrides=dict(settings) or None,
+            force_write_version_files=True,
+        )
+    return {"version": version}