From 2d453e07c69e9e194e71f03d03bdc2fcf136241f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Eustace?= Date: Wed, 7 Jul 2021 11:26:31 +0200 Subject: [PATCH] Update the documentation --- docs/basic-usage.md | 18 ++-- docs/cli.md | 68 ++++++++++++--- docs/dependency-specification.md | 8 +- docs/managing-dependencies.md | 141 +++++++++++++++++++++++++++++++ docs/pyproject.md | 21 ++++- 5 files changed, 228 insertions(+), 28 deletions(-) create mode 100644 docs/managing-dependencies.md diff --git a/docs/basic-usage.md b/docs/basic-usage.md index 1b7dbf764f5..ebf024163d0 100644 --- a/docs/basic-usage.md +++ b/docs/basic-usage.md @@ -48,8 +48,8 @@ authors = ["Sébastien Eustace "] [tool.poetry.dependencies] python = "*" -[tool.poetry.dev-dependencies] -pytest = "^3.4" +[tool.poetry.group.dev.dependencies] +pytest = "^6.0" ``` ### Initialising a pre-existing project @@ -68,7 +68,7 @@ If you want to add dependencies to your project, you can specify them in the `to ```toml [tool.poetry.dependencies] -pendulum = "^1.4" +pendulum = "^2.1" ``` As you can see, it takes a mapping of **package names** and **version constraints**. @@ -82,7 +82,7 @@ Also, instead of modifying the `pyproject.toml` file by hand, you can use the `a $ poetry add pendulum ``` -It will automatically find a suitable version constraint **and install** the package and subdependencies. +It will automatically find a suitable version constraint **and install** the package and sub-dependencies. ## Using your virtual environment @@ -137,8 +137,8 @@ To deactivate this virtual environment simply use `deactivate`. ### Version constraints -In our example, we are requesting the `pendulum` package with the version constraint `^1.4`. -This means any version greater or equal to 1.4.0 and less than 2.0.0 (`>=1.4.0 <2.0.0`). +In our example, we are requesting the `pendulum` package with the version constraint `^2.1`. +This means any version greater or equal to 2.1.0 and less than 3.0.0 (`>=2.1.0 <3.0.0`). Please read [Dependency specification]({{< relref "dependency-specification" >}} "Dependency specification documentation") for more in-depth information on versions, how versions relate to each other, and on the different ways you can specify dependencies. @@ -159,7 +159,7 @@ for the version constraint you have specified. ## Installing dependencies -To install the defined dependencies for your project, just run the `install` command. +To install the defined dependencies for your project, just run the [`install`]({{< relref "cli#install" >}}) command. ```bash poetry install @@ -172,7 +172,7 @@ When you run this command, one of two things may happen: If you have never run the command before and there is also no `poetry.lock` file present, Poetry simply resolves all dependencies listed in your `pyproject.toml` file and downloads the latest version of their files. -When Poetry has finished installing, it writes all of the packages and the exact versions of them that it downloaded to the `poetry.lock` file, +When Poetry has finished installing, it writes all the packages and their exact versions that it downloaded to the `poetry.lock` file, locking the project to those specific versions. You should commit the `poetry.lock` file to your project repo so that all people working on the project are locked to the same versions of dependencies (more below). @@ -187,7 +187,7 @@ Either way, running `install` when a `poetry.lock` file is present resolves and but Poetry uses the exact versions listed in `poetry.lock` to ensure that the package versions are consistent for everyone working on your project. As a result you will have all dependencies requested by your `pyproject.toml` file, but they may not all be at the very latest available versions -(some of the dependencies listed in the `poetry.lock` file may have released newer versions since the file was created). +(some dependencies listed in the `poetry.lock` file may have released newer versions since the file was created). This is by design, it ensures that your project does not break because of unexpected changes in dependencies. ### Commit your `poetry.lock` file to version control diff --git a/docs/cli.md b/docs/cli.md index 0a1b8a265af..62f4be8af0e 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -133,20 +133,36 @@ This ensures that everyone using the library will get the same versions of the d If there is no `poetry.lock` file, Poetry will create one after dependency resolution. -You can specify to the command that you do not want the development dependencies installed by passing -the `--no-dev` option. +If you want to exclude one or more dependency group for the installation, you can use +the `--without` option. ```bash -poetry install --no-dev +poetry install --without test,docs ``` -Conversely, you can specify to the command that you only want to install the development dependencies -by passing the `--dev-only` option. Note that `--no-dev` takes priority if both options are passed. +{{% note %}} +The `--no-dev` option is now deprecated. You should use the `--without dev` notation instead. +{{% /note %}} + +You can also select optional dependency groups with the `--with` option. ```bash -poetry install --dev-only +poetry install --with test,docs ``` +It's also possible to only install specific dependency groups by using the `only` option. + +```bash +poetry install --only test,docs +``` + +{{% note %}} +The `--dev-only` option is now deprecated. You should use the `--only dev` notation instead. +{{% /note %}} + +See [Dependency groups]({{< relref "managing-dependencies#dependency-groups" >}}) for more information +about dependency groups. + If you want to remove old dependencies no longer present in the lock file, use the `--remove-untracked` option. @@ -179,13 +195,17 @@ If you want to skip this installation, use the `--no-root` option. poetry install --no-root ``` -Installation of your project's package is also skipped when the `--dev-only` -option is passed. +Installation of your project's package is also skipped when the `--only` +option is used. ### Options -* `--no-dev`: Do not install dev dependencies. -* `--dev-only`: Only install dev dependencies. +* `--without`: The dependency groups to ignore for installation. +* `--with`: The optional dependency groups to include for installation. +* `--only`: The only dependency groups to install. +* `--default`: Only install the default dependencies. +* `--no-dev`: Do not install dev dependencies. (**Deprecated**) +* `--dev-only`: Only install dev dependencies. (**Deprecated**) * `--no-root`: Do not install the root package (your project). * `--dry-run`: Output the operations but do not execute anything (implicitly enables --verbose). * `--remove-untracked`: Remove dependencies not presented in the lock file @@ -311,9 +331,19 @@ poetry add "requests[security,socks]~=2.22.0" poetry add "git+https://github.com/pallets/flask.git@1.1.1[dotenv,dev]" ``` +If you want to add a package to a specific group of dependencies, you can use the `--group (-G)` option: + +```bash +poetry add mkdocs --group docs +``` + +See [Dependency groups]({{< relref "managing-dependencies#dependency-groups" >}}) for more information +about dependency groups. + ### Options -* `--dev (-D)`: Add package as development dependency. +* `--group (-D)`: The group to add the dependency to. +* `--dev (-D)`: Add package as development dependency. (**Deprecated**) * `--editable (-e)`: Add vcs/path dependencies as editable. * `--extras (-E)`: Extras to activate for the dependency. (multiple values allowed) * `--optional`: Add as an optional dependency. @@ -334,9 +364,19 @@ list of installed packages. poetry remove pendulum ``` +If you want to remove a package from a specific group of dependencies, you can use the `--group (-G)` option: + +```bash +poetry remove mkdocs --group docs +``` + +See [Dependency groups]({{< relref "managing-dependencies#dependency-groups" >}}) for more information +about dependency groups. + ### Options -* `--dev (-D)`: Removes a package from the development dependencies. +* `--group (-D)`: The group to remove the dependency from. +* `--dev (-D)`: Removes a package from the development dependencies. (**Deprecated**) * `--dry-run` : Outputs the operations but will not execute anything (implicitly enables --verbose). @@ -365,6 +405,10 @@ dependencies: ### Options +* `--without`: Do not show the information of the specified groups' dependencies. +* `--with`: Show the information of the specified optional groups' dependencies as well. +* `--only`: Only show the information of dependencies belonging to the specified groups. +* `--default`: Only show the information of the default dependencies. * `--no-dev`: Do not list the dev dependencies. * `--tree`: List the dependencies as a tree. * `--latest (-l)`: Show the latest version. diff --git a/docs/dependency-specification.md b/docs/dependency-specification.md index e2fa0e4e021..e8b865da340 100644 --- a/docs/dependency-specification.md +++ b/docs/dependency-specification.md @@ -210,21 +210,21 @@ you can shift from using "inline table" syntax, to the "standard table" syntax. An example where this might be useful is the following: ```toml -[tool.poetry.dev-dependencies] +[tool.poetry.group.dev.dependencies] black = {version = "19.10b0", allow-prereleases = true, python = "^3.6", markers = "platform_python_implementation == 'CPython'"} ``` -As a single line, this is a lot to digest. To make this a little bit easier to +As a single line, this is a lot to digest. To make this a bit easier to work with, you can do the following: ```toml -[tool.poetry.dev-dependencies.black] +[tool.poetry.group.dev.dependencies.black] version = "19.10b0" allow-prereleases = true python = "^3.6" markers = "platform_python_implementation == 'CPython'" ``` -All of the same information is still present, and ends up providing the exact +The same information is still present, and ends up providing the exact same specification. It's simply split into multiple, slightly more readable, lines. diff --git a/docs/managing-dependencies.md b/docs/managing-dependencies.md new file mode 100644 index 00000000000..6b4e3e254ca --- /dev/null +++ b/docs/managing-dependencies.md @@ -0,0 +1,141 @@ +--- +draft: false +layout: single +menu: + docs: + weight: 11 +title: Managing dependencies +type: docs +--- + + +# Managing dependencies + +## Dependency groups + +Poetry provides a way to **organize** your dependencies by **groups**. For instance, you might have +dependencies that are only needed to test you project or to build the documentation. + +To declare a new dependency group, use a `tool.poetry.group.` section +where `` is the name of your dependency group (for instance, `test`): + +```toml +[tool.poetry.group.test] # This part can be left out + +[tool.poetry.group.test.dependencies] +pytest = "^6.0.0" +pytest-mock = "*" +``` + +{{% note %}} +All dependencies **must be compatible with each other** across groups since they will +be resolved regardless of whether they are required for installation or not (see [Installing group dependencies]({{< relref "#installing-group-dependencies" >}})). + +Think of dependency groups as **labels** associated with your dependencies: they don't have any bearings +on whether their dependencies will be resolved and installed **by default**, they are simply a way to organize +the dependencies logically. +{{% /note %}} + +The dependencies declared in `tool.poetry.dependencies` are part of an implicit `default` group. + +```toml +[tool.poetry.dependencies] # Default dependency group +httpx = "*" +pendulum = "*" + +[tool.poetry.group.test.dependencies] +pytest = "^6.0.0" +pytest-mock = "*" +``` + +{{% note %}} +**A note about the `dev-dependencies` section** + +Any dependency declared in the `dev-dependencies` section will automatically be added to a `dev` group. +So the two following notations are equivalent: + +```toml +[tool.poetry.dev-dependencies] +pytest = "^6.0.0" +pytest-mock = "*" +``` + +```toml +[tool.poetry.group.dev.dependencies] +pytest = "^6.0.0" +pytest-mock = "*" +``` + +Poetry will slowly transition away from the `dev-dependencies` notation which will soon be deprecated, +so it's advised to migrate your existing development dependencies to the new `group` notation. +{{% /note %}} + +### Optional groups + +A dependency group can be declared as optional. This makes sense when you have +a group of dependencies that are only required in a particular environment or for +a specific purpose. + +```toml +[tool.poetry.group.docs] +optional = true + +[tool.poetry.group.docs.dependencies] +mkdocs = "*" +``` + +{{% warning %}} +Optional group dependencies will **still** be resolved along other dependencies, so +special care should be taken to ensure they are compatible with each other. +{{% /warning %}} + +### Adding a dependency to a group + +The [`add`]({{< relref "cli#add" >}}) command is the preferred way to add dependencies +to a group. This is done by using the `--group (-G)` option. + +```bash +poetry add pytest --group test +``` + +If the group does not already exist, it will be created automatically. + +### Installing group dependencies + +**By default**, dependencies across **all groups** will be installed when executing `poetry install`. + +You can **exclude** one or more groups with the `--without` option: + +```bash +poetry install --without test,docs +``` + +You can also opt in [optional groups]({{< relref "#optional-groups" >}}) by using the `--with` option: + +```bash +poetry install --with docs +``` + +If you only want to install the **default**, non-grouped, dependencies, you can do so +with the `--default` option: + +```bash +poetry install --default +``` + +Finally, in some case you might want to install **only specific groups** of dependencies +without installing the default dependencies. For that purpose, you can use +the `--only` option. + +```bash +poetry install --only docs +``` + +### Removing dependencies from a group + +The [`remove`]({{< relref "cli#remove" >}}) command supports a `--group` option +to remove packages from a specific group: + +```bash +poetry remove mkdocs --group docs +``` diff --git a/docs/pyproject.md b/docs/pyproject.md index e102bffc104..d7e75daa6f8 100644 --- a/docs/pyproject.md +++ b/docs/pyproject.md @@ -201,7 +201,7 @@ If no format is specified, it will default to include both `sdist` and `wheel`. exclude = ["my_package/excluded.py"] ``` -## `dependencies` and `dev-dependencies` +## dependencies and dependency groups Poetry is configured to look for dependencies on [PyPi](https://pypi.org) by default. Only the name and a version string are required in this case. @@ -211,7 +211,8 @@ Only the name and a version string are required in this case. requests = "^2.13.0" ``` -If you want to use a private repository, you can add it to your `pyproject.toml` file, like so: +If you want to use a [private repository]({{< relref "repositories#using-a-private-repository" >}}), +you can add it to your `pyproject.toml` file, like so: ```toml [[tool.poetry.source]] @@ -229,6 +230,20 @@ python = "^3.6" ``` {{% /note %}} +You can organize your dependencies in [groups]({{< relref "managing-dependencies#dependency-groups" >}}) +to manage them in a more granular way. + +```toml +[tool.poetry.group.test.dependencies] +pytest = "*" + +[tool.poetry.group.docs.dependencies] +mkdocs = "*" +``` + +See [Dependency groups]({{< relref "managing-dependencies#dependency-groups" >}}) for a more in-depth look +at how to manage dependency groups. + ## `scripts` This section describes the scripts or executables that will be installed when installing the package @@ -290,7 +305,7 @@ pip install awesome[databases] {{% note %}} The dependencies specified for each `extra` must already be defined as project dependencies. -Dependencies listed in the `dev-dependencies` section cannot be specified as extras. +Dependencies listed in [dependency groups]({{< relref "managing-dependencies#dependency-groups" >}}) cannot be specified as extras. {{% /note %}}