From 10ccf61b836296959d4fae090fe8d864ba60bfc9 Mon Sep 17 00:00:00 2001 From: Nick Papior Date: Sun, 27 Oct 2024 20:20:13 +0100 Subject: [PATCH 1/5] clarified docs for env-vars and config files More links between sections are added. It should bring all documentation together in a more coherent manner. The Environemnt variables section has been cleaned. Now there are not 3 *random* examples which might have confused users to only suspect that those 3 examples where the only available ones. Now this section clarifies how *any* CLI-option is specified through an env var, and clarifies that the shell example, *is* an example. Signed-off-by: Nick Papior --- docs/html/topics/configuration.md | 52 +++++++++++++++++++------------ 1 file changed, 32 insertions(+), 20 deletions(-) diff --git a/docs/html/topics/configuration.md b/docs/html/topics/configuration.md index 12bad0ad7a4..c508c0ffc63 100644 --- a/docs/html/topics/configuration.md +++ b/docs/html/topics/configuration.md @@ -2,11 +2,13 @@ # Configuration -pip allows a user to change its behaviour via 3 mechanisms: +pip allows a user to change its behaviour via 3 mechanisms. +These mechanisms are listed in order of priority, meaning that +command line options has [preference](config-preference): -- command line options -- environment variables -- configuration files +1. command line options +2. [environment variables](env-variables) +3. [configuration files](config-file) This page explains how the configuration files and environment variables work, and how they are related to pip's various command line options. @@ -28,7 +30,12 @@ pip has 3 "levels" of configuration files: - `user`: per-user configuration file. - `site`: per-environment configuration file; i.e. per-virtualenv. -Additionally, environment variables can be specified which will override any of the above. +```{note} +Options specified through environment variables or command line options +take precedence over configuration files. + +See the [preference section](config-preference) for more details. +``` ### Location @@ -199,33 +206,38 @@ trusted-host = This enables users to add additional values in the order of entry for such command line arguments. -## Environment Variables +(env-variables)= -pip's command line options can be set with environment variables using the -format `PIP_` . Dashes (`-`) have to be replaced with -underscores (`_`). +## Environment Variables -- `PIP_TIMEOUT=60` is the same as `--timeout=60` -- ``` - PIP_FIND_LINKS="http://mirror1.example.com http://mirror2.example.com" - ``` +All pip's command line options have equivalent environment variables, +they can be specified using: +```shell +PIP_ +``` - is the same as +Options with dashes (`-`) have to be replaced with underscores (`_`). - ``` - --find-links=http://mirror1.example.com --find-links=http://mirror2.example.com - ``` +Examples: -Repeatable options that do not take a value (such as `--verbose`) can be -specified using the number of repetitions: +```shell +PIP_VERBOSE=3 PIP_CACHE_DIR=/home/user/tmp pip ... +# is equivalent to +pip ... -vvv --cache-dir=/home/user/tmp +``` -- `PIP_VERBOSE=3` is the same as `pip install -vvv` +All option values follows the same rules as for the [configuration files](config-file). ```{note} Environment variables set to an empty string (like with `export X=` on Unix) will **not** be treated as false. Use `no`, `false` or `0` instead. + +Consequently, boolean options prefixed with `--no-*` can be disabled by using +truthy values, e.g. `PIP_NO_CACHE_DIR=true`. ``` +(config-preference)= + ## Precedence / Override order Command line options override environment variables, which override the From 627a1ae1e94ec6350a00a80e406490b30eca7772 Mon Sep 17 00:00:00 2001 From: Nick Papior Date: Sun, 27 Oct 2024 20:22:42 +0100 Subject: [PATCH 2/5] added towncrier rst Signed-off-by: Nick Papior --- news/13050.doc.rst | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 news/13050.doc.rst diff --git a/news/13050.doc.rst b/news/13050.doc.rst new file mode 100644 index 00000000000..96e15ec5540 --- /dev/null +++ b/news/13050.doc.rst @@ -0,0 +1,2 @@ +Clarified documentation for using environment variables +instead of command line options. From c28176f989aae3a07804aaa6f40f77c1ff6266b3 Mon Sep 17 00:00:00 2001 From: Nick Papior Date: Mon, 16 Dec 2024 13:04:40 +0100 Subject: [PATCH 3/5] worked on @ichard26 suggestions Signed-off-by: Nick Papior --- docs/html/topics/configuration.md | 44 +++++++++++++------------------ 1 file changed, 18 insertions(+), 26 deletions(-) diff --git a/docs/html/topics/configuration.md b/docs/html/topics/configuration.md index c508c0ffc63..b4fe5c98702 100644 --- a/docs/html/topics/configuration.md +++ b/docs/html/topics/configuration.md @@ -3,8 +3,7 @@ # Configuration pip allows a user to change its behaviour via 3 mechanisms. -These mechanisms are listed in order of priority, meaning that -command line options has [preference](config-preference): +These mechanisms are listed in order of priority, highest to lowest: 1. command line options 2. [environment variables](env-variables) @@ -24,17 +23,17 @@ and how they are related to pip's various command line options. Configuration files can change the default values for command line options. The files are written using standard INI format. -pip has 3 "levels" of configuration files: +pip has 3 "levels" of configuration files, in order of priority, highest to lowest: -- `global`: system-wide configuration file, shared across users. -- `user`: per-user configuration file. - `site`: per-environment configuration file; i.e. per-virtualenv. +- `user`: per-user configuration file. +- `global`: system-wide configuration file, shared across users. + +```{important} +Values in command-specific sections override values in the global section. -```{note} Options specified through environment variables or command line options take precedence over configuration files. - -See the [preference section](config-preference) for more details. ``` ### Location @@ -210,20 +209,24 @@ command line arguments. ## Environment Variables -All pip's command line options have equivalent environment variables, +All pip command line options have equivalent environment variables, they can be specified using: ```shell -PIP_ +PIP_ ``` -Options with dashes (`-`) have to be replaced with underscores (`_`). +Dashes (`-`) have to be replaced with underscores (`_`). Examples: ```shell PIP_VERBOSE=3 PIP_CACHE_DIR=/home/user/tmp pip ... -# is equivalent to +PIP_FIND_LINKS="http://mirror1.example.com http://mirror2.example.com" pip ... +PIP_NO_DEPS=yes pip ... +# are equivalent to pip ... -vvv --cache-dir=/home/user/tmp +pip ... --find-links=http://mirror1.example.com --find-links=http://mirror2.example.com +pip ... --no-deps ``` All option values follows the same rules as for the [configuration files](config-file). @@ -234,19 +237,8 @@ Use `no`, `false` or `0` instead. Consequently, boolean options prefixed with `--no-*` can be disabled by using truthy values, e.g. `PIP_NO_CACHE_DIR=true`. -``` - -(config-preference)= - -## Precedence / Override order -Command line options override environment variables, which override the -values in a configuration file. Within the configuration file, values in -command-specific sections override values in the global section. +Exception options are: -Examples: - -- `--host=foo` overrides `PIP_HOST=foo` -- `PIP_HOST=foo` overrides a config file with `[global] host = foo` -- A command specific section in the config file `[] host = bar` - overrides the option with same name in the `[global]` config file section. +- `PIP_NO_BUILD_ISOLATION=off`, see e.g. #5735 for details. +``` From 2a21ccc0a170c92e64a035d08981c47133bc7037 Mon Sep 17 00:00:00 2001 From: Richard Si Date: Mon, 16 Dec 2024 17:58:47 -0500 Subject: [PATCH 4/5] Break out PIP_NO_BUILD_ISOLATION footgun warning --- docs/html/topics/configuration.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/html/topics/configuration.md b/docs/html/topics/configuration.md index b4fe5c98702..aec9916ccd5 100644 --- a/docs/html/topics/configuration.md +++ b/docs/html/topics/configuration.md @@ -237,8 +237,13 @@ Use `no`, `false` or `0` instead. Consequently, boolean options prefixed with `--no-*` can be disabled by using truthy values, e.g. `PIP_NO_CACHE_DIR=true`. +``` -Exception options are: +```{warning} +`PIP_NO_BUILD_ISOLATION` functions **opposite** to how it reads. For example, to +disable build isolation, `PIP_NO_BUILD_ISOLATION` must be set to a **falsy** value, +e.g. `PIP_NO_BUILD_ISOLATION=off`. -- `PIP_NO_BUILD_ISOLATION=off`, see e.g. #5735 for details. +This confusing behavior is known and will be addressed, please see issue {issue}`5735` for +discussion on potential fixes. ``` From ab28ee62c8733eeba0a409aef07958c8b2970d14 Mon Sep 17 00:00:00 2001 From: Richard Si Date: Mon, 16 Dec 2024 18:03:34 -0500 Subject: [PATCH 5/5] Remove unnecesary docs news entry --- news/13050.doc.rst | 2 -- 1 file changed, 2 deletions(-) delete mode 100644 news/13050.doc.rst diff --git a/news/13050.doc.rst b/news/13050.doc.rst deleted file mode 100644 index 96e15ec5540..00000000000 --- a/news/13050.doc.rst +++ /dev/null @@ -1,2 +0,0 @@ -Clarified documentation for using environment variables -instead of command line options.