Amend PEP440 to limit version identifiers

PEP440 does not contain a limit for version ids. Can we please add one?

things like uselesscapitalquiz · PyPI happen without it, and other issues arise not least of which is user a11y related to trying to fit/show all of the wild versioning

stats from pypi:
we have 9.9mm releases, median version is 5 characters, 99th percentil is 20, and maximal is 217(!!)

I propose a 128 char cap, 100 would affect ~9 current releases some releases in the last months with ~110-115 char versioning which I honestly don’t understand but… whatever! 128 is fine.

refs:

9 Likes

In your PR you wrote:

Installation tools MUST NOT reject otherwise valid versions solely because they exceed this limit.

So I am confused where and how you want this spec to be enforced?

I also don’t think tools that currently limit version size, in some sense, are breaking the spec? For example uv’s current parser caps each non-local number component in a version to 264 - 2, I think that’s a reasonable tool choice (although they had at least two reports of users hitting this limit).

3 Likes

I have no real issue with adding a limit, but I do have a number of comments I’d make:

  1. I don’t imagine that pip, or any of the other projects I work on, would change as a result of this. There’s no benefit to us in enforcing, or even checking for, such a limit, and no-one has reported any issues with what we currently do. Even if they did, I’d be inclined to simply say “that’s a silly version number”, rather than go to any effort to support over-long versions.
  2. This feels like a technical solution trying to address a social problem. It’s a fairly simple technical solution, so I don’t mind doing it, but the underlying issue is that people aren’t respecting the spirit of our standards, and we should be addressing that (via social pressure, good practice guidelines, better education, etc.) rather than just playing whack-a-mole with people playing silly games.
  3. If we make this change, what happens to the existing projects? Are they somehow retroactively declared invalid? Will they be deleted from PyPI? Because if they remain, tools won’t be able to rely on the change anyway, they’ll still have to handle over-long versions, such handling will simply be “dealing with bad data” rather than “dealing with extreme edge cases”.

I think we’re too willing to accept “the standard allows it” as a justification for misbehaviour. Why isn’t it sufficient for PyPI to either just produce bad output, or replace the version with something like <unprintable version> when faced with data like this? And why can’t we simply say that projects with metedata that’s clearly not taking the standards seriously will get removed?

As a data point, I’ll note that Rust requires semver for version numbers, and the semver standard (based on a quick review of the spec) imposes no limit on the number of digits in a version component. So the project uselesscapitalquiz · PyPI linked above has a valid semver version. And yet, cargo rejects it as the “minor version” component is too big to fit in a u64 - a practical limitation, but not technically compliant with the standard. So it seems other communities are OK working with a “don’t be silly” attitude to issues like this.

Having said all that, and just to reiterate, I have no issue with making the proposed change (as long as the question of what gets done with existing projects gets resolved).

7 Likes

I’m not very fond of arbitrary caps, though setting a limit of uint64 (or even uint32) on each element would be have a practical benefit. If we added custom code to accelerate packaging’s version handing in CPython in C or Rust (something we’ve thought of in the past), it’s quite possible we might want to only implement uint64. Packaging code written in other languages, like the mentioned Rust handling, probably often make this limit too.

I don’t see packaging.version adding a check to the very, very performance sensitive code to limit it artificially in Python, however. Something like tools “MAY limit to uint64” or something like that likely would be fine (and a better reflection of the status quo).

6 Likes

I think we “SHOULD” have a limit on the max value of a version segment as {n}, and say that installation tools “MUST” support at least that length of version numbers’ release segments. I don’t think there should be a max limit specified for installers.

And… I don’t feel strongly between len(str(n)) <= 128 or n < 2**32 or n < 2**64. I think we need a limit to set expectations, given how this keeps popping up somewhat regularly.

Yea, reviewing the Semantic Versioning 2.0.0 | Semantic Versioning – there’s no relevant limit here.

3 Likes

FYI, here are real issues where people may exceeded uint64 or hit arbitrary limits:

I don’t personally think it needs an update, but it tool/infrastructure/library authors think it needs a clarification, I think it’s fine to add that tools may reject versions based on their size of individual components or the entire version. And that can be either character limits or byte limits, whatever makes sense for the tool, I think what the limit is is different for different contexts and I’m not sure it makes sense to be explicit in the spec.

In my head the limit would only apply when publishing new releases (rathr than when installing existing releases), not installing so that isn’t really worded in a way to reflect the enforcement point well.

i don’t think it’s wise to have enforcement from the installer to reject a version (not allow install) because it exceeds the (proposed) 128 characters

To me, this doesn’t seem like it needs to be in the spec. PyPI can set the policy of a 128 maximum characters and give a useful error message when/if users hit it.

What’s the concern about the spec?

5 Likes

Looking at the current text in the PR for this proposed change:

Version identifiers for new releases MUST NOT exceed 128 characters after :ref:normalization <version-specifiers-normalization>, including any local version label.

Installation tools MUST NOT reject otherwise valid versions solely because they exceed this limit.

I feel like this is exceedingly strict. I’d prefer softer language along the lines of:

Public version identifiers SHOULD NOT exceed 128 characters after :ref:normalization <version-specifiers-normalization>.

Installation tools MUST accept versions with a public version identifiers of at least 128 characters.


