setuptools-git-versioning 3.0.1__tar.gz → 3.1.0__tar.gz

{setuptools_git_versioning-3.0.1/setuptools_git_versioning.egg-info → setuptools_git_versioning-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: setuptools-git-versioning
-Version: 3.0.1
+Version: 3.1.0
 Summary: Use git repo data for building a version number according to PEP-440
 Author-email: dolfinus <martinov.m.s.8@gmail.com>
 License: MIT
@@ -20,6 +20,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.7
 Description-Content-Type: text/x-rst
@@ -81,7 +82,8 @@ between ``setuptools-git-versioning`` and other tools.
 
 - Only Git v2 is supported
 
-- Only Setuptools build backend is supported (no Poetry & others)
+- Setuptools and `scikit-build-core <https://scikit-build-core.readthedocs.io>`_ build backends are
+  supported (no Poetry & others)
 
 - Currently does not support automatic exporting of package version to a file for runtime use
   (but you can use ``setuptools-git-versioning > file`` redirect instead)
@@ -173,3 +175,31 @@ and then add new argument ``setuptools_git_versioning`` with config options:
     )
 
 Commands are the same as above, plus ``python -m setup.py`` returns the same version.
+
+``scikit-build-core``
+~~~~~~~~~~~~~~~~~~~~~
+
+If your project uses the `scikit-build-core <https://scikit-build-core.readthedocs.io>`_ build backend,
+add ``setuptools-git-versioning`` to ``build-system.requires``,
+mark the ``version`` field as dynamic,
+register the dynamic-metadata provider,
+and configure options under the usual ``[tool.setuptools-git-versioning]`` section:
+
+.. code:: toml
+
+    [build-system]
+    requires = [ "scikit-build-core", "setuptools-git-versioning>=3.0,<4", ]
+    build-backend = "scikit_build_core.build"
+
+    [project]
+    name = "mypackage"
+    dynamic = ["version"]
+
+    [tool.scikit-build.metadata.version]
+    provider = "setuptools_git_versioning.scikit_metadata"
+
+    [tool.setuptools-git-versioning]
+    enabled = true
+
+All options under ``[tool.setuptools-git-versioning]`` work exactly as the for ``setuptools`` backend.
+Inline configuration under ``[tool.scikit-build.metadata.version]`` is not supported.

{setuptools_git_versioning-3.0.1 → setuptools_git_versioning-3.1.0}/README.rst

@@ -50,7 +50,8 @@ between ``setuptools-git-versioning`` and other tools.
 
 - Only Git v2 is supported
 
-- Only Setuptools build backend is supported (no Poetry & others)
+- Setuptools and `scikit-build-core <https://scikit-build-core.readthedocs.io>`_ build backends are
+  supported (no Poetry & others)
 
 - Currently does not support automatic exporting of package version to a file for runtime use
   (but you can use ``setuptools-git-versioning > file`` redirect instead)
@@ -142,3 +143,31 @@ and then add new argument ``setuptools_git_versioning`` with config options:
     )
 
 Commands are the same as above, plus ``python -m setup.py`` returns the same version.
+
+``scikit-build-core``
+~~~~~~~~~~~~~~~~~~~~~
+
+If your project uses the `scikit-build-core <https://scikit-build-core.readthedocs.io>`_ build backend,
+add ``setuptools-git-versioning`` to ``build-system.requires``,
+mark the ``version`` field as dynamic,
+register the dynamic-metadata provider,
+and configure options under the usual ``[tool.setuptools-git-versioning]`` section:
+
+.. code:: toml
+
+    [build-system]
+    requires = [ "scikit-build-core", "setuptools-git-versioning>=3.0,<4", ]
+    build-backend = "scikit_build_core.build"
+
+    [project]
+    name = "mypackage"
+    dynamic = ["version"]
+
+    [tool.scikit-build.metadata.version]
+    provider = "setuptools_git_versioning.scikit_metadata"
+
+    [tool.setuptools-git-versioning]
+    enabled = true
+
+All options under ``[tool.setuptools-git-versioning]`` work exactly as the for ``setuptools`` backend.
+Inline configuration under ``[tool.scikit-build.metadata.version]`` is not supported.

{setuptools_git_versioning-3.0.1 → setuptools_git_versioning-3.1.0}/pyproject.toml

@@ -9,7 +9,7 @@ build-backend = "setuptools.build_meta:__legacy__"
 
 [project]
 name = "setuptools-git-versioning"
