Skip to main content

Versioning It with your Version In Git

Project description

Project Status: Active — The project has reached a stable, usable state and is being actively developed. CI Status coverage pyversions Conda Version MIT License

GitHub | PyPI | Documentation | Issues | Changelog

versioningitVersioning It with your Version In Git

versioningit is yet another Python packaging plugin for automatically determining your package’s version based on your version control repository’s tags. Unlike others, it allows easy customization of the version format and even lets you easily override the separate functions used for version extraction & calculation.

Features:

  • Works with both setuptools and Hatch

  • Installed & configured through PEP 518’s pyproject.toml (or, alternatively, through versioningit.toml for non-Python projects)

  • Supports Git, modern Git archives, and Mercurial

  • Formatting of the final version uses format template strings, with fields for basic VCS information and separate template strings for distanced vs. dirty vs. distanced-and-dirty repository states

  • Can optionally write the final version and other details to a file for loading at runtime

  • Provides custom hooks for inserting the final version and other details into a source file at build time

  • The individual methods for VCS querying, tag-to-version calculation, version bumping, version formatting, and writing the version to a file can all be customized using either functions defined alongside one’s project code or via publicly-distributed entry points

  • Can alternatively be used as a library for use in setup.py or the like, in case you don’t want to or can’t configure it via pyproject.toml

  • The only thing it does is calculate your version and optionally write it to a file; there’s no overriding of your sdist contents based on what’s in your Git repository, especially not without a way to turn it off, because that would just be rude.

Installation & Setup

versioningit requires Python 3.8 or higher. Just use pip for Python 3 (You have pip, right?) to install versioningit and its dependencies:

python3 -m pip install versioningit

However, usually you won’t need to install versioningit in your environment directly. Instead, you specify it in your project’s pyproject.toml file in the build-system.requires key, like so:

# If using Setuptools:
[build-system]
requires = [
    "setuptools",
    "versioningit",
]
build-backend = "setuptools.build_meta"

# If using Hatch:
[build-system]
requires = [
    "hatchling",
    "versioningit",
]
build-backend = "hatchling.build"

# This setting is also required if you're using Hatch:
[tool.hatch.version]
source = "versioningit"

Then, you configure versioningit by adding a [tool.versioningit] table to your pyproject.toml. See the documentation for details, but you can get up & running with just the minimal configuration, an empty table:

[tool.versioningit]

versioningit eliminates the need to list an explicit version in setup.py, setup.cfg, or pyproject.toml (and any explicit version you do list will be ignored when using versioningit), so you should remove any such settings in order to reduce confusion.

Note: If you’re specifying your project metadata via a [project] table in pyproject.toml, you need to set project.dynamic = ["version"] in order for versioningit to work.

Once you have a [tool.versioningit] table in your pyproject.toml — and once your repository has at least one tag — building your project with build or similar will result in your project’s version automatically being set based on the latest tag in your Git repository. You can test your configuration and see what the resulting version will be using the versioningit command (see the documentation).

Example Configurations

One of versioningit’s biggest strengths is its ability to configure the version format using placeholder strings. The default format configuration looks like this:

[tool.versioningit.format]
# Format used when there have been commits since the most recent tag:
distance = "{base_version}.post{distance}+{vcs}{rev}"
# Example formatted version: 1.2.3.post42+ge174a1f

# Format used when there are uncommitted changes:
dirty = "{base_version}+d{build_date:%Y%m%d}"
# Example formatted version: 1.2.3+d20230922

# Format used when there are both commits and uncommitted changes:
distance-dirty = "{base_version}.post{distance}+{vcs}{rev}.d{build_date:%Y%m%d}"
# Example formatted version: 1.2.3.post42+ge174a1f.d20230922

Other format configurations of interest include:

  • The default format used by setuptools_scm:

    [tool.versioningit.next-version]
    method = "smallest"
    
    [tool.versioningit.format]
    distance = "{next_version}.dev{distance}+{vcs}{rev}"
    # Example formatted version: 1.2.4.dev42+ge174a1f
    
    dirty = "{base_version}+d{build_date:%Y%m%d}"
    # Example formatted version: 1.2.3+d20230922
    
    distance-dirty = "{next_version}.dev{distance}+{vcs}{rev}.d{build_date:%Y%m%d}"
    # Example formatted version: 1.2.4.dev42+ge174a1f.d20230922
  • The format used by versioneer:

    [tool.versioningit.format]
    distance = "{base_version}+{distance}.{vcs}{rev}"
    # Example formatted version: 1.2.3+42.ge174a1f
    
    dirty = "{base_version}+{distance}.{vcs}{rev}.dirty"
    # Example formatted version: 1.2.3+42.ge174a1f.dirty
    
    distance-dirty = "{base_version}+{distance}.{vcs}{rev}.dirty"
    # Example formatted version: 1.2.3+42.ge174a1f.dirty
  • The format used by vcversioner:

    [tool.versioningit.format]
    distance = "{base_version}.post{distance}"
    # Example formatted version: 1.2.3.post42
    
    dirty = "{base_version}"
    # Example formatted version: 1.2.3
    
    distance-dirty = "{base_version}.post{distance}"
    # Example formatted version: 1.2.3.post42

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

versioningit-3.3.0.tar.gz (220.3 kB view details)

Uploaded Source

Built Distribution

versioningit-3.3.0-py3-none-any.whl (38.4 kB view details)

Uploaded Python 3

File details

Details for the file versioningit-3.3.0.tar.gz.

File metadata

  • Download URL: versioningit-3.3.0.tar.gz
  • Upload date:
  • Size: 220.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.5

File hashes

Hashes for versioningit-3.3.0.tar.gz
Algorithm Hash digest
SHA256 b91ad7d73e73d21220e69540f20213f2b729a1f9b35c04e9e137eaf28d2214da
MD5 2a4674421f849eeb2c443723b7db9309
BLAKE2b-256 89f4bc578cc80989c572231a36cc03cc097091176fa3fb8b4e2af1deb4370eb7

See more details on using hashes here.

File details

Details for the file versioningit-3.3.0-py3-none-any.whl.

File metadata

  • Download URL: versioningit-3.3.0-py3-none-any.whl
  • Upload date:
  • Size: 38.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.5

File hashes

Hashes for versioningit-3.3.0-py3-none-any.whl
Algorithm Hash digest
SHA256 23b1db3c4756cded9bd6b0ddec6643c261e3d0c471707da3e0b230b81ce53e4b
MD5 1e8d4a3e4741b6ccd7a7de476ed3082b
BLAKE2b-256 1c59964ecb8008722d27d8a835baea81f56a91cea8e097b3be992bc6ccde6367

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page