Skip to content

Commit

Permalink
docs: wip update dependency-specification.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@finswimmer
finswimmer committed Nov 27, 2024
1 parent cb41d4f commit 286cfa9
Showing 1 changed file with 120 additions and 111 deletions.
231 changes: 120 additions & 111 deletions docs/dependency-specification.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -84,31 +84,6 @@ must still be specified in the `tool.poetry` section.

## Version constraints

{{% warning %}}
Some of the following constraints can only be used in `tool.poetry.dependencies` and not in `project.dependencies`.
When using `poetry add` such constraints are automatically converted into an equivalent constraint.
{{% /warning %}}

### Caret requirements

{{% warning %}}
Not supported in `project.dependencies`.
{{% /warning %}}

**Caret requirements** allow [SemVer](https://semver.org/) compatible updates to a specified version. An update is allowed if the new version number does not modify the left-most non-zero digit in the major, minor, patch grouping. For instance, if we previously ran `poetry add requests@^2.13.0` and wanted to update the library and ran `poetry update requests`, poetry would update us to version `2.14.0` if it was available, but would not update us to `3.0.0`. If instead we had specified the version string as `^0.1.13`, poetry would update to `0.1.14` but not `0.2.0`. `0.0.x` is not considered compatible with any other version.

Here are some more examples of caret requirements and the versions that would be allowed with them:

| Requirement | Versions allowed |
| ----------- | ---------------- |
| ^1.2.3 | >=1.2.3 <2.0.0 |
| ^1.2 | >=1.2.0 <2.0.0 |
| ^1 | >=1.0.0 <2.0.0 |
| ^0.2.3 | >=0.2.3 <0.3.0 |
| ^0.0.3 | >=0.0.3 <0.0.4 |
| ^0.0 | >=0.0.0 <0.1.0 |
| ^0 | >=0.0.0 <1.0.0 |

### Compatible release requirements

**Compatible release requirements** specify a minimal version with the ability to update to later versions of the same level.
Expand All @@ -122,24 +97,6 @@ If you only specify a major, and minor version, then minor- and patch-level chan
| ~=1.2.3 | >=1.2.3 <1.3.0 |
| ~=1.2 | >=1.2.0 <2.0.0 |

### Tilde requirements

{{% warning %}}
Not supported in `project.dependencies`.
{{% /warning %}}

**Tilde requirements** specify a minimal version with some ability to update.
If you specify a major, minor, and patch version or only a major and minor version, only patch-level changes are allowed.
If you only specify a major version, then minor- and patch-level changes are allowed.

`~1.2.3` is an example of a tilde requirement.

| Requirement | Versions allowed |
| ----------- | ---------------- |
| ~1.2.3 | >=1.2.3 <1.3.0 |
| ~1.2 | >=1.2.0 <1.3.0 |
| ~1 | >=1.0.0 <2.0.0 |

### Wildcard requirements

**Wildcard requirements** allow for the latest (dependency dependent) version where the wildcard is positioned.
Expand Down Expand Up @@ -182,29 +139,77 @@ Exact versions can also be specified with `==` according to [PEP 440](https://pe

`==1.2.3` is an example of this.

### Caret requirements

{{% warning %}}
Not supported in `project.dependencies`.

When using `poetry add` such constraints are automatically converted into an equivalent constraint.
{{% /warning %}}

**Caret requirements** allow [SemVer](https://semver.org/) compatible updates to a specified version. An update is allowed if the new version number does not modify the left-most non-zero digit in the major, minor, patch grouping. For instance, if we previously ran `poetry add requests@^2.13.0` and wanted to update the library and ran `poetry update requests`, poetry would update us to version `2.14.0` if it was available, but would not update us to `3.0.0`. If instead we had specified the version string as `^0.1.13`, poetry would update to `0.1.14` but not `0.2.0`. `0.0.x` is not considered compatible with any other version.

Here are some more examples of caret requirements and the versions that would be allowed with them:

| Requirement | Versions allowed |
| ----------- | ---------------- |
| ^1.2.3 | >=1.2.3 <2.0.0 |
| ^1.2 | >=1.2.0 <2.0.0 |
| ^1 | >=1.0.0 <2.0.0 |
| ^0.2.3 | >=0.2.3 <0.3.0 |
| ^0.0.3 | >=0.0.3 <0.0.4 |
| ^0.0 | >=0.0.0 <0.1.0 |
| ^0 | >=0.0.0 <1.0.0 |

### Tilde requirements

{{% warning %}}
Not supported in `project.dependencies`.

When using `poetry add` such constraints are automatically converted into an equivalent constraint.
{{% /warning %}}

**Tilde requirements** specify a minimal version with some ability to update.
If you specify a major, minor, and patch version or only a major and minor version, only patch-level changes are allowed.
If you only specify a major version, then minor- and patch-level changes are allowed.

`~1.2.3` is an example of a tilde requirement.

| Requirement | Versions allowed |
| ----------- | ---------------- |
| ~1.2.3 | >=1.2.3 <1.3.0 |
| ~1.2 | >=1.2.0 <1.3.0 |
| ~1 | >=1.0.0 <2.0.0 |

### Using 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:

```shell
poetry add django@^4.0.0
poetry add "django@>=4.0.0"
```

The above would translate to the following entry in `pyproject.toml`:
```toml
Django = "^4.0.0"
dependencies = [
"django (>=4.0.0)"
]

```

The special keyword `latest` is also understood by the `@` operator:
```shell
poetry add django@latest
```

The above would translate to the following entry in `pyproject.toml`, assuming the latest release of `django` is `4.0.5`:
The above would translate to the following entry in `pyproject.toml`, assuming the latest release of `django` is `5.1.3`:
```toml
Django = "^4.0.5"
dependencies = [
"django (>=5.1.3,<6.0.0)"
]

```

#### Extras
Expand All @@ -220,13 +225,6 @@ poetry add django[bcrypt]@^4.0.0
To depend on a library located in a `git` repository,
the minimum information you need to specify is the location of the repository with the git key:

```toml
[tool.poetry.dependencies]
requests = { git = "https://github.com/requests/requests.git" }
```

or in the `project` section:

```toml
[project]
# ...
Expand All @@ -235,25 +233,18 @@ dependencies = [
]
```

Since we haven’t specified any other information,
Poetry assumes that we intend to use the latest commit on the `main` branch
to build our project.

You can combine the `git` key with the `branch` key to use another branch.
Alternatively, use `rev` or `tag` to pin a dependency to a specific commit hash
or tagged ref, respectively. For example:
or in the `tool.poetry` section:

```toml
[tool.poetry.dependencies]
# Get the latest revision on the branch named "next"
requests = { git = "https://github.com/kennethreitz/requests.git", branch = "next" }
# Get a revision by its commit hash
flask = { git = "https://github.com/pallets/flask.git", rev = "38eb5d3b" }
# Get a revision by its tag
numpy = { git = "https://github.com/numpy/numpy.git", tag = "v0.13.2" }
requests = { git = "https://github.com/requests/requests.git" }
```

or in the `project` section:
Since we haven’t specified any other information,
Poetry assumes that we intend to use the latest commit on the `main` branch
to build our project.

To use another branch, commit hash or tagged ref append this information to the git url:

```toml
[project]
Expand All @@ -265,6 +256,19 @@ dependencies = [
]
```

or combine the `git` key with the `branch`, `rev` or `tag` key respectively in the
`tool.poetry` section. For example:

```toml
[tool.poetry.dependencies]
# Get the latest revision on the branch named "next"
requests = { git = "https://github.com/kennethreitz/requests.git", branch = "next" }
# Get a revision by its commit hash
flask = { git = "https://github.com/pallets/flask.git", rev = "38eb5d3b" }
# Get a revision by its tag
numpy = { git = "https://github.com/numpy/numpy.git", tag = "v0.13.2" }
```

In cases where the package you want to install is located in a subdirectory of the VCS repository, you can use the `subdirectory` option, similarly to what [pip](https://pip.pypa.io/en/stable/topics/vcs-support/#url-fragments) provides:

```toml
Expand All @@ -281,9 +285,19 @@ poetry add "git+https://github.com/myorg/mypackage_with_subdirs.git#subdirectory

To use an SSH connection, for example in the case of private repositories, use the following example syntax:

```toml
[project]
# ...
dependencies = [
"pendulum @ git+ssh://git@github.com/sdispater/pendulum.git"
]
```

or

```toml
[tool.poetry.dependencies]
requests = { git = "git@github.com:requests/requests.git" }
pendulum = { git = "git@github.com/sdispater/pendulum.git" }
```

To use HTTP basic authentication with your git repositories, you can configure credentials similar to
Expand All @@ -296,22 +310,18 @@ poetry add git+https://github.com/org/project.git
```

{{% note %}}
With Poetry 1.2 releases, the default git client used is [Dulwich](https://www.dulwich.io/).
The default git client used is [Dulwich](https://www.dulwich.io/).

We fall back to legacy system git client implementation in cases where
[gitcredentials](https://git-scm.com/docs/gitcredentials) is used. This fallback will be removed in
a future release where `gitcredentials` helpers can be better supported natively.

In cases where you encounter issues with the default implementation that used to work prior to
Poetry 1.2, you may wish to explicitly configure the use of the system git client via a shell
subprocess call.
In cases where you encounter issues with the default implementation, you may wish to
explicitly configure the use of the system git client via a shell subprocess call.

```bash
poetry config system-git-client true
```

Keep in mind however, that doing so will surface bugs that existed in versions prior to 1.2 which
were caused due to the use of the system git client.
{{% /note %}}

## `path` dependencies
Expand Down Expand Up @@ -375,13 +385,6 @@ poetry add https://example.com/my-package-0.1.0.tar.gz
You can specify [PEP-508 Extras](https://www.python.org/dev/peps/pep-0508/#extras)
for a dependency as shown here.

```toml
[tool.poetry.dependencies]
gunicorn = { version = "^20.1", extras = ["gevent"] }
```

or in the `project` section:

```toml
[project]
# ...
Expand All @@ -390,6 +393,13 @@ dependencies = [
]
```

or in the `tool.poetry` section:

```toml
[tool.poetry.dependencies]
gunicorn = { version = "^20.1", extras = ["gevent"] }
```

{{% note %}}
These activate extra defined for the dependency, to configure an optional dependency
for extras in your project refer to [`extras`]({{< relref "pyproject#extras" >}}).
Expand Down Expand Up @@ -429,18 +439,6 @@ It is not possible to define source dependencies in the `project` section.

You can also specify that a dependency should be installed only for specific Python versions:

```toml
[tool.poetry.dependencies]
tomli = { version = "^2.0.1", python = "<3.11" }
```

```toml
[tool.poetry.dependencies]
pathlib2 = { version = "^2.2", python = "^3.9" }
```

or in the `project` section:

```toml
[project]
# ...
Expand All @@ -450,18 +448,22 @@ dependencies = [
]
```

## Using environment markers
or in the `tool.poetry` section:

If you need more complex install conditions for your dependencies,
Poetry supports [environment markers](https://www.python.org/dev/peps/pep-0508/#environment-markers)
via the `markers` property:
```toml
[tool.poetry.dependencies]
tomli = { version = "^2.0.1", python = "<3.11" }
```

```toml
[tool.poetry.dependencies]
pathlib2 = { version = "^2.2", markers = "python_version <= '3.4' or sys_platform == 'win32'" }
pathlib2 = { version = "^2.2", python = "^3.9" }
```

or in the `project` section:
## Using environment markers

If you need more complex install conditions for your dependencies,
Poetry supports [environment markers](https://www.python.org/dev/peps/pep-0508/#environment-markers):

```toml
[project]
Expand All @@ -471,6 +473,13 @@ dependencies = [
]
```

or in the `tool.poetry` section via the `markers` property:

```toml
[tool.poetry.dependencies]
pathlib2 = { version = "^2.2", markers = "python_version <= '3.4' or sys_platform == 'win32'" }
```

## Multiple constraints dependencies

Sometimes, one of your dependency may have different version ranges depending
Expand All @@ -480,16 +489,6 @@ Let's say you have a dependency on the package `foo` which is only compatible
with Python 3.6-3.7 up to version 1.9, and compatible with Python 3.8+ from version 2.0:
you would declare it like so:

```toml
[tool.poetry.dependencies]
foo = [
{version = "<=1.9", python = ">=3.6,<3.8"},
{version = "^2.0", python = ">=3.8"}
]
```

or in the `project` section:

```toml
[project]
# ...
Expand All @@ -499,6 +498,16 @@ dependencies = [
]
```

or in the `tool.poetry` section:

```toml
[tool.poetry.dependencies]
foo = [
{version = "<=1.9", python = ">=3.6,<3.8"},
{version = "^2.0", python = ">=3.8"}
]
```

{{% note %}}
The constraints **must** have different requirements (like `python`)
otherwise it will cause an error when resolving dependencies.
Expand Down

0 comments on commit 286cfa9

Please sign in to comment.