This relates to the broader discussion I opened here: https://discuss.python.org/t/2fa-usability-on-pypi-and-with-packaging-tools/38167/7

Here are some hatch-specific pain points IMHO:

• the docs do not mention 2FA or token-based authentication, leaving me in the dark
• hatch publish --help, similarly, did not help either, which left me dumbfounded
• the "credentials" prompt that hatch publish prints is not descriptive enough: is it expecting a password? something else? is it to safe to paste a secret in that prompt, or not?
• the __token__ special username should IMHO be considered an implementation detail of the PyPI REST API, not something that users should be facing, since it's relatively obscure

Ideally, when trying to upload using hatch publish, I should have the following user experience:

$ hatch publish
repository username: ...
repository password: ...

ERROR: two-factor authentication is enabled for username 'username' on repository 'URL'.
Please ensure an API token exists for this project and then use `hatch publish --token-auth`.

$ hatch publish --token-auth
API token for project: ...

@ofek @jeanas

hey @pitrou i'm workign through this now too - we are creating some tutorials on publishing using hatch. It seems like running

hatch publish -u __token__ works and then you simply provide the token Did that accomplish what you need? i'm thinking about adding a how-to on this to the hatch docs (just a small contribution) as it was unclear to me too how to ensure hatch authenticates via a token rather than a username.

i think for me what was confusing was when i ran hatch publish it asked for the username but then said [TOKEN] and i wasn't sure what that meant. so specityying -u __token__ seems to work

did that work for you?

Hi @lwasser

hey @pitrou i'm workign through this now too - we are creating some tutorials on publishing using hatch.

Thanks for writing these tutorials, however it would be much nicer if the hatch UI was improved, or at least if its own docs included such instructions.

It seems like running hatch publish -u token works and then you simply provide the token Did that accomplish what you need?

Normally, yes, -u __token__ should work AFAIU.
However, I've been using twine instead, and I haven't had the need to publish a package recently, so I can't concretely confirm.

i hear you. i suspect a docs enhancement would be really helpful here and a lower lift. our tutorial work is totally separate from hatch i'm just noting painpoints and where docs might be useful in case i have bandwidth to help a bit here too! :)

I can confirm that -u __token__ worked for me. The first time I used hatch I used a username that then got cached. At some point I got annoyed to specify the __token__ each time and found out that it is possible to change some config file (can‘t remember where). Now, a simple hatch publish is enough.

Conclusion: Improving the already good documentation would be very helpful.

Documentation was improved in #789

Is there anything else that needs doing here?

Thanks for this! It's certainly more descriptive and detailed, but I'm surprised it does not seem to explicitly mention two-factor auth anywhere (*). While API tokens are mentioned, it does not explicitly say how to use them with hatch (some guesswork from the user might suggest they work together with the __token__ special value, though).

Perhaps I'm overdoing this, so feel free to ignore ;-)

(*) a quick grep suggests the word "factor" does not appear once under https://github.com/pypa/hatch/tree/master/docs .

Sure, I can talk about that!

I'm hitting this just now - I have no clue how to use a newly obtained token. I keep getting prompted for my password to keyring (on macOS) and then pypi tells me password based authentication is no longer supported.

I have a ~/.pypirc but it seems to be ignored by hatch, or at least I don't know how to get it used.

Workaround for now is to do: hatch publish -u __token__ and then supply the token interactively when prompted. I'd love to be able to just do hatch publish again though.

Ah, potentially hatch publish --initialize-auth does it. Maybe worth a try.

hey there everyone ! i'd love a review if someone wants to have a loo at this pr that just tweaks the auth pages. i left some questions in the pr as well as i found that hatch didn't seem to recognize my auth info in the toml file as it said it might. but it did actually find my pypirc file. @corneliusroemer this is different from your experience!

Perhaps we can use this pr to better clarify what behavior users should expect? ✨