diff --git a/docs/changelog/2423.doc.rst b/docs/changelog/2423.doc.rst new file mode 100644 index 000000000..94c90bdc5 --- /dev/null +++ b/docs/changelog/2423.doc.rst @@ -0,0 +1 @@ +Explain advantages of ``PIP_CONSTRAINT`` environment variable over ``--constraint`` argument. diff --git a/docs/example/basic.rst b/docs/example/basic.rst index c7b15e445..8e69289b7 100644 --- a/docs/example/basic.rst +++ b/docs/example/basic.rst @@ -121,26 +121,35 @@ Depending on requirements.txt or defining constraints .. versionadded:: 1.6.1 -(experimental) If you have a ``requirements.txt`` file or a ``constraints.txt`` file you can add it to your ``deps`` variable like this: +(experimental) If you have a ``requirements.txt`` file you can add it to your ``deps`` variable like this: .. code-block:: ini [testenv] deps = -rrequirements.txt -or +This is actually a side effect that all elements of the dependency list is directly passed to ``pip``. + +If you have a ``constraints.txt`` file you could add it to your ``deps`` like the ``requirements.txt`` file above. +However, then it would not be applied to + +* build time dependencies when using isolated builds (https://github.com/pypa/pip/issues/8439) +* run time dependencies not already listed in ``deps``. + +A better method may be to use ``setenv`` like this: .. code-block:: ini [testenv] - deps = - -rrequirements.txt - -cconstraints.txt + setenv = PIP_CONSTRAINT=constraints.txt + +Make sure that all dependencies, including transient dependencies, are listed in your ``constraints.txt`` file or the version used may vary. + +It should be noted that ``pip``, ``setuptools`` and ``wheel`` are often not part of the dependency tree and will be left at whatever version ``virtualenv`` used to seed the environment. All installation commands are executed using ``{toxinidir}`` (the directory where ``tox.ini`` resides) as the current working directory. Therefore, the underlying ``pip`` installation will assume ``requirements.txt`` or ``constraints.txt`` to exist at ``{toxinidir}/requirements.txt`` or ``{toxinidir}/constraints.txt``. -This is actually a side effect that all elements of the dependency list is directly passed to ``pip``. For more details on ``requirements.txt`` files or ``constraints.txt`` files please see: