setuptools expects a local version identifier for a build tag

[gh-andre]

I'm trying to build a package with a build tag and setuptools appears to expect a Python local version identifier and not a build tag.

That is, given this project:

[build-system]
requires = ["setuptools>=65.0"]
build-backend = "setuptools.build_meta"

[project]
name = "setuptools_build_tag_test"
version = "0.1.0"
requires-python = ">=3.10"

, and using this build syntax

 python3 -m build \
         --config-setting=--build-option=egg_info \
         --config-setting=--build-option=--tag-build=123.abc

, will fail with this error message:

pkg_resources.extern.packaging.version.InvalidVersion: Invalid version: '0.1.0123.abc'

I would expect that setuptools would add a dash to form the format for wheel packages from the page below.

{distribution}-{version}(-{build tag})?-{python tag}-{abi tag}-{platform tag}.whl

https://packaging.python.org/en/latest/specifications/binary-distribution-format/#file-format

The only way I could make it work is to use a dummy Python local version, as defined on this page:

https://peps.python.org/pep-0440/#local-version-identifiers

So, the same command, but with a local version identifier injected into the build tag does produce a valid binary package:

 python3 -m build \
         --config-setting=--build-option=egg_info \
         --config-setting=--build-option=--tag-build=+ci-123.abc

However, it replaces the dash with a dot, so the whole sequence becomes a local version, like this:

setuptools_build_tag_test-0.1.0+ci.123.abc-py3-none-any.whl

I can see on the page below that eggs are deprecated in favor of wheels, but given how setuptools builds a binary package, I read it as if eggs are deprecated as the output format, but not the egg_info, which is what being used in this process.

https://setuptools.pypa.io/en/latest/deprecated/commands.html#egg-info-create-egg-metadata-and-set-build-tags

Is there another way to build a wheel package with a build tag with setuptools?

[abravalheri]

Hi @gh-andre,

Is there another way to build a wheel package with a build tag with setuptools?

The short answer is no. Currently, the only way is via egg_info settings (either in the setup.cfg file or as CLI arguments in the way you described). If you would like to contribute with PRs to improve this, we can discuss the feature. There are tools that automatically add "fixed format" build info, e.g. setuptools-scm and bump2version (see https://github.com/c4urself/bump2version/blob/master/RELATED.md), but those might not offer the flexibility of arbitrary tagging schemes.

---

Regarding the problem you are facing, I can see in PEP 440, the version must be in the following format:

<public version identifier>[+<local version label>]

Please note that:

• 123.abc cannot be part of a public version identifier. So that is why you need a local version.
• The local version is always the last segment in the version and it is subject to normalisation (as the entire version) - that explains why everything becomes the local version.

You can have a look on this regex for a short summary.

If you want to avoid local versions, you might be able to try something with .devXXX or .postXXX, but please note that you need to conform with an specific format. These don't simply allow free string annotations.

[gh-andre]

@abravalheri

Thanks for responding. I'm using this functionality for tracking build maturity, so I'm specifically looking for being able to generate a build tag in binary wheel packages, so it is changing for the same version, as the quality of the build is maturing towards the release.

Such packages require specialized package repositories (e.g. Artifactory) and are not intended for public repositories, which is most of those version bumping tools are missing - CI builds are not supposed to change the version, which is planned by the Product Owner based on the level of changes. Once a release is made, then the build tag can be dropped and the released package may be submitted into a public repository.

So far I only found setuptools to provide the functionality to generate build tags, even though it ends up to be a local version, which is really intended for downstream package maintainers. I guess I'll keep looking.

Thanks for the insights. Much appreciated.

[abravalheri]

Thanks for the brief explanation @gh-andre.

I am afraid that in Python packaging versions cannot be "free form". They should be compliant with a specific format, which still allows some level of build information, but not any arbitrary string. It is very likely that any other tool will perform the same validations...

Setuptools recently updated a library that we use for these validations, and that is why now we are more strict (this was done after a few years of deprecation warnings).

[gh-andre]

@abravalheri

Thanks again for your thoughts. It seems I made an impression that I'm trying to bend the meaning of the version, which is not my intent at all. I want to use version exactly as Python defines it, without even the local version, which in my current setup is a mere workaround based on the current outcome.

Python also defines the binary package nomenclature and the latter does allow a build tag, which is what I'm looking for, but having a hard time finding a tool that would generate build tags. Perhaps I could describe it better in that when I found --tag-build in setuptools, I was expecting that it would take the value supplied and produce a package with the build tag in it.

In other words, if I used --tag-build=123.abc, I was hoping to end up with this package:

setuptools_build_tag_test-0.1.0-123.abc-py3-none-any.whl

[gh-andre]

I spent a bit more time looking at the alternatives to generate wheels with build tags and didn't find any - all build backends I looked at seem to ignore build tags in wheel packages. One workaround I found is to repackage a wheel package with wheel and include the build number after the fact. Posting here in case if somebody finds this useful.

setuptools just concatenates the content of --build-tag with the distribution version, so it should not be used at all. That is, given this command for a distribution abc with version 0.1.0:

python3 -m build \
        --config-setting=--build-option=egg_info \
        --config-setting=--build-option=--tag-build=123 \
        abc

, it will create invalid version by concatenating 0.1.0 and 123 as text, which yields this package:

abc-0.1.123-py3-none-any.whl

Instead, I run a regular build without fancy options and then invoke wheel like this:

python3 -m build abc
wheel tags --build=123 abc/dist/abc-0.1.0-py3-none-any.whl

, which repackages the wheel as abc-0.1.0-123-py3-none-any.whl and updates internal files, such as abc-0.1.0.dist-info/WHEEL to include the build number.

The only missing bit for me is that wheel only understands the build number as a number and not as metadata, which is what the binary wheel format specification allows, so there is no way to add things like the branch name into the build metadata (e.g. abc-0.1.0-123.main-py3-none-any.whl) and something like a folder per branch, etc is required.