I went down a rabbit hole today with poetry Issue 7047 (hyperlink removed due to 2 link limit for new users) That more or less arose due to (what i feel was) ambiguity inside the PEP 440 spec. The core of issue was that PEP 440 was not IMO clear on how to handle ">=1.3.0" when only "1.3.0rc1" was available.
I read PEP 440 and understood that 1.3.0rc1 would be a valid solution due to it falling into the following category in #handling-of-pre-releases
accept remotely available pre-releases for version specifiers where there is no final or post release that satisfies the version specifier
However, the poetry maintainer had another understanding of the spec that I could find no fault with given the literal text of PEP 440. In summary they argued that 1.3.0rc1 was less than 1.3.0 and thus not a valid solution, however if no 1.3.0 existed but a 1.3.1rc1 did that would be a valid solution due to it being >=1.3.0.
There was some additional confusion here as tools like pip & pipenv considered 1.3.0rc1 to be a valid solution for >=1.3.0 whereas poetry did not for the aforementioned reason.
Request
In PEP 440 it makes the callout that
The versioning specification may be updated with clarifications without requiring a new PEP or a change to the metadata version.
Therefore Iâm asking that the pre-release / examples section in PEP 440 be updated to include several example(s) to illustrate the intent of the spec (one way or the other).
This matches my intuition when reasoning about versions, regardless of what the tools currently do. However, maybe the behavior (whether the rc1 satisfies the constraint or not) should depend on a flag, e.g. pip install --pre?
Thanks for confirming / reviewing. Would it be possible to include this or something very similar as an example in the PEP 440 section mentioned above?
As for the pip thing it certainly contributed to the confusion so I hope it gets resolved but if the example gets added it will help prevent some of that confusion.
Genenrally, once marked Final PEPs donât get updated. They are intended to be the historical record of the change proposal, discussion, and resolution, not the living documentation.
I would say that quote should not have been in the PEP in the first place. Everything should be going to PyPA specifications - Python Packaging User Guide at this point, and if a PEP hasnât been migrated over to there then itâs simply lacking someone to take the time to do it.
Moving PEP 440 to instead a âPython Version Specificationâ under packaging.python.org, and making PEP 440 prominently and consistently link to it would be great to have.