Update docs

```toml

[tool.poetry.dependencies]

requests = "^2.18"

pendulum = "^1.4"

```

As you can see, it takes a mapping of **package names** and **version constraints**.

```

It will automatically find a suitable version constraint.

### Version constraints

In our example, we are requesting the `pendulum` package with the version constraint `^1.4`.

This means any version geater or equal to 1.4.0 and less than 2.0.0 (`>=1.4.0 <2.0.0`).

Please read [versions](/versions/) for more in-depth information on versions, how versions relate to each other, and on version constraints.

!!!note

    **How does Poetry download the right files?**

    When you specify a dependency in `pyproject.toml`, Poetry first take the name of the package

    that you have requested and searches for it in any repository you have registered using the `repositories` key.

    If you have not registered any extra repositories, or it does not find a package with that name in the

    repositories you have specified, it falls bask on PyPI.

    When Poetry finds the right package, it then attempts to find the best match

    for the version constraint you have specified.

## Installing dependencies

To install the defined dependencies for your project, just run the `install` command.

```bash

poetry install

```

When you run this command, one of two things may happen:

### Installing without `pyproject.lock`

If you have never run the command before and there is also no `pyproject.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 `pyproject.lock` file,

locking the project to those specific versions.

You should commit the `pyproject.lock` file to your project repo so that all people working on the project are locked to the same versions of dependencies (more below).

### Installing with `pyproject.lock`

This brings us to the second scenario. If there is already a `pyproject.lock` file as well as a `pyproject.toml` file

when you run `poetry install`, it means either you ran the `install` command before,

or someone else on the project ran the `install` command and committed the `pyproject.lock` file to the project (which is good).

Either way, running `install` when a `pyproject.lock` file is present resolves and installs all dependencies that you listed in `pyproject.toml`,

but Poetry uses the exact versions listed in `pyproject.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 `pyproject.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 `pyproject.lock` file to version control

Committing this file to VC is important because it will cause anyone who sets up the project

to use the exact same versions of the dependencies that you are using.

Your CI server, production machines, other developers in your team,

everything and everyone runs on the same dependencies,

which mitigates the potential for bugs affecting only some parts of the deployments.

Even if you develop alone, in six months when reinstalling the project you can feel confident

the dependencies installed are still working even if your dependencies released many new versions since then.

(See note below about using the update command.)

!!!note

    For libraries it is not necessary to commit the lock file.

## Updating dependencies to their latest versions

As mentioned above, the `pyproject.lock` file prevents you from automatically getting the latest versions

of your dependencies.

To update to the latest versions, use the `update` command.

This will fetch the latest matching versions (according to your `pyproject.toml` file)

and update the lock file with the new versions.

(This is equivalent to deleting the `pyproject.lock` file and running `install` again.)

!!!note

    Poetry will display a Warning when executing an install command if `pyproject.lock` and `pyproject.toml`

    are not synchronized.

# Commands

You've already learned how to use the command-line interface to do some things.

This chapter documents all the available commands.

To get help from the command-line, simply call `poetry` or `poetry list` to see the complete list of commands,

then `--help` combined with any of those can give you more information.

