Clarify that a Pipfile is a tool to generate Pipfle.lock, and not a build description on its own.

[defnull]

Executable build descriptions are a bad idea. See https://www.reddit.com/r/Python/comments/5e2vci/pipfile_a_new_and_much_better_way_to_declare/da9c2ku/ or uncountable blog posts and articles all over the Internet for very good examples. It should be common knowledge by now, still the same errors are made again and again.

Pipfile has a nice hybrid approach in that it allows developers to generate a static Pipfile.lock from a dynamic description. Tools can parse the static Pipfile.lock and know exactly what to do, while developers can work with the more convenient Pipfile and can be as smart or lazy as they want to. This approach might actually work very well.

For this to work, and for others like me to accept this idea, I thing the following point should be stressed out more: Tools work with Pipfile.lock exclusively. A build system should never automatically execute a Pipfile to generate a missing or outdated Pipfile.lock. The pipfile module should never be a build requirement.

[kwlzn]

I think in general the whole idea and problem space behind Pipfile+Pipfile.lock et al could benefit from a real world narrative with better framing in standard industry terminology.

the requirements.txt form today provides a set of "requirement specifications" which are used in conjunction with other configurations (extended args in requirements.txt, cli args, config files) with tools like pip to both resolve and install requirements. the bigger idea behind a "Pipfile.lock" represents a broader concept known as a "frozen resolve". the idea behind a "frozen resolve" is to break the resolution (e.g. the translation of requirements specifications like "requests" or "requests>=1.0" against other constraints - interpreter type, platform, abi, etc - into a set of URLs, based on their metadata) apart from the retrieval (where possible) and installation/bundling/etc of the resolve product (e.g. fetching "http://my-file-server/requests/requests-2.11.1-py2.py3-none-any.whl" at some sha and installing that into a venv/pex/par etc).

because resolves against open ended constraints can be heinously non-deterministic, the idea of frozen resolves has emerged as a way to bring sanity into larger production environments. rather than checking in open ended constraints that when resolved lead to non-deterministic behavior at e.g. the same git sha but at different time periods - frozen resolves lead to retrieval of consistent products (assuming an immutable file store) with a consistent installation/bundling result. more importantly, frozen resolves can never spontaneously fail at the resolve phase due to unsatisfiable constraints. this effectively surfaces resolution issues directly to developers at commit time as a first class development step rather than later as package constraints shift due to unpinned versions (or transitive unpinned versions).

so effectively, a Pipfile.lock is a "frozen resolve". I feel like in particular the name Pipfile.lock seems like a huge verbiage mistake. this isn't a lockfile at all. it's an entirely new product type that is the intermediate step to more deterministic python software builds.

[lordmauve]

How about renaming Pipfile.lock to Pipfile, and then Pipfile to Pipfile.in or Pipfile.in.py? This would mirror "make" conventions and the existing MANIFEST.in.

[mekhami]

Why is mirroring C conventions more valuable than mirroring other conventions like Ruby? My gut reaction tells me we should look for crossover with the other interpreted language communities instead of makefiles and other compiled code systems.

[swistakm]

@mekhami Why to mirror other conventions if there is already one that is used by built-in Python library? @lordmauve made a good point when he mentioned MANIFEST.in that is used by distutils.

[tysonclugg]

+1 on following existing conventions: The abstract requirements should come from the install_requires and possibly the extras_require sections of setup.py, not from a file named Pipfile. The concrete (compiled) requirements should be written to requirements.txt (and requirements-dev.txt or similar as necessary), not to a file named Pipfile.lock.

Otherwise, it's just https://xkcd.com/927/ all over again. Please, we don't need another way to spell either requirements.txt or setup.py.

[tysonclugg]

For anyone that's interested, I've implemented the suggested behaviour from my comment above in jazzband/pip-tools#418 - I hope others find it useful. 😉

[kennethreitz]

jazzband/pip-tools#418 (comment) sheds some light on this

[pradyunsg]

Given #47, what's the status of this?

[kennethreitz]

@defnull please send a pull request to the README with the clarity you're seeking.

[defnull]

@kennethreitz This issue was an early feedback. Either it is still relevant and you should re-open the issue, or not and it can be closed without a change in README. I am no longer involved in this project and won't spend time on a pull request for a closed issue.

[kennethreitz]

I think it's pretty clear now.