Ir para o conteúdo

Principais comandos do 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 desenvolvido.
  • 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 via arquivo pyproject.toml.

O ambiente virtual do Poetry normalmente é criado em um dos seguintes diretórios:

  • Linux: ~/.cache/pypoetry/virtualenvs.
  • macOS: ~/Library/Caches/pypoetry/virtualenvs.
  • Microsoft Windows:
    • C:\Users\<username>\AppData\Local\pypoetry\Cache\virtualenvs.
    • %LOCALAPPDATA%\pypoetry\Cache\virtualenvs.

Como instalar

Linux

1
curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python3 -

Microsoft Windows

Nota

Comando deve ser executado no PowerShell

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

Para verificar a instalação:

1
poetry --version

Como atualizar

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

1
poetry self update

Para atualizar para a versão de desenvolvimento:

1
poetry self update --preview

Para atualizar para uma versão especifica:

1
poetry self update 0.8.0

Criando um novo projeto

Para criar um novo projeto é utilizado o comando:

1
poetry new nome-do-projeto

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
nome-do-projeto
|   pyproject.toml
|   README.rst
|
+---nome_do_projeto
|       __init__.py
|
\---tests
        test_nome_do_projeto.py
        __init__.py

Nota

O código será criado na pasta nome_do_projeto.


Utilizando em um projeto existente

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

1
poetry init

Ao executar o comando será feitas algumas perguntas:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
# Nome do projeto/pacote/biblioteca.
Package name [nome-do-projeto]:
# Versão do projeto.
Version [0.1.0]:
# Descrição.
Description []:
# Autor ou autores.
Author [natorsc <natorsc@gmail.com>, n to skip]:
# Licença.
License []:
# Versão do Python.
Compatible Python versions [^3.9]:
# Adicionar dependências de produção.
Would you like to define your main dependencies interactively? (yes/no) [yes]
# Adicionar dependências de desenvolvimento.
Would you like to define your development dependencies interactively? (yes/no) [yes]
# Gerar arquivo de configuração (pyproject.toml).
Do you confirm generation? (yes/no) [yes]

Para que não haja essa interação utilizar:

1
poetry init --no-interaction

Gerenciando dependências

Nota

Ao instalar algum pacote o ambiente virtual será criado (caso o mesmo não exista).

Instalar

Adicionando a ultima versão:

1
poetry add django

Adicionando uma versão especifica.

1
poetry add nome-do-pacote@^3.2

Instando uma versão maior ou igual:

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

Adicionando a partir de um diretório local:

1
2
3
poetry add ./my-package/
poetry add ../my-package/dist/my-package-0.1.0.tar.gz
poetry add ../my-package/dist/my_package-0.1.0.whl

Adicionar o pacote como dependência de desenvolvimento:

1
poetry add --dev nome-do-pacote

Ou

1
poetry add -D nome-do-pacote

Atualizar

Para atualizar as dependências:

1
poetry update

Para atualizar pacotes específicos:

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

Remover

Para remover dependências:

1
poetry remove nome-do-pacote

Instalando via pyproject.toml

Para projetos que já possuam um arquivo pyproject.toml:

1
poetry install

Para instalar se adicionar os pacotes de desenvolvimento:

1
poetry install --no-dev

Exibir as dependências

Exibir todas as dependências do projeto:

1
poetry show

Exibir as dependências de produção:

1
poetry show --no-dev

Exibir a arvore de dependências:

1
poetry show --tree

Exibir a versão instalada e a ultima versão disponível:

1
poetry show --latest

Exibir as dependências que estão desatualizadas:

1
poetry show --outdated

Executando um script

1
poetry run python -V

Ambiente virtual

Ativar

1
poetry shell

Alternar

1
poetry env use python3.9

Ou

1
poetry env use 3.9

Listar

Para listar os ambientes virtuais de um projeto:

1
poetry env list

Informações

Para visualizar informações do ambiente virtual:

1
poetry env info

Para ver o local onde o ambiente virtual foi criado:

1
poetry env info --path

Remover

Pode ser utilizada uma das seguintes sintaxes:

1
2
3
4
poetry env remove /full/path/to/python
poetry env remove python3.7
poetry env remove 3.7
poetry env remove nome-doprojeto-O3eWbxRl-py3.7

No Microsoft Windows é possível utilizar:

1
poetry env remove python

Gerar arquivo requirements.txt

Gerar arquivo requirements.txt com as depedências de produção (com hashes):

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

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

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

Gerar arquivo requirements.txt com as dependências de desenvolvimento (com hashes):

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

Gerar pacote

1
poetry build

Publicar pacote (PyPI)

1
poetry publish

Extra

Auto completar

macOS

1
2
# Bash (Homebrew)
poetry completions bash > $(brew --prefix)/etc/bash_completion.d/poetry.bash-completion

Linux

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
# 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