Documentation / configuration around publishing packages is very unclear

[michelcrypt4d4mus]

I'm a new user of poetry and I have found it to be a really great tool - feels like someone is finally figuring out a way to deal with the chaos of pip world. Many thanks for your hard work on this.

As a new user I found the documentation clear and the functionality intuitive up until the moment I went to publish my package to PyPi. The confusion started when I went to configure settings for the publish command. The docs say:

If you want to store your credentials for a specific repository, you can do so easily:

poetry config http-basic.foo <username> <password>

A lot of things are unclear here to a new reader:

1. Is this for a a repo called http-basic, foo, or something else?
2. If it's a repo called foo as I assume, what is http-basic all about?
3. I'm trying to configure a TestPyPi token not a username and password. How do I do that?

A little beyond that this section purports to help with pypi:

To publish to PyPI, you can set your credentials for the repository named pypi.
Note that it is recommended to use API tokens when uploading packages to PyPI. Once you have created a new token, you can tell Poetry to use it:

poetry config pypi-token.pypi my-token

Is pypi-token a kind of auth that's unique to pypi or would that work for TestPyPi as well? The way the docs are written it's unclear whether pypi-token is an important type signifier or just some random string. Is it a thing unique to pypi? If so, does it mean anything to a private repo or to TestPyPi?

All of this is very much running against "the principal of least surprise" to me. I feel like given the structure of the config key/value pairs, what would not surprise me would be if to set the token for a repo called testpypi that I set up with poetry config repositories.testpypi I had to run something like poetry config repositories.testpypi.token MY_TOKEN. poetry config pypi-token.testpypi not only seems to have nothing to do with a repo it also is seemingly backwards from how the hierarchy of a configuration would look.

Once I figured it out and ran poetry config pypi-token.testpypi pypi-TOKENSTUFFBLAHBLAH I would classify the fact that afterwards running poetry config --list shows nothing to me about the token I just configured as "surprising."

And while it's not as confusing, it's also sort of not a "least surprise" vibe to me that when I run

poetry config repositories.testpypi https://test.pypi.org/legacy/

and I end up with a setting in repositories.testpypi.url.

Hopefully that's helpful - I feel just a few small tweaks could go a long way towards making this section easier to parse for the next new user.

[dimbleby]

Not sure I follow all of that: but if you're up for it, then an MR would be a great way to clarify what you're asking for - and also to bring it a step closer to happening.

[michelcrypt4d4mus]

Sorry, what's an "MR"?

[dimbleby]

A merge request. I am inviting you to be the change you want to see!

[github-actions]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.