Ir para o conteúdo

Criação de um projeto Python com Poetry

A utilização de ferramentas que permitam o gerenciamento das dependências de um projeto de software, é uma boa prática e também facilita o trabalho do desenvolvedor, pois muitas delas além da gestão das dependências também facilitam a criação e manutenção do projeto de software.

Cada linguagem de programação possui algum gerenciador de dependências, a exemplo temos Apache Mavem para aplicações Java e Kotlin, Gradle para aplicações Java, Groovy, Kotlin, Android, Scala e JavaScript, ainda para JavaScript temos NPM e Yarn e para Python além do Pip podemos contar com o Poetry.

O Objetivo deste post é apresentar a ferramenta de gerenciamento e empacotamento em Python, o Poetry, todo o conteúdo aqui exposto é uma tradução resumida do conteúdo disponibilizado no site oficial do Poetry.

O que é Poetry?

O Poetry é uma ferramenta para gerenciamento de dependências e empacotamento em Python. Ele permite a você declarar ou instalar as bibliotecas das quais seu projeto depende. Para mais informações acesse python-poetry.org.

Requisitos de sistema

Poetry requer Python 2.7 ou 3.5+. É multiplataforma e o objetivo é fazê-lo funcionar igualmente bem no Windows, Linux e OSX.

Importante

Segundo o desenvolvedor, a partir da versão 1.2 o Python 2.7 e 3.5 não terão mais suporte.

Instalação e atualização do Poetry

Instalação do Poetry via Terminal Linux/OSX

$ curl -sSL https://install.python-poetry.org | python3 -

<span style="color: #8be9fd;">Retrieving Poetry metadata</span>

This will download and install the latest version of <span style="color: #8be9fd;">Poetry</span>,
a dependency and package manager for Python.

It will add the `poetry` command to <span style="color: #8be9fd;">Poetry</span>'s bin directory, located at:

Welcome to <span style="color: #8be9fd;">Poetry</span>!

This will download and install the latest version of Poetry,
a dependency and package manager for Python.

It will add the `poetry` command to Poetry's bin directory, located at:

<span style="color: #f3f99d;">$HOME/.local/bin</span>

You can uninstall at any time by executing this script with the --uninstall option,
and these changes will be reverted.

Installing <span style="color: #8be9fd;">Poetry</span> (1.5.1): <span style="color: #f3f99d;">Done</span>

<span style="color: #8be9fd;">Poetry</span> (1.5.1) is installed now. Great!

To get started you need <span style="color: #8be9fd;">Poetry</span>'s bin directory (<span style="color: #f3f99d;">$HOME/.local/bin</span>) in your `PATH`
environment variable.

Add `export PATH="<span style="color: #f3f99d;">$HOME/.local/bin:$PATH</span>"` to your shell configuration file.

Alternatively, you can call <span style="color: #8be9fd;">Poetry</span> explicitly with <span style="font-weight: bold;">`$HOME/.local/bin/poetry`</span>.

You can test that everything is set up by executing:

<span style="font-weight: bold;">`poetry --version`</span>

Instalação do Poetry no Windows PowerShell

PS C:\Users\{username}> (Invoke-WebRequest -Uri https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py -UseBasicParsing).Content | python -

O instalador instala o Poetry na pasta ( HOME ) do usuário. No Linux/OSX, localizado em $HOME/.poetry/bin e no Windows em %USERPROFILE%\.poetry\bin, adicionando automaticamente as configurações necessária ao $PATH.

Atualização do Poetry

Para atualizar o Poetry para a versão estável mais recente.

$ poetry self update
Updating to <span style="color: BlueViolet;">1.1.13</span>

- Downloading <span style="color: BlueViolet;">poetry-1.1.13-darwin.tar.gz</span> <span style="color: LimeGreen;">100%</span>

<span style="color: BlueViolet;">Poetry</span> (<span style="color: LimeGreen;">1.1.13</span>) is installed now. Great!

Configuração do Poetry

A configuração do Poetry pode ser feita diretamente no arquivo config.toml que pode ser encontrado nos diretórios:

  • Linux: ~/.config/pypoetry
  • Mac OS: ~/Library/Application Support/pypoetry
  • Windows: C:\Users\<username>\AppData\Roaming\pypoetry

Outra forma de configurar o Poetry é por meio do comando poetry seguido do parâmetro config.

$ poetry config --list

