Add a `--prepend` option to the `pipx ensurepath` command

[agriyakhetarpal]

• [x] I have added a news fragment under changelog.d/ (if the patch affects the end users)

Summary of changes

Closes #1424.

This PR adds an option to pipx ensurepath, i.e., pipx ensurepath --prepend to allow users to prepend pipx-installed applications to the PATH environment variable rather than appending to it. This is disabled and set to False by default; it is only enabled if the user does pipx ensurepath --prepend (or its --force counterparts such as pipx ensurepath --force --prepend or pipx ensurepath --prepend --force). The implementation is through userpath.prepend, which is similar to userpath.append (see https://github.com/ofek/userpath#api).

Test plan

Tested by running

# command(s) to exercise these changes
pipx ensurepath --prepend  # or pipx ensurepath --prepend --force if already in PATH

This modifies my ~/.zshrc file on macOS accordingly:

# Created by `pipx` on 2024-05-20 14:27:49
export PATH="$PATH:/Users/agriyakhetarpal/.local/bin"

# Created by `pipx` on 2024-06-13 14:24:36
export PATH="/Users/agriyakhetarpal/.local/bin:$PATH"

Therefore, the latter entry from these changes has prepended pipx's installation location to PATH. The earlier entry is from an older pipx installation I had that had appended the location. I'm happy to add additional tests in an appropriate place in tests/ as necessary (though I notice that ensurepath doesn't have tests yet), and update the documentation (not sure where a mention of this would be best appropriate to add, though).

[agriyakhetarpal]

Thanks for this contribution. I think a quick note about this in the installation docs would be nice. Else lgtm.

Thanks for the review – addressed in 435173f45cd7fb71cbdbfd12f5b42740dfb1d179; I added a note to docs/installation.md, renaming the "Global installation" heading to "Customising your installation" as I felt that it was the best place to mention something related to pipx ensurepath, similar to the --global argument.

[chrysle]

Please rebase.

[agriyakhetarpal]

Done, @chrysle

[chrysle]

Thanks!