"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "docs/_index.md" between
poetry-1.1.15.tar.gz and poetry-1.2.0.tar.gz

About: Poetry is a tool for dependency management and packaging in Python.

_index.md  (poetry-1.1.15):_index.md  (poetry-1.2.0)
skipping to change at line 16 skipping to change at line 16
menu: menu:
docs: docs:
weight: 0 weight: 0
--- ---
# Introduction # Introduction
Poetry is a tool for **dependency management** and **packaging** in Python. Poetry is a tool for **dependency management** and **packaging** in Python.
It allows you to declare the libraries your project depends on and it will manag e (install/update) them for you. It allows you to declare the libraries your project depends on and it will manag e (install/update) them for you.
Poetry offers a lockfile to ensure repeatable installs, and can build your proje ct for distribution.
## System requirements ## System requirements
Poetry requires Python 2.7 or 3.5+. It is multi-platform and the goal is to make Poetry requires **Python 3.7+**. It is multi-platform and the goal is to make it
it work equally well work equally well
on Windows, Linux and OSX. on Linux, macOS and Windows.
## Installation
{{% note %}} {{% note %}}
Python 2.7 and 3.5 will no longer be supported in the next feature release (1.2) If you are viewing documentation for the development branch, you may wish to ins
. tall a preview or development version of Poetry.
You should consider updating your Python version to a supported one. See the **advanced** installation instructions to use a preview or alternate ver
sion of Poetry.
{{% /note %}} {{% /note %}}
## Installation {{< tabs tabTotal="3" tabID1="installing-with-the-official-installer" tabID2="in
stalling-with-pipx" tabID3="installing-manually" tabName1="With the official ins
taller" tabName2="With pipx" tabName3="Manually (advanced)" >}}
{{< tab tabID="installing-with-the-official-installer" >}}
Poetry provides a custom installer that will install `poetry` isolated We provide a custom installer that will install Poetry in a new virtual environm
from the rest of your system by vendorizing its dependencies. This is the ent to isolate it
recommended way of installing `poetry`. from the rest of your system. This ensures that dependencies will not be acciden
tally upgraded or
uninstalled, and allows Poetry to manage its own environment.
{{< steps >}}
{{< step >}}
**Install Poetry**
The installer script is available directly at [install.python-poetry.org](https:
//install.python-poetry.org),
and is developed in [its own repository](https://github.com/python-poetry/instal
l.python-poetry.org).
The script can be executed directly (i.e. 'curl python') or downloaded and then
executed from disk
(e.g. in a CI environment).
{{% warning %}} {{% warning %}}
The `get-poetry.py` script described here will be replaced in Poetry 1.2 by `ins The previous `get-poetry.py` and `install-poetry.py` installers are deprecated.
tall.python-poetry.org`. Any installs performed
From Poetry **1.1.7 onwards**, you can already use this script as described [her using `get-poetry.py` should be uninstalled and reinstalled using `install.pytho
e]({{< relref "docs/master/#installation" >}}). n-poetry.org` to ensure
in-place upgrades are possible.
{{% /warning %}} {{% /warning %}}
### osx / linux / bashonwindows install instructions **Linux, macOS, Windows (WSL)**
```bash ```bash
curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poet ry.py | python - curl -sSL https://install.python-poetry.org | python3 -
``` ```
### windows powershell install instructions
{{% note %}}
Note: On some systems, `python` may still refer to Python 2 instead of Python 3.
We always suggest the
`python3` binary to avoid ambiguity.
{{% /note %}}
**Windows (Powershell)**
```powershell ```powershell
(Invoke-WebRequest -Uri https://raw.githubusercontent.com/python-poetry/poetry/m aster/get-poetry.py -UseBasicParsing).Content | python - (Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Cont ent | py -
``` ```
{{% note %}} {{% note %}}
You only need to install Poetry once. It will automatically pick up the current If you have installed Python through the Microsoft Store, replace `py` with `pyt
Python version and use it to [create virtualenvs]({{< relref "managing-environme hon` in the command
nts" >}}) accordingly. above.
{{% /note %}} {{% /note %}}
The installer installs the `poetry` tool to Poetry's `bin` directory. {{< /step >}}
On Unix it is located at `$HOME/.poetry/bin` and on Windows at `%USERPROFILE%\.p {{< step >}}
oetry\bin`. **Install Poetry (advanced)**
This directory will be automatically added to your `$PATH` environment variable, By default, Poetry is installed into a platform and user-specific directory:
by appending a statement to your `$HOME/.profile` configuration (or equivalent f
iles).
If you do not feel comfortable with this, please pass the `--no-modify-path` fla
g to
the installer and manually add the Poetry's `bin` directory to your path.
Finally, open a new shell and type the following: - `~/Library/Application Support/pypoetry` on MacOS.
- `~/.local/share/pypoetry` on Linux/Unix.
- `%APPDATA%\pypoetry` on Windows.
If you wish to change this, you may define the `$POETRY_HOME` environment variab
le:
```bash ```bash
poetry --version curl -sSL https://install.python-poetry.org | POETRY_HOME=/etc/poetry python3 -
``` ```
If you see something like `Poetry 0.12.0` then you are ready to use Poetry. If you want to install prerelease versions, you can do so by passing `--preview`
If you decide Poetry isn't your thing, you can completely remove it from your sy option to `install-poetry.py`
stem or by using the `$POETRY_PREVIEW` environment variable:
by running the installer again with the `--uninstall` option or by setting
the `POETRY_UNINSTALL` environment variable before executing the installer.
```bash ```bash
python get-poetry.py --uninstall curl -sSL https://install.python-poetry.org | python3 - --preview
POETRY_UNINSTALL=1 python get-poetry.py curl -sSL https://install.python-poetry.org | POETRY_PREVIEW=1 python3 -
``` ```
By default, Poetry is installed into the user's platform-specific home directory Similarly, if you want to install a specific version, you can use `--version` op
. If you wish to change this, you may define the `POETRY_HOME` environment varia tion or the `$POETRY_VERSION`
ble: environment variable:
```bash ```bash
POETRY_HOME=/etc/poetry python get-poetry.py curl -sSL https://install.python-poetry.org | python3 - --version 1.2.0
curl -sSL https://install.python-poetry.org | POETRY_VERSION=1.2.0 python3 -
``` ```
If you want to install prerelease versions, you can do so by passing `--preview` You can also install Poetry from a `git` repository by using the `--git` option:
to `get-poetry.py`
or by using the `POETRY_PREVIEW` environment variable:
```bash ```bash
python get-poetry.py --preview curl -sSL https://install.python-poetry.org | python3 - --git https://github.com
POETRY_PREVIEW=1 python get-poetry.py /python-poetry/poetry.git@master
``` ````
{{< /step >}}
{{< step >}}
**Add Poetry to your PATH**
Similarly, if you want to install a specific version, you can use `--version` or The installer creates a `poetry` wrapper in a well-known, platform-specific dire
the `POETRY_VERSION` ctory:
environment variable:
- `$HOME/.local/bin` on Unix.
- `%APPDATA%\Python\Scripts` on Windows.
If this directory is not present in your `$PATH`, you can add it in order to inv
oke Poetry
as `poetry`.
Alternatively, the full path to the `poetry` binary can always be used:
- `$POETRY_HOME/bin/poetry` if `$POETRY_HOME` is set.
- `~/Library/Application Support/pypoetry/bin/poetry` on MacOS.
- `~/.local/share/pypoetry/bin/poetry` on Linux/Unix.
- `%APPDATA%\pypoetry\Scripts\poetry` on Windows.
{{< /step >}}
{{< step >}}
**Use Poetry**
Once Poetry is installed and in your `$PATH`, you can execute the following:
```bash ```bash
python get-poetry.py --version 0.12.0 poetry --version
POETRY_VERSION=0.12.0 python get-poetry.py
``` ```
{{% note %}} If you see something like `Poetry (version 1.2.0)`, your install is ready to use
Note that the installer does not support Poetry releases < 0.12.0. !
{{% /note %}} {{< /step >}}
{{< step >}}
**Update Poetry**
{{% note %}} Poetry is able to update itself when installed using the official installer.
The setup script must be able to find one of following executables in your shell
's path environment:
- `python` (which can be a py3 or py2 interpreter) ```bash
- `python3` poetry self update
- `py.exe -3` (Windows) ```
- `py.exe -2` (Windows)
{{% /note %}}
### Alternative installation methods (not recommended) If you want to install pre-release versions, you can use the `--preview` option.
{{% note %}} ```bash
Using alternative installation methods will make Poetry always poetry self update --preview
use the Python version for which it has been installed to create ```
virtualenvs.
So, you will need to install Poetry for each Python version you And finally, if you want to install a specific version, you can pass it as an ar
want to use and switch between them. gument
{{% /note %}} to `self update`.
```bash
poetry self update 1.2.0
```
#### Installing with `pip` {{% warning %}}
Poetry `1.1` series releases are not able to update in-place to `1.2` or newer s
eries releases.
To migrate to newer releases, uninstall using your original install method, and
then reinstall
using the [methods above]({{< ref "#installation" >}} "Installation").
{{% /warning %}}
{{< /step >}}
{{< step >}}
**Uninstall Poetry**
Using `pip` to install Poetry is possible. If you decide Poetry isn't your thing, you can completely remove it from your sy
stem
by running the installer again with the `--uninstall` option or by setting
the `POETRY_UNINSTALL` environment variable before executing the installer.
```bash ```bash
pip install --user poetry curl -sSL https://install.python-poetry.org | python3 - --uninstall
curl -sSL https://install.python-poetry.org | POETRY_UNINSTALL=1 python3 -
``` ```
{{% warning %}} {{% warning %}}
Be aware that it will also install Poetry's dependencies If you installed using the deprecated `get-poetry.py` script, you should use it
which might cause conflicts with other packages. to uninstall instead:
```bash
curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poet
ry.py | python3 - --uninstall
```
{{% /warning %}} {{% /warning %}}
#### Installing with `pipx` {{< /step >}}
{{< /steps >}}
{{< /tab >}}
{{< tab tabID="installing-with-pipx" >}}
Using [`pipx`](https://github.com/pypa/pipx) to install Poetry is also possible
and fully supported.
`pipx` is used to install Python CLI applications globally while still isolating
them in virtual environments.
`pipx` will manage upgrades and uninstalls when used to install Poetry.
Using [`pipx`](https://github.com/cs01/pipx) to install Poetry is also possible. {{< steps >}}
`pipx` is used to install Python CLI applications globally while still isolatin {{< step >}}
g them in virtual environments. This allows for clean upgrades and uninstalls. p **Install Poetry**
ipx supports Python 3.6 and later. If using an earlier version of Python, consid
er [pipsi](https://github.com/mitsuhiko/pipsi).
```bash ```bash
pipx install poetry pipx install poetry
``` ```
{{< /step >}}
{{< step >}}
**Install Poetry (advanced)**
`pipx` can be install different versions of Poetry, using the same syntax as pip
:
```bash ```bash
pipx upgrade poetry pipx install poetry==1.2.0
``` ```
`pipx` can also install versions of Poetry in parallel, which allows for easy te
sting of alternate or prerelease
versions. Each version is given a unique, user-specified suffix, which will be u
sed to create a unique binary name:
```bash ```bash
pipx uninstall poetry pipx install --suffix=@1.2.0 poetry==1.2.0
poetry@1.2.0 --version
``` ```
[Github repository](https://github.com/cs01/pipx). ```bash
pipx install --suffix=@preview --pip-args=--pre poetry
poetry@preview --version
```
## Updating `poetry` Finally, `pipx` can install any valid [pip requirement spec](https://pip.pypa.io
/en/stable/cli/pip_install/), which
allows for installations of the development version from `git`, or even for loca
l testing of pull requests:
Updating Poetry to the latest stable version is as simple as calling the `self u ```
pdate` command. pipx install --suffix @master git+https://github.com/python-poetry/poetry.git@ma
ster
pipx install --suffix @pr1234 git+https://github.com/python-poetry/poetry.git@re
fs/pull/1234/head
```bash
poetry self update
``` ```
{{< /step >}}
{{< step >}}
**Update Poetry**
If you want to install pre-release versions, you can use the `--preview` option. ```bash
pipx upgrade poetry
```
{{< /step >}}
{{< step >}}
**Uninstall Poetry**
```bash ```bash
poetry self update --preview pipx uninstall poetry
``` ```
{{< /step >}}
{{< /steps >}}
And finally, if you want to install a specific version, you can pass it as an ar {{< /tab >}}
gument {{< tab tabID="installing-manually" >}}
to `self update`.
Poetry can be installed manually using `pip` and the `venv` module. By doing so
you will essentially perform the steps carried
out by the official installer. As this is an advanced installation method, these
instructions are Unix-only and omit specific
examples such as installing from `git`.
The variable `$VENV_PATH` will be used to indicate the path at which the virtual
environment was created.
```bash ```bash
poetry self update 0.8.0 python3 -m venv $VENV_PATH
$VENV_PATH/bin/pip install -U pip setuptools
$VENV_PATH/bin/pip install poetry
``` ```
{{% note %}} Poetry will be available at `$VENV_PATH/bin/poetry` and can be invoked directly
The `self update` command will only work if you used the recommended or symlinked elsewhere.
installer to install Poetry.
{{% /note %}}
{{% note %}} To uninstall Poetry, simply delete the entire `$VENV_PATH` directory.
If you are still on poetry version < 1.0 use `poetry self:update` instead.
{{% /note %}} {{< /tab >}}
{{< /tabs >}}
## Enable tab completion for Bash, Fish, or Zsh ## Enable tab completion for Bash, Fish, or Zsh
`poetry` supports generating completion scripts for Bash, Fish, and Zsh. `poetry` supports generating completion scripts for Bash, Fish, and Zsh.
See `poetry help completions` for full details, but the gist is as simple as usi ng one of the following: See `poetry help completions` for full details, but the gist is as simple as usi ng one of the following:
```bash ### Bash
# Bash
poetry completions bash > /etc/bash_completion.d/poetry.bash-completion
# Bash (Homebrew)
poetry completions bash > $(brew --prefix)/etc/bash_completion.d/poetry.bash-com
pletion
# Fish #### Auto-loaded (recommended)
poetry completions fish > ~/.config/fish/completions/poetry.fish
# Fish (Homebrew) ```bash
poetry completions fish > (brew --prefix)/share/fish/vendor_completions.d/poetry poetry completions bash >> ~/.bash_completion
.fish ```
# Zsh #### Lazy-loaded
poetry completions zsh > ~/.zfunc/_poetry
# Oh-My-Zsh ```bash
mkdir $ZSH_CUSTOM/plugins/poetry poetry completions bash > ${XDG_DATA_HOME:~/.local/share}/bash_completion/comple
poetry completions zsh > $ZSH_CUSTOM/plugins/poetry/_poetry tions/poetry
```
# prezto ### Fish
poetry completions zsh > ~/.zprezto/modules/completion/external/src/_poetry
```fish
poetry completions fish > ~/.config/fish/completions/poetry.fish
``` ```
{{% note %}} ### Zsh
You may need to restart your shell in order for the changes to take effect.
{{% /note %}} ```zsh
poetry completions zsh > ~/.zfunc/_poetry
```
For `zsh`, you must then add the following line in your `~/.zshrc` before `compi nit`: You must then add the following lines in your `~/.zshrc`, if they do not already exist:
```bash ```bash
fpath+=~/.zfunc fpath+=~/.zfunc
autoload -Uz compinit && compinit
``` ```
For `oh-my-zsh`, you must then enable poetry in your `~/.zshrc` plugins #### Oh My Zsh
```zsh
mkdir $ZSH_CUSTOM/plugins/poetry
poetry completions zsh > $ZSH_CUSTOM/plugins/poetry/_poetry
```
You must then add `poetry` to your plugins array in `~/.zshrc`:
```text ```text
plugins( plugins(
poetry poetry
... ...
) )
``` ```
#### prezto
```zsh
poetry completions zsh > ~/.zprezto/modules/completion/external/src/_poetry
```
{{% note %}}
You may need to restart your shell in order for these changes to take effect.
{{% /note %}}
 End of changes. 63 change blocks. 
129 lines changed or deleted 247 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)