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

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.

[kennethreitz]

It’s targeted at people building applications.

[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 😃.)