<span style="color: cyan;">cache-dir</span> = "/Users/{username}/Library/Caches/pypoetry"
<span style="color: cyan;">experimental.new-installer</span> = true
<span style="color: cyan;">installer.parallel</span> = true
<span style="color: cyan;">virtualenvs.create</span> = true
<span style="color: cyan;">virtualenvs.in-project</span> = true
<span style="color: cyan;">virtualenvs.path</span> = "{cache-dir}/virtualenvs"  # /Users/{username}/Library/Caches/pypoetry/virtualenvs

As configurações disponíveis são:

cache-dir

Caminho para o diretório de cache usado pelo Poetry, padrão é um dos seguintes diretórios:

  • Mac OS: ~/Library/Caches/pypoetry
  • Windows: C:\Users\<username>\AppData\Local\pypoetry\Cache
  • Unix: ~/.cache/pypoetry

installer.parallel

Use a execução paralela ao usar o >=1.1.0. O padrão é true.

virtualenvs.create

Cria um novo ambiente virtual, se ainda não houver um. O padrão é true.

virtualenvs.path

Diretório onde os ambientes virtuais serão criados. O padrão é {cache-dir}/virtualenvs para Linux e Mac OS e {cache-dir}\virtualenvsno Windows.

repositories.

Defina um novo repositório alternativo. Consulte Repositories para mais informações.

virtualenvs.in-project

Uma variável importante, que setada como true, define que o virtualenv seja criado no diretório do raiz do projeto.

$ poetry config virtualenvs.in-project true
$

Nota

O Padrão desta variável é None, fazendo com que o virtualenv seja criado em: {cache-dir}/virtualenvs no Linux/Mac OS e {cache-dir}\virtualenvs no Windows.

Utilização básica do Poetry

Criação e Configuração de um projeto - Project setup

Para criar um novo projeto basta chamar o poetry new <nome_do_projeto>

$ poetry new poetry-demo
Created package <span style="color: BlueViolet;">poetry_demo</span> in <span style="color: BlueViolet;">poetry-demo</span>

Utilizando o comando tree, é possível ver a estrutura do projeto criado.

$ tree poetry-demo
poetry-demo
├── README.rst
├── poetry_demo
│   └── __init__.py
├── pyproject.toml
└── tests
    ├── __init__.py
    └── test_poetry_demo.py

2 directories, 5 files

Nota

Veja mais opções para criação de um novo projeto com o comando poetry new --help

$ poetry new --name app poetry-demo

Created package <span style="color: BlueViolet;">app</span> in <span style="color: BlueViolet;">poetry-demo</span>

Utilizando o comando tree, é possível ver a estrutura do projeto criado.

$ tree poetry-demo
poetry-demo
├── README.rst
├── app
│   └── __init__.py
├── pyproject.toml
└── tests
    ├── __init__.py
    └── test_app.py

2 directories, 5 files

O arquivo pyproject.toml é o arquivo mais importante aqui. Através dele será possível fazer a gestão das dependências do projeto.

[tool.poetry]
name = "app"
version = "0.1.0"
description = ""
authors = ["Nome do author <email@author.com>"]

[tool.poetry.dependencies]
python = "^3.9"

[tool.poetry.dev-dependencies]
pytest = "^5.2"

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

Inicializar um projeto em um diretório pré-existente

Outra forma de inicializar um projeto Poetry é por meio do comando poetry init

$ mkdir poetry-demo
$ cd poetry-demo
$ poetry init

This command will guide you through creating your <span style="color: BlueViolet;">pyproject.toml</span> config.

<span style="color: BlueViolet;">Package name [</span><span style="color: LimeGreen;">poetry-demo</span><span style="color: BlueViolet;">]:</span>
<span style="color: BlueViolet;">Version [</span><span style="color: LimeGreen;">0.1.0</span><span style="color: BlueViolet;">]:</span>
<span style="color: BlueViolet;">Description []:</span>  My first project with poetry
<span style="color: BlueViolet;">Author [</span><span style="color: LimeGreen;">Your name <username@domain.com>, n to skip</span><span style="color: BlueViolet;">]:</span>
<span style="color: BlueViolet;">License []:</span>  
<span style="color: BlueViolet;">Compatible Python versions [</span><span style="color: LimeGreen;">^3.10</span><span style="color: BlueViolet;">]:</span>

