Vercheck

Check if a version number is PEP-440 compliant and optionally compare it against a version specified in a python file or the PKG-INFO metadata file.

Rationale

When you use a Python package, you may want to check a package's version. To check the Python package/library, a __version__ attribute is a common practice recommended by PEP 396.

import package_name
print(package_name.__version__)

Module version numbers SHOULD conform to the normalized version format specified in PEP 440 The canonical public version identifiers MUST comply with the following scheme:

[N!]N(.N)*[{a|b|rc}N][.postN][.devN]

Hard-coding the version of your package in the pyproject.toml may not be ideal, as it requires you to update it manually and if you want your package to have access to its own version, you will have to add a global variable with the version to a source package. This means you will have to manually keep those versions in sync. A common approach is using dynamic metadata.

[project]
name = "mypkg"
dynamic = "version"

[tool.setuptools.dynamic.version]
attr = "mypkg.about.__version__"

When you release a new version of your package, checking the version number is a good practice. You can automate this in your CI/CD pipeline, for example, using GitHub Actions.

      - name: Check tag name
        if: >-
          github.event_name == 'push' &&
          startsWith(github.ref, 'refs/tags')
        run: |
          pip install vercheck
          vercheck $GITHUB_REF_NAME src/vercheck/about.py

This will check that your tag name is a valid version number and that the version number in the src/vercheck/about.py file is the same as the tag name.

Requirements

• Python >= 3.10, no dependencies outside of the standard library.

Installation

You can install Vercheck via pip from PyPI:

$ pip install vercheck

Usage

to get a quick overview of the available commands and options, you can use the vercheck -h command.

usage: vercheck [-h] [--check-version-number-only] version [filename]

Check if the version is PEP-440 conformant.

positional arguments:
  version               The version number to compare against.
  filename              The path to the file containing the version information.

options:
  -h, --help            show this help message and exit
  --check-version-number-only
                        Only check if the version number is PEP-440 compliant without trying to retrieve a version from a file.

vercheck will exit with a non-zero exit code if the version number is not PEP-440 compliant, the file path does not exist or the version number is not equal to the version number in the file.

Examples:

vercheck 0.2.0 src/vercheck/about.py

This will check if the version number is PEP-440 compliant and if the version number is equal to the version number in the src/vercheck/about.py file. It does not provide any output if the version number is PEP-440 compliant and the version number is equal to the version number in the file. If an error is encountered, it will print the error message and exit with a non-zero exit code.

vercheck 0.2.0 --check-version-number-only

This will check if the version number is PEP-440 compliant without trying to retrieve a version from a file.

vercheck 0.2.0 src

or

vercheck 0.2.0 src/vercheck.egg-info/PKG-INFO

This will check if the version number is PEP-440 compliant and if the version number is equal to the version number in the src/vercheck.egg-info/PKG-INFO file. The output will be:

Warning: filename src does not end with '.py'
Checking version in src
Found 'src/vercheck.egg-info'

Contributing

Contributions are very welcome. To learn more, see the Contributor Guide.

License

Distributed under the terms of the MIT license, Vercheck is free and open source software.

Issues

If you encounter any problems, please file an issue along with a detailed description.

Related

dynamic-versioning