As `Poetry` uses [cleo](https://github.com/sdispater/cleo) you can call commands by short name if it's not ambiguous.

```bash

poetry up

```

calls `poetry update`.

## Global options

* `--verbose (-v|vv|vvv)`: Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug.

* `--help (-h)` : Display help information.

* `--quiet (-q)` : Do not output any message.

* `--ansi`: Force ANSI output.

* `--no-ansi`: Disable ANSI output.

* `--version (-V)`: Display this application version.

## new

This command will help you kickstart your new Python project by creating

a directory structure suitable for most projects.

```bash

poetry new my-package

```

will create a folder as follows:

```text

my-package

├── pyproject.toml

├── README.rst

├── my_package

│   └── __init__.py

└── tests

    ├── __init__.py

    └── test_my_package

```

If you want to name your project differently than the folder, you can pass

the `--name` option:

```bash

poetry new my-folder --name my-package

```

## install

The `install` command reads the `pyproject.toml` file from the current directory, resolves the dependencies,

and installs them.

```bash

poetry install

```

If there is a `pyproject.lock` file in the current directory,

it will use the exact versions from there instead of resolving them.

This ensures that everyone using the library will get the same versions of the dependencies.

If there is no `pyproject.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.

```bash

poetry install --no-dev

```

You can also specify the extras you want installed

by passing the `--E|--extras` option (See [Extras](#extras) for more info)

```bash

poetry install --extras "mysql pgsql"

poetry install -E mysql -E pgsql

```

### Options

* `--no-dev`: Do not install dev dependencies.

* `--extras (-E)`: Features to install (multiple values allowed).

## update

In order to get the latest versions of the dependencies and to update the `pyproject.lock` file,

you should use the `update` command.

```bash

poetry update

```

This will resolve all dependencies of the project and write the exact versions into `pyproject.lock`.

If you just want to update a few packages and not all, you can list them as such:

```bash

poetry update requests toml

```

### Options

* `--dry-run` : Outputs the operations but will not execute anything (implicitly enables --verbose).

## add

The `add` command adds required packages to your `pyproject.toml` and installs them.

If you do not specify a version constraint,

poetry will choose a suitable one based on the available package versions.

```bash

poetry add requests pendulum

```

### Options

* `--dev (-D)`: Add package as development dependency.

* `--optional` : Add as an optional dependency.

* `--dry-run` : Outputs the operations but will not execute anything (implicitly enables --verbose).

## remove

The `remove` command removes a package from the current

list of installed packages

```bash

poetry remove pendulum

```

### Options

* `--dev (-D)`: Removes a package from the development dependencies.

* `--dry-run` : Outputs the operations but will not execute anything (implicitly enables --verbose).

## show

To list all of the available packages, you can use the `show` command.

```bash

poetry show

```

If you want to see the details of a certain package, you can pass the package name.

```bash

poetry show pendulum

name        : pendulum

version     : 1.4.2

description : Python datetimes made easy

dependencies:

 - python-dateutil >=2.6.1

 - tzlocal >=1.4

 - pytzdata >=2017.2.2

```

### Options

* `--tree`: List the dependencies as a tree.

* `--latest (-l)`: Show the latest version.

* `--outdated (-o)`: Show the latest version but only for packages that are outdated.

## build

The `build` command builds the source and wheels archives.

```bash

poetry build

```

Note that, at the moment, only pure python wheels are supported.

### Options

* `--format (-F)`: Limit the format to either wheel or sdist.

## publish

This command builds (if not already built) and publishes the package to the remote repository.

It will automatically register the package before uploading if this is the first time it is submitted.

```bash

poetry publish

```

### Options

* `--repository (-r)`: The repository to register the package to (default: `pypi`).

Should match a repository name set by the [`config`](#config) command.

## config

The `config` command allows you to edit poetry config settings and repositories.

```bash

poetry config --list

```

### Usage

````bash

poetry config [options] [setting-key] [setting-value1] ... [setting-valueN]

````

`setting-key` is a configuration option name and `setting-value1` is a configuration value.

### Modifying repositories

In addition to modifying the config section,

the config command also supports making changes to the repositories section by using it the following way:

```bash

poetry config repositories.foo https://foo.bar/simple/

```

This will set the url for repository `foo` to `https://foo.bar/simple/`.

If you want to store your credentials for a specific repository, you can do so easily:

```bash

poetry config http-basic.foo username password

```

If you do not specify the password you will be prompted to write it.

### Options

* `--unset`: Remove the configuration element named by `setting-key`.

* `--list`: Show the list of current config variables.

## search

This command searches for packages on a remote index.

```bash

poetry search requests pendulum

```

### Options

* `--only-name (-N)`: Search only in name.

## lock

This command locks (without installing) the dependencies specified in `pyproject.toml`.

```bash

poetry lock

```

# Libraries

This chapter will tell you how to make your library installable through Poetry.

## Every project is a package

As soon as you have a `pyproject.toml` in a directory, that directory is a package.

However, to make it accessible to others you will need to package and publish it.

## Versioning

While Poetry does not enforce any convention regardind package versioning,

it **strongly** recommends to follow [semantic versioning](https://semver.org).

This has many advantages for the end users and allows them to set appropriate

[version constraints](/versions/).

## Lock file

For your library, you may commit the `pyproject.lock` file if you want to.

This can help your team to always test against the same dependency versions.

However, this lock file will not have any effect on other projects that depend on it.

It only has an effect on the main project.

If you do not want to commit the lock file and you are using git, add it to the `.gitignore`.

## Packaging

Before you can actually publish your library, you will need to package it.

```bash

poetry build

```

This command will package your library in two different formats: `sdist` which is

the source format, and `wheel` which is a `compiled` package.

Once that's done you are ready to publish your library

## Publishing to PyPI

Alright, so now you can publish packages.

Poetry will publish to [PyPI](https://pypi.org) by default. Anything that is published to PyPI

is available automatically through Poetry. Since [pendulum](https://pypi.org/project/pendulum/)

if on PyPI we can depend on it without having to specify any additional repositories.

If we wanted to share `poetry-demo` with the Python community, we would publish on PyPI as weel.

Doing so is really easy.

```bash

poetry publish

```

This will package and publish the library to PyPI, at the condition that you are a registered user

and you have [configured your credentials](/repositories/#adding-credentials) properly.

!!!note

    The `publish` command also executes `build` by default.

    If you want to build your packages separately and later publish them,

    just pass the `--no-build` option.

Once this is done, your library will be availbale to anyone.

## Publishing to a private repository

Sometimes, you may want to keep your library private but also being accessible to you team.

In this case, you will need to use a private repository.

In order to publish to a private repository, you will need to add it to your

global list of repositories. See [Adding a repository](/repositories/#adding-a-repository)

for more information.

Once this is done, you can actually publish to it like so:

```bash

poetry publish -r my-repository

```

# Repositories

## Using the PyPI repository

By default, Poetry is configured to use the [PyPI](https://pypi.org) repository,

for package installation and publishing.

So, when you add dependencies to your project, Poetry will assume they are available

on PyPI.

This represent most cases and will likely be enough for most users.

## Using a private repository

However, at times, you may need to keep your package private while still being

able to share it with your teammates. In this case, you will need to use a private

repository.

### Adding a repository

Adding a new repository is easy with the `config` command.

```bash

poetry config repositories.foo https://foo.bar/simple/

```

This will set the url for repository `foo` to `https://foo.bar/simple/`.

### Configuring credentials

If you want to store your credentials for a specific repository, you can do so easily:

```bash

poetry config http-basic.foo username password

```

If you do not specify the password you will be prompted to write it.

!!!note

    To publish to PyPI, you can set your credentials for the repository

    named `pypi`:

    ```bash

    poetry config http-basic.pypi username password

    ```

### Install dependencies from a private repository

Now that you can publish to your private repository, you need to be able to

install dependencies from it.

For that, you have to edit your `pyproject.toml` file, like so

```toml

[[tool.poetry.source]]

name = "foo"

url = "https://foo.bar/simple/"

```

From now on, Poetry will also look for packages in your private repository.

# Versions and constraints

Poetry recommends following [semantic versioning](https://semver.org) but will not enforce it.

## Version constraints

### Caret requirements

**Caret requirements** allow SemVer 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.

In this case, if we 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:

```text

^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

**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.

```text

~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 any version where the wildcard is positioned.

`*`, `1.*` and `1.2.*` are examples of wildcard requirements.

```text

* := >=0.0.0

1.* := >=1.0.0 <2.0.0

1.2.* := >=1.2.0 <1.3.0

```

### Inequality requirements

**Inequality requirements** allow manually specifying a version range or an exact version to depend on.

Here are some examples of inequality requirements:

```text

>= 1.2.0

> 1

< 2

!= 1.2.3

```

### Exact requirements

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 version requirements can also be separated with a comma, e.g. `>= 1.2, < 1.5`.

### `git` dependencies

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" }

```

Since we haven’t specified any other information,

Poetry assumes that we intend to use the latest commit on the `master` branch to build our project.

You can combine the `git` key with the `rev`, `tag`, or `branch` keys to specify something else.

Here's an example of specifying that you want to use the latest commit on a branch named `next`:

```toml

[tool.poetry.dependencies]

requests = { git = "https://github.com/kennethreitz/requests.git", branch = "next" }

```

### Python restricted dependencies

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

```toml

[tool.poetry.dependencies]

pathlib2 = { version = "^2.2", python = "~2.7" }

```

```toml

[tool.poetry.dependencies]

pathlib2 = { version = "^2.2", python = ["~2.7", "^3.2"] }

```