Skip to content

P
python-poetry
Commit 7ad55b5c by Arun Babu Neelicattu
Options

doc: improve dependency group related documentation

parent c7fc93bc
Showing with 47 additions and 22 deletions
docs/cli.md
...@@ -215,10 +215,10 @@ option is used. ...@@ -215,10 +215,10 @@ option is used.
### Options ### Options
* `--without`: The dependency groups to ignore for installation. * `--without`: The dependency groups to ignore.
* `--with`: The optional dependency groups to include for installation. * `--with`: The optional dependency groups to include.
* `--only`: The only dependency groups to install. * `--only`: The only dependency groups to include.
* `--default`: Only install the default dependencies. * `--default`: Only include the default dependencies. (**Deprecated**)
* `--sync`: Synchronize the environment with the locked packages and the specified groups. * `--sync`: Synchronize the environment with the locked packages and the specified groups.
* `--no-root`: Do not install the root package (your project). * `--no-root`: Do not install the root package (your project).
* `--dry-run`: Output the operations but do not execute anything (implicitly enables --verbose). * `--dry-run`: Output the operations but do not execute anything (implicitly enables --verbose).
...@@ -227,6 +227,9 @@ option is used. ...@@ -227,6 +227,9 @@ option is used.
* `--dev-only`: Only install dev dependencies. (**Deprecated**) * `--dev-only`: Only install dev dependencies. (**Deprecated**)
* `--remove-untracked`: Remove dependencies not presented in the lock file. (**Deprecated**) * `--remove-untracked`: Remove dependencies not presented in the lock file. (**Deprecated**)
{{% note %}}
When `--only` is specified, `--with` and `--without` options are ignored.
{{% /note %}}
## update ## update
...@@ -252,10 +255,18 @@ update the constraint, for example `^2.3`. You can do this using the `add` comma ...@@ -252,10 +255,18 @@ update the constraint, for example `^2.3`. You can do this using the `add` comma
### Options ### Options
* `--without`: The dependency groups to ignore.
* `--with`: The optional dependency groups to include.
* `--only`: The only dependency groups to include.
* `--default`: Only include the default dependencies. (**Deprecated**)
* `--dry-run` : Outputs the operations but will not execute anything (implicitly enables --verbose). * `--dry-run` : Outputs the operations but will not execute anything (implicitly enables --verbose).
* `--no-dev` : Do not install dev dependencies. * `--no-dev` : Do not update the development dependencies. (**Deprecated**)
* `--lock` : Do not perform install (only update the lockfile). * `--lock` : Do not perform install (only update the lockfile).
{{% note %}}
When `--only` is specified, `--with` and `--without` options are ignored.
{{% /note %}}
## add ## add
The `add` command adds required packages to your `pyproject.toml` and installs them. The `add` command adds required packages to your `pyproject.toml` and installs them.
...@@ -425,15 +436,18 @@ required by ...@@ -425,15 +436,18 @@ required by
### Options ### Options
* `--without`: Do not show the information of the specified groups' dependencies. * `--without`: The dependency groups to ignore.
* `--with`: Show the information of the specified optional groups' dependencies as well. * `--with`: The optional dependency groups to include.
* `--only`: Only show the information of dependencies belonging to the specified groups. * `--only`: The only dependency groups to include.
* `--default`: Only show the information of the default dependencies. * `--default`: Only include the default dependencies. (**Deprecated**)
* `--no-dev`: Do not list the dev dependencies. * `--no-dev`: Do not list the dev dependencies. (**Deprecated**)
* `--tree`: List the dependencies as a tree. * `--tree`: List the dependencies as a tree.
* `--latest (-l)`: Show the latest version. * `--latest (-l)`: Show the latest version.
* `--outdated (-o)`: Show the latest version but only for packages that are outdated. * `--outdated (-o)`: Show the latest version but only for packages that are outdated.
{{% note %}}
When `--only` is specified, `--with` and `--without` options are ignored.
{{% /note %}}
## build ## build
......
docs/managing-dependencies.md
...@@ -36,6 +36,7 @@ on whether their dependencies will be resolved and installed **by default**, the ...@@ -36,6 +36,7 @@ on whether their dependencies will be resolved and installed **by default**, the
the dependencies logically. the dependencies logically.
{{% /note %}} {{% /note %}}
{{% note %}}
The dependencies declared in `tool.poetry.dependencies` are part of an implicit `default` group. The dependencies declared in `tool.poetry.dependencies` are part of an implicit `default` group.
```toml ```toml
...@@ -47,6 +48,7 @@ pendulum = "*" ...@@ -47,6 +48,7 @@ pendulum = "*"
pytest = "^6.0.0" pytest = "^6.0.0"
pytest-mock = "*" pytest-mock = "*"
``` ```
{{% /note %}}
{{% note %}} {{% note %}}
**A note about the `dev-dependencies` section** **A note about the `dev-dependencies` section**
...@@ -109,7 +111,14 @@ If the group does not already exist, it will be created automatically. ...@@ -109,7 +111,14 @@ If the group does not already exist, it will be created automatically.
### Installing group dependencies ### Installing group dependencies
**By default**, dependencies across **all groups** will be installed when executing `poetry install`. **By default**, dependencies across **all non-optional groups** will be installed when executing
`poetry install`.
{{% note %}}
The default set of dependencies for a project includes the implicit `default` group defined in
`tool.poetry.dependencies` as well as all groups that are not explicitly marked as an
[optional group]({{< relref "#optional-groups" >}}).
{{% /note %}}
You can **exclude** one or more groups with the `--without` option: You can **exclude** one or more groups with the `--without` option:
...@@ -123,20 +132,22 @@ You can also opt in [optional groups]({{< relref "#optional-groups" >}}) by usin ...@@ -123,20 +132,22 @@ You can also opt in [optional groups]({{< relref "#optional-groups" >}}) by usin
poetry install --with docs poetry install --with docs
``` ```
If you only want to install the **default**, non-grouped, dependencies, you can do so Finally, in some case you might want to install **only specific groups** of dependencies
with the `--default` option: without installing the default set of dependencies. For that purpose, you can use
the `--only` option.
```bash ```bash
poetry install --default poetry install --only docs
``` ```
Finally, in some case you might want to install **only specific groups** of dependencies {{% note %}}
without installing the default dependencies. For that purpose, you can use If you only want to install the project's runtime dependencies, you can do so with the
the `--only` option. `--only default` notation:
```bash ```bash
poetry install --only docs poetry install --only default
``` ```
{{% /note %}}
### Removing dependencies from a group ### Removing dependencies from a group
......
src/poetry/console/commands/group_command.py
...@@ -20,27 +20,27 @@ class GroupCommand(EnvCommand): ...@@ -20,27 +20,27 @@ class GroupCommand(EnvCommand):
option( option(
"without", "without",
None, None,
"The dependency groups to ignore for installation.", "The dependency groups to ignore.",
flag=False, flag=False,
multiple=True, multiple=True,
), ),
option( option(
"with", "with",
None, None,
"The optional dependency groups to include for installation.", "The optional dependency groups to include.",
flag=False, flag=False,
multiple=True, multiple=True,
), ),
option( option(
"default", "default",
None, None,
"Only install the default dependencies." "Only include the default dependencies."
" (<warning>Deprecated</warning>)", " (<warning>Deprecated</warning>)",
), ),
option( option(
"only", "only",
None, None,
"The only dependency groups to install.", "The only dependency groups to include.",
flag=False, flag=False,
multiple=True, multiple=True,
), ),
......
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