Merge branch 'master' into pinned_preversion

HISTORY.txt

@@ -1,3 +1,11 @@
+11.8.1:
+ - Removed (unused) Safety DB (licensing concerns).
+11.8.0:
+ - Fix a major bug in locking resolution.
+11.7.4:
+ - Don't use JSON results — problematic.
+11.7.3:
+ - Increase compatibility with strange Python installations (concurrency.futures).
 11.7.2:
  - Bugfixes.
 11.7.1:

Pipfile

@@ -1,6 +1,6 @@
 [dev-packages]
 
-"pipenv" = {path = ".", editable = true}
+pipenv = {path = ".", editable = true}
 "flake8" = ">=3.3.0,<4"
 pytest = "*"
 mock = "*"
@@ -9,14 +9,16 @@ twine = "*"
 sphinx-click = "*"
 pytest-xdist = "*"
 click = "*"
-"pytest-pypy" = {path = "./tests/pytest-pypi", editable = true}
+pytest-pypy = {path = "./tests/pytest-pypi", editable = true}
 pytest-tap = "*"
 stdeb = {version="*", sys_platform="== 'linux'"}
+black = {version="*", python_version="=='3.6'"}
 
 
 [packages]
 
 
+
 [scripts]
 
 tests = "bash ./run-tests.sh"

docs/advanced.rst

@@ -12,6 +12,7 @@ This document covers some of Pipenv's more glorious and advanced features.
 
 - Dependencies of wheels provided in a ``Pipfile`` will not be captured by ``$ pipenv lock``.
 - There are some known issues with using private indexes, related to hashing. We're actively working to solve this problem. You may have great luck with this, however.
+- Installation is intended to be as determinstic as possible — use the ``--sequential`` flag to increase this, if experiencing issues.
 
 ☤ Specifying Package Indexes
 ----------------------------
@@ -459,3 +460,28 @@ interfaces that don't participate in Python-level dependency resolution
 at all, use the `PIP_IGNORE_INSTALLED` setting::
 
     $ PIP_IGNORE_INSTALLED=1 pipenv install --dev
+
+
+.. _pipfile-vs-setuppy:
+
+☤ Pipfile vs setup.py
+---------------------
+
+There is a subtle but very important distinction to be made between **applications** and **libraries**. This is a very common source of confusion in the Python community.
+
+Libraries provide reusable functionality to other libraries and applications (let's use the umbrella term **projects** here). They are required to work alongside other libraries, all with their own set of subdependencies. They define **abstract dependencies**. To avoid version conflicts in subdependencies of different libraries within a project, libraries should never ever pin dependency versions. Although they may specifiy lower or (less frequently) upper bounds, if they rely on some specific feature/fix/bug. Library dependencies are specified via ``install_requires`` in ``setup.py``.
+
+Libaries are ultimately meant to be used in some **application**. Applications are different in that they usually are not depended on by other projects. They are meant to be deployed into some specific environment and only then should the exact versions of all their dependencies and subdependencies be made concrete. To make this process easier is currently the main goal of ``pipenv``.
+
+To summarize:
+
+- For libraries, define **abstract dependencies** via ``install_requires`` in ``setup.py``. The decision of which version exactly to be installed and where to obtain that dependency is not yours to make!
+- For applications, define **dependencies and where to get them** in the `Pipfile` and use this file to update the set of **concrete dependencies** in ``Pipfile.lock``. This file defines a specific idempotent environment that is known to work for your project. The ``Pipfile.lock`` is your source of truth. The ``Pipfile`` is a convenience for you to create that lock-file, in that it allows you to still remain somewhat vague about the exact version of a dependency to be used. ``pipenv`` is there to help you define a working conflict-free set of specific dependency-versions, which would otherwise be a very tedious task.
+- Of course, ``Pipfile`` and ``pipenv`` are still useful for library developers, as they can be used to define a development or test environment.
+- And, of course, there are projects for which the distinction between library and application isn't that clear. In that case, use ``install_requires`` alongside ``pipenv`` and ``Pipfile``.
+
+You can also do this::
+
+    $ pipenv install -e .
+
+This will tell Pipenv to lock all your ``setup.py``–declared dependencies.

docs/index.rst

@@ -26,6 +26,7 @@ Pipenv is a tool that aims to bring the best of all packaging worlds (bundler, c
 
 It automatically creates and manages a virtualenv for your projects, as well as adds/removes packages from your ``Pipfile`` as you install/uninstall packages. It also generates the ever-important ``Pipfile.lock``, which is used to produce deterministic builds.
 
+Pipenv is primarily meant to provide users and developers of applications with an easy method to setup a working environment. For the distinction between libraries and applications and the usage of ``setup.py`` vs ``Pipfile`` to define dependencies, see :ref:`pipfile-vs-setuppy`.
 
 .. raw:: html