From af83ed1a995b1af8a5b0d7bb3bfdb0f4fc88dd63 Mon Sep 17 00:00:00 2001 From: AP Ljungquist Date: Fri, 24 Jun 2022 17:03:34 +0200 Subject: [PATCH] Improve advice on constraints files (#2423) Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> --- docs/changelog/2423.doc.rst | 1 + docs/example/basic.rst | 21 +++++++++++++++------ 2 files changed, 16 insertions(+), 6 deletions(-) create mode 100644 docs/changelog/2423.doc.rst 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: