Como utilizar o gerenciador de dependências e empacotador Poetry

O Poetry é uma ferramenta de linha de comando que permite:

  • Criar um ou mais ambientes virtuais para o projeto que está sendo desenvolvendo.
  • Gerenciar as dependências do projeto, separando as mesmas em produção e desenvolvimento.
  • Criar pacotes sdist (*tar.gz) e wheel (*.whl) a partir do projeto que está sendo desenvolvido.
  • Realizar a configuração e build do projeto através de um arquivo pyproject.toml.

Os ambientes virtuais criados com o Poetry normalmente são armazenados em um dos seguintes diretórios:

Distribuições Linux:

~/.cache/pypoetry/virtualenvs

macOS:

~/Library/Caches/pypoetry/virtualenvs

Microsoft Windows:

C:\Users\<username>\AppData\Local\pypoetry\Cache\virtualenvs

Ou:

%LOCALAPPDATA%\pypoetry\Cache\virtualenvs

Instalação

Distribuições Linux

curl -sSL \
https://raw.githubusercontent.com/python-poetry/poetry/master/install-poetry.py  python3 -

Microsoft Windows

Nota: Comando deve ser executado com o PowerShell.

(Invoke-WebRequest -Uri https://raw.githubusercontent.com/python-poetry/poetry/master/install-poetry.py -UseBasicParsing).Content  python -

Para verificar se a instalação foi realizada com sucesso feche o terminal e abra novamente, em seguida execute o comando:

poetry --version

Nota: Em alguns casos pode ser necessário reiniciar o sistema operacional.


Principais comandos

Atualizar o Poetry

Para atualizar para a ultima versão disponível:

poetry self update

Para atualizar para a versão de desenvolvimento:

poetry self update --preview

Para atualizar para uma versão especifica:

poetry self update 0.8.0

Criar um novo projeto

Para criar um novo projeto é utilizado o comando:

poetry new nome-do-projeto

Logo após o comando será criada a seguinte estrutura de diretórios e arquivos:

nome-do-projeto/
├── nome_do_projeto
│   └── __init__.py
├── pyproject.toml
├── README.rst
└── tests
    ├── __init__.py
    └── test_nome_do_projeto.py

2 directories, 5 files

Utilizar em um projeto existente

Para adicionar o Poetry em um projeto já existente é utilizado o comando:

poetry init

Ao executar o comando serão realizadas diversas perguntas para configuração do projeto.

Para que não não sejam feitas as perguntas de configuração do projeto execute:

poetry init --no-interaction

Gerenciando dependências

Adicionando pacotes

Adicionar a ultima versão de um pacote:

poetry add nome-do-pacote

Adicionar uma versão especifica de um pacote:

poetry add nome-do-pacote@^3.2

Adicionar uma versão maior ou igual de um pacote:

poetry add "nome-do-pacote>=3.2"

Adicionando a partir de um diretório local:

poetry add ./nome-do-pacote/
poetry add ../caminho-até-o-pacote/nome-do-pacote-0.1.0.tar.gz
poetry add ../caminho-até-o-pacote/nome-do-pacote-0.1.0.whl

Adicionar um pacote como dependência de desenvolvimento:

poetry add --dev nome-do-pacote

Outra forma de adicionar o pacote como dependência de desenvolvimento:

poetry add -D nome-do-pacote

Atualizando pacotes

Para atualizar todos os pacotes:

poetry update

Para atualizar pacotes específicos:

poetry update nome-do-pacote nome-do-outro-pacote

Removendo pacotes

Para remover um pacote:

poetry remove nome-do-pacote

Instalando todas as dependências

Para instalar pacotes em um projetos que já possua um arquivo pyproject.toml executar:

poetry install

O comando acima realiza algo equivalente ao comando:

pip install -r requirements.txt

Para instalar sem adicionar os pacotes de desenvolvimento:

poetry install --no-dev

Exibindo pacotes instalados

Para exibir todos os pacotes instalados (produção e desenvolvimento) de um projeto:

poetry show

Para exibir apenas os pacotes de produção:

poetry show --no-dev

Para visualizar a arquivo de dependências:

poetry show --tree

Para verificar a versão instalada de um pacotes e a ultima disponível:

poetry show --latest

Para visualizar os pacotes que estão desatualizados:

poetry show --outdated

Executando um script

Para executar um script python com o Poetry é utilizando o seguinte comando:

poetry run python nome-do-script.py

Ambiente virtual

Ativar

Para ativar um ambiente virtual do Poetry:

poetry shell

Alternar

Para alternar entre ambientes virtuais que foram criados para um projeto:

poetry env use python3.9

Outro comando possível é:

poetry env use 3.9

Listar

Para listar os ambientes virtuais de um projeto:

poetry env list

Informações

Para visualizar informações do ambiente virtual:

poetry env info

Para ver o local onde o ambiente virtual foi criado:

poetry env info --path

Comando acima é útil para quando se faz necessária a configuração do ambiente virtual em um editor de texto ou IDE.

Remover

Para remover um ambiente virtual utilize uma das seguintes sintaxes:

poetry env remove /caminho/até/o/interpretador/python
poetry env remove python3.9
poetry env remove 3.9
poetry env remove nome-doprojeto-O3eWbxRl-py3.9

No Microsoft Windows é possível utilizar:

poetry env remove python

Requirements.txt

Para gerar o arquivo requirements.txt com as dependências de produção (com hashes):

poetry export \
-f requirements.txt \
--output requirements.txt

Para gerar o arquivo requirements.txt com as dependências de produção (sem hashes):

poetry export \
--without-hashes \
-f requirements.txt \
--output requirements.txt

Para gerar o arquivo requirements.txt com as dependências de desenvolvimento (com hashes):

poetry export \
--dev \
-f requirements.txt \
--output requirements.txt

Criar um pacote

Para criar um pacote com o Poetry basta executar o comando:

poetry build

Serão criado os pacotes nos formatos sdist (*tar.gz) e wheel (*.whl).


Publicar um pacote (PyPI)

Para realizar a publicação do pacote que foi criado no PyPI:

poetry publish

Extra

Auto completar

macOS
# Bash (Homebrew)
poetry completions bash > $(brew --prefix)/etc/bash_completion.d/poetry.bash-completion
Distribuições Linux
# Bash
poetry completions bash > /etc/bash_completion.d/poetry.bash-completion
# Fish
poetry completions fish > ~/.config/fish/completions/poetry.fish
# Fish (Homebrew)
poetry completions fish > (brew --prefix)/share/fish/vendor_completions.d/poetry.fish
# Zsh
poetry completions zsh > ~/.zfunc/_poetry
# Oh-My-Zsh
mkdir $ZSH_CUSTOM/plugins/poetry
poetry completions zsh > $ZSH_CUSTOM/plugins/poetry/_poetry
# prezto
poetry completions zsh > ~/.zprezto/modules/completion/external/src/_poetry