<span style="color: BlueViolet;">Would you like to define your main dependencies interactively? (yes/no)</span> [<span style="color: LimeGreen;">yes</span><span style="color: BlueViolet;">]</span> no
<span style="color: BlueViolet;">Would you like to define your development dependencies interactively? (yes/no)</span> [<span style="color: LimeGreen;">yes</span><span style="color: BlueViolet;">]</span> no
<span style="color: BlueViolet;">Generated file</span>

[tool.poetry]
name = "poetry-demo"
version = "0.1.0"
description = "My first project with poetry"
authors = ["Your name <username@domain.com>"]

[tool.poetry.dependencies]
python = "^3.10"

[tool.poetry.dev-dependencies]

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

<span style="color: BlueViolet;">Do you confirm generation? (yes/no)</span> [<span style="color: LimeGreen;">yes</span><span style="color: BlueViolet;">]</span>

Adicionar dependências ao projeto

A maneira mais fácil de para se adicionar dependências ao projeto é pelo meio do comando poetry add <dependencia>

$ poetry add pendulum
Creating virtualenv <span style="color: cyan;">poetry-demo</span> in /Users/{username}/dados/workspaces-python/poetry-demo/.venv
Using version ^2.1.2 for <span style="color: cyan;">pendulum</span>

<span style="color: BlueViolet;">Updating dependencies</span>
<span style="color: BlueViolet;">Resolving dependencies...</span> (0.3s)

<span style="color: BlueViolet;">Writing lock file</span>

Package operations: <span style="color: BlueViolet;">4</span> installs, <span style="color: BlueViolet;">0</span> updates, <span style="color: BlueViolet;">0</span> removals

  <span style="color: LimeGreen;">•</span> Installing <span style="color: cyan;">six</span> (<span style="color: LimeGreen;">1.16.0</span>)
  <span style="color: LimeGreen;">•</span> Installing <span style="color: cyan;">python-dateutil</span> (<span style="color: LimeGreen;">2.8.2</span>)
  <span style="color: LimeGreen;">•</span> Installing <span style="color: cyan;">pytzdata</span> (<span style="color: LimeGreen;">2020.1</span>)
  <span style="color: LimeGreen;">•</span> Installing <span style="color: cyan;">pendulum</span> (<span style="color: LimeGreen;">2.1.2</span>)

Também é possível adicionar dependências ao projeto editando o arquivo pyproject.toml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
[tool.poetry]
name = "app"
version = "0.1.0"
description = ""
authors = ["Nome do author <email@author.com>"]

[tool.poetry.dependencies]  #(1)
python = "^3.9"
pendulum = "^2.1.2"  #(2)

[tool.poetry.dev-dependencies]  #(3)
pytest = "^5.2"

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"
  1. Sessão de dependências do projeto;
  2. Dependências do projeto em suas (versões/restrições), mais informações leia: Especificação de dependência;
  3. Sessão de dependências de desenvolvimento.

Instalação das dependências

Para instalar as dependências definidas no projeto, basta executar o comando poetry install.

$ poetry install
Installing dependencies from lock file

<span style="font-weight: bold;">Package operations:</span> <span style="color: BlueViolet;">4</span> installs, <span style="color: BlueViolet;">0</span> updates, <span style="color: BlueViolet;">0</span> removals

  <span style="color: LimeGreen;">•</span> Installing <span style="color: cyan;">six</span> (<span style="color: LimeGreen;">1.16.0</span>)
  <span style="color: LimeGreen;">•</span> Installing <span style="color: cyan;">python-dateutil</span> (<span style="color: LimeGreen;">2.8.2</span>)
  <span style="color: LimeGreen;">•</span> Installing <span style="color: cyan;">pytzdata</span> (<span style="color: LimeGreen;">2020.1</span>)
  <span style="color: LimeGreen;">•</span> Installing <span style="color: cyan;">pendulum</span> (<span style="color: LimeGreen;">2.1.2</span>)

Nota

Ao executar a instalação das dependências o Poetry cria/grava todos os pacotes e suas versões exatas que baixou no *_poetry.lock_*, este arquivo tem a função de bloquear o projeto para utilizar essas versões específicas, portanto este arquivos deve ser enviado junto ao repositório do projeto para que todas as pessoas que trabalham no projeto sejam bloqueadas para as mesmas versões de dependências.

O que aprendemos?

Neste post aprendemos de forma resumida a instalar e configurar o Poetry, criar projetos utilizando a ferramento e por fim aprendemos a instalar as dependências de um projeto de software Python.

Referências

POETRY. Site oficial do Poetry. Online disponível em: python-poetry.org. Acesso em 09/10/2021.