{"library":"incremental","title":"Incremental","description":"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.","status":"active","version":"24.11.0","language":"en","source_language":"en","source_url":"https://github.com/twisted/incremental","tags":["versioning","calver","build system","packaging"],"install":[{"cmd":"pip install incremental","lang":"bash","label":"Install Incremental"},{"cmd":"pipx install incremental","lang":"bash","label":"Install CLI tool (recommended)"}],"dependencies":[{"reason":"Required for the 'incremental' command-line interface.","package":"click","optional":false},{"reason":"Build backend dependency when using with setuptools.","package":"setuptools","optional":true},{"reason":"Build backend dependency when using with Hatchling.","package":"hatchling","optional":true},{"reason":"Core utilities for Python packages, an indirect dependency via build backends.","package":"packaging","optional":false}],"imports":[{"note":"The primary class for defining project versions.","symbol":"Version","correct":"from incremental import Version"}],"quickstart":{"code":"# 1. In your project's `_version.py` file:\nfrom incremental import Version\n\n__version__ = Version(\"my_project\", 24, 11, 0, release_candidate=0)\n\n# 2. In your project's top-level `__init__.py` file:\n# from ._version import __version__\n\n# 3. Accessing the version (e.g., from setup.py or build system):\n# import importlib.metadata\n# project_version = importlib.metadata.version('my_project')\n\n# Or, if __version__ is exposed via __init__.py:\n# from my_project import __version__\n# print(__version__.public()) # '24.11.0rc0'","lang":"python","description":"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."},"warnings":[{"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.","message":"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`.","severity":"breaking","affected_versions":"24.7.0"},{"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`.","message":"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.","severity":"deprecated","affected_versions":"All versions (best practice guidance for Python >= 3.6)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always verify that the `package` argument in `Version(\"package_name\", ...)` exactly matches the declared package name in your build configuration.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-05T00:00:00.000Z","next_check":"2026-07-04T00:00:00.000Z"}