Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix: enhance existing authentication docs #1780

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
Open

fix: enhance existing authentication docs #1780

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
cd76f3f
fix: authentication docs
lwasser Nov 6, 2024
05bfa4b
Update with 2FA info
lwasser Nov 6, 2024
546e27b
fix: final edits
lwasser Nov 6, 2024
b452824
Update docs/how-to/publish/auth.md
lwasser Jan 22, 2025
31d6ed0
Update docs/how-to/publish/auth.md
lwasser Jan 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 31 additions & 10 deletions docs/how-to/publish/auth.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,32 @@

----

The username is derived from the following sources, in order of precedence:
To publish to an index such as PyPI or TestPyPI you need two things:
lwasser marked this conversation as resolved.
Show resolved Hide resolved

1. The `--user` / `-u` cli option.
1. a username (e.g. `__token__` for PyPI)
lwasser marked this conversation as resolved.
Show resolved Hide resolved
2. a token value or other form of trusted authentication from the index (PyPI)
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
2. a token value or other form of trusted authentication from the index (PyPI)
2. a password, token value or other form of trusted authentication for the package index



!!! warning "PyPI requires 2FA"
PyPI now requires 2-factor Authentication (2FA) for all publication processes. Be sure to set this up before proceeding with publishing your package to TestPyPI or PyPI.

## Storing your PyPI credentials

You can chose to either enter your username when using `hatch publish` or you can store it.

Your PyPI username is derived from the following sources, in order of precedence:

1. The `--user` / `-u` cli option. e.g. `hatch publish -u __token__`
2. The `HATCH_INDEX_USER` environment variable.
3. The [`repos` tables](../../plugins/publisher/package-index.md).
4. The [`~/.pypirc` file](https://packaging.python.org/en/latest/specifications/pypirc/).
4. The [`~/.pypirc` file](https://packaging.python.org/en/latest/specifications/pypirc/) which is also the default file used by Twine to publish to PyPI.
5. The input to an interactive prompt.

As a fallback the value `__token__` is applied.
If you don't provide a username, the value `__token__` is used by default.

### Password / credentials

The password is looked up in these:
Your password or credential value is looked up in the following places and in this order of precedence:

1. The [`~/.pypirc` file](https://packaging.python.org/en/latest/specifications/pypirc/)
if the username was provided by it.
Expand All @@ -22,10 +37,16 @@ The password is looked up in these:
5. A variety of OS-level credentials services backed by [keyring](https://github.com/jaraco/keyring).
6. The input to an interactive prompt.

If interactively provided credentials were used, the username will be stored in
[Hatch's cache](../../config/hatch.md#cache) and the password stored in the available
If you input your password and/or username into the interactive prompt when using `hatch publish`, then Hatch will store those credentials in
[Hatch's cache](../../config/hatch.md#cache). Your password stored in an available
[keyring](https://github.com/jaraco/keyring) backed credentials stores.

For automated releasing to PyPI, it is recommended to use ["Trusted Publishing" with OIDC](https://docs.pypi.org/trusted-publishers/)
(e.g. PyPA's [`pypi-publish`](https://github.com/pypa/gh-action-pypi-publish) GitHub Action)
or per-project [API tokens](https://pypi.org/help/#apitoken).
!!! note "Keyring storage"
By default Hatch tries to store your authentication credentials in a keyring application. For the time being, this means that you may run into issues using Hatch Publish in a controlled environment such as GitHub codespaces. In this case, you may want to use Twine to publish.

## Use trusted publisher workflows for automated publishing

If you wish to automate your release workflow, we recommend that you use PyPI's ["Trusted Publishing" with OIDC](https://docs.pypi.org/trusted-publishers/). A GitHub Action supporting this workflow can be found
[`here: pypi-publish`](https://github.com/pypa/gh-action-pypi-publish).

While trusted publish approach is preferred, you can also use per-project [API tokens](https://pypi.org/help/#apitoken).
9 changes: 5 additions & 4 deletions docs/publish.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,13 @@

-----

After your project is [built](build.md), you can distribute it using the [`publish`](cli/reference.md#hatch-publish) command.
After you have [built](build.md) your project's distribution files, you can distribute it using the [`hatch publish`](cli/reference.md#hatch-publish) command.

The `-p`/`--publisher` option controls which publisher to use, with the default being [index](plugins/publisher/package-index.md).
The `-p`/`--publisher` option controls which publisher to use (e.g. PyPI vs TestPyPi), with the default being [index](plugins/publisher/package-index.md).

## Artifact selection

By default, the `dist` directory located at the root of your project will be used:
By default, Hatch will look in your `dist/` directory located at the root of your project for your distribution files:

```console
$ hatch publish
Expand All @@ -19,7 +19,8 @@ dist/hatch_demo-1rc0.tar.gz ... success
https://pypi.org/project/hatch-demo/1rc0/
```

You can instead pass specific paths as arguments:
However, you can instead pass specific paths as arguments
to `hatch publish` if your distribution files are located somewhere else:

```
hatch publish /path/to/artifacts foo-1.tar.gz
Expand Down
1 change: 1 addition & 0 deletions hatch.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,7 @@ dependencies = [
"pymdown-extensions~=10.8.1",
# Necessary for syntax highlighting in code blocks
"pygments~=2.18.0",
"griffe<1.0",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(how) is this related to the proposed prose changes?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hey @funkyfuture i mentioned this to @ofek right now the docs won't build without this change in the hatch doc environment. I read it's a known issue. I think ofek wants to make the change separately / rebuild the environment. But if anyone wants to pull this down and build they will have issues without this change (or atleast that is what i discovered).

# Validation
# https://github.com/linkchecker/linkchecker/pull/669#issuecomment-1267236287
"linkchecker @ git+https://github.com/linkchecker/linkchecker.git@d9265bb71c2054bf57b8c5734a4825d62505c779",
Expand Down
Loading