Add --format option to list command.

[comkieffer]

This flag controls how the output should be formatted. It accepts 3
possible values:

• human, the default value, uses the current output;
• freeze, prints the installed packages using a format similar to pip freeze (name==version).
• json: prints the complete details of the installed package in JSON

• I have added an entry to docs/changelog.md

Summary of changes

• change src/pipx/main.py to add the --format option
• change src/pipx/commands/list_packages.py to implement the new formats
• change docs/examples.md to add an example of the new functionality

Test plan

Ensure that the following commands produce the expected output:

The following command should produce the same output as the current version of pipx

$ pipx list 
$ pipx list --format human

The --format freeze option should list only installed packages and versions:

$ pipx list --format freeze

The --format json should list the complete details of the installed packages.

$ pipx list --format json
$ pipx list --format json --include-injected

[comkieffer]

I adopted the design that was suggested in #109 and #392

This seemed to make sense to me but I'm willing to change it if your thinking has changed since then.

[itsayellow]

Thanks for the PR. I'm currently really busy with other pipx-related activities, so if it takes a few days for me or somebody else to look at this, please be patient, we'll get to it. 🙂

[itsayellow]

Thanks for the PR! It's nicer to have contributed code than contributed wishes 😄

Some questions:

Since I'm not one who's been looking for this functionality, could you help me understand what the use case for this would be? How would this help a pipx user?

Could you give some example outputs of the human and json outputs, for pipx installations with at least a couple of installed venvs?

For the human format, it looks as though you are not showing both the "suffix" option for venvs, and the injected packages. I suppose this goes back to what the use case is--but is this desirable, or an oversight?

[comkieffer]

Thanks for getting back to this.

The main use case of the structured format is automation. My main use case is rebuilding by development environment. Being able to easily export a list of packages installed with pipx helps reduce the effort required to keep the solution up to date.

For the human format, I tried to stick to the existing output. It should be identical to the previous output. Any changes are definitely an oversight on my part.

I attached the output pipx list with bot the human and json on my local machine. The commands used are:

$ python src/pipx list --format json | jq > pipx-list.json
$ python src/pipx list --format human > pipx-list.txt

pipx-list.txt
pipx-list.json

[itsayellow]

Ok, in that case, I think the "freeze" format leaves out some information, such as:

• injected packages
• suffix (optional) for the venv
• Python version for the venv

Adding some or all of those back in would stop it from looking like output from pip freeze, but pipx is a different tool with additional information. I think at least the top 2 and probably all 3 are worth including. I'm imagining something still in "one-line-per-venv" format, perhaps something comma separated.

The question is if the "freeze" format is needed at all, given the absolutely complete "json" format. I suppose "freeze" could be useful for very primitive scripts, possibly shell scripts.

Another interesting option I just thought of would be a "script" output, which would just be the shell commands, e.g.:

pipx install pylint==2.1 --python 3.9
pipx inject pylint mypy==0.3

pipx install black==19.0b1 --suffix _old

etc.
Perhaps that's more useful than the "freeze" format?

The whole point of having pip freeze is because pip can actually import back a file containing the output from a pip freeze. Is what you're looking for really just pipx export / pipx import? Because I actually started working on that myself, the import is not too bad to implement.

[itsayellow]

And sorry, above when I asked about human, I really meant the freeze format. That other new format was really the one I was curious about, and seemed to be missing some information.

[uranusjr]

The question I haven’t seen asked throughout the discussion (including here and linked issues) is how the output is expected to be used. If it is supposed to be fed back into pipx (either directly or indirectly), maybe the best solution is to provide a pair of pipx freeze/pipx unfreeze commands. This way pipx can use whatever format that fits best (likely JSON) without worrying about interoperability. If the goal is to fed the output into something else (e.g. pip in a virtual environment), maybe the solution is to export multiple files, one with all top-level apps, and each additional file packages injected into an app. The point is that someone needs to explain the motivation, rationale, and specification first (like what you read in PEP documents) before a reasonable design can be reached and implemented.

[itsayellow]

The question I haven’t seen asked throughout the discussion (including here and linked issues) is how the output is expected to be used.

I literally just asked 3 comments ago "What's the use case?" 😆

He answered " My main use case is rebuilding my development environment." To which I suggested pipx export / pipx import which is another way of saying pipx freeze / pipx unfreeze.

[uranusjr]

But nobody went that route, and I assume people have reasons to prefer pipx list --format=.... It’d be nice if someone could explain why pipx list --format=freeze fits the use cases better than export/import.

[comkieffer]

That actually seems to be a better, more thought through option.

Do you want to close this PR and make an issue to discuss this further?

[itsayellow]

That actually seems to be a better, more thought through option.

Do you want to close this PR and make an issue to discuss this further?

Sure, especially if that's ok with you.

Again, thanks so much for actually taking the time to contribute code, we always appreciate it. In this case it just seems we need to more thinking on exactly how the functionality should work.