Separater for "pre-release version" #569

New Issue

2026-02-17T12:13:11-06:00

GiteaMirror commented

2026-02-17 12:13:11 -06:00

Originally created by @buhtz on GitHub (Jan 2, 2023).

I try to understand the SemVer 2.0 rule about pre-release version.

Let me cite the beginning of the first sentence of that rule

A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers ...

What is about the hyphen? Is it a MUST HAVE when specifying a pre-release version? So the "MAY" in that cited sentence only refer to the case that a pre-release version can but don't have to be specified?

I observed that Python/pip/setuptools to ignore the hyphen.

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

[project]
name = "Hyperorg"
version = "0.0.0-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.

How do you assess this situation in the context and from the viewpoint of SemVer? What is your opinion?

Originally created by @buhtz on GitHub (Jan 2, 2023). I try to understand the SemVer 2.0 rule about [pre-release version](https://semver.org/#spec-item-9). Let me cite the beginning of the first sentence of that rule > A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers ... What is about the _hyphen_? Is it a MUST HAVE when specifying a pre-release version? So the "MAY" in that cited sentence only refer to the case that a pre-release version can but don't have to be specified? I observed that Python/pip/setuptools to ignore the hyphen. In my `pyproject.toml` I specified the version that way. ``` [project] name = "Hyperorg" version = "0.0.0-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`. How do you assess this situation in the context and from the viewpoint of SemVer? What is your opinion?

GiteaMirror commented

2026-02-17 12:13:12 -06:00

@steveklabnik commented on GitHub (Jan 3, 2023):

the MAY there is referring to the fact that a pre-release version MAY or may not exist. If a pre-release version exists, it must have the hyphen.

I'm not familiar enough with pip to know if this is a bug or a true divergence from the spec.

@steveklabnik commented on GitHub (Jan 3, 2023): the MAY there is referring to the fact that a pre-release version MAY or may not exist. If a pre-release version exists, it *must* have the hyphen. I'm not familiar enough with `pip` to know if this is a bug or a true divergence from the spec.

GiteaMirror commented

2026-02-17 12:13:13 -06:00

@jwdonahue commented on GitHub (Jan 23, 2023):

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

Until PEP-440 Python had a long history of supporting just about any version number scheme you can think of. Your packaging tool in this case is working hard to accept as wide a range of inputs as possible and transform them to standard PEP-440. Despite many references in Python related docs, they don't really adhere to SemVer specs, except possibly for their interpretation of the version triple (M.m.p).

@jwdonahue commented on GitHub (Jan 23, 2023): > You can see in the output of pip that the version number used is different from the number I specified in my pyproject.toml. [Until PEP-440](https://peps.python.org/pep-0440/) Python had a long history of supporting just about any version number scheme you can think of. Your packaging tool in this case is working hard to accept as wide a range of inputs as possible and transform them to standard PEP-440. Despite many references in Python related docs, they don't really adhere to SemVer specs, except possibly for their interpretation of the version triple (M.m.p).