So PyPI already supports validating these tokens, and just not generating the more complex varieties?
Yes, but not exactly. PyPI supports generating:
- tokens without restrictions,
- tokens with restricted to a single project for which the use has rights
And checking:
- tokens without a restriction (of course)
- tokens restricted to an arbitrary number of arbitrary projects (it just checks that the current upload is included in those projects)
A user doing a bit of reverse engineering, reading Warehouse code, OR using pypitoken can generate tokens in the slight gap between what Warehouse can generate and what Warehouse can verify, but this gap is really small.
For now pypitoken doesn’t add advanced restrictions yet. I’ve paved the way for those to be included but that’s all. As of today, switching Warehouse token generation to pypitoken would not add nor remove features. The fact that the lib exists as a local tool for users adds a few features to Warehouse (e.g. this) (they were already possible before but undocumented)
Your question did highlight some lack of clarity in the doc, so I’ve taken the opportunity to update this section.
Though I’d assume that integrating into Warehouse is more about UI? Presumably they can already add more caveats to when generating tokens easily enough.
The important parts of integration into Warehouse are:
- token generation: this part has the UI all done already
- token verification: this is the part where each type of restriction must be included. More precisely: if we use
pypitoken, Warehouse won’t need to know how tokens are verified, but it will need to provide the appropriate context needed for the verification, and the more restrictions we’ll implement, the more context Warehouse will need to provide.
And then there’s the step of adding restrictions. This one, as you noted, needs adding more UI. As of today, it’s expected that if we add new restrictions in PyPI, we need to add some UI to generate those restrictions, but with pypitoken, it’s not true anymore. You can generate a “full” token, and then apply restriction locally in a python shell or script. Of course, it’s possible to implement applying those restrictions in Warehouse directly through UI, but what used to be a requirement is now just a possibility.
I hope I’ve answered your questions, and thank you a lot for your kind message 
!