Documentation should describe what pipenv does and who it's for

[njsmith]

Looking at the docs, we learn that:

• pipenv is "python dev workflow for humans" – that sounds good, I'm a human with a python dev workflow
• it's "the officially recommended Python packaging tool"
• it "bring[s] the best of all packaging worlds to the Python world"
• it solves "multi-faceted" problems
• it "replaces ... manual pip calls"

Basically what I get from this is that everyone should be using pipenv because it solves all the problems that other tools solved but better. What I don't get from it is any indication of what it actually does. This is especially confusing since AFAICT it doesn't actually solve any of my packaging problems.

I asked about this on twitter, and as far as I can tell the conclusion is that pipenv is targeted specifically at solving one specific problem in Python development: when you're working on an application you'll be deploying into a virtualenv (e.g. a django website), and want to control the dependencies used in the virtualenv, keep them consistent across your team, manage upgrades in a systematic way, etc.

I write Python libraries. I use pip and virtualenv and requirements.txt files a lot. For example:

• Creating ad-hoc virtualenvs to test particular combinations of python/library versions to reproduce reported issues
• Installing packages for general use into my user environment
• Recording which packages are needed to run tests, or build the docs, or format the source code, for convenience of other devs and for use in CI (e.g. test-requirements.txt, rtd-requirements.txt)

So far as I can tell, all of these are out-of-scope of pipenv, right? It's simply not intended at all to help developers like me? Or is it?

It would be very helpful if the docs could start with some information about who this project is intended for and what problems it's trying to help them solve.

[njsmith]

(To be clear, this isn't at all a criticism of pipenv itself – it's totally reasonable for it to be targeted at a specific use case. It should just make that clear to avoid over-promising :-).)

[vascowhite]

@njsmith It's good to know it's not just me. Thanks for putting it over so clearly.

[kennethreitz]

It's targeted at people building applications.

[njsmith]

Does this bug being closed mean that you consider the current documentation sufficient, or...?

BTW, in that twitter thread (specifically the (subthread ending here), @ncoghlan actually made a pretty good case that it could be useful for libraries too, perhaps with a few tweaks.

[uranusjr]

@njsmith Would you be interested in submitting a pull request?

[ncoghlan]

#857 is genuinely a problem for libraries at the moment, as if any of your dependencies use environment markers then the lock file contents will end up being platform and/or version dependent.

So I think for now we'd be doing users a favour by being clear that the current "sweet spot" for pipenv is when you're deploying to a specific target environment (e.g. custom apps for a specific organisation, or targeting a specific OS+Python version combo).

We do want pipenv to support other cases, but they have more rough edges on them than that core app development use case.

[ksonj]

I took a stab at describing how pipenv/Pipfile fits into the current ecosystem: #1733

[kennethreitz]

merged ✨🍰✨