Automating Python Package Versioning with CalVer

As software projects evolve, keeping track of versions becomes crucial for maintaining compatibility, identifying changes, and managing dependencies. In the world of Python, the calver package offers a convenient solution for automatically defining your package version as a calendar version. In this article, we will explore how to leverage calver to automate your package versioning process.

Getting Started

To begin using calver, you need to ensure it is present during your project’s build step by specifying it as one of the build requirements in your pyproject.toml file. Here’s an example:

#toml
[build-system]
requires = ["setuptools>=42", "calver"]

Next, you will need to enable the generation of the version automatically based on the date by adding the following to your setup.py file:

#python
from setuptools import setup

setup(
    ...
    use_calver=True,
    setup_requires=['calver'],
    ...
)

Generating Version Numbers

Once calver is set up, you can easily generate the version number by running the following command:

#console
$ python setup.py --version
2020.6.16

By default, calver generates the version string using the format "%Y.%m.%d", which represents the year, month, and day. You can customize the format by overriding the use_calver argument in your setup.py file.

For example, to include the hour and minute in the version, you can modify the use_calver argument like this:

#python
use_calver="%Y.%m.%d.%H.%M"

Alternatively, you can entirely override the version generation process by passing a callable that will be invoked at build time. The callable should return the desired version string. Here’s an example:

#python
import datetime
from setuptools import setup

def long_now_version():
    now = datetime.datetime.now()
    return now.strftime("%Y").zfill(5) + "." + now.strftime("%m.%d")

setup(
    ...
    use_calver=long_now_version,
    setup_requires=['calver'],
    ...
)

With these configurations, you have full control over how the version string is generated.

Conclusion

Automating package versioning is essential for maintaining consistency and ensuring that all team members are using the correct version of a project. With the calver package, you can simplify the process by defining your package version as a calendar version. By following the steps outlined in this article, you can easily configure calver in your project, generate versions based on the date, and customize the version format.

If you have any questions or would like to learn more about calver, please refer to the calver repository on GitHub.

References

1. calver repository