Incremental

24.11.0 · active · verified Sun Apr 05

Incremental is a Python library that implements a CalVer (Calendar Versioning) manager for Python projects. It provides tools to define and manage project versions following a YY.MM.PATCH scheme, including release candidates, post-releases, and development releases. The library is currently at version 24.11.0 and follows a calendar-based release cadence.

Warnings

breaking Version 24.7.0 introduced a breaking change where projects using build backends like `setuptools.build_meta` could fail to build with a `KeyError: 'project'` during `_load_pyproject_toml`.
Fix: Upgrade to a newer version of `incremental` (e.g., 24.7.1 or later) which contains a fix for this `pyproject.toml` parsing issue. Ensure your `pyproject.toml` explicitly defines a `[project]` table with a `name` key if you are using a dynamic version.
deprecated Exposing `__version__` directly in `__init__.py` is becoming less common. Python 3.6 and later provide `importlib.metadata.version()` as a standard, more robust way to retrieve an installed package's version at runtime.
Fix: While `incremental` still supports populating `__version__`, consider migrating your code to use `importlib.metadata.version('your-package-name')` for runtime version checks. This also allows `incremental` to be solely a build dependency, removing it from `install_requires`.
gotcha The `incremental` CLI tool (e.g., `incremental update`) requires `click` and is best installed via `pipx` to avoid polluting your project's dependencies with CLI tools.
Fix: Install `incremental` with `pipx install incremental` to ensure the command-line utility is available in an isolated environment, preventing potential dependency conflicts with your project.
gotcha When initializing `incremental.Version`, the 'package' argument must precisely match the name used in your `pyproject.toml` or `setup.py` (e.g., `[project] name = "my_project"`). Mismatches can lead to unexpected behavior or build failures.
Fix: Always verify that the `package` argument in `Version("package_name", ...)` exactly matches the declared package name in your build configuration.

Install

pip install incremental Install Incremental
pipx install incremental Install CLI tool (recommended)

Imports

Version
```
from incremental import Version
```
The primary class for defining project versions.

Quickstart

Define your project's version using the `Version` class in a `_version.py` file. Optionally, expose it via your package's `__init__.py`. For modern Python (>=3.8), `importlib.metadata.version()` is the recommended way to retrieve an installed package's version dynamically. The `incremental update` CLI tool automates the `_version.py` file management.

# 1. In your project's `_version.py` file:
from incremental import Version

__version__ = Version("my_project", 24, 11, 0, release_candidate=0)

# 2. In your project's top-level `__init__.py` file:
# from ._version import __version__

# 3. Accessing the version (e.g., from setup.py or build system):
# import importlib.metadata
# project_version = importlib.metadata.version('my_project')

# Or, if __version__ is exposed via __init__.py:
# from my_project import __version__
# print(__version__.public()) # '24.11.0rc0'

view raw JSON →