Introduce pipx pin and pipx unpin commands

[dukecat0]

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

Summary of changes

Introduce pipx pin and pipx unpin commands, which can be used to pin or unpin the version
of an installed package, so it will not be upgraded by pipx upgrade or pipx upgrade-all.

Closes #891
Closes #802

Test plan

Tested by running

nox -s tests-3.12

[chrysle]

Thanks for submitting this! I wonder whether it would be a valid use case to extend this behaviour to work with injected packages, too?

Another idea: Provide protection from removal for a pipx-installed package by pipx pin via an option.

[dukecat0]

I wonder whether it would be a valid use case to extend this behaviour to work with injected packages, too?

That sounds like a good idea! Probably I will add a new option for it.

Another idea: Provide protection from removal for a pipx-installed package by pipx pin via an option.

Not sure if it's a common usage, but we can add it in the future if there are requests about this.

[dukecat0]

I wonder whether it would be a valid use case to extend this behaviour to work with injected packages, too?

I am implementing the logic of --injected-packages-only and it will only pin injected packages only instead of main package. (As running pipx pin <package> should prevent both main package and injected packages from upgrading during pipx upgrade-all --include-injected.)

[chrysle]

I am implementing the logic of --injected-packages-only and it will only pin injected packages only instead of main package.

Sounds good. You don't think one should be able to select which injected package to work with?

[dukecat0]

Yes, forgot to mention it in the above comment. 😅 I will mark this PR as draft first.

[dukecat0]

The failed test seems unrelated to this PR.

[huxuan]

The failed test seems unrelated to this PR.

Rerun makes everything OK. :-)

[kpfleming]

This feature was included in the 1.6.0 release but the documentation appears to be incomplete. When I run pipx --help then 'pin' and 'unpin' are included in the command list but don't have descriptions:

subcommands:
  Get help for commands with pipx COMMAND --help

  {install,install-all,uninject,inject,pin,unpin,upgrade,upgrade-all,upgrade-shared,uninstall,uninstall-all,reinstall,reinstall-all,list,interpreter,run,runpip,ensurepath,environment,completions}
    install             Install a package
    install-all         Install all packages
    uninject            Uninstall injected packages from an existing Virtual Environment
    inject              Install packages into an existing Virtual Environment
    upgrade             Upgrade a package
    upgrade-all         Upgrade all packages. Runs `pip install -U <pkgname>` for each package.
    upgrade-shared      Upgrade shared libraries.
    uninstall           Uninstall a package
    uninstall-all       Uninstall all packages
    reinstall           Reinstall a package
    reinstall-all       Reinstall all packages
    list                List installed packages
    interpreter         Interact with interpreters managed by pipx
    run                 Download the latest version of a package to a temporary virtual environment, then run an app from it. Also compatible with local `__pypackages__` directory (experimental).
    runpip              Run pip in an existing pipx-managed Virtual Environment
    ensurepath          Ensure directories necessary for pipx operation are in your PATH environment variable.
    environment         Print a list of environment variables and paths used by pipx.
    completions         Print instructions on enabling shell completions for pipx

They also don't appear in the online docs at https://pipx.pypa.io/stable/docs/ except (again) in the list of subcommands, but without descriptions of their behavior or entries in the table of contents.

[dukecat0]

This was fixed in #1438.