Address likely FAQs about Pipfile in the README

[nchammas]

I know this project was just open-sourced and is still under active development, so consider this a reminder to update the README with some additional info when the time is right.

Some questions that immediately popped into my mind, which others are likely to ask, include:

1. How does Pipfile relate to setup.py and the upcoming pyproject.toml? Is it the same relationship as the one described here between requirements.txt and setup.py?
2. With the planned setup.py to pyproject.toml transition, we seem to be moving away from using Python and more towards using a declarative syntax for specifying build system requirements. With this proposed requirements.txt to Pipfile transition, however, we seem to be moving in the opposite direction. Could you comment on this?
3. Does Pipfile just use a Python-like syntax, or will it actually run Python code, like setup.py?
4. What is the purpose of Pipfile.lock, and will packaging end-users need to care about this file?

[ncoghlan]

Noting my preferred answers to these from a high level ecosystem-interoperability-wrangling point of view (some details here are shamelessly stolen from http://yehudakatz.com/2010/12/16/clarifying-the-roles-of-the-gemspec-and-gemfile/ ):

1. Pipfile is intended primarily for deploying applications and services directly from source control, while pyproject.toml is aimed primarily at the publication of explicitly versioned software components like libraries and frameworks (e.g. to the Python Package Index). Applications and services that also support library-style installation as part of a larger application or service may provide both kinds of file, with Pipfile delegating to pyproject.tomlto avoid metadata duplication.
2. The overall ecosystem level aim is to support the use of entirely declarative metadata at software installation time. Both pyproject.toml and Pipfile.lock work towards that goal in their respective domains. By contrast, execution of arbitrary software is both necessary and expected during software build processes, so the more modest goal for that step is to offer declarative bootstrapping of the build environment.
3. Pipfile.lock is a JSON file and hence readable without executing arbitrary code, but I have no strong opinion on Pipfile itself (there are pros and cons on either side)
4. Pipfile provides executable instructions on how to find and install the dependencies for an application or service, while Pipfile.lock provides a snapshot of a tested combination of specific versions of those dependencies.

[ncoghlan]

I filed #6 to discuss the "arbitrary Python code in Pipfile or not?" question, as I think the convenience of just using exec is possible (so Python syntax works normally), while still strongly encouraging a declarative style by blocking straightforward access to most builtins.

[defnull]

I should have posted #7 as a comment here instead of opening a new issue.

[holdenweb]

Yes, the current README leaves many interesting questions unanswered: what's the exact relationship between pip and pipfile, what does it actually create, is it an alternative to pip or does it merely generate requirements files from some other dependency specifications? And so on. The current README is clearly written by someone who already knows the answers to these questions, but the outsider can't currently see much of a reason to become an insider, or even a user.

[nchammas]

1. How does Pipfile relate to setup.py and the upcoming pyproject.toml? Is it the same relationship as the one described here between requirements.txt and setup.py?

This repo has been linked to on both Reddit and Hacker News, and the above question in particular seems to be driving a lot of misguided comments.

[pradyunsg]

Do #47 and #49 address this?