vcs-versioning 1.0.1__tar.gz

vcs_versioning-1.0.1/.gitignore

@@ -0,0 +1,57 @@
+### JetBrains template
+# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion
+
+*.iml
+
+## Directory-based project format:
+.idea/
+
+### Other editors
+.*.swp
+.vscode/
+
+### Python template
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+
+
+# Distribution / packaging
+.env/
+env/
+.venv/
+venv/
+build/
+dist/
+.eggs/
+lib/
+lib64/
+*.egg-info/
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+pip-wheel-metadata
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+.pytest_cache
+.mypy_cache/
+
+nosetests.xml
+coverage.xml
+*,cover
+.hypothesis/
+
+# Sphinx documentation
+docs/_build/
+
+# MkDocs documentation
+site/
+
+.serena/cache/

vcs_versioning-1.0.1/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+<!-- towncrier release notes start -->
+
+## 1.0.1 (2026-03-09)
+
+### Miscellaneous
+
+- Simplify release tag creation to use a single ``createRelease`` API call instead of separate ``createTag``/``createRef``/``createRelease`` calls, avoiding dangling tag objects on partial failures. ([#release-pipeline](https://github.com/pypa/setuptools-scm/issues/release-pipeline))
+
+## 1.0.0 (2026-02-26)
+
+### Major Changes
+
+- First stable release of vcs-versioning as a standalone package. ([#1228](https://github.com/pypa/setuptools-scm/issues/1228))
+
+
+### Deprecated
+
+- Rename `python-simplified-semver` to `semver-pep440` and `release-branch-semver` to `semver-pep440-release-branch` to prevent confusion with actual semver (which these schemes don't produce — they produce PEP 440-compliant versions). The old names still work but emit a deprecation warning. ([#679](https://github.com/pypa/setuptools-scm/issues/679))
+
+
+### Added
+
+- Add experimental integrator workflow API for composable configuration building. Allows build backends to progressively build Configuration objects from pyproject.toml, distribution metadata, and manual overrides. ([#1228](https://github.com/pypa/setuptools-scm/issues/1228))
+- Add EnvReader class for structured reading of environment variable overrides with tool prefixes and distribution-specific variants (e.g., SETUPTOOLS_SCM_PRETEND vs VCS_VERSIONING_PRETEND). ([#1228](https://github.com/pypa/setuptools-scm/issues/1228))
+- Requires Python 3.10 or newer. Modern type annotations and language features used throughout. ([#1228](https://github.com/pypa/setuptools-scm/issues/1228))
+- Add towncrier-fragments version scheme that infers version bumps based on changelog fragment types (feature=minor, bugfix=patch, removal=major). ([#1228](https://github.com/pypa/setuptools-scm/issues/1228))
+- Initial release of vcs-versioning as a standalone package. Core version inference logic extracted from setuptools-scm for reuse by other build backends and tools. ([#1228](https://github.com/pypa/setuptools-scm/issues/1228))
+
+
+### Miscellaneous
+
+- Improved CLI type safety with OutputData TypedDict and better type annotations throughout CLI handling. ([#1228](https://github.com/pypa/setuptools-scm/issues/1228))
+- Modernized type annotations to Python 3.10+ syntax throughout codebase. Generated version files now use modern `tuple[int | str, ...]` syntax with `from __future__ import annotations`. ([#1228](https://github.com/pypa/setuptools-scm/issues/1228))
+- Enhanced GlobalOverrides: env_reader is now a required validated field. additional_loggers changed from string to tuple of logger instances for better type safety. ([#1228](https://github.com/pypa/setuptools-scm/issues/1228))
+- Converted _cli module into a package with improved structure. Archival templates moved to resource files. Added CliNamespace for typed arguments. ([#1228](https://github.com/pypa/setuptools-scm/issues/1228))
+
+## 0.1.1
+
+Initial release of vcs-versioning as a separate package extracted from setuptools-scm.
+

vcs_versioning-1.0.1/LICENSE.txt

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2023-present Ronny Pfannschmidt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

vcs_versioning-1.0.1/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: vcs-versioning
+Version: 1.0.1
+Summary: the blessed package to manage your versions by vcs metadata
+Project-URL: Documentation, https://github.com/pypa/setuptools-scm#readme
+Project-URL: Issues, https://github.com/pypa/setuptools-scm/issues
+Project-URL: Source, https://github.com/pypa/setuptools-scm
+Author-email: Ronny Pfannschmidt <opensource@ronnypfannschmidt.de>
+License-Expression: MIT
+License-File: LICENSE.txt
+Classifier: Development Status :: 1 - Planning
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: packaging>=20
+Requires-Dist: tomli>=1; python_version < '3.11'
+Requires-Dist: typing-extensions; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+# vcs-versioning
+
+[![PyPI - Version](https://img.shields.io/pypi/v/vcs-versioning.svg)](https://pypi.org/project/vcs-versioning)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/vcs-versioning.svg)](https://pypi.org/project/vcs-versioning)
+
+-----
+
+**Table of Contents**
+
+- [Installation](#installation)
+- [License](#license)
+
+## Installation
+
+```console
+pip install vcs-versioning
+```
+
+## License
+
+`vcs-versioning` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

vcs_versioning-1.0.1/README.md

@@ -0,0 +1,21 @@
+# vcs-versioning
+
+[![PyPI - Version](https://img.shields.io/pypi/v/vcs-versioning.svg)](https://pypi.org/project/vcs-versioning)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/vcs-versioning.svg)](https://pypi.org/project/vcs-versioning)
+
+-----
+
+**Table of Contents**
+
+- [Installation](#installation)
+- [License](#license)
+
+## Installation
+
+```console
+pip install vcs-versioning
+```
+
+## License
+
+`vcs-versioning` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

vcs_versioning-1.0.1/_own_version_of_vcs_versioning.py

@@ -0,0 +1,85 @@
+"""
+Version helper for vcs-versioning package.
+
+This module allows vcs-versioning to use VCS metadata for its own version,
+with the tag prefix 'vcs-versioning-'.
+
+Used by hatchling's code version source.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import Callable
+from pathlib import Path
+
+from vcs_versioning import Configuration
+from vcs_versioning import _types as _t
+from vcs_versioning._backends import _git as git
+from vcs_versioning._backends import _hg as hg
+from vcs_versioning._fallbacks import fallback_version, parse_pkginfo
+from vcs_versioning._get_version_impl import get_version
+from vcs_versioning._version_schemes import (
+    ScmVersion,
+    get_local_node_and_date,
+    get_no_local_node,
+    guess_next_dev_version,
+)
+
+log = logging.getLogger("vcs_versioning")
+
+# Try these parsers in order for vcs-versioning's own version
+try_parse: list[Callable[[_t.PathT, Configuration], ScmVersion | None]] = [
+    parse_pkginfo,
+    git.parse,
+    hg.parse,
+    git.parse_archival,
+    hg.parse_archival,
+    fallback_version,  # Last resort: use fallback_version from config
+]
+
+
+def parse(root: str, config: Configuration) -> ScmVersion | None:
+    for maybe_parse in try_parse:
+        try:
+            parsed = maybe_parse(root, config)
+        except OSError as e:
+            log.warning("parse with %s failed with: %s", maybe_parse, e)
+        else:
+            if parsed is not None:
+                return parsed
+    return None
+
+
+def _get_version() -> str:
+    """Get version from VCS with vcs-versioning- tag prefix."""
+    # Use no-local-version if VCS_VERSIONING_NO_LOCAL is set (for CI uploads)
+    local_scheme = (
+        get_no_local_node
+        if os.environ.get("VCS_VERSIONING_NO_LOCAL")
+        else get_local_node_and_date
+    )
+
+    # Resolve repo root from this file's location so version detection works
+    # regardless of cwd (e.g. when uv build runs from workspace root).
+    _here = Path(__file__).resolve()
+    _repo_root = _here.parent.parent
+    _pyproject_path = _here.parent / "pyproject.toml"
+
+    return get_version(
+        root=str(_repo_root),
+        fallback_root=str(_here.parent),
+        relative_to=str(_pyproject_path),
+        parse=parse,
+        version_scheme=guess_next_dev_version,
+        local_scheme=local_scheme,
+        tag_regex=r"^vcs-versioning-(?P<version>v?\d+(?:\.\d+){0,2}[^\+]*)(?:\+.*)?$",
+        scm={
+            "git": {"describe_command": git.make_describe_command("vcs-versioning-*")}
+        },
+        fallback_version="0.1.1+pre.tag",
+    )
+
+
+__version__: str = _get_version()

vcs_versioning-1.0.1/changelog.d/.gitkeep

@@ -0,0 +1,8 @@
+# Changelog fragments directory
+# Add your changelog fragments here following the naming convention:
+# {issue_number}.{type}.md
+#
+# Where type is one of: feature, bugfix, deprecation, removal, doc, misc
+#
+# Example: 123.feature.md
+

vcs_versioning-1.0.1/changelog.d/README.md

@@ -0,0 +1,32 @@
+# Changelog Fragments
+
+This directory contains changelog fragments that will be assembled into the CHANGELOG.md file during release.
+
+## Fragment Types
+
+- **feature**: New features or enhancements
+- **bugfix**: Bug fixes
+- **deprecation**: Deprecation warnings
+- **removal**: Removed features (breaking changes)
+- **doc**: Documentation improvements
+- **misc**: Internal changes, refactoring, etc.
+
+## Naming Convention
+
+Fragments should be named: `{issue_number}.{type}.md`
+
+Examples:
+- `123.feature.md` - New feature related to issue #123
+- `456.bugfix.md` - Bug fix for issue #456
+- `789.doc.md` - Documentation update for issue #789
+
+## Content
+
+Each fragment should contain a brief description of the change:
+
+```markdown
+Add support for custom version schemes via plugin system
+```
+
+Do not include issue numbers in the content - they will be added automatically.
+

vcs_versioning-1.0.1/changelog.d/template.md

@@ -0,0 +1,21 @@
+{% for section, _ in sections.items() %}
+{% set underline = underlines[0] %}{% if section %}{{section}}
+{{ underline * section|length }}{% set underline = underlines[1] %}
+
+{% endif %}
+{% if sections[section] %}
+{% for category, val in definitions.items() if category in sections[section]%}
+
+### {{ definitions[category]['name'] }}
+
+{% for text, values in sections[section][category].items() %}
+- {{ text }} ({{ values|join(', ') }})
+{% endfor %}
+
+{% endfor %}
+{% else %}
+No significant changes.
+
+{% endif %}
+{% endfor %}
+

vcs_versioning-1.0.1/pyproject.toml

@@ -0,0 +1,183 @@
+[build-system]
+build-backend = "hatchling.build"
+requires = [
+  "hatchling",
+  "packaging>=20",
+  'typing-extensions; python_version < "3.11"',
+]
+
+[project]
+name = "vcs-versioning"
+description = "the blessed package to manage your versions by vcs metadata"
+readme = "README.md"
+keywords = [
+]
+license = "MIT"
+authors = [
+  { name = "Ronny Pfannschmidt", email = "opensource@ronnypfannschmidt.de" },
+]
+requires-python = ">=3.10"
+classifiers = [
+  "Development Status :: 1 - Planning",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+dynamic = [
+  "version",
+]
+dependencies = [
+  "packaging>=20",
+  'tomli>=1; python_version < "3.11"',
+  'typing-extensions; python_version < "3.11"',
+]
+
+[dependency-groups]
+test = [
+  "pytest",
+  "pytest-cov",
+  "pytest-xdist",
+]
+
+[project.urls]
+Documentation = "https://github.com/pypa/setuptools-scm#readme"
+Issues = "https://github.com/pypa/setuptools-scm/issues"
+Source = "https://github.com/pypa/setuptools-scm"
+
+[project.scripts]
+"vcs-versioning" = "vcs_versioning._cli:main"
+
+[project.entry-points."setuptools_scm.parse_scm"]
+".git" = "vcs_versioning._backends._git:parse"
+".hg" = "vcs_versioning._backends._hg:parse"
+
+[project.entry-points."setuptools_scm.parse_scm_fallback"]
+".git_archival.txt" = "vcs_versioning._backends._git:parse_archival"
+".hg_archival.txt" = "vcs_versioning._backends._hg:parse_archival"
+"PKG-INFO" = "vcs_versioning._fallbacks:parse_pkginfo"
+"pyproject.toml" = "vcs_versioning._fallbacks:fallback_version"
+"setup.py" = "vcs_versioning._fallbacks:fallback_version"
+
+[project.entry-points."setuptools_scm.local_scheme"]
+dirty-tag = "vcs_versioning._version_schemes:get_local_dirty_tag"
+no-local-version = "vcs_versioning._version_schemes:get_no_local_node"
+node-and-date = "vcs_versioning._version_schemes:get_local_node_and_date"
+node-and-timestamp = "vcs_versioning._version_schemes:get_local_node_and_timestamp"
+
+[project.entry-points."setuptools_scm.version_scheme"]
+"calver-by-date" = "vcs_versioning._version_schemes:calver_by_date"
+"guess-next-dev" = "vcs_versioning._version_schemes:guess_next_dev_version"
+"no-guess-dev" = "vcs_versioning._version_schemes:no_guess_dev_version"
+"only-version" = "vcs_versioning._version_schemes:only_version"
+"post-release" = "vcs_versioning._version_schemes:postrelease_version"
+"python-simplified-semver" = "vcs_versioning._version_schemes._standard:_deprecated_simplified_semver_version"
+"release-branch-semver" = "vcs_versioning._version_schemes._standard:_deprecated_release_branch_semver_version"
+"semver-pep440" = "vcs_versioning._version_schemes:simplified_semver_version"
+"semver-pep440-release-branch" = "vcs_versioning._version_schemes:release_branch_semver_version"
+"towncrier-fragments" = "vcs_versioning._version_schemes._towncrier:version_from_fragments"
+
+[tool.hatch.version]
+source = "code"
+path = "_own_version_of_vcs_versioning.py"
+search-paths = ["src"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vcs_versioning"]
+
+[tool.hatch.envs.default]
+dependencies = [
+  "pytest",
+  "pytest-cov",
+]
+[tool.hatch.envs.default.scripts]
+cov = "pytest --cov-report=term-missing --cov-config=pyproject.toml --cov=vcs_versioning --cov=tests {args}"
+no-cov = "cov --no-cov {args}"
+
+[[tool.hatch.envs.test.matrix]]
+python = [ "38", "39", "310", "311", "312", "313" ]
+
+[tool.vcs-versioning]
+root = ".."
+version_scheme = "towncrier-fragments"
+tag_regex = "^vcs-versioning-(?P<version>v?\\d+(?:\\.\\d+){0,2}[^\\+]*)(?:\\+.*)?$"
+fallback_version = "0.1.0"
+scm.git.describe_command = ["git", "describe", "--dirty", "--tags", "--long", "--match", "vcs-versioning-*"]
+
+[tool.coverage.run]
+branch = true
+parallel = true
+omit = [
+  "vcs_versioning/__about__.py",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+  "no cov",
+  "if __name__ == .__main__.:",
+  "if TYPE_CHECKING:",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["testing_vcs"]
+python_files = ["test_*.py"]
+addopts = ["-ra", "--strict-markers", "-p", "vcs_versioning.test_api"]
+markers = [
+  "issue: marks tests related to specific issues",
+  "no_init: use setup_hg(init=False) for wd fixture - hg check without worktree",
+  "skip_commit: allows to skip committing in the helpers",
+]
+
+[tool.uv]
+default-groups = ["test"]
+
+[tool.towncrier]
+directory = "changelog.d"
+filename = "CHANGELOG.md"
+start_string = "<!-- towncrier release notes start -->\n"
+template = "changelog.d/template.md"
+title_format = "## {version} ({project_date})"
+issue_format = "[#{issue}](https://github.com/pypa/setuptools-scm/issues/{issue})"
+underlines = ["", "", ""]
+
+[[tool.towncrier.type]]
+directory = "major"
+name = "Major Changes"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "breaking"
+name = "Breaking Changes"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "removal"
+name = "Removed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "deprecation"
+name = "Deprecated"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "feature"
+name = "Added"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "bugfix"
+name = "Fixed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "doc"
+name = "Documentation"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "misc"
+name = "Miscellaneous"
+showcontent = true

vcs_versioning-1.0.1/src/vcs_versioning/__init__.py

@@ -0,0 +1,110 @@
+"""VCS-based versioning for Python packages
+
+Core functionality for version management based on VCS metadata.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# Public API exports
+from ._config import DEFAULT_LOCAL_SCHEME, DEFAULT_VERSION_SCHEME, Configuration
+from ._pyproject_reading import PyProjectData
+from ._scm_version import ScmVersion
+from ._version_cls import NonNormalizedVersion, Version
+from ._version_inference import infer_version_string
+
+
+def build_configuration_from_pyproject(
+    pyproject_data: PyProjectData,
+    *,
+    dist_name: str | None = None,
+    **integrator_overrides: Any,
+) -> Configuration:
+    """Build Configuration from PyProjectData with full workflow.
+
+    EXPERIMENTAL API for integrators.
+
+    This helper orchestrates the complete configuration building workflow:
+    1. Extract config from pyproject_data.section
+    2. Determine dist_name (argument > pyproject.project_name)
+    3. Apply integrator overrides (override config file)
+    4. Apply environment TOML overrides (highest priority)
+    5. Create and validate Configuration instance
+
+    Integrators create PyProjectData themselves:
+
+    Example 1 - From file:
+        >>> from vcs_versioning import PyProjectData, build_configuration_from_pyproject
+        >>> from vcs_versioning.overrides import GlobalOverrides
+        >>>
+        >>> with GlobalOverrides.from_env("HATCH_VCS", dist_name="my-pkg"):
+        ...     pyproject = PyProjectData.from_file("pyproject.toml")
+        ...     config = build_configuration_from_pyproject(
+        ...         pyproject_data=pyproject,
+        ...         dist_name="my-pkg",
+        ...     )
+
+    Example 2 - Manual composition:
+        >>> from pathlib import Path
+        >>> from vcs_versioning import PyProjectData, build_configuration_from_pyproject
+        >>>
+        >>> pyproject = PyProjectData(
+        ...     path=Path("pyproject.toml"),
+        ...     tool_name="vcs-versioning",
+        ...     project={"name": "my-pkg"},
+        ...     section={"local_scheme": "no-local-version"},
+        ...     is_required=True,
+        ...     section_present=True,
+        ...     project_present=True,
+        ...     build_requires=[],
+        ... )
+        >>> config = build_configuration_from_pyproject(
+        ...     pyproject_data=pyproject,
+        ...     version_scheme="semver-pep440-release-branch",  # Integrator override
+        ... )
+
+    Args:
+        pyproject_data: Parsed pyproject data (integrator creates this)
+        dist_name: Distribution name (overrides pyproject_data.project_name)
+        **integrator_overrides: Integrator-provided config overrides
+                               (override config file, but overridden by env)
+
+    Returns:
+        Configured Configuration instance ready for version inference
+
+    Priority order (highest to lowest):
+        1. Environment TOML overrides (TOOL_OVERRIDES_FOR_DIST, TOOL_OVERRIDES)
+        2. Integrator **overrides arguments
+        3. pyproject_data.section configuration
+        4. Configuration defaults
+
+    This allows integrators to provide their own transformations
+    while still respecting user environment variable overrides.
+    """
+    from ._integrator_helpers import build_configuration_from_pyproject_internal
+
+    return build_configuration_from_pyproject_internal(
+        pyproject_data=pyproject_data,
+        dist_name=dist_name,
+        **integrator_overrides,
+    )
+
+
+__all__ = [
+    "DEFAULT_LOCAL_SCHEME",
+    "DEFAULT_VERSION_SCHEME",
+    "Configuration",
+    "NonNormalizedVersion",
+    "PyProjectData",
+    "ScmVersion",
+    "Version",
+    "build_configuration_from_pyproject",
+    "infer_version_string",
+]
+
+# Experimental API markers for documentation
+__experimental__ = [
+    "PyProjectData",
+    "build_configuration_from_pyproject",
+]

vcs_versioning-1.0.1/src/vcs_versioning/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from ._cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

vcs_versioning-1.0.1/src/vcs_versioning/_backends/__init__.py

@@ -0,0 +1,3 @@
+"""VCS backends (private module)"""
+
+from __future__ import annotations