Document use of distutils/index-server for managing API tokens

[ryanlovett]

Your Environment

1. Your operating system: Ubuntu 20.04

2. Version of python you are running: 3.8.3

3. How did you install twine? Did you use your operating system's package manager or pip or something else? conda

4. Version of twine you have installed (include complete output of):

% twine --version
twine version 4.0.1 (importlib-metadata: 4.8.2, keyring: 23.4.0, pkginfo:
1.8.1, requests: 2.28.1, requests-toolbelt: 0.9.1, urllib3: 1.26.4)

5. Which package repository are you targeting? jupyter-rsession-proxy

My ~/.pypirc:

[jupyter-rsession-proxy]
  repository = https://upload.pypi.org/legacy/
  username = __token__
  password = {omitted}

[pypi]
  username = {omitted}
  password = {omitted}

The Issue

I'm trying pypi api tokens for the first time. I created one and created a section in ~/.pypirc, however twine isn't seeing it:

% twine upload dist/* -r jupyter-rsession-proxy
ERROR    InvalidConfiguration: Missing 'jupyter-rsession-proxy' section from
         ~/.pypirc.
         More info: https://packaging.python.org/specifications/pypirc/
% grep jupyter-rsession-proxy ~/.pypirc
[jupyter-rsession-proxy]

I was only able to upload by replacing [jupyter-rsession-proxy] with [pypi] in the config file, commenting out the normal [pypi] section, and then omitting -r jupyter-rsession-proxy from the command line arguments.

This issue resembles #564, though my ~/.pypirc definitely exists.

[sigmavirus24]

You found the right issue which should have led you to https://github.com/pypa/twine/issues/496#issuecomment-578461036 which I believe contains the fix you want

[ryanlovett]

@sigmavirus24 That worked great, thanks! I added:

[distutils]
index-servers =
    pypi
    jupyter-rsession-proxy

and twine worked. I'll turn this into a documentation issue in case docs help people in the short term. It seems like #496 touches on the larger topic of the best way to implement it.

[ryanlovett]

So just a request to add this helpful tip to the docs.

[bhrutledge]

I think this should be covered by https://packaging.python.org/en/latest/specifications/pypirc/, which is linked from Twine's configuration docs:

Twine can read repository configuration from a .pypirc file, either in your home directory, or provided with the --config-file option. For details on writing and using .pypirc, see the specification in the Python Packaging User Guide.

I'd prefer for that document to be the authority for configuration, and not duplicate its content in Twine's docs. However, as a maintainer of Twine and packaging.python.org, I'm open to suggestions on how to improve the spec and/or refer to it from Twine.

[ryanlovett]

@bhrutledge I understand not wanting to duplicate authoritative information. In my case I needed to use multiple API keys, extrapolated a likely configuration, and failed. Then I used a search engine, came across one or two github issues about the issue, and still failed. If this is down to me just being impatient, failing at internet-fu, or just plain RTM, then please ignore. If it seems like sufficient number of people are running into this, then maybe change "see the specification" to "see the specification and examples" in the docs?

[bhrutledge]

If this is down to me just being impatient, failing at internet-fu, or just plain RTM, then please ignore.

I don't think this is a failure on your part. I think Twine's docs could be more descriptive about why one might to use a .pypirc (e.g. multiple repositories and/or tokens). Also, the .pypirc specification doesn't explicitly mention multiple tokens, but it could. Do you think one or both of those would have helped you?

[ryanlovett]

The "using another package index" example should have been enough. The more I see now, the lazier I was then.

[sigmavirus24]

No need to be harsh on yourself. We're not trying to imply you were being lazy, just that we weren't looking at different things than you were to find the information. Different things can make it hard to find information we need when we need it and I think we'd like to understand what might have been helpful if it has we're different for you because that might help someone else