[Documentation] Install with pipx

[lwbt]

What's missing?

I want to suggest pipx as another alternative installation method to add to the documentation/README.md and probably the new default installation method.

Your solution

It could be as simple as:

pipx install puddletag

# To run puddletag, it should be on you PATH now:
puddletag

And that works well. When you know your way around Linux/FOSS and Python. More complete instructions would look like this:

# Linux installation of pipx taken from https://pypa.github.io/pipx/installation/
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# Install Puddletag
pipx install puddletag

# Improve desktop integration with shortcut and icon
mkdir -pv "$HOME/.local/share/"{applications,icons}
ln -sv "$HOME/.local/pipx/venvs/puddletag/share/applications/puddletag.desktop" \
  "$HOME/.local/share/applications/"
ln -sv "$HOME/.local/pipx/venvs/puddletag/share/pixmaps/puddletag.png" \
  "$HOME/.local/share/icons/"

# You can run in from the command line, but it should have a functional icon
# like any other app in your app drawer now.

Upgrading to a newer version is as easy as:

pipx upgrade puddletag

Or if you want to upgrade all the other tools you installed with pipx to do pipx upgrade-all. When you switch to a newer Python version (e.g. distribution release upgrade), do pipx reinstall-all.

Any alternatives?

Well there was Flatpak support which had been discussed and declined: #735

Someone is publishing a snap, not sure if that is official, but as an Ubuntu user who also uses other Linux systems like Steam Deck, the best outcome for Snapd seems to be that it will be successful on Ubuntu while every other Linux distribution seems to avoid it in favor of Flatpak or other mechanisms (static binaries, AppImage, or pipx).

Anything else?

It's apparently meant to be for CLI utilities (also supports generating Shell Completion for tools) but it works surprisingly well with Puddletag so far (I loaded up a few files and added a comment to the comment field of an album, but Puddletag worked well in a venv before and this is no different, just easier). I heard about it in talkpython.fm some time ago, but it took until today for me to look into it, because my experience with Python and Pip had been messy in the past and I'd thought it would be a nice to have that is still super complicated to implement and convince maintainers to do so. But was very simple as you can seem.

I wish you all the best for your holidays.

[sandrotosi]

i think we wrote README.md installation section before we started publishing puddletag to PyPI. so what i think we should advertise it to use pip (i dont think there's any advantage is advertising pipx) to install puddletag

[corubba]

I didn't know about pipx before, but it's a longstanding recommendation not to install packages globally with pip install, and pipx provides a easy way to apply that. If nothing else, I like the core idea and can see the value for users. I haven't used it myself, but at the end of the day it is a wrapper around pip and venv, so I am optimistic and inclined to believe that breakage is rather unlikely. Pending any disastrous findings during a future validation, I have no argument against not at least mentioning it and allowing the user to make an (hopefully informed) decision. But the same policy as with Flatpak applies: no special treatments or workarounds, it has to work with the normal (python packaging compliant) PyPI package. If it turns out to be a trouble maker, we always have to option to remove it from our docs again.

And since we touched the topic of installation docs: I think the distribution packages should still be the first choice. The packagers take care of any distro specifics, and users can easily install and run it; plus it gets automatically updated (in most cases), and the .desktop file and logo is put in the right place. Sure we get the occasional issue with distro-specific problems, but from a user-perspective this is as comfortable as it gets; install and forget. And yes, some distros can take a bit to include a new version, but as long as it is working and doing its job, the average user won't care if it's v1.1 or v2.

If for some reason the distro-package isn't working or you want to use a newer version, the PyPI package should be next choice. At the very least I would provide instructions to install via pip in a venv, with a link to some informational resource explaining why global pip install (without a venv) is not recommended. And follow that by a note offering pipx as a equivalent but "easier" alternative to the manual setup, using the one-liner and a link to the pipx docs for further reading. If you want to be super-conservative include something along the lines of "pipx should work most of the time, if something goes wrong please also try the pip+venv way." Both have to come with a disclaimer that the user will need to keep it up to date themselves.

And lastly, for those seeking the absolute bleeding edge or wanting to contribute, instructions for a git checkout and venv setup with requirements. This a nice thing to have to easy participation, and also to point user to when asking to test a bugfix or feature. I was never fond of and would drop the git plus distro-dependencies variant.

[sandrotosi]

I decided to go with

1. pypi
2. distro pkgs
3. source code

we'll see what reactions (if any) that'll bring, but i think advertise pypi first makes sense, given we immediately release there while with distro pkgs there's always a delay (in particular close to their releases, like it's happening now in Debian)