Update infromation about `pip_pre` configuration options #2885

Czaki · 2023-01-20T10:34:01Z

The docs for tox configuration still mention --pre flag even if tox uses PIP_PRE environment variables. This may lead to confusion, as in #2690.
In this PR, I updated documentation to allow understanding of this change without looking for closed issues.

Czaki · 2023-01-20T10:41:01Z

docs/config.rst

@@ -726,8 +726,7 @@ Pip installer

   Determines the command used for installing packages into the virtual environment; both the package under test and its
   dependencies (defined with :ref:`deps`). Must contain the substitution key ``{packages}`` which will be replaced by
-   the package(s) to install.  You should also accept ``{opts}`` -- it will contain index server options such as
-   ``--pre`` (configured as ``pip_pre``).
+   the package(s) to install.  You should also accept ``{opts}`` -- it will contain index server options.


As pre-release is configured now with the environment variable, I removed it from the example but do not have any idea what could be the replacement.

As I understand, currently, all pip options could be configured using environment variables, so I'm not sure if opts is really required and maybe should be removed.

Czaki · 2023-01-20T11:00:15Z

I cannot find information if pip 20.3.4 (last supporting python 2.7) supports configuration via environment variables.

masenf · 2023-01-22T17:26:45Z

docs/config.rst

@@ -751,9 +750,10 @@ Pip installer
   :default: false
   :version_added: 1.9

-   If ``true``, adds ``--pre`` to the ``opts`` passed to :ref:`install_command`. This will cause it to install the
+   If ``true``, adds ``PIP_PRE=1`` to the `environment <https://pip.pypa.io/en/stable/topics/configuration/#environment-variables>`_. This will cause pip it to install the


This is not correct.

Setting pip_pre = true in a [testenv] does cause tox to add --pre to the opts:

tox/src/tox/tox_env/python/pip/pip_install.py

Lines 54 to 67 in 997128c

def post_process_install_command(self, cmd: Command) -> Command:

install_command = cmd.args

pip_pre: bool = self._env.conf["pip_pre"]

try:

opts_at = install_command.index("{opts}")

except ValueError:

if pip_pre:

install_command.append("--pre")

else:

if pip_pre:

install_command[opts_at] = "--pre"

else:

install_command.pop(opts_at)

return cmd

The environment variable PIP_PRE is only set when using the legacy CLI flag --pre:

tox/src/tox/session/cmd/legacy.py

Lines 60 to 65 in 4558fee

our.add_argument(

"--pre",

action="store_true",

help="deprecated use PIP_PRE in set_env instead - install pre-releases and development versions of"

"dependencies; this will set PIP_PRE=1 environment variable",

)

tox/src/tox/session/cmd/legacy.py

Lines 121 to 122 in 4558fee

if getattr(option, "pre", False):

set_env["PIP_PRE"] = "1"

The environment variable PIP_PRE is only set when using the legacy CLI flag --pre:

Is there a plan to remove inconsistency? Or should I update the description in this PR to inform about this?

It's my understanding that the "pip flags" accepted by the tox CLI are deprecated and will be eventually removed. The pip environment variables should be used to influence pip instead of passing (some accepted subset) of pip flags to tox.

Basically tox has no reason to maintain these pip flags now that pip exposes all of its options via environment variable.

Ok.
But I still need to figure out what this means for this PR. Should it be closed? Modified (ex. add an explanation to avoid confusion)?

@Czaki we have the following doc for the cli flag already: https://tox.wiki/en/latest/cli_interface.html#tox-legacy---pre

So I don't think this patch is strictly needed. However if you wanted to mention the legacy CLI flag in the testenv config section as "this config value may be overridden externally via the --pre cli flag (deprecated) or by setting PIP_PRE=1". Also note that setting PIP_PRE=0 does NOT override the testenv config, since that will use the pip cli flag, which takes precedence over envvars.

If the user can set the pre flag, we should fix it so that it works. However, we should also document that this flag is deprecated and we encourage using the environment variables instead.

docs/config.rst

gaborbernat · 2023-02-05T21:55:53Z

Seems this has stalled, closing for now we can reopen when you get time for it again.

Czaki · 2023-02-05T23:17:18Z

Seems this has stalled, closing for now we can reopen when you get time for it again.

It is stalled because I'm confused what is proper solution.

Did best option is to describe difference between legacy --pre flag and pip_pre configuration option, or add code changes to uniform behavior (also marking pip_pre as deprecated as it could be configured using setenv configuration option?

Czaki · 2023-02-08T19:22:47Z

As I read tox source code, it looks like it should be handled in the same way as setenv, some variant of EnvConfigSet that will return SetEnv instance with "PIP_PRE=1" as input text.

It is correct assumption?

If it us correct then where I should register for such a class? Or could you point proper part of the documentation where I could read?

update docs about pre release install

5f9e912

Czaki requested a review from gaborbernat as a code owner January 20, 2023 10:34

add timeline information

d721a95

psf-chronographer bot added the bot:chronographer:provided label Jan 20, 2023

Czaki commented Jan 20, 2023

View reviewed changes

gaborbernat approved these changes Jan 20, 2023

View reviewed changes

masenf requested changes Jan 22, 2023

View reviewed changes

MeCorey approved these changes Jan 27, 2023

View reviewed changes

docs/config.rst Show resolved Hide resolved

gaborbernat closed this Feb 5, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update infromation about `pip_pre` configuration options #2885

Update infromation about `pip_pre` configuration options #2885

Czaki commented Jan 20, 2023

Czaki Jan 20, 2023

Czaki commented Jan 20, 2023

masenf Jan 22, 2023

Czaki Jan 22, 2023

masenf Jan 22, 2023

Czaki Jan 22, 2023

masenf Jan 22, 2023

gaborbernat Jan 22, 2023

gaborbernat Feb 6, 2023

gaborbernat commented Feb 5, 2023

Czaki commented Feb 5, 2023

Czaki commented Feb 8, 2023

	def post_process_install_command(self, cmd: Command) -> Command:
	install_command = cmd.args
	pip_pre: bool = self._env.conf["pip_pre"]
	try:
	opts_at = install_command.index("{opts}")
	except ValueError:
	if pip_pre:
	install_command.append("--pre")
	else:
	if pip_pre:
	install_command[opts_at] = "--pre"
	else:
	install_command.pop(opts_at)
	return cmd

	our.add_argument(
	"--pre",
	action="store_true",
	help="deprecated use PIP_PRE in set_env instead - install pre-releases and development versions of"
	"dependencies; this will set PIP_PRE=1 environment variable",
	)

Update infromation about pip_pre configuration options #2885

Update infromation about pip_pre configuration options #2885

Conversation

Czaki commented Jan 20, 2023

Choose a reason for hiding this comment

Czaki commented Jan 20, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gaborbernat commented Feb 5, 2023

Czaki commented Feb 5, 2023

Czaki commented Feb 8, 2023

Update infromation about `pip_pre` configuration options #2885

Update infromation about `pip_pre` configuration options #2885