User not warned/informed about version normalization

[buhtz]

setuptools version

latest

Python version

3.9.2

OS

GNU/Linux Debian

Additional environment information

No response

Description

I was redirected from this pip issue into here. Not sure if I'm correct here. There is also an Issue about the topic in the SemVer repo.

In my pyproject.toml I specified the version that way.

[project]
name = "Hyperorg"
version = "0.0.0-a7"

Please note that there is a - between major.minor.patch (0.0.0) and the pre-release (a7).
But when installing that package the - is ignored and the version converted into 0.0.0a7.

Defaulting to user installation because normal site-packages is not writeable
Obtaining file:///home/user/ownCloud/my.work/hyperorg
  Installing build dependencies ... done
  Checking if build backend supports build_editable ... done
  Getting requirements to build editable ... done
  Installing backend dependencies ... done
  Preparing editable metadata (pyproject.toml) ... done
...
Building wheels for collected packages: Hyperorg
  Building editable for Hyperorg (pyproject.toml) ... done
  Created wheel for Hyperorg: filename=Hyperorg-0.0.0a7-0.editable-py3-none-any.whl size=28823 sha256=1583ed9065e32d744de48aa238573ba73261847f21f6f2392b14531e41ed270b
  Stored in directory: /tmp/pip-ephem-wheel-cache-40fuuce2/wheels/5f/2b/4e/da5701aa1703d6fcd24e8e2650399fa8b7b0f51407e60776c6
...
Successfully installed Hyperorg-0.0.0a7

$ cat pyproject.toml | grep a7
version = "0.0.0-a7"

You can see in the output of pip that the version number used is different from the number I specified in my pyproject.toml.

Please note that this breaks Semantiv Versioning. The hyphen is mandatory. I'm aware of thhe paragraph in PEP440 mentioning this exception.

Expected behavior

I'm sure there are reason why you do it that way.

But you have to inform the users when modifying a specification he made in its pyproject.toml. This should throw a warning when you take the version string and modify it.

How to Reproduce

s.o.

Output

s.o.

[abravalheri]

Hi @buhtz, I will reclassify this issue as a FR because my understanding is that setuptools is working as intended (it follows the specs) and you would like to propose a change in behaviour to be implemented.

In principle, I am (personally) against using a warning because it has the potential of breaking many CI setups (it is a common/recommended practice to set PYTHONWARNINGS=error in CI envs). Since the standard specifies version normalization, there are people that might be relying on this feature.

Something that could be done is to print an informative message for the user. If you or any other member of the community is interested in this direction, I think the best way forward would be submitting a PR.

[buhtz]

I'm against re-classifying this Issue as a FR. If you see a FR please open a new one and link them.

In principle, I am (personally) against using a warning because it has the potential of breaking many CI setups (it is a common/recommended practice to set PYTHONWARNINGS=error in CI envs).

I don't see how a message on "stderr" would break "many CI setups".

It is a bug because setuptools does silently modifies what the user specifies.

Since the standard specifies version normalization, there are people that might be relying on this feature.

This is OK for me and I assume there are good reason why setuptools does not allow hyphens at that position. But the wish of the users need to be respected in a way to inform him that his wished specs are not able to fulfill by the tool he choose.

[abravalheri]

Hi @buhtz,

I don't see how a message on "stderr" would break "many CI setups".

I agree that a message on stderr will not break any CI. This is exactly what I am agreeing in the phrase something that could be done is to print an informative message for the user.

Another completely different different thing is to use Python warnings system. If using Python warnings system, any CI setup that (correctly) uses PYTHONWARNINGS=error (or an equivalent via -W or pytest) can potentially break unfairly (because the expectation set is that the version is parsed and normalised).

Right now I am trying to do some issue triaging. So I would like you to kindly cooperate in the classification of the issue. But please feel free to submit a PR implementing the change requested.

[buhtz]

OK, there was a misunderstanding. I interpreted your "print" as print() which goes to stdout.
Maybe logging.warning() (goes to stderr) is a good choice?

I'm not familiar with the warning system of Python.

[abravalheri]

Yeah, logging.warning() sounds like a good alternative.

[buhtz]

Additional information:
Also using a dot (like version = "0.0.0.a7") is transformed into 0.0.0a7.

But in [PEP440])[https://peps.python.org/pep-0440/#semantic-versioning) it was mentioned as a workaround to replace the - with a ..

[abravalheri]

Hi @buhtz, PEP 440 says that . are normalized in the same way as -:

Pre-release separators
Pre-releases should allow a ., -, or _ separator between the release segment and the pre-release segment. The normal form for this is without a separator. This allows versions such as 1.1.a1 or 1.1-a1 which would be normalized to 1.1a1.

PEP 440 suggests using .dev to workaround semantic version (probably requiring some post-processing, I am not sure how this would look like, but definitely not 0.0.0-a7):

One possible mechanism to translate such semantic versioning based source labels to compatible public versions is to use the .devN suffix to specify the appropriate version order.

The PEP also says:

Semantic versions containing a hyphen (pre-releases - clause 10) or a plus sign (builds - clause 11) are not compatible with this PEP and are not permitted in the public version field.