Skip to content

P
python-poetry
Commit 73e4bde8 by Mathieu Kniewallner Committed by GitHub
Options

doc(configuration): improve documentation (#6254) 

# Pull Request Check List

- [ ] Added **tests** for changed code.
- [ ] Updated **documentation** for changed code.

Bunch of improvements over `Configuration` documentation:
- Better show default value of options
- Add some missing `Introduced in <VERSION>` notes
- Add backticks around types for better readability

Will backport to `1.2` branch before final release.
parent ec3a6c14
Showing with 83 additions and 54 deletions
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.<name>`
**Type**: string
**Type**: `string`
Set a new alternative repository. See [Repositories]({{< relref "repositories" >}}) for more information.
### `http-basic.<name>`:
**Types**: string, string
**Type**: `(string, string)`
Set repository credentials (`username` and `password`) for `<name>`.
See [Repositories - Configuring credentials]({{< relref "repositories#configuring-credentials" >}})
......@@ -349,7 +378,7 @@ for more information.
### `pypi-token.<name>`:
**Type**: string
**Type**: `string`
Set repository credentials (using an API token) for `<name>`.
See [Repositories - Configuring credentials]({{< relref "repositories#configuring-credentials" >}})
......@@ -357,7 +386,7 @@ for more information.
### `certificates.<name>.cert`:
**Type**: string | bool
**Type**: `string | boolean`
Set custom certificate authority for repository `<name>`.
See [Repositories - Configuring credentials - Custom certificate authority]({{< relref "repositories#custom-certificate-authority-and-mutual-tls-authentication" >}})
......@@ -368,7 +397,7 @@ repository.
### `certificates.<name>.client-cert`:
**Type**: string
**Type**: `string`
Set client certificate for repository `<name>`.
See [Repositories - Configuring credentials - Custom certificate authority]({{< relref "repositories#custom-certificate-authority-and-mutual-tls-authentication" >}})
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment