From f631c2c029521508b5d2c7779cdbfc8a0f1ad545 Mon Sep 17 00:00:00 2001 From: Bartek Sokorski Date: Fri, 10 Jun 2022 01:18:45 +0200 Subject: [PATCH 1/5] docs: Add paragraph about @ operator --- docs/dependency-specification.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/dependency-specification.md b/docs/dependency-specification.md index 0bb79368724..da225b8164e 100644 --- a/docs/dependency-specification.md +++ b/docs/dependency-specification.md @@ -77,10 +77,25 @@ You can specify the exact version of a package. This will tell Poetry to install this version and this version only. If other dependencies require a different version, the solver will ultimately fail and abort any install or update procedures. -#### Multiple requirements +### Multiple requirements Multiple version requirements can also be separated with a comma, e.g. `>= 1.2, < 1.5`. +### `@` operator + +You can specify requirements, using `@` operator. This is understood the same way as `==` specifier, with one difference. +After `@` symbol, you can use any specifiers that are valid in `pyproject.toml` file. For example: + +```shell +poetry add django@^4.0.0 +``` + +Would translate to following entry in `pyproject.toml`: +```toml +Django = "^4.0.0" +``` + + ## `git` dependencies To depend on a library located in a `git` repository, From 80a1d7f53830e56b7d3e8c481c6b7ae9b9022037 Mon Sep 17 00:00:00 2001 From: Bartek Sokorski Date: Sat, 11 Jun 2022 14:31:25 +0200 Subject: [PATCH 2/5] Add more information about @ operator and fix grammar --- docs/dependency-specification.md | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/docs/dependency-specification.md b/docs/dependency-specification.md index da225b8164e..e1422551dd9 100644 --- a/docs/dependency-specification.md +++ b/docs/dependency-specification.md @@ -81,20 +81,38 @@ If other dependencies require a different version, the solver will ultimately fa Multiple version requirements can also be separated with a comma, e.g. `>= 1.2, < 1.5`. -### `@` operator +### Using the `@` operator -You can specify requirements, using `@` operator. This is understood the same way as `==` specifier, with one difference. -After `@` symbol, you can use any specifiers that are valid in `pyproject.toml` file. For example: +You can specify requirements, using the `@` operator. This is understood the same way as `==` specifier, with one difference. +After the `@` operator, you can use any specifiers that are valid in `pyproject.toml` file. For example: ```shell poetry add django@^4.0.0 ``` -Would translate to following entry in `pyproject.toml`: +Would translate to the following entry in `pyproject.toml`: ```toml Django = "^4.0.0" ``` +This operator, can also be used with in conjunction with word `latest`, to specify latest available version. +For example: +```shell +poetry add django@latest +``` + +Would translate to the following entry in `pyproject.toml`: +```toml +Django = "^4.0.5" +``` + +#### Extras + +To use extras for package using the `@` operator, formula is: `package[extra]@version`, for example: + +```shell +poetry add django[bcrypt]@^4.0.0 +``` ## `git` dependencies From 29f272d101e2021f33dd767fe9a9322168df51bc Mon Sep 17 00:00:00 2001 From: Bartek Sokorski Date: Sun, 19 Jun 2022 15:58:47 +0200 Subject: [PATCH 3/5] Add info about @ being CLI only --- docs/cli.md | 4 ++++ docs/dependency-specification.md | 5 +++-- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index 8898a0c585f..aa2f9361116 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -304,6 +304,10 @@ poetry add "pendulum>=2.0.5" poetry add pendulum==2.0.5 ``` +{{% note %}} +See the [Dependency specification]({{< relref "dependency-specification#using-the--operator" >}}) page for more information about `@` operator. +{{% /note %}} + If you try to add a package that is already present, you will get an error. However, if you specify a constraint, like above, the dependency will be updated by using the specified constraint. diff --git a/docs/dependency-specification.md b/docs/dependency-specification.md index 9576f560c9a..ab29c82d385 100644 --- a/docs/dependency-specification.md +++ b/docs/dependency-specification.md @@ -86,8 +86,9 @@ If other dependencies require a different version, the solver will ultimately fa ### Using the `@` operator -You can specify requirements, using the `@` operator. This is understood the same way as `==` specifier, with one difference. -After the `@` operator, you can use any specifiers that are valid in `pyproject.toml` file. For example: +When adding dependencies via CLI `add` command, you can use `@` operator. +This is understood the same way as `==` specifier, with one difference. After the `@` operator, you can use any +specifiers that are valid in `pyproject.toml` file. For example: ```shell poetry add django@^4.0.0 From f5ee414738a4b742a71249111b394370e767b104 Mon Sep 17 00:00:00 2001 From: Bartosz Sokorski Date: Sun, 19 Jun 2022 22:04:11 +0200 Subject: [PATCH 4/5] Apply suggestions from code review Co-authored-by: Bjorn Neergaard Co-authored-by: Bjorn Neergaard --- docs/cli.md | 2 +- docs/dependency-specification.md | 15 +++++++-------- 2 files changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index aa2f9361116..f1192f52ae0 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -305,7 +305,7 @@ poetry add pendulum==2.0.5 ``` {{% note %}} -See the [Dependency specification]({{< relref "dependency-specification#using-the--operator" >}}) page for more information about `@` operator. +See the [Dependency specification]({{< relref "dependency-specification#using-the--operator" >}}) page for more information about the `@` operator. {{% /note %}} If you try to add a package that is already present, you will get an error. diff --git a/docs/dependency-specification.md b/docs/dependency-specification.md index ab29c82d385..094a244df83 100644 --- a/docs/dependency-specification.md +++ b/docs/dependency-specification.md @@ -86,33 +86,32 @@ If other dependencies require a different version, the solver will ultimately fa ### Using the `@` operator -When adding dependencies via CLI `add` command, you can use `@` operator. -This is understood the same way as `==` specifier, with one difference. After the `@` operator, you can use any -specifiers that are valid in `pyproject.toml` file. For example: +When adding dependencies via CLI `add` command, you can use the `@` operator. +This is understood similarly to the `==` syntax, but also allows prefixing any +specifiers that are valid in `pyproject.toml`. For example: ```shell poetry add django@^4.0.0 ``` -Would translate to the following entry in `pyproject.toml`: +The above would translate to the following entry in `pyproject.toml`: ```toml Django = "^4.0.0" ``` -This operator, can also be used with in conjunction with word `latest`, to specify latest available version. -For example: +The special keyword `latest` is also understood by the `@` operator: ```shell poetry add django@latest ``` -Would translate to the following entry in `pyproject.toml`: +The above would translate to the following entry in `pyproject.toml`, assuming the latest release of `django` is `4.0.5`: ```toml Django = "^4.0.5" ``` #### Extras -To use extras for package using the `@` operator, formula is: `package[extra]@version`, for example: +Extras and `@` can be combined as one might expect (`package[extra]@version`): ```shell poetry add django[bcrypt]@^4.0.0 From bf387a328e5d7f937d52d4ba6c59abe1a58fb0b4 Mon Sep 17 00:00:00 2001 From: Bjorn Neergaard Date: Sun, 19 Jun 2022 16:15:08 -0600 Subject: [PATCH 5/5] Update docs/dependency-specification.md --- docs/dependency-specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dependency-specification.md b/docs/dependency-specification.md index 094a244df83..2feeb6e5563 100644 --- a/docs/dependency-specification.md +++ b/docs/dependency-specification.md @@ -86,7 +86,7 @@ If other dependencies require a different version, the solver will ultimately fa ### Using the `@` operator -When adding dependencies via CLI `add` command, you can use the `@` operator. +When adding dependencies via `poetry add`, you can use the `@` operator. This is understood similarly to the `==` syntax, but also allows prefixing any specifiers that are valid in `pyproject.toml`. For example: