Reword, reorder or rework tool recommendations for application dependencies

[astrojuanlu]

Quoting @pfmoore in #701 (comment):

Very little of the discussion on this issue was actually about the maintenance status of pipenv, more about issues such as how alternatives should be presented, whether recommending pipenv is the right choice in the first place, etc. Those issues remain, but I think someone should open a new issue, with a concrete alternative proposal to start the discussion, rather than just continue debating on this issue.

The situation of Pipenv has changed a lot since the original concerns about the viability of the project were raised. However, I still found it weird to see it's the prominent recommendation, with pip, pip-tools, and Poetry as secondary alternatives. Why?

Disclaimer: I used Pipenv for some time while it was still maintained by Kenneth, then abandoned it in favor of pip-tools. Never used Poetry. I don't have a horse in this race, I just care about having good recommendations for newcomers and for my students.

• All tools have pros and cons, and Pipenv is no exception. My personal opinion is that Pipenv tradeoffs are not significantly better than the ones made by the other tools - but of course, this is one guy's opinion. I wonder if there has been some analysis (updated somewhat recently) of the merits of each tool, so it can justify this ordering and presentation.
• Pipenv relies on pypa/pipfile, a format that advertises itself as "a replacement for the existing standard pip's requirements.txt file". However, the README has a big WARNING: This project is under active design and development. Nothing is set in stone at this point in time., and the experimental nature of the spec is not in line with the privileged position of Pipenv in the tool recommendations. (This might of course be a problem with the README instead.) On the other hand, the proposal to make pip adopt it has been frozen for almost two years, and in fact, it hasn't received much attention, so it is to be expected that, for the short and medium-term at least, Pipenv will be the only tool to support this format.
  • This is a minor point for users, but it's a pain point for maintainers. If people keep using Pipenv, more people will ask applications and services to support pipfile. And if the spec is not maintained or it's experimental, it might not be very appealing to do so, in turn, frustrating Pipenv users. It's all a matter of setting the appropriate expectations.
• The Pipenv recommendation looks at odds with the venv/virtualenv recommendation. At least, according to the Python Guide, venv has to be used "in place of Pipenv", rather than alongside it.

With all these things in mind (which are all debatable of course), I think the recommendations should either:

• Present the tools in a more neutral way, that doesn't give one a privilege over the other. The downside is that people might want to "just use the tool that everybody else is using" and not willing to make decisions. Or,
• Sort the tools according to some up-to-date criteria. For example, as of June 2021 I personally find pip-tools to play along better with virtual environments, have simpler mechanics, and give continuity to the good ol' requirements.txt files. "Simplicity", and "compatibility with existing tools and standards" are possible criteria, but there might be others. Maybe Piptools or Poetry are better according to some other arbitrary dimensions, but we should make such dimensions more explicit regardless.

Thoughts?

[webknjaz]

That sounds reasonable. We need to be impartial so the neutral way looks like what we need.

[merwok]

If that’s useful, I have noted my personal pros and cons for some of the current tools here: Pylons/pyramid#3270 (comment)

Feel free to reuse any of that in a PR.

FWIW I still use virtualenvwrapper (which calls virtualenv which uses venv) rather than in-project virtual env (or installer-managed virtual env), pip-tools when I can, pipenv or poetry when I must. Strongly dislike that pipenv updates dependencies when you do another operation, it’s one of the bad ideas of npm.

[rbarrois]

I would be really interested in having a clean heuristic to decide whether a tool should be recommended or not; in my opinion, this would rely not on the tool's ergonomics / behaviour, but in its support for documented formats, approved PEPs, and APIs.

For instance, we could have:

1. A set of target standards; at this point in time, this would likely be python -m venv, wheels and pyproject.toml (maybe also something about exposing a common CLI for building projects into deb/rpm/pkgbuild formats?);
2. A set of currently mainstream standards; this might be virtualenvwrapper, wheels, setup.cfg, setuptools as the "recommended stack of yesteryear";
3. Other optional sets of standards, for in-development PEPs or long-term support environments ("Use these if you want to be compatible with RHEL 1.0"?)

Based on those, it would be possible to recommend tools that work best with both sets of standards, and clarify the potential limitations of other tools?

[wodny]

If that’s useful, I have noted my personal pros and cons for some of the current tools here: Pylons/pyramid#3270 (comment)

Nice. I thought of adding a table of projects with functions in columns like comparisons on Wikipedia. Possibly to Tool recommendations or Project Summaries. With some normalization of cells maybe, like:

• sourcing version - pyproject.toml, from source by regex, from source by import, from source by AST (with optional remarks like: via plugin)
• editable installs: yes/no
• manages virtual environments: no, in project's directory, in central directory
• supports PEP-517 as: frontend, backend, both
• supports PEP-621, [project] in pyproject.toml section: yes/no
• supports PEP-631, common dependencies spec. format: yes/no
• plugins support: yes/no
• supported layouts: src-layout, single package subdirectory, custom
• supports binary extensions: yes/no

I think that supported since version x remarks and references to commits/pull requests/issues would be useful as proofs and to check if a feature is still available (like: is non-PEP-517 project without setup.py supported - as an extreme example). Links to GitHub would be especially useful because of annotations about the issue being referenced somewhere else, possibly changing the functionality.

I've done a partial summary like that recently for work. I've used it once already when writing a comment concerning setuptools. Maybe I should transform my notes into a table and add it to the packaging docs? Do other people like tables?

[matthewfeickert]

👋 Based on a recent Twitter discussion I'd like to take a crack at opening a PR to address these points, but as this has been a discussion that has gone on for some time I'd prefer to get some PyPA maintainers consensus on an action proposal before working on a PR 👍 (once I'm back from vacation later this week). (So cc'ing @willingc, @jefftriplett, @brettcannon early on this given the Twitter discussion — as well as anyone else seeing this 🙂).

Thanks @astrojuanlu for opening this Issue, as I think it outlines a good plan. My suggestion is to do both (or rather one after the other):

With all these things in mind (which are all debatable of course), I think the recommendations should either:

• Present the tools in a more neutral way, that doesn't give one a privilege over the other. The downside is that people might want to "just use the tool that everybody else is using" and not willing to make decisions.

Presenting tools on a more neutral ground should(?) be easier to form a consensus on how to phrase things and doing one PR for that first would at least move the issue forward in an actionable way.

• Sort the tools according to some up-to-date criteria. For example, as of June 2021 I personally find pip-tools to play along better with virtual environments, have simpler mechanics, and give continuity to the good ol' requirements.txt files. "Simplicity", and "compatibility with existing tools and standards" are possible criteria, but there might be others. Maybe Piptools or Poetry are better according to some other arbitrary dimensions, but we should make such dimensions more explicit regardless.

I think that to the people that are actually using these guides the more information/recommendations on how the use cases they have align best with the tools available the better. So this seems useful. 👍 Though, to me, it seems like there is more nuanced discussion to be had here and any PR that satisfies this front would take longer to implement. If the recommendations on tooling have already been made more neutral in the first PR, then perhaps it would be easier for everyone to come to an agreement on how these recommendations should be split out/made (as some of the examples from other people in this Issue have already (helpfully!) shown).

Thoughts?

[brettcannon]

I think the key thing is to make sure the info is clear and timeless. So starting to make recommendations or full blown tutorials run the risk of going stale compared to listing known tools which have support and then linking to their tools.

Long term, I hope all the work we have been doing around standards like PEP 621 will make it easier to write one tutorial on how to specify stuff and then list the tools that support the specs.

[astrojuanlu]

pipenv docs have been down for about a week pypa/pipenv#4805 which is unfortunate, but I think it makes clear that the project is not in good shape.

I don't think we have reached a crystal clear consensus or agreed on what exactly do we want beyond some general recommendations, so I guess it will be easier to discuss over an actual pull request.

[pradyunsg]

Pipenv relies on pypa/pipfile, a format that advertises itself as "a replacement for the existing standard pip's requirements.txt file". However, the README has a big WARNING: This project is under active design and development. Nothing is set in stone at this point in time., and the experimental nature of the spec is not in line with the privileged position of Pipenv in the tool recommendations. (This might of course be a problem with the README instead.) On the other hand, the proposal to make pip adopt it has been frozen for almost two years, and in fact, it hasn't received much attention, so it is to be expected that, for the short and medium-term at least, Pipenv will be the only tool to support this format.

I agree. That project's README will benefit from getting it's "flair" toned down to match reality.

Present the tools in a more neutral way, that doesn't give one a privilege over the other.

I think it's pretty clear that "picking" pipenv for this tutorial turned out to be the wrong call for various reasons; both technical and social. I don't think back when this call was made, any of those were self-evident -- there was no crystal ball available to predict what things would look like. Heck, even the maintainership story for this site was better back then and we weren't in the third year of a global pandemic. :)

That said, I think that the generally neutral tone of this guide, combined with the current structure of the website, is actually really bad. IMO This guide should have "guided paths", with a clear presentation of tradeoffs between the choices you'd make and a set of opinionated defaults as well. It's a non-trivial amount of work to pivot to that though (both in terms of the technical work toward authoring/reorganising of the content, as well as the social work needed to get everyone on-board-enough) -- so... I don't think that should block improving this specific thing.

Sort the tools according to some up-to-date criteria.

One of the things that this site is struggling from is that there's limited capacity to author, update and improve the content here. But, again, yes, I also agree that this would be an improvement over status quo.

---

A part of the problem here is that we've lost some of the institutionalised knowledge that the folks who maintained this guide in ~2018 or ~2019 had; through the regular churn of people moving on to other projects and things in life.

---

So, I have a concrete plan for people to critique (it's an amagamation of both the options presented in OP).

• Move away from recommending pipenv in tooling recommendations, recommending pip + pip-tools/pipenv/poetry instead.
• Pivot the "guide" page, to present the options as a gradient of increasing complexity + scope-of-tooling -- as done in https://packaging.python.org/en/latest/guides/installing-scientific-packages/ -- putting things like manually managed pip requirements.txt files, pip-tools, pipenv and poetry on "equal" footing; moving away from a guided tutorial to using pipenv to being a guide on how to pick the right option for you.

I don't want to add hatch and other tools in a first shot of improving the recommendation here -- those can be added in a separate follow up. I'm thinking of this as a stopgap solution that doesn't needed the sort of concentrated long-ish term effort that something like #1039 would need.

I'll file the two PRs for this "soon". If I haven't done that by March 7th (i.e. over the weekend), please @-mention me here. :)

[pradyunsg]

I agree. That project's README will benefit from getting it's "flair" toned down to match reality.

Done in pypa/pipfile#138.

[pradyunsg]

The recommendations have been updated, with #1055.

Pivot the "guide" page, to present the options as a gradient of increasing complexity + scope-of-tooling -- as done in packaging.python.org/en/latest/guides/installing-scientific-packages -- putting things like manually managed pip requirements.txt files, pip-tools, pipenv and poetry on "equal" footing; moving away from a guided tutorial to using pipenv to being a guide on how to pick the right option for you.

I haven't come around to this, but I propose that we make this a separate follow up issue instead of keeping this one open until I come around to it.

I'll go ahead and close this issue, and will file a follow up! :)