-version = "3.0.1"
+version = "3.1.0"
 authors = [{name = "dolfinus", email = "martinov.m.s.8@gmail.com"}]
 license = {text = "MIT"}
 description = "Use git repo data for building a version number according to PEP-440"
@@ -25,6 +25,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Operating System :: OS Independent",
 ]
 requires-python = ">=3.7"
@@ -65,8 +66,8 @@ dev_template = "{tag}.post{ccount}"
 
 [dependency-groups]
 dev = [
-  "ruff~=0.14.11",
-  "prek~=0.2.28",
+  "ruff~=0.15.13",
+  "prek~=0.4.0",
 ]
 test = [
   "build>=1.1.1",
@@ -77,19 +78,23 @@ test = [
   # Some tests need to write TOML, but tomli and tomllib are read-only, and toml package is unmaintained
   "tomli-w>=1.0.0",
   "wheel>=0.42.0",
+  "scikit-build-core>=0.5",
 ]
 docs = [
   "furo~=2025.12.19",
   "numpydoc~=1.10.0",
+  # https://github.com/sphinx-toolbox/sphinx-toolbox/issues/201
   "sphinx~=8.2.3",
   "sphinx-argparse~=0.5.2",
+  # https://github.com/sphinx-toolbox/sphinx-toolbox/pull/209
   "sphinx-autodoc-typehints~=3.5.2",
   "sphinx-copybutton~=0.5.2",
   "sphinx-last-updated-by-git~=0.3.8",
+  # https://github.com/sphinx-toolbox/sphinx-toolbox/issues/189
   "sphinx-tabs~=3.4.5",
   "sphinxcontrib-towncrier~=0.5.0a0",
   "towncrier~=25.8.0",
-  "sphinx-toolbox~=4.1.0",
+  "sphinx-toolbox~=4.1.2",
 ]
 
 [tool.uv]

{setuptools_git_versioning-3.0.1 → setuptools_git_versioning-3.1.0}/setuptools_git_versioning/__init__.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any
 
+from setuptools_git_versioning.archival import parse_archival_file, version_from_archival
 from setuptools_git_versioning.git import (
     count_since,
     get_all_tags,
@@ -37,5 +38,7 @@ __all__ = [
     "get_version",
     "infer_version",
     "is_dirty",
+    "parse_archival_file",
+    "version_from_archival",
     "version_from_git",
 ]

setuptools_git_versioning-3.1.0/setuptools_git_versioning/archival.py

@@ -0,0 +1,225 @@
+from __future__ import annotations
+
+import logging
+import os  # noqa: TC003
+import re
+from dataclasses import dataclass
+from email.parser import HeaderParser
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from setuptools_git_versioning.defaults import (
+    DEFAULT_DEV_TEMPLATE,
+    DEFAULT_DIRTY_TEMPLATE,
+    DEFAULT_TEMPLATE,
+)
+from setuptools_git_versioning.factories import create_branch_formatter, create_tag_formatter
+from setuptools_git_versioning.log import DEBUG, INFO
+from setuptools_git_versioning.subst import resolve_substitutions
+
+if TYPE_CHECKING:
+    from typing import Callable
+
+    from packaging.version import Version
+
+ARCHIVAL_FILENAME = ".git_archival.txt"
+DESCRIBE_UNSUPPORTED = "%(describe"
+FORMAT_UNSUBSTITUTED = "$Format"
+DESCRIBE_PARTS = 3  # tag-N-gSHA
+
+REF_TAG_RE = re.compile(r"(?<=\btag: )([^,]+)\b")
+REF_HEAD_RE = re.compile(r"HEAD\s*->\s*([^,]+)")
+FULL_SHA_RE = re.compile(r"^([0-9a-f]{40}|[0-9a-f]{64})$")  # SHA-1 or SHA-256
+
+log = logging.getLogger(__name__)
+
+
+@dataclass
+class ArchivalData:
+    tag: str
+    ccount: int
+    sha: str
+    full_sha: str
+    dirty: bool
+    branch: str | None
+
+
+def parse_archival_file(path: str | os.PathLike) -> dict[str, str]:
+    """Read a .git_archival.txt file and return its key/value pairs.
+
+    Keys are normalized to lowercase so lookups behave consistently
+    regardless of whether the file uses `node:` or `Node:` etc.
+    """
+    content = Path(path).read_text(encoding="utf-8")
+    log.log(DEBUG, "'%s' content:\n%s", ARCHIVAL_FILENAME, content)
+    message = HeaderParser().parsestr(content)
+
+    # HeaderParser treats the first blank line as the end of headers.
+    # Anything after it ends up in the message body and is silently
+    # dropped from .items(). Warn the user instead of losing fields.
+    payload = message.get_payload()
+    if isinstance(payload, str) and payload.strip():
+        log.warning(
+            "'%s' contains content after a blank line; those fields will be ignored",
+            ARCHIVAL_FILENAME,
+        )
+
+    return {key.lower(): value for key, value in message.items()}
+
+
+def _parse_describe(describe: str) -> tuple[str, int, str | None, bool]:
+    """Parse a `git describe`-style string into (tag, ccount, short_sha, dirty)."""
+    dirty = False
+    if describe.endswith("-dirty"):
+        dirty = True
+        describe = describe[: -len("-dirty")]
+
+    parts = describe.rsplit("-", 2)
+    if len(parts) < DESCRIBE_PARTS:
+        return describe, 0, None, dirty
+
+    tag, ccount_str, gnode = parts
+    try:
+        ccount = int(ccount_str)
+    except ValueError:
+        return describe, 0, None, dirty
+
+    short_sha = gnode[1:] if gnode.startswith("g") else gnode
+    return tag, ccount, short_sha, dirty
+
+
+def _branch_from_ref_names(ref_names: str) -> str | None:
+    match = REF_HEAD_RE.search(ref_names)
+    if match:
+        return match.group(1).strip()
+    return None
+
+
+def get_data_from_archival_file(data: dict[str, str]) -> ArchivalData | None:
+    """Convert parsed archival data into structured version info, or None.
+
+    Returns None when the file looks unsubstituted or otherwise unusable so
+    the caller can fall through to live git.
+    """
+    if any(FORMAT_UNSUBSTITUTED in value for value in data.values()):
+        log.warning(
+            "'%s' contains unprocessed '$Format:...$' placeholders, skipping",
+            ARCHIVAL_FILENAME,
+        )
+        return None
+
+    node = data.get("node", "").strip()
+    full_sha = node if FULL_SHA_RE.match(node) else ""
+    ref_names = data.get("ref-names", "")
+    branch = _branch_from_ref_names(ref_names)
+    describe = data.get("describe-name", "").strip()
+
+    describe_tag: str | None = None
+    ccount = 0
+    short_sha = ""
+    dirty = False
+
+    if describe and DESCRIBE_UNSUPPORTED not in describe:
+        describe_tag, ccount, parsed_sha, dirty = _parse_describe(describe)
+        if parsed_sha:
+            short_sha = parsed_sha
+    elif describe:
+        log.warning(
+            "git archive did not expand %(describe...) (git <2.32), falling back to ref-names",
+        )
+
+    if describe_tag is not None:
+        tag = describe_tag
+    else:
+        tags = REF_TAG_RE.findall(ref_names)
+        if not tags:
+            log.log(
+                INFO,
+                "'%s' has no usable describe-name or tag in ref-names",
+                ARCHIVAL_FILENAME,
+            )
+            return None
+        tag = tags[0].strip()
+
+    # Prefer the full SHA when available so {sha} matches the live-git
+    # path's `full_sha[:8]` rendering. Fall back to the short SHA from
+    # describe-name only when no valid `node` field is present.
+    if full_sha:
+        short_sha = full_sha[:8]
+    elif short_sha:
+        full_sha = short_sha
+
+    return ArchivalData(
+        tag=tag,
+        ccount=ccount,
+        sha=short_sha[:8],
+        full_sha=full_sha,
+        dirty=dirty,
+        branch=branch,
+    )
+
+
+def version_from_archival(  # noqa: PLR0913
+    project_root: str | os.PathLike,
+    *,
+    package_name: str | None = None,
+    template: str = DEFAULT_TEMPLATE,
+    dev_template: str = DEFAULT_DEV_TEMPLATE,
+    dirty_template: str = DEFAULT_DIRTY_TEMPLATE,
+    tag_formatter: Callable[[str], str] | str | None = None,
+    branch_formatter: Callable[[str], str] | str | None = None,
+) -> Version | None:
+    """Return a Version derived from .git_archival.txt, or None if unavailable."""
+    archival_path = Path(project_root).joinpath(ARCHIVAL_FILENAME)
+    if not archival_path.exists():
+        log.log(DEBUG, "No '%s' present at '%s'", ARCHIVAL_FILENAME, project_root)
+        return None
+
+    log.log(INFO, "File '%s' is found, reading its content", archival_path)
+    data = parse_archival_file(archival_path)
+    info = get_data_from_archival_file(data)
+    if info is None:
+        return None
+
+    log.log(DEBUG, "Parsed archival data: %r", info)
+
+    tag = info.tag
+    if tag_formatter is not None:
+        tag_format_callback = create_tag_formatter(tag_formatter, package_name=package_name, root=project_root)
+        tag = tag_format_callback(tag)
+        log.log(DEBUG, "Tag after formatting: %r", tag)
+
+    if info.dirty:
+        log.log(INFO, "Using template from 'dirty_template' option")
+        chosen = dirty_template
+    elif info.ccount > 0:
+        log.log(INFO, "Using template from 'dev_template' option")
+        chosen = dev_template
+    else:
+        log.log(INFO, "Using template from 'template' option")
+        chosen = template
+
+    # When ref-names is absent or doesn't reveal a current branch, default
+    # to the literal "HEAD" so `{branch}` substitution mirrors what
+    # `git rev-parse --abbrev-ref HEAD` produces in detached-HEAD state.
+    branch = info.branch if info.branch is not None else "HEAD"
+    if branch_formatter is not None:
+        branch_format_callback = create_branch_formatter(branch_formatter, package_name=package_name, root=project_root)
+        branch = branch_format_callback(branch)
+        log.log(INFO, "Branch after formatting: %r", branch)
+
+    rendered = resolve_substitutions(
+        chosen,
+        sha=info.sha,
+        tag=tag,
+        ccount=info.ccount,
+        branch=branch,
+        full_sha=info.full_sha,
+    )
+    log.log(INFO, "Version number after resolving substitutions: %r", rendered)
+
+    # Deferred to avoid a top-level circular import:
+    # `version.py` imports `version_from_archival` from this module.
+    from setuptools_git_versioning.version import sanitize_version
+
+    return sanitize_version(rendered)

setuptools_git_versioning-3.1.0/setuptools_git_versioning/scikit_metadata.py

@@ -0,0 +1,81 @@
+"""Dynamic metadata provider for the scikit-build-core build backend."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from setuptools_git_versioning.defaults import set_default_options
+from setuptools_git_versioning.setup import read_toml
+from setuptools_git_versioning.version import version_from_git
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+__all__ = ["dynamic_metadata", "get_requires_for_dynamic_metadata"]
+
+
+def dynamic_metadata(
+    field: str,
+    settings: Mapping[str, Any] | None = None,
+) -> str:
+    if field != "version":
+        msg = f"Only the 'version' field is supported, got {field!r}"
+        raise ValueError(msg)
+
+    if settings:
+        msg = (
+            "Inline configuration under [tool.scikit-build.metadata.version] is not supported. "
+            "Configure setuptools-git-versioning under [tool.setuptools-git-versioning] instead."
+        )
+        raise ValueError(msg)
+
+    root = Path.cwd()
+
+    config = read_toml(root=root)
+    if not config:
+        msg = (
+            "Missing [tool.setuptools-git-versioning] section in pyproject.toml. "
+            "Add it (with at minimum 'enabled = true') to use this provider."
+        )
+        raise ValueError(msg)
+
+    if not config.pop("enabled", True):
+        msg = (
+            "[tool.setuptools-git-versioning] has 'enabled = false' but the scikit-build-core "
+            "metadata provider for setuptools-git-versioning was selected. "
+            "Either remove the provider or set 'enabled = true'."
+        )
+        raise ValueError(msg)
+
+    set_default_options(config)
+
+    package_name = _read_project_name(root)
+
+    return str(version_from_git(package_name, **config, root=root))
+
+
+def _read_project_name(root: Path) -> str | None:
+    pyproject = root / "pyproject.toml"
+    if not pyproject.is_file():
+        return None
+
+    try:
+        import tomllib
+
+        with pyproject.open("rb") as file:
+            data = tomllib.load(file)
+    except ImportError:
+        import tomli
+
+        with pyproject.open("rb") as file:
+            data = tomli.load(file)
+
+    name = data.get("project", {}).get("name")
+    return name if isinstance(name, str) else None
+
+
+def get_requires_for_dynamic_metadata(
+    _settings: Mapping[str, Any] | None = None,
+) -> list[str]:
+    return ["setuptools-git-versioning"]

{setuptools_git_versioning-3.0.1 → setuptools_git_versioning-3.1.0}/setuptools_git_versioning/version.py

@@ -11,6 +11,7 @@ from typing import Callable
 # where 'packaging' is not installed yet
 from packaging.version import Version
 
+from setuptools_git_versioning.archival import version_from_archival
 from setuptools_git_versioning.defaults import (
     DEFAULT_DEV_TEMPLATE,
     DEFAULT_DIRTY_TEMPLATE,
@@ -114,6 +115,19 @@ def version_from_git(  # noqa: PLR0915, PLR0912, PLR0913, C901
                 # running on sdist package, do not sanitize
                 return Version(version_str)
 
+    archival_version = version_from_archival(
+        project_root,
+        package_name=package_name,
+        template=template,
+        dev_template=dev_template,
+        dirty_template=dirty_template,
+        tag_formatter=tag_formatter,
+        branch_formatter=branch_formatter,
+    )
+    if archival_version is not None:
+        log.log(INFO, "Resolved version from '.git_archival.txt': %s", archival_version)
+        return archival_version
+
     if version_callback is not None:
         if version_file is not None:
             msg = "Either 'version_file' or 'version_callback' can be passed, but not both at the same time"

{setuptools_git_versioning-3.0.1 → setuptools_git_versioning-3.1.0/setuptools_git_versioning.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: setuptools-git-versioning
-Version: 3.0.1
+Version: 3.1.0
 Summary: Use git repo data for building a version number according to PEP-440
 Author-email: dolfinus <martinov.m.s.8@gmail.com>
 License: MIT
@@ -20,6 +20,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.7
 Description-Content-Type: text/x-rst
@@ -81,7 +82,8 @@ between ``setuptools-git-versioning`` and other tools.
 
 - Only Git v2 is supported
 
-- Only Setuptools build backend is supported (no Poetry & others)
+- Setuptools and `scikit-build-core <https://scikit-build-core.readthedocs.io>`_ build backends are
+  supported (no Poetry & others)
 
 - Currently does not support automatic exporting of package version to a file for runtime use
   (but you can use ``setuptools-git-versioning > file`` redirect instead)
@@ -173,3 +175,31 @@ and then add new argument ``setuptools_git_versioning`` with config options:
     )
 
 Commands are the same as above, plus ``python -m setup.py`` returns the same version.
+
+``scikit-build-core``
+~~~~~~~~~~~~~~~~~~~~~
+
+If your project uses the `scikit-build-core <https://scikit-build-core.readthedocs.io>`_ build backend,
+add ``setuptools-git-versioning`` to ``build-system.requires``,
+mark the ``version`` field as dynamic,
+register the dynamic-metadata provider,
+and configure options under the usual ``[tool.setuptools-git-versioning]`` section:
+
+.. code:: toml
+
+    [build-system]
+    requires = [ "scikit-build-core", "setuptools-git-versioning>=3.0,<4", ]
+    build-backend = "scikit_build_core.build"
+
+    [project]
+    name = "mypackage"
+    dynamic = ["version"]
+
+    [tool.scikit-build.metadata.version]
+    provider = "setuptools_git_versioning.scikit_metadata"
+
+    [tool.setuptools-git-versioning]
+    enabled = true
+
+All options under ``[tool.setuptools-git-versioning]`` work exactly as the for ``setuptools`` backend.
+Inline configuration under ``[tool.scikit-build.metadata.version]`` is not supported.

{setuptools_git_versioning-3.0.1 → setuptools_git_versioning-3.1.0}/setuptools_git_versioning.egg-info/SOURCES.txt

@@ -3,11 +3,13 @@ README.rst
 pyproject.toml
 setuptools_git_versioning/__init__.py
 setuptools_git_versioning/__main__.py
+setuptools_git_versioning/archival.py
 setuptools_git_versioning/cli.py
 setuptools_git_versioning/defaults.py
 setuptools_git_versioning/factories.py
 setuptools_git_versioning/git.py
 setuptools_git_versioning/log.py
+setuptools_git_versioning/scikit_metadata.py
 setuptools_git_versioning/setup.py
 setuptools_git_versioning/subst.py
 setuptools_git_versioning/version.py