@@ -68,7 +68,7 @@ If you want to add dependencies to your project, you can specify them in the `to
...
@@ -68,7 +68,7 @@ If you want to add dependencies to your project, you can specify them in the `to
```toml
```toml
[tool.poetry.dependencies]
[tool.poetry.dependencies]
pendulum="^1.4"
pendulum="^2.1"
```
```
As you can see, it takes a mapping of **package names** and **version constraints**.
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
...
@@ -82,7 +82,7 @@ Also, instead of modifying the `pyproject.toml` file by hand, you can use the `a
$ poetry add pendulum
$ 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
## Using your virtual environment
...
@@ -137,8 +137,8 @@ To deactivate this virtual environment simply use `deactivate`.
...
@@ -137,8 +137,8 @@ To deactivate this virtual environment simply use `deactivate`.
### Version constraints
### Version constraints
In our example, we are requesting the `pendulum` package with the version constraint `^1.4`.
In our example, we are requesting the `pendulum` package with the version constraint `^2.1`.
This means any version greater or equal to 1.4.0 and less than 2.0.0 (`>=1.4.0 <2.0.0`).
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,
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.
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.
...
@@ -159,7 +159,7 @@ for the version constraint you have specified.
## Installing dependencies
## 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
```bash
poetry install
poetry install
...
@@ -172,7 +172,7 @@ When you run this command, one of two things may happen:
...
@@ -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,
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.
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.
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).
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
...
@@ -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.
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,
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
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.
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
### Commit your `poetry.lock` file to version control
Poetry provides a way to **organize** your dependencies by **groups**. For instance, you might have
dependencies that are only needed to test your project or to build the documentation.
To declare a new dependency group, use a `tool.poetry.group.<group>` section
where `<group>` 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="*"
```
Optional groups can be installed in addition to the **default** dependencies by using the `--with`
option of the [`install`]({{<relref"cli#install">}}) command.
```bash
poetry install --with docs
```
{{% warning %}}
Optional group dependencies will **still** be resolved alongside 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 --grouptest
```
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 --withouttest,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