I intentionally removed the local version segment from the limits – that is meant for use outside of public indexes, and I don’t think there’s any good reason for us to place limits on them given the motivations we have for adding the restrictions currently.

3 Likes

I’m fine with doing that, too! I just asked around during the core dev sprint and thought it might be beneficial for a reasonable limit to be had for all.

As a matter of policy we will probably limit them in warehouse going forward so I’ll close my open issues/PR :slight_smile:

2 Likes

This is my view as well. PEP 440 has lots of permissive elements that are there to tolerate the variety that already existed on PyPI when we wrote it, but there’s a collective benefit over time if publishing tools and index servers impose reasonable limits for future releases in the interests of improving general ecosystem usability.

3 Likes

I think this kind of thing is exactly what specs / standards are for — aligning tools on what they should and should not support. That way you don’t have weird discrepancies where PyPI accepts a certain length of version and pip rejects it or build backends produce it and it only fails at update, etc.

9 Likes

Great, and fyi, I wasn’t trying to be defensive or call you out here, in case I came across that way.

We’ve had a lot of issues with this spec in the past around interpretation and minor changes. So I’m wary of adding language for specific use cases, especially when no existing language prevents you from applying limits that make sense for your use cases.

1 Like

I didn’t take it that way :slight_smile: I just didn’t want to make a bunch of people mad if it shouldn’t be solely a policy decision and also try and bring along tools if possible, like Paul mentioend:

1 Like

That’s fine, but the PR in it’s inception explicitly created a split between installers and other tools: Set a limit on version identifiters for new releases by JacobCoffee · Pull Request #2163 · pypa/packaging.python.org · GitHub

Version identifiers for new releases MUST NOT exceed 128 characters after
:ref:normalization <version-specifiers-normalization>, including any local
version label.

Installation tools MUST NOT reject otherwise valid versions solely because
they exceed this limit.

This kind of tool split is especially hard for libraries like packaging which have to serve both installers and other tools.

Further, we’ve put a great deal of effort into the performance of constructing a Version objects in packaging. Implementing a rule like this would add significant cost, we would have to create a string normalized form and test it’s length every construction. During a large resolve of requirements, a Python package dependency resolver might construct millions of Version objects. So I would be strongly -1 on this particular type of limit for all tools.

And I don’t think it should be surprising to users when publishing to a hosted service like PyPI that there exists some limit on name lengths and version lengths. The same is true for distribution size and project size, users can make arbitary large wheels locally, but they shouldn’t be surprised when they can’t use PyPI to backup their 8 TB hard drives encrypted as wheels. Likewise I could make a 10 MB reply to this post in a local markdown file, but I shouldn’t be surprised for DPO to refuse it.

2 Likes

My 2c on vane-extension-avro 0.2.0.0.0.0.0.0.4.0.0.0.1.0.479461690.1185714868.1255361793.351122130.3816423014.3324815424.3683476377.302257264… that’s already beyond reasonable.

For comparison, Docker image tags are limited to 128 chars, and commonly include a crypto checksum, while the digest is sha256:<64 chars>.

In the Docker universe, it’s common to make an image with an ephemeral tag, push to the registry, run the CI, and then re-tag that very image with a human-readable name if the tests pass.

There’s no provision for such workflow at PYPI, is there? AFAIK there’s not, apart from the vnd-pypi-http-fetch allusion in PEP-694.

This also means that it would be quite justifiable to make the limit shorter, say 32 chars.

The limit can always be increased later.

I would also eagerly support proactively cleaning out useless junk from PYPI, e.g.:

https://pypi.org/project/zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz/
https://pypi.org/project/0-._.-._.-._.-._.-._.-._.-0/
https://pypi.org/project/01d61084-d29e-11e9-96d1-7c5cf84ffe8e/

Extrapolating that to packages with silly versions, I’d be more than fine to nuke those too.

1 Like

I think that just means multi purpose libraries like packaging should stick with the actually common behaviour: not enforcing the optional limitations.

Setting an overall character limit on the unparsed version or a value limit on the individual numeric fields isn’t the kind of complicated logic that needs to be handled by a shared implementation.

Great, but if that’s the the case, this doesn’t seem like a standard? And if not let’s not go through the pains of carefully defining when it is and isn’t supposed to apply, and just let tools pick sensible numbers for their use case.

1 Like

Checking for precedent, probably the closest we have are:

  • recommending against allowing local version identifier segments on public index servers
  • the admonition for index servers to disallow multiple releases with equivalent versions (implicitly vs consuming tools arbitrarily picking one, but that isn’t spelled out clearly)
  • the distinction between direct URLs being a valid version specifier and them being an appropriate version specifier (including disallowing them entirely on PyPI)

It would likely make sense to use a softer “MAY” (rather than “SHOULD”) at the standard level, since the intent is more to document a permission for projects with a focused role like warehouse rather than to create an obligation for multi-purpose projects like packaging.

1 Like

If we combine that with a minimum requirement (say 20 characters, to catch the 99th percentile on PyPI) then we have the assurance @pganssle was looking for (“to avoid weird discrepancies, stick to 20-character versions or less”) while not having to deal with invalidating existing projects or imposing validation costs on code that doesn’t need it.

2 Likes