vcver - Dynamic Versioning from VCS

0.2.12 · active · verified Tue Apr 14

vcver is a Python library that automates the generation of package version strings by extracting information directly from version control systems such as Git or Mercurial. This enables dynamic versioning based on commit hashes, tags, and branch names, particularly useful for development builds. It seamlessly integrates with `setuptools` and is actively maintained with releases occurring roughly annually. The current version is 0.2.12.

Warnings

gotcha vcver relies on Git or Mercurial being installed and accessible in the system's PATH. If the repository is not a valid Git/Mercurial repository or the VCS tools are not found, `vcver.get_version()` will fall back to a default (e.g., '0.0.0') or raise an error depending on configuration.
Fix: Ensure `git` or `hg` executables are installed and available in the system's PATH, and that your project directory is a valid VCS repository.
gotcha When running in environments where `.git` or `.hg` directories are not present (e.g., installed packages from PyPI, CI/CD environments that don't clone full history), `vcver.get_version()` might not produce the expected dynamic version. For release builds, consider using `vcver.set_version()` to explicitly embed a fixed version.
Fix: For production releases, use `vcver.set_version('X.Y.Z')` as part of your build process to hardcode the version, or ensure your build system retains the `.git` or `.hg` directory.

Install

pip install vcver Install stable version

Imports

get_version
```
import vcver
version = vcver.get_version()
```
When used in `setup.py` for `setuptools.setup(version=...)`, direct import like `from vcver import get_version` can cause issues if vcver itself depends on the package's version being defined during import. The standard recommendation is `version=vcver.get_version()` after `import vcver`.

Quickstart

Demonstrates how to integrate vcver into a `setup.py` for dynamic versioning using `setuptools.setup()`, and how to retrieve the version string directly within Python code.

import vcver

# Example usage in setup.py for setuptools:
# from setuptools import setup
# setup(
#     name='your_package',
#     version=vcver.get_version(),
#     # ... other setup arguments
# )

# Or to get the version directly:
current_version = vcver.get_version()
print(f"Current package version: {current_version}")

view raw JSON →