Empacotamento Python

Se você deseja mais informações sobre o Poetry, pode ler os seguintes artigos:

• Projetos Python com Poetry e VSCode. Parte 1
• Projetos Python com Poetry e VSCode. Parte 2
• Projetos Python com Poetry e VSCode. Parte 3

Para um guia abrangente sobre o UV, o gerenciador de pacotes Python ultrarrápido, leia: UV: O Gerenciador de Pacotes Python Ultrarrápido.

Introdução

Empacotamento Python é o processo de preparar seu projeto Python para distribuição e instalação. Existem duas abordagens principais: o método tradicional setup.py e a abordagem moderna pyproject.toml (definida em PEP-517, PEP-518 e PEP-660).

Para um guia abrangente sobre o manuseio de caminhos de arquivos e diretórios, essencial para gerenciar estruturas de projetos, consulte a página Caminhos de Arquivos e Diretórios.

Abordagem Tradicional: setup.py

O arquivo setup.py está no centro de um projeto Python tradicional. Ele descreve todos os metadados sobre seu projeto. Existem alguns campos que você pode adicionar a um projeto para dar a ele um rico conjunto de metadados que descrevem o projeto. No entanto, existem apenas três campos obrigatórios: name, version e packages. O campo name deve ser exclusivo se você deseja publicar seu pacote no Python Package Index (PyPI). O campo version rastreia diferentes lançamentos do projeto. O campo packages descreve onde você colocou o código-fonte Python dentro do seu projeto.

Isso permite que você instale facilmente pacotes Python. Muitas vezes, é suficiente escrever:

python setup.py install

e o módulo se instalará.

Exemplo: setup.py

Nosso setup.py inicial também incluirá informações sobre a licença e reutilizará o arquivo README.txt para o campo long_description. Isso ficará assim:

# setup.py: define metadados do pacote para distribuição
from distutils.core import setup
setup(
   name='pythonCheatsheet',  # Nome do pacote (deve ser exclusivo no PyPI)
   version='0.1',  # Número da versão
   packages=['pipenv',],  # Lista de pacotes a serem incluídos
   license='MIT',  # Tipo de licença
   long_description=open('README.txt').read(),  # Lê a descrição do arquivo
)

Abordagem Moderna: pyproject.toml

O arquivo pyproject.toml é o padrão moderno para configuração de projetos Python (PEP-517, PEP-518, PEP-660). Ele fornece uma maneira unificada de especificar os requisitos do sistema de compilação e os metadados do projeto em um único formato de arquivo declarativo.

Benefícios do pyproject.toml

• Declarativo: Todos os metadados do projeto em um só lugar
• Independente do sistema de compilação: Funciona com setuptools, poetry, flit e outros backends de compilação
• Sem execução de código: Mais seguro e previsível do que setup.py
• Padronizado: Segue os padrões PEP para melhor suporte de ferramentas

Exemplo: pyproject.toml

Aqui está um exemplo básico de pyproject.toml usando setuptools:

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "pythonCheatsheet"
version = "0.1"
description = "Um pacote de folhas de dicas Python"
readme = "README.txt"
requires-python = ">=3.8"
license = {text = "MIT"}
authors = [
    {name = "Your Name", email = "your.email@example.com"}
]
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "black>=22.0",
]

Instalação a partir do pyproject.toml

Com pyproject.toml, você pode instalar seu pacote usando pip:

pip install .

Ou no modo editável:

pip install -e .

Escolhendo a Abordagem Certa

• Use setup.py: Se você estiver trabalhando com projetos legados ou precisar de controle granular
• Use pyproject.toml: Para novos projetos (recomendado), pois é o padrão moderno e fornece melhor suporte de ferramentas

Encontre mais informações visitando a documentação oficial.

Links Relevantes

• Ambientes Virtuais
• Caminhos de Arquivos e Diretórios
• UV: O Gerenciador de Pacotes Python Ultrarrápido
• Projetos Python com Poetry e VSCode. Parte 1
• Projetos Python com Poetry e VSCode. Parte 2
• Projetos Python com Poetry e VSCode. Parte 3
• import()