From a8b1da97b0c76b4617bb9ebf0120cc132739237a Mon Sep 17 00:00:00 2001 From: Mathieu Kniewallner Date: Sun, 28 Aug 2022 11:09:46 +0200 Subject: [PATCH] [1.2] doc(configuration): improve documentation (#6255) Backport of https://github.com/python-poetry/poetry/pull/6254. --- docs/configuration.md | 137 +++++++++++++++++++++++++----------------- 1 file changed, 83 insertions(+), 54 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 50410f43de8..9b601677d73 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -147,7 +147,7 @@ You can override the Cache directory by setting the `POETRY_CACHE_DIR` environme ### `cache-dir` -**Type**: string +**Type**: `string` The path to the cache directory used by Poetry. @@ -159,7 +159,9 @@ Defaults to one of the following directories: ### `experimental.system-git-client` -**Type**: boolean +**Type**: `boolean` + +**Default**: `false` *Introduced in 1.2.0* @@ -169,33 +171,30 @@ Poetry uses `dulwich` by default for git related tasks to not rely on the availa If you encounter any problems with it, set to `true` to use the system git backend. -Defaults to `false`. - -### `installer.parallel` - -**Type**: boolean +### `installer.max-workers` -Use parallel execution when using the new (`>=1.1.0`) installer. -Defaults to `true`. +**Type**: `int` -### `installer.max-workers` +**Default**: `number_of_cores + 4` -**Type**: int +*Introduced in 1.2.0* -Set the maximum number of workers while using the parallel installer. Defaults to `number_of_cores + 4`. +Set the maximum number of workers while using the parallel installer. The `number_of_cores` is determined by `os.cpu_count()`. -If this raises a `NotImplentedError` exception `number_of_cores` is assumed to be 1. +If this raises a `NotImplementedError` exception, `number_of_cores` is assumed to be 1. If this configuration parameter is set to a value greater than `number_of_cores + 4`, the number of maximum workers is still limited at `number_of_cores + 4`. {{% note %}} -This configuration will be ignored when `installer.parallel` is set to false. +This configuration is ignored when `installer.parallel` is set to `false`. {{% /note %}} ### `installer.no-binary` -**Type**: string | bool +**Type**: `string | boolean` + +**Default**: `false` *Introduced in 1.2.0* @@ -240,22 +239,33 @@ Unless this is required system-wide, if configured globally, you could encounter across all your projects if incorrectly set. {{% /warning %}} +### `installer.parallel` + +**Type**: `boolean` + +**Default**: `true` + +*Introduced in 1.1.4* + +Use parallel execution when using the new (`>=1.1.0`) installer. ### `virtualenvs.create` -**Type**: boolean +**Type**: `boolean` + +**Default**: `true` Create a new virtual environment if one doesn't already exist. -Defaults to `true`. If set to `false`, poetry will install dependencies into the current python environment. ### `virtualenvs.in-project` -**Type**: boolean +**Type**: `boolean` + +**Default**: `None` Create the virtualenv inside the project's root directory. -Defaults to `None`. If not set explicitly, `poetry` by default will create virtual environment under `{cache-dir}/virtualenvs` or use the `{project-dir}/.venv` directory when one is available. @@ -265,35 +275,27 @@ If set to `true`, the virtualenv will be created and expected in a folder named If set to `false`, `poetry` will ignore any existing `.venv` directory. -### `virtualenvs.path` - -**Type**: string - -Directory where virtual environments will be created. -Defaults to `{cache-dir}/virtualenvs` (`{cache-dir}\virtualenvs` on Windows). +### `virtualenvs.options.always-copy` -### `virtualenvs.prompt` +**Type**: `boolean` -**Type**: string +**Default**: `false` -Format string defining the prompt to be displayed when the virtual environment is activated. -The variables `project_name` and `python_version` are available for formatting. -Defaults to `"{project_name}-py{python_version}"`. +*Introduced in 1.2.0* -### `virtualenvs.options.always-copy` +If set to `true` the `--always-copy` parameter is passed to `virtualenv` on creation of the virtual environment, so that +all needed files are copied into it instead of symlinked. -**Type**: boolean +### `virtualenvs.options.no-pip` -If set to `true` the `--always-copy` parameter is passed to `virtualenv` on creation of the venv. Thus all needed files are copied into the venv instead of symlinked. -Defaults to `false`. +**Type**: `boolean` -### `virtualenvs.options.no-pip` +**Default**: `false` -**Type**: boolean +*Introduced in 1.2.0* -If set to `true` the `--no-pip` parameter is passed to `virtualenv` on creation of the venv. This means when a new -virtual environment is created, `pip` will not be installed in the environment. -Defaults to `false`. +If set to `true` the `--no-pip` parameter is passed to `virtualenv` on creation of the virtual environment. This means +when a new virtual environment is created, `pip` will not be installed in the environment. {{% note %}} Poetry, for its internal operations, uses the `pip` wheel embedded in the `virtualenv` package installed as a dependency @@ -306,12 +308,15 @@ packages. This is desirable for production environments. ### `virtualenvs.options.no-setuptools` -**Type**: boolean +**Type**: `boolean` + +**Default**: `false` + +*Introduced in 1.2.0* -If set to `true` the `--no-setuptools` parameter is passed to `virtualenv` on creation of the venv. This means when a new -virtual environment is created, `setuptools` will not be installed in the environment. Poetry, for its internal operations, -does not require `setuptools` and this can safely be set to `true`. -Defaults to `false`. +If set to `true` the `--no-setuptools` parameter is passed to `virtualenv` on creation of the virtual environment. This +means when a new virtual environment is created, `setuptools` will not be installed in the environment. Poetry, for its +internal operations, does not require `setuptools` and this can safely be set to `true`. {{% warning %}} Some development tools like IDEs, make an assumption that `setuptools` (and other) packages are always present and @@ -320,28 +325,52 @@ available within a virtual environment. This can cause some features in these to ### `virtualenvs.options.system-site-packages` -**Type**: boolean +**Type**: `boolean` + +**Default**: `false` Give the virtual environment access to the system site-packages directory. Applies on virtualenv creation. -Defaults to `false`. + +### `virtualenvs.path` + +**Type**: `string` + +**Default**: `{cache-dir}/virtualenvs` + +Directory where virtual environments will be created. ### `virtualenvs.prefer-active-python` (experimental) -**Type**: boolean +**Type**: `boolean` + +**Default**: `false` + +*Introduced in 1.2.0* + +Use currently activated Python version to create a new virtual environment. +If set to `false`, Python version used during Poetry installation is used. + +### `virtualenvs.prompt` -Use currently activated Python version to create a new venv. -Defaults to `false`, which means Python version used during Poetry installation is used. +**Type**: `string` + +**Default**: `{project_name}-py{python_version}` + +*Introduced in 1.2.0* + +Format string defining the prompt to be displayed when the virtual environment is activated. +The variables `project_name` and `python_version` are available for formatting. ### `repositories.` -**Type**: string +**Type**: `string` Set a new alternative repository. See [Repositories]({{< relref "repositories" >}}) for more information. ### `http-basic.`: -**Types**: string, string +**Type**: `(string, string)` Set repository credentials (`username` and `password`) for ``. See [Repositories - Configuring credentials]({{< relref "repositories#configuring-credentials" >}}) @@ -349,7 +378,7 @@ for more information. ### `pypi-token.`: -**Type**: string +**Type**: `string` Set repository credentials (using an API token) for ``. See [Repositories - Configuring credentials]({{< relref "repositories#configuring-credentials" >}}) @@ -357,7 +386,7 @@ for more information. ### `certificates..cert`: -**Type**: string | bool +**Type**: `string | boolean` Set custom certificate authority for repository ``. See [Repositories - Configuring credentials - Custom certificate authority]({{< relref "repositories#custom-certificate-authority-and-mutual-tls-authentication" >}}) @@ -368,7 +397,7 @@ repository. ### `certificates..client-cert`: -**Type**: string +**Type**: `string` Set client certificate for repository ``. See [Repositories - Configuring credentials - Custom certificate authority]({{< relref "repositories#custom-certificate-authority-and-mutual-tls-authentication" >}})