{"id":23594365,"url":"https://github.com/kiyoon/version-pioneer","last_synced_at":"2025-05-07T22:07:30.473Z","repository":{"id":269707301,"uuid":"906476399","full_name":"kiyoon/version-pioneer","owner":"kiyoon","description":"Versioneer fork with hatchling, pdm support with useful CLI. Manage git tag-based version for any project.","archived":false,"fork":false,"pushed_at":"2025-02-11T05:31:47.000Z","size":237,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-15T18:49:53.560Z","etag":null,"topics":["git","hatch","hatchling","pdm","python","setuptools","version","version-manager","versioning"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kiyoon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-21T02:33:47.000Z","updated_at":"2025-03-06T12:40:22.000Z","dependencies_parsed_at":"2025-02-06T10:34:13.938Z","dependency_job_id":null,"html_url":"https://github.com/kiyoon/version-pioneer","commit_stats":null,"previous_names":["kiyoon/version-pioneer"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiyoon%2Fversion-pioneer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiyoon%2Fversion-pioneer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiyoon%2Fversion-pioneer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiyoon%2Fversion-pioneer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kiyoon","download_url":"https://codeload.github.com/kiyoon/version-pioneer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252961837,"owners_count":21832196,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["git","hatch","hatchling","pdm","python","setuptools","version","version-manager","versioning"],"created_at":"2024-12-27T09:17:46.873Z","updated_at":"2025-05-07T22:07:30.460Z","avatar_url":"https://github.com/kiyoon.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🧗🏽 Version-Pioneer: General-Purpose Versioneer for Any Build Backends\n\n[![image](https://img.shields.io/pypi/v/version-pioneer.svg)](https://pypi.python.org/pypi/version-pioneer)\n[![PyPI - Downloads](https://img.shields.io/pypi/dm/version-pioneer)](https://pypistats.org/packages/version-pioneer)\n[![image](https://img.shields.io/pypi/l/version-pioneer.svg)](https://pypi.python.org/pypi/version-pioneer)\n[![image](https://img.shields.io/pypi/pyversions/version-pioneer.svg)](https://pypi.python.org/pypi/version-pioneer)\n\n|  |  |\n|--|--|\n|[![Ruff](https://img.shields.io/badge/Ruff-3670A0?style=for-the-badge\u0026logo=python\u0026logoColor=ffdd54)](https://github.com/astral-sh/ruff) |[![Actions status](https://github.com/kiyoon/version-pioneer/workflows/Style%20checking/badge.svg)](https://github.com/kiyoon/version-pioneer/actions)|\n| [![Ruff](https://img.shields.io/badge/Ruff-3670A0?style=for-the-badge\u0026logo=python\u0026logoColor=ffdd54)](https://github.com/astral-sh/ruff) | [![Actions status](https://github.com/kiyoon/version-pioneer/workflows/Linting/badge.svg)](https://github.com/kiyoon/version-pioneer/actions) |\n| [![pytest](https://img.shields.io/badge/pytest-3670A0?style=for-the-badge\u0026logo=python\u0026logoColor=ffdd54)](https://github.com/pytest-dev/pytest) [![doctest](https://img.shields.io/badge/doctest-3670A0?style=for-the-badge\u0026logo=python\u0026logoColor=ffdd54)](https://docs.python.org/3/library/doctest.html) | [![Actions status](https://github.com/kiyoon/version-pioneer/workflows/Tests/badge.svg)](https://github.com/kiyoon/version-pioneer/actions) [![codecov](https://codecov.io/gh/kiyoon/version-pioneer/graph/badge.svg?token=QS5JX9VTPM)](https://codecov.io/gh/kiyoon/version-pioneer) |\n| [![uv](https://img.shields.io/badge/uv-3670A0?style=for-the-badge\u0026logo=python\u0026logoColor=ffdd54)](https://github.com/astral-sh/uv) | [![Actions status](https://github.com/kiyoon/version-pioneer/workflows/Check%20pip%20compile%20sync/badge.svg)](https://github.com/kiyoon/version-pioneer/actions) |\n\n**General-purpose Git tag-based version manager that works with any language and any build system.**\n\n- 🧑‍🍳 **Highly customisable**: It's an easy-to-read script. [Literally a simple Python script](src/version_pioneer/versionscript.py) in which you can customise the version format or anything you need.\n- 🐍 Runs with Python 3.8+\n- ❌📦 No dependencies like package, config file etc. It runs with one Python file. \n- ⭕ Works with any build backend with hooks. (Supports setuptools, hatchling, pdm)\n- 🦀 Works with any language, not just Python.\n    - Version format `\"digits\"` generates digits-only version string which is useful for multi-language projects, Chrome Extension, etc. because their versioning standard is different.\n    - CLI makes it easy to compute the version without vendoring anything in the project.\n- 🧙‍♂️ Auto-magically infer version even when the git info is missing.\n    - Downloaded from GitHub Releases? Read from the directory name.\n        - The `parentdir_prefix` is automatically resolved from `pyproject.toml`'s source URL etc.\n    - sdist built without writing a resolved versionfile?\n        - Read from PKG-INFO.\n- 🔢 New version formats:\n    - `\"pep440-master\"`: shows the distance from the tag to master/main, and the master to the current branch. (e.g. 1.2.3\u0026#8203;**+4.gxxxxxxx**\u0026#8203;_.5.gxxxxxxx_ )\n    - `\"digits\"`: the distance and dirty information compiled to the last digit. (e.g. 1.2.3\u0026#8203;**.4**)\n- \u003c/\u003e API provided for complete non-vendored mode support.\n    - With Versioneer you still had to install a `_version.py` script in your project, but Version-Pioneer is able to be installed as a package.\n- 💻 CLI tool to get version string, execute the `_version.py` versionscript, and test your setup.\n\n## 🏃 Quick Start (script not vendored, with build backend plugins)\n\n1. Configure `pyproject.toml`. `[tool.version-pioneer]` section is required.\n    ```toml\n    [tool.version-pioneer]\n    versionscript = \"src/my_project/_version.py\"  # Where to \"read\" the Version-Pioneer script (to execute `get_version_dict()`).\n    versionfile-sdist = \"src/my_project/_version.py\"  # Where to \"write\" the version dict for sdist.\n    versionfile-wheel = \"my_project/_version.py\"  # Where to \"write\" the version dict for wheel.\n    ```\n\n2. Create `src/my_project/_version.py` with `get_version_dict()` in your project.\n    ```python\n    # Example _version.py, completely non-vendored.\n    from pathlib import Path\n\n    from version_pioneer.api import get_version_dict_wo_exec\n\n\n    def get_version_dict():\n        # NOTE: during installation, __file__ is not defined\n        # When installed in editable mode, __file__ is defined\n        # When installed in standard mode (when built), this file is replaced to a compiled versionfile.\n        if \"__file__\" in globals():\n            cwd = Path(__file__).parent\n        else:\n            cwd = Path.cwd()\n\n        return get_version_dict_wo_exec(\n            cwd=cwd,\n            style=\"pep440\",\n            tag_prefix=\"v\",\n        )\n    ```\n\n3. Put the following code in your project's `__init__.py` to use the version string.\n    ```python\n    # src/my_project/__init__.py\n    from ._version import get_version_dict\n\n    __version__ = get_version_dict()[\"version\"]\n    ```\n\n\u003e [!TIP]\n\u003e Use `version-pioneer install --no-vendor` CLI command to perform the step 2 and 3 automatically.\n\n4. Configure your build backend to execute `_version.py` and use the version string. Setuptools, Hatchling and PDM are supported.\n\n📦 Setuptools:\n\n```toml\n# append to pyproject.toml\n[build-system]\nrequires = [\"setuptools\", \"version-pioneer\"]\nbuild-backend = \"setuptools.build_meta\"\n```\n\n`setup.py`:\n\n```python\nfrom setuptools import setup\nfrom version_pioneer.build.setuptools import get_cmdclass, get_version\n\nsetup(\n    version=get_version(),\n    cmdclass=get_cmdclass(),\n)\n```\n\n🥚 Hatchling:\n\n```toml\n# append to pyproject.toml\n[build-system]\nrequires = [\"hatchling\", \"version-pioneer\"]\nbuild-backend = \"hatchling.build\"\n\n[tool.hatch.version]\nsource = \"version-pioneer\"\n\n[tool.hatch.build.hooks.version-pioneer]\n# section is empty because we read config from `[tool.version-pioneer]` section.\n```\n\nPDM:\n\n```toml\n# append to pyproject.toml\n[build-system]\nrequires = [\"pdm-backend\", \"version-pioneer\"]\nbuild-backend = \"pdm.backend\"\n```\n\nVoilà! The version string is now dynamically generated from git tags, and the `_version.py` file is replaced with a constant \"versionfile\" when building a wheel or source distribution.\n\n\u003e [!TIP]\n\u003e The `_version.py` gets replaced to a constant version file when you build your package, so `version-pioneer` shouldn't be in your package dependencies.\n\u003e Instead, you may put it as a \"dev dependency\" in your `pyproject.toml`.\n\u003e\n\u003e ```toml\n\u003e [project.optional-dependencies]\n\u003e dev = [\"version-pioneer\"]\n\u003e ```\n\u003e\n\u003e Your package could be installed with `pip install -e '.[dev]'` for development.\n\n\n### Usage with vendoring the script\n\nIf you don't want to add a dev dependency, you can simply vendor the \"versionscript\" in your project.\n\nCopy-paste the entire [`versionscript.py`](src/version_pioneer/versionscript.py) to your project, use it as is or customise it to your needs.\n\nIf you choose to modify the script, remember one rule: the versionscript file must contain `get_version_dict()` function that returns a dictionary with a \"version\" key. (more precisely, the `VersionDict` type in the script.)\n\n```python\n# Valid _version.py\ndef get_version_dict():\n    # Your custom logic to get the version string.\n    return { \"version\": version, ... }\n```\n\n\u003e [!TIP]\n\u003e Use `version-pioneer install` or `version-pioneer print-versionscript-code` CLI commands that helps you install (vendor) the `versionscript.py` file to your project.\n\n\n\n\n## 🛠️ Configuration\n\nUnlike Versioneer, the configuration is located in two places: `pyproject.toml` and the \"versionscript\" (`src/my_project/_version.py`). This is to make it less confusing, because in Versioneer, most of the pyproject.toml config were actually useless once you install `versionscript.py` in your project.\n\nThe idea is that the toml config just tells you where the script is (for build backends to identify them), and the script has everything it needs. \n\n### `pyproject.toml` [tool.version-pioneer]: Configuration for build backends and Version-Pioneer CLI. \n\n- `versionscript`: Path to the versionscript to execute `get_version_dict()`. (e.g. `src/my_project/_version.py`)\n- `versionfile-sdist`: Path to save the resolved versionfile in the *sdist* build directory (e.g. `src/my_project/_version.py`)\n- `versionfile-wheel`: Path to save the resolved versionfile in the *wheel* build directory (e.g. `my_project/_version.py`)\n\nThe main idea is that when you build your project, \"versionscript\" is executed to write the \"versionfile\".  \nWhen you build a source distribution (sdist), the `versionfile-sdist` gets replaced to a short constant file.  \nWhen you build a wheel, the `versionfile-wheel` gets replaced to a short constant file.\n\n\u003e [!TIP]\n\u003e Leave out the `versionfile-sdist` and/or `versionfile-wheel` setting if you don't want to write/replace the versionfile in the build directory. \n\n\n### `_version.py` versionscript: Configuration for resolving the version string.\n\nYou can modify the config in the script. \n\n```python\n@dataclass(frozen=True)\nclass VersionPioneerConfig:\n    style: VersionStyle = VersionStyle.pep440\n    tag_prefix: str = \"v\"\n    parentdir_prefix: Optional[str] = None\n    verbose: bool = False\n```\n\n- `style`: similar to Versioneer's `style` option. Three major styles are:\n    - `pep440`: \"1.2.3+4.gxxxxxxx.dirty\" (default)\n    - `pep440-master`: \"1.2.3+4.gxxxxxxx.5.gxxxxxxx.dirty\"\n        - Shows the distance from the tag to master/main, and the master to the current branch.\n        - Useful when you mainly work on a branch and merge to master/main.\n    - `digits`: \"1.2.3.5\"\n        - Digits-only version string.\n        - The last number is the distance from the tag (dirty is counted as 1, thus 5 in this example).\n        - Useful for multi-language projects, Chrome Extension, etc.\n    - See Versioneer for more styles (or read documentation in _version.py).\n- `tag_prefix`: tag to look for in git for the reference version.\n- `parentdir_prefix`: if there is no .git, like it's a source tarball downloaded from GitHub Releases, find version from the name of the parent directory. e.g. setting it to \"github-repo-name-\" will find the version from \"github-repo-name-1.2.3\"\n    - 🧙‍♂️ Set to None to auto-magically infer from pyproject.toml's GitHub/GitLab URL or project name. (New in Version-Pioneer)\n- `verbose`: print debug messages.\n\nIf you want to customise the logic, you can modify the entire script. However you modify the script, remember that this file has to be able to run like a standalone script without any other dependencies (like package, files, config, etc.).\n\n## 💡 Understanding Version-Pioneer (completely vendored, without build backend plugins)\n\nThis section explains how Version-Pioneer works, so you can customise it to your needs.\n\n### Basic: versionscript.py as a script\n\nThe core functionality is in one file: [`versionscript.py`](src/version_pioneer/versionscript.py). This code is either used as a script (`python versionscript.py`) that prints a json of all useful information, or imported as a module (`from my_project.versionscript import get_version_dict`), depending on your needs.\n\nRun it in your project to see what it prints. Change git tags, commit, and see how it changes.\n\n```console\n$ git tag v1.2.3\n$ python versionscript.py\n{\"version\": \"1.2.3\", \"full_revisionid\": \"xxxxxx\", \"dirty\": False, \"error\": None, \"date\": \"2024-12-17T12:25:42+0900\"}\n$ git commit --allow-empty -m \"commit\"\n$ python versionscript.py\n{\"version\": \"1.2.3+1.gxxxxxxx\", \"full_revisionid\": \"xxxxxx\", \"dirty\": True, \"error\": None, \"date\": \"2024-12-17T12:25:42+0900\"}\n```\n\n### Basic: converting versionscript.py to a constant versionfile (for build)\n\nYou lose the git history during build, so you need to convert the `versionscript.py` to a constant version string.  \nJust `exec` the original `versionscript.py` and save the result as you wish: text, json, etc.\n\n```python\n# code to evaluate get_version_dict() from the version script\nPath(\"src/my_project/_version.py\").read_text()\nmodule_globals = {}\nexec(version_py, module_globals)\nprint(module_globals[\"get_version_dict\"]())\n```\n\n### Basic: building a Python package (replacing \"versionscript\" to a constant \"versionfile\")\n\nPlace `versionscript.py` in your project source directory (like `src/my_project/_version.py`). When you install your package like `pip install -e .`, the code is unchanged, so it will always print up-to-date version string from git tags.\n\nHowever, if you install like `pip install .` or `pyproject-build`, `uv build` etc., you would lose the git history so the `src/my_project/_version.py` should change.  \nThe original file is replaced with this. This is generated by literally executing the above file and saving version_dict as a constant.\n\n```python\n# pseudo code of _version.py \"versionfile\", generated.\ndef get_version_dict():\n    return { \"version\": \"0.3.2+15.g2127fd3.dirty\", \"full_revisionid\": \"2127fd373d14ed5ded497fc18ac1c1b667f93a7d\", \"dirty\": True, \"error\": None, \"date\": \"2024-12-17T12:25:42+0900\" }\n```\n\n### Advanced: Configuring a 🥚 Hatchling Hook\n\nEven if you are not familiar with Hatchling, hear me out. It is very straightforward.\n\nAdd hatchling configuration to `pyproject.toml`.\n\n\u003e [!NOTE]\n\u003e In this tutorial, we're assuming that `versionscript` == `versionfile-sdist` for the sake of simplicity.\n\u003e This will replace the _version.py itself.\n\u003e\n\u003e If you want to keep the original versionscript.py (different `versionfile-sdist`), first exec `versionfile-sdist` if it exists, otherwise exec `versionscript`.  \n\u003e The reason is that once sdist is built, the version should have been already evaluated and the git information is removed, so `versionfile-sdist` must take precedence.\n\n```toml\n[build-system]\nrequires = [\"hatchling\", \"tomli ; python_version \u003c '3.11'\"]\nbuild-backend = \"hatchling.build\"\n\n# We assume versionscript == versionfile-sdist thus we can use what hatchling provides, and we don't need a metadata hook.\n[tool.hatch.version]\nsource = \"code\"\npath = \"src/my_project/_version.py\"\nexpression = \"get_version_dict()['version']\"\n\n[tool.hatch.build.hooks.custom]\npath = \"hatch_build.py\"\n\n[tool.version-pioneer]\nversionscript = \"src/my_project/_version.py\"\nversionfile-sdist = \"src/my_project/_version.py\"\nversionfile-wheel = \"my_project/_version.py\"\n\n[project]\nname = \"my-project\"\ndynamic = [\"version\"]\n```\n\nAdd `hatch_build.py` to the project root.\n\n```python\nfrom __future__ import annotations\n\nimport sys\nimport tempfile\nimport textwrap\nfrom os import PathLike\nfrom pathlib import Path\nfrom typing import Any\n\nfrom hatchling.builders.hooks.plugin.interface import BuildHookInterface\n\nif sys.version_info \u003c (3, 11):\n    import tomli as tomllib\nelse:\n    import tomllib\n\n\ndef load_toml(file: str | PathLike) -\u003e dict[str, Any]:\n    with open(file, \"rb\") as f:\n        return tomllib.load(f)\n\n\nclass CustomPioneerBuildHook(BuildHookInterface):\n    def initialize(self, version: str, build_data: dict[str, Any]) -\u003e None:\n        self.temp_versionfile = None\n\n        if version == \"editable\":\n            return\n\n        pyproject_toml = load_toml(Path(self.root) / \"pyproject.toml\")\n\n        # evaluate the original versionscript.py file to get the computed versionfile\n        versionscript = Path(\n            pyproject_toml[\"tool\"][\"version-pioneer\"][\"versionscript\"]\n        )\n        version_py = versionscript.read_text()\n        module_globals = {}\n        exec(version_py, module_globals)\n        version_dict = module_globals[\"get_version_dict\"]()\n\n        # replace the file with the constant version\n        # NOTE: Setting delete=True will delete too early on Windows\n        self.temp_versionfile = tempfile.NamedTemporaryFile(mode=\"w\", delete=False)  # noqa: SIM115\n        self.temp_versionfile.write(\n            textwrap.dedent(f\"\"\"\n                # THIS \"versionfile\" IS GENERATED BY version-pioneer\n                # by evaluating the original versionscript and storing the computed versions as a constant.\n\n                def get_version_dict():\n                    return {version_dict}\n            \"\"\").strip()\n        )\n        self.temp_versionfile.flush()\n\n        build_data[\"force_include\"][self.temp_versionfile.name] = Path(\n            pyproject_toml[\"tool\"][\"version-pioneer\"][\"versionfile-sdist\"]\n        )\n\n    def finalize(\n        self,\n        version: str,\n        build_data: dict[str, Any],\n        artifact_path: str,\n    ) -\u003e None:\n        if self.temp_versionfile is not None:\n            # Delete the temporary version file\n            self.temp_versionfile.close()\n            Path(self.temp_versionfile.name).unlink()\n```\n\nIt just replaces the `_version.py` \"versionscript\" with a constant \"versionfile\", by executing the versionscript.\nThis is skipped when the project is installed in editable mode (`pip install -e .`).\n\nNow you can install your package with `pip install .`, `pip install -e .`, or build a wheel with `hatch build`, `pyproject-build` (`python -m build`), or `uv build`.\n\n\u003e [!IMPORTANT]\n\u003e Validate if `uv build --sdist`, `uv build --wheel` produces the same result as `uv build` (both sdist and wheel are built at the same time).\n\u003e We provide a CLI command `version-pioneer build-consistency-test` to help you with this.\n\n### Advanced: Configuring a PDM backend hook\n\nThe idea is the same, but the PDM doesn't really evaluate a code to get a version string (or maybe it doesn't work in this case).\nSo we do both in the hook.\n\n📄 pyproject.toml:\n\n```toml\nrequires = [\"pdm-backend\"]\nbuild-backend = \"pdm.backend\"\n\n[tool.pdm.build]\ncustom-hook = \"pdm_build.py\"\n\n[tool.version-pioneer]\nversionscript = \"src/my_project/_version.py\"\nversionfile-sdist = \"src/my_project/_version.py\"\nversionfile-wheel = \"my_project/_version.py\"\n\n[project]\nname = \"my-project\"\ndynamic = [\"version\"]\n```\n\n🐍 pdm_build.py:\n\n```python\nimport textwrap\nfrom pathlib import Path\n\nfrom pdm.backend.hooks.base import Context\n\n\ndef pdm_build_initialize(context: Context):\n    # Update metadata version\n    versionscript = Path(\n        context.config.data[\"tool\"][\"version-pioneer\"][\"versionscript\"]\n    )\n    versionscript_code = versionscript.read_text()\n    version_module_globals = {}\n    exec(versionscript_code, version_module_globals)\n    version_dict = version_module_globals[\"get_version_dict\"]()\n    context.config.metadata[\"version\"] = version_dict[\"version\"]\n\n    # Write the static version file\n    if context.target != \"editable\":\n        if context.target == \"wheel\":\n            versionscript = context.config.data[\"tool\"][\"version-pioneer\"][\n                \"versionfile-wheel\"\n            ]\n\n        context.ensure_build_dir()\n        versionscript = context.build_dir / Path(versionscript)\n        versionscript.parent.mkdir(parents=True, exist_ok=True)\n        versionscript.write_text(\n            textwrap.dedent(f\"\"\"\n                # THIS \"versionfile\" IS GENERATED BY version-pioneer\n                # by evaluating the original versionscript and storing the computed versions as a constant.\n\n                def get_version_dict():\n                    return {version_dict}\n            \"\"\").strip()\n        )\n```\n\n## 🚀 Version-Pioneer CLI\n\nThe above usage should be completely fine, but we also provide a CLI tool to help you install and evaluate versionscript.py.\n\n```bash\n# Install with pip\npip install 'version-pioneer[cli]'\n\n# Install with uv tool (in a separate environment, just for the CLI)\nuv tool install 'version-pioneer[cli]'\n```\n\n```console\n$ version-pioneer\n\n Usage: version-pioneer [OPTIONS] COMMAND [ARGS]...\n\n 🧗 Version-Pioneer: Dynamically manage project version with hatchling and pdm support.\n\n╭─ Commands ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮\n│ install                    Add _version.py, modify __init__.py and maybe setup.py.                                             │\n│ print-versionscript-code   Print the content of _version.py (versionscript.py) file (for manual installation).                 │\n│ exec-versionscript         Resolve the _version.py file for build, and print the content.                                      │\n│ get-version-wo-exec        WITHOUT evaluating the _version.py file, get version from VCS with built-in Version-Pioneer logic.  │\n│ build-consistency-test     Check if builds are consistent with sdist, wheel, both, sdist -\u003e sdist.                             │\n╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\n```\n\n\n### `version-pioneer install`: Install _version.py to your project\n\n1. Configure `pyproject.toml` with `[tool.version-pioneer]` section.\n\n```toml\n[tool.version-pioneer]\nversionscript = \"src/my_project/_version.py\"\nversionfile-sdist = \"src/my_project/_version.py\"\nversionfile-wheel = \"my_project/_version.py\"\n```\n\n2. `version-pioneer install` will copy-paste the [`versionscript.py`](src/version_pioneer/versionscript.py) to the `versionscript` path you specified, and define `__version__` to your `__init__.py`.\n\nIf you are using setuptools backend, it will also create a `setup.py` file for you.\n\nYou can set `--no-vendor` option to import `version_pioneer` as a module to reduce the boilerplate code in your project. (This adds a dev dependency to your project.)\n\n\n### `version-pioneer exec-versionscript`: Resolve _version.py and get the version\n\nExamples:\n\n```console\n$ version-pioneer exec-versionscript --output-format version-string\n0.1.0+8.g6228bc4.dirty\n\n$ version-pioneer exec-versionscript --output-format json\n{\"version\": \"0.1.0+8.g6228bc4.dirty\", \"full_revisionid\": \"6228bc46e14cfc4e238e652e56ccbf3f2cb1e91f\", \"dirty\": true, \"error\": null, \"date\": \"2024-12-21T21:03:48+0900\"}\n\n$ version-pioneer exec-versionscript --output-format python\n#!/usr/bin/env python3\n# THIS \"versionfile\" IS GENERATED BY version-pioneer-0.1.0\n# by evaluating the original versionscript and storing the computed versions as a constant.\n\ndef get_version_dict():\n    return {'version': '0.1.0+8.g6228bc4.dirty', 'full_revisionid': '6228bc46e14cfc4e238e652e56ccbf3f2cb1e91f', 'dirty': True, 'error': None, 'date': '2024-12-21T21:03:48+0900'}\n\n\nif __name__ == \"__main__\":\n    import json\n\n    print(json.dumps(__version_dict__))\n```\n\n### `version-pioneer get-version-wo-exec`: Get version without using _version.py\n\nThis is useful when you want to get the version string without evaluating the versionscript file, like your project is probably not Python.\n\nIt's the same as running the `versionscript.py` script (unchanged, not the vendored one), but with more options.\n\n```console\n$ version-pioneer get-version-wo-exec\n0.1.0+8.g6228bc4.dirty\n\n$ version-pioneer get-version-wo-exec --output-format json\n{\"version\": \"0.1.0+8.g6228bc4.dirty\", \"full_revisionid\": \"6228bc46e14cfc4e238e652e56ccbf3f2cb1e91f\", \"dirty\": true, \"error\": null, \"date\": \"2024-12-21T21:03:48+0900\"}\n\n$ version-pioneer get-version-wo-exec --style digits\n0.1.0.9\n```\n\n### `version-pioneer build-consistency-test`: Test build consistency\n\nUseful to check if you have configured Version-Pioneer correctly. It builds the project with `uv build`, `uv build --sdist`, `uv build --wheel`, and checks if the version strings and the package content are consistent. Also it builds sdist from sdist and perform the check.\n\n```console\n$ version-pioneer build-consistency-test\n06:35:25 INFO     version_pioneer - Running with version-pioneer 0.1.0+41.g8b148ed.dirty               __init__.py:202\n         INFO     version_pioneer.api - Testing build consistency...                                        api.py:212\n         INFO     version_pioneer.api - Changing cwd to /Users/kiyoon/project/version-pioneer               api.py:220\n         INFO     version_pioneer.api - Building the project with `uv build`                                api.py:226\n06:35:26 INFO     version_pioneer.api - Building the project with `uv build --sdist` and `uv build --wheel` api.py:235\n06:35:27 SUCCESS  version_pioneer.api - ✅ 2 wheel builds are consistent.                                   api.py:272\n         SUCCESS  version_pioneer.api - ✅ 2 sdist builds are consistent.                                   api.py:288\n         INFO     version_pioneer.api - Building the project with `uv build --sdist` using the built sdist  api.py:290\n                  (chaining test).\n         INFO     version_pioneer.api - Changing cwd to the built sdist directory:                          api.py:294\n                  /var/folders/r5/9cpfjfjx3b73b6stl7_w712h0000gn/T/tmpzuq_uwdn/dist/version_pioneer-0.1.0+4\n                  1.g8b148ed.dirty\n         SUCCESS  version_pioneer.api - ✅ Chained sdist builds are consistent.                             api.py:324\n         INFO     version_pioneer.api - Build wheel using the sdist.                                        api.py:327\n06:35:28 SUCCESS  version_pioneer.api - ✅ sdist -\u003e wheel chained build is consistent with the non-chained  api.py:346\n                  build.\n         INFO     version_pioneer.api - Deleting temporary directory                                        api.py:351\n                  /var/folders/r5/9cpfjfjx3b73b6stl7_w712h0000gn/T/tmpzuq_uwdn\n         SUCCESS  version_pioneer.api - 💓 All tests passed! 3 sdist builds and 3 wheel builds are          api.py:354\n                  consistent.\n\n\n```\n\n\n## 📚 Note\n\n- Only supports git.\n- `git archive` is not supported. Original Versioneer uses `.gitattributes` to tell git to replace some strings in `_version.py` when archiving. But this is not enough information (at least in my case) and the version string always becomes `0+unknown`. So I dropped it.\n\n\n### Build chaining problem\n\nIt's good to note that, chaining building (project -\u003e sdist -\u003e sdist -\u003e wheel) may result in different version strings if not configured correctly. We take the following strategy to make it consistent:\n\n1. `versionfile-sdist` is evaluated first, if it exists.\n\nMost of the time your `versionscript` and `versionfile-sdist` would be the same. But for some reason you choose to have a seaparate file,\nand imagine if we execute the versionscript again in a built sdist. It may produce a different version string because now we don't have git information.\n\nTherefore, `versionfile-sdist` takes precedence (if it exists) over `versionscript`, for resolving version.\n\n\n2. Each backend works differently under the hood. Some things to note:\n\n**Setuptools**:\n\n- If `setup.cfg` doesn't exist, the sdist build will generate the file.\n    - Thus, if you build sdist from sdist, the `*.egg-info/SOURCES.txt` will contain `setup.cfg` so the result is slightly different.\n- `version_pioneer.build.setuptools.get_version()` finds the PKG-INFO to look up the version.\n    - It's the function you used in `setup(version=get_version())`.\n    - Building from sdist wouldn't look at git tags, but the `PKG-INFO` file. So the version string is consistent after multiple builds.\n\n**Hatchling**:\n\n- Once sdist is built, the PKG-INFO is present, and hatchling's version source plugin is ignored.\n- `versionfile-wheel` doesn't really get used, but I would still configure it for consistency.\n\n**PDM Backend**:\n\n- Building with pdm removes `dynamic = [\"version\"]` from `pyproject.toml`'s `[project]` section.\n    - Instead, the `version=\"0.1.0\"` (whatever it is during the build) is written.\n- However, the build hook can still change the metadata version, thus the versionfile / versionscript is still executed.\n    - It will be the versionfile that is already resolved, so the version string is consistent.\n\n\n## ❓ Why this fork?\n\n[Versioneer](https://github.com/python-versioneer/python-versioneer) finds the closest git tag like `v1.2.3` and generates a version string like `1.2.3+4.gxxxxxxx.dirty`.\n\n- `1.2.3` is the closest git tag.\n- `+4` is the number of commits since the tag.\n- `gxxxxxxx` is the git commit hash (without the leading `g`).\n- `.dirty` is appended if the working directory is dirty (i.e. has uncommitted changes).\n\n[setuptools-scm](https://github.com/pypa/setuptools-scm) is a similar tool, but with some differences:\n\n- How the version string is rendered: `1.2.3+4.gxxxxxxx.dirty` vs `1.2.4.dev4+gxxxxxxx`\n    - No `.dirty` in setuptools-scm.\n    - Infer the next version number (i.e. 1.2.4 instead of 1.2.3).\n- The `_version.py` file is always a constant in setuptools-scm.\n    - Versioneer can dynamically generate the version string at runtime, so it's always up-to-date. Useful for development (pip install -e .).\n    - Setuptools-scm won't ever change the version string after installation. You need to reinstall to update the version string.\n\nI have used versioneer for years, and I like the format and dynamic resolution of versions for development. However,\n\n1. It doesn't support any build backends other than `setuptools` (like `pdm`, `hatchling`, `poetry`, `maturin`, `scikit-build`, etc.)\n2. It doesn't support projects that are not Python (like Rust, Chrome Extension, etc.).\n\nEvery time I had to figure out how to integrate a new VCS versioning plugin but they all work differently and produce different version strings. GitHub Actions and other tools may not work with all different version format. Different language usually expects different format, and it's especially hard to make it compatible for mixed language projects.\n\nThe original versioneer is 99% boilerplate code to make it work with all legacy setuptools configurations, trying to \"generate\" code depending on the configuration, etc.. But the core functionality is simple: just get version from git tag and format it. I had to leverage this logic to integrate Versioneer in every project I had.\n\n## 🚧 Development\n\nRun tests:\n\n```bash\n# install uv (brew install uv, pip install uv, ...)\nuv pip install deps/requirements-dev.in\npytest\n```\n\n`uv` is required to run tests because we use `uv build`.\n\nTypes of tests:\n\n- install with setuptools, hatchling, pdm\n- version after tag, commit, dirty\n- invalid version-pioneer config\n- build with `uv build`, `uv build --sdist`, `uv build --wheel`\n    - Important: all three can produce different results if sdist isn't generated correctly from the first place.\n    - When building both at the same time (`uv build`), it seems to make sdist first and then wheel from the sdist (not directly from the source dir).\n    - If the sdist doesn't contain resolved `_version.py`, the wheel build will get no version, because git information is gone.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiyoon%2Fversion-pioneer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkiyoon%2Fversion-pioneer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiyoon%2Fversion-pioneer/lists"}