Publish: Docs for using the keyring

[konstin]

While publishing from CI is clearly the better choice, for smaller projects it may just not be worth the effort, so we also support publishing from a local machine.

We don't support .pypirc, the non-standard file that saves password as plaintext to the user home. Instead, we recommend using the keyring for local publishing, using the operating system's much more secure, mostly standardized and better queryable credential store as backend. This comes with the catch that the keyring keys by URL+username, so we need to use the horrible query string attach to tag per-project scoped tokens to a more specific URL (pypa/twine#565).

Fixes #7963

[cthoyt]

Given that the ?PACKAGE_NAME suffix is a hack, I think it would also be beneficial to include in this guide the fact that you can have a single token for all publish URLs, and adding the hack is only an optional security precaution that allows you to have different tokens for different packages. I would suggest also including a section that says something like:

If you don't need the added security of scoping tokens to single packages, and instead use one token for all packages, you can use the following:

keyring set 'https://upload.pypi.org/legacy/' __token__

Then you can publish with:

uv publish --username __token__ --keyring-provider subprocess --publish-url 'https://upload.pypi.org/legacy/'

[cthoyt]

Not to open up another can of worms, but what makes something standard or not? the .pypirc file is well-documented by the PyPA under its specifications list at https://packaging.python.org/en/latest/specifications/pypirc/

[zanieb]

.pypirc is documented by the PyPA but isn't really a standard specification (i.e., no PEP) and the PyPA is warning people not to use it. Please use #7676 for discussion on that topic.

[konstin]

Personally, I find it misleading that .pypirc is in the specifications section of packaging.python.org next to the actual authoritative specs. As zanie said it has no PEP, it was added pypa/packaging.python.org#734 and it's a user guide and not a specification. The only mention in a PEP is a 2002(!) extension to distutils: https://github.com/python/peps/blob/0bb65f91d0eb1b087eee1c61d2bc446f421ab032/peps/pep-0301.rst?plain=1#L233.

I'm focussing the guide on security best practices, such as using the keyring with least-privileged tokens.