Skip to content

Commit af83ed1

Browse files
Improve advice on constraints files (#2423)
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
1 parent 5169fdf commit af83ed1

File tree

2 files changed

+16
-6
lines changed

2 files changed

+16
-6
lines changed

docs/changelog/2423.doc.rst

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Explain advantages of ``PIP_CONSTRAINT`` environment variable over ``--constraint`` argument.

docs/example/basic.rst

+15-6
Original file line numberDiff line numberDiff line change
@@ -121,26 +121,35 @@ Depending on requirements.txt or defining constraints
121121

122122
.. versionadded:: 1.6.1
123123

124-
(experimental) If you have a ``requirements.txt`` file or a ``constraints.txt`` file you can add it to your ``deps`` variable like this:
124+
(experimental) If you have a ``requirements.txt`` file you can add it to your ``deps`` variable like this:
125125

126126
.. code-block:: ini
127127
128128
[testenv]
129129
deps = -rrequirements.txt
130130
131-
or
131+
This is actually a side effect that all elements of the dependency list is directly passed to ``pip``.
132+
133+
If you have a ``constraints.txt`` file you could add it to your ``deps`` like the ``requirements.txt`` file above.
134+
However, then it would not be applied to
135+
136+
* build time dependencies when using isolated builds (https://github.com/pypa/pip/issues/8439)
137+
* run time dependencies not already listed in ``deps``.
138+
139+
A better method may be to use ``setenv`` like this:
132140

133141
.. code-block:: ini
134142
135143
[testenv]
136-
deps =
137-
-rrequirements.txt
138-
-cconstraints.txt
144+
setenv = PIP_CONSTRAINT=constraints.txt
145+
146+
Make sure that all dependencies, including transient dependencies, are listed in your ``constraints.txt`` file or the version used may vary.
147+
148+
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.
139149

140150
All installation commands are executed using ``{toxinidir}`` (the directory where ``tox.ini`` resides) as the current working directory.
141151
Therefore, the underlying ``pip`` installation will assume ``requirements.txt`` or ``constraints.txt`` to exist at ``{toxinidir}/requirements.txt`` or ``{toxinidir}/constraints.txt``.
142152

143-
This is actually a side effect that all elements of the dependency list is directly passed to ``pip``.
144153

145154
For more details on ``requirements.txt`` files or ``constraints.txt`` files please see:
146155

0 commit comments

Comments
 (0)