CalVer (Setuptools Extension)

Warnings

• breaking Python 3.5, 3.6, 3.7, and 3.8 support has been dropped in recent versions. Earlier versions supported these, but new releases require Python 3.9 or newer.
  Fix: Upgrade your Python environment to 3.9 or newer, or pin `calver` to an older version compatible with your Python interpreter (e.g., `<2025.03.31` for 3.5/3.6, `<2025.04.01` for 3.7/3.8).
• breaking Significant changes were made to adopt `pyproject.toml` fully, deprecating older `setup.py` based configurations. Projects using `setup.py` or older `pyproject.toml` configurations might need updates.
  Fix: Migrate your project configuration to the modern `pyproject.toml` structure as shown in the quickstart example and the official documentation.
• gotcha The internal use of `datetime.datetime.utcnow()` was deprecated and could cause `DeprecationWarning` in specific Python environments or when warnings are treated as errors during builds.
  Fix: Upgrade `calver` to version `2025.10.20` or newer to resolve the `DeprecationWarning`.
• gotcha For reproducible builds, `calver` supports the `SOURCE_DATE_EPOCH` environment variable. If not set, the build will use the current timestamp.
  Fix: Set the `SOURCE_DATE_EPOCH` environment variable to a Unix timestamp in your build environment (e.g., CI/CD pipelines) to ensure consistent versioning across builds.

Install

• pip install calver Install library

Imports

• __build_backend__

  build-backend = "calver:__build_backend__"

  This is not a Python import statement, but rather the entry point specified in `pyproject.toml` for setuptools to use CalVer as the build backend.
• version

  version = {attr = "calver.version"}

  This is used within the `[tool.setuptools.dynamic]` section of `pyproject.toml` to instruct setuptools to retrieve the version dynamically from `calver.version`.

Quickstart

CalVer is configured declaratively in your `pyproject.toml` file. This example demonstrates how to set `calver` as the build backend and use it to dynamically set your project's version.

# pyproject.toml
[build-system]
requires = ["setuptools>=61", "calver"]
build-backend = "calver:__build_backend__"

[project]
name = "my-calver-package"
authors = [
    {name = "Your Name", email = "your.email@example.com"}
]
description = "A package using CalVer"
readme = "README.md"
requires-python = ">=3.9"
dynamic = ["version"]

[tool.setuptools.dynamic]
version = {attr = "calver.version"}