Empacotando projetos Python#

Este tutorial mostra como empacotar um projeto Python simples. Ele mostrará como adicionar os arquivos e a estrutura necessários para criar o pacote, como construir o pacote e como enviá-lo para o Índice de Pacotes do Python (PyPI).

Dica

Se você tiver problemas para executar os comandos neste tutorial, copie o comando e sua saída e, em seguida, relate um problema no repositório packaging-problems no GitHub. Faremos o nosso melhor para ajudá-lo!

Alguns comandos exigem uma nova versão de pip, então comece certificando-se de que você tenha a versão mais recente instalada:

python3 -m pip install --upgrade pip
py -m pip install --upgrade pip

Um projeto simples#

Este tutorial usa um projeto simples chamado example_package_YOUR_USERNAME_HERE. Se seu nome de usuário for me, então o pacote seria example_package_me; isso garante que você tenha um nome de pacote exclusivo que não entre em conflito com os pacotes carregados por outras pessoas seguindo este tutorial. Recomendamos seguir este tutorial como está usando este projeto, antes de empacotar seu próprio projeto.

Crie a seguinte estrutura de arquivos localmente:

packaging_tutorial/
└── src/
    └── example_package_YOUR_USERNAME_HERE/
        ├── __init__.py
        └── example.py

O diretório que contém os arquivos Python deve corresponder ao nome do projeto. Isso simplifica a configuração e é mais óbvio para os usuários que instalam o pacote.

__init__.py is recommended to import the directory as a regular package, even if as is our case for this tutorial that file is empty [1].

example.py é um exemplo de módulo dentro do pacote que pode conter a lógica (funções, classes, constantes, etc.) do seu pacote. Abra esse arquivo e insira o seguinte conteúdo:

def add_one(number):
    return number + 1

Se você não está familiarizado com módulos e pacotes de importação do Python, reserve alguns minutos para ler a documentação do Python para pacotes e módulos.

Depois de criar esta estrutura, você desejará executar todos os comandos neste tutorial dentro do diretório packaging_tutorial.

Criando arquivos do pacote#

Agora você adicionará arquivos que são usados para preparar o projeto para distribuição. Quando terminar, a estrutura do projeto ficará assim:

packaging_tutorial/
├── LICENSE
├── pyproject.toml
├── README.md
├── src/
│   └── example_package_YOUR_USERNAME_HERE/
│       ├── __init__.py
│       └── example.py
└── tests/

Criando um diretório de teste#

tests/ é um espaço reservado, ou placeholder, para arquivos de teste. Deixe-o vazio por enquanto.

Escolhendo uma construção de backend#

Tools like pip and construir do not actually convert your sources into a distribution package (like a wheel); that job is performed by a build backend. The build backend determines how your project will specify its configuration, including metadata (information about the project, for example, the name and tags that are displayed on PyPI) and input files. Build backends have different levels of functionality, such as whether they support building extension modules, and you should choose one that suits your needs and preferences.

You can choose from a number of backends; this tutorial uses Hatchling by default, but it will work identically with Setuptools, Flit, PDM, and others that support the [project] table for metadata.

Nota

Alguns backends de construção fazem parte de ferramentas maiores que fornecem uma interface de linha de comando com recursos adicionais, como inicialização de projeto e gerenciamento de versão, além de construção, envio e instalação de pacotes. Este tutorial usa ferramentas de propósito único que funcionam de forma independente.

The pyproject.toml tells build frontend tools like pip and construir which backend to use for your project. Below are some examples for common build backends, but check your backend’s own documentation for more details.

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"
[build-system]
requires = ["flit_core>=3.4"]
build-backend = "flit_core.buildapi"
[build-system]
requires = ["pdm-backend"]
build-backend = "pdm.backend"

The requires key is a list of packages that are needed to build your package. The frontend should install them automatically when building your package. Frontends usually run builds in isolated environments, so omitting dependencies here may cause build-time errors. This should always include your backend’s package, and might have other build-time dependencies.

The build-backend key is the name of the Python object that frontends will use to perform the build.

Both of these values will be provided by the documentation for your build backend, or generated by its command line interface. There should be no need for you to customize these settings.

Additional configuration of the build tool will either be in a tool section of the pyproject.toml, or in a special file defined by the build tool. For example, when using setuptools as your build backend, additional configuration may be added to a setup.py or setup.cfg file, and specifying setuptools.build_meta in your build allows the tools to locate and use these automatically.

Configurando metadados#

Abra pyproject.toml e insira o seguinte conteúdo. Mude o name para incluir seu nome de usuário; isso garante que você tenha um nome de pacote exclusivo que não entre em conflito com os pacotes carregados por outras pessoas que seguem este tutorial.

[project]
name = "example_package_YOUR_USERNAME_HERE"
version = "0.0.1"
authors = [
  { name="Example Author", email="author@example.com" },
]
description = "A small example package"
readme = "README.md"
requires-python = ">=3.8"
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]

[project.urls]
Homepage = "https://github.com/pypa/sampleproject"
Issues = "https://github.com/pypa/sampleproject/issues"
  • name é o nome da distribuição do seu pacote. Pode ser qualquer nome, desde que contenha apenas letras, números, ., _ e -. Também não deve ser feito em PyPI. Certifique-se de atualizá-lo com seu nome de usuário para este tutorial, pois isso garante que você não tentará enviar um pacote com o mesmo nome de um que já existe.

  • version is the package version. (Some build backends allow it to be specified another way, such as from a file or Git tag.)

  • authors é usado para identificar o autor do pacote; você especifica um nome e um e-mail para cada autor. Você também pode listar maintainers no mesmo formato.

  • description é um resumo curto do pacote contendo apenas uma frase.

  • readme is a path to a file containing a detailed description of the package. This is shown on the package detail page on PyPI. In this case, the description is loaded from README.md (which is a common pattern). There also is a more advanced table form described in the pyproject.toml guide.

  • requires-python gives the versions of Python supported by your project. An installer like pip will look back through older versions of packages until it finds one that has a matching Python version.

  • classifiers fornece o índice e pip alguns metadados adicionais sobre seu pacote. Nesse caso, o pacote é compatível apenas com Python 3, está licenciado sob a licença MIT e é independente do sistema operacional. Você deve sempre incluir pelo menos a(s) versão(ões) do Python em que seu pacote funciona, em que licença seu pacote está disponível e em quais sistemas operacionais seu pacote funcionará. Para obter uma lista completa de classificadores, consulte https://pypi.org/classifiers/.

  • urls permite listar qualquer número de links extras para mostrar no PyPI. Geralmente, isso pode ser para o código-fonte, a documentação, os rastreadores de problemas, etc.

See the pyproject.toml guide for details on these and other fields that can be defined in the [project] table. Other common fields are keywords to improve discoverability and the dependencies that are required to install your package.

Criando README.md#

Abra README.md e insira o seguinte conteúdo. Você pode personalizar isso se desejar.

# Example Package

This is a simple example package. You can use
[GitHub-flavored Markdown](https://guides.github.com/features/mastering-markdown/)
to write your content.

Criando um LICENSE#

É importante que cada pacote enviado para o Índice de Pacotes do Python inclua uma licença. Isso informa aos usuários que instalam seu pacote os termos sob os quais eles podem usá-lo. Para obter ajuda na escolha de uma licença, consulte https://choosealicense.com/. Depois de escolher uma licença, abra LICENSE e digite o texto da licença. Por exemplo, se você escolheu a licença MIT:

Copyright (c) 2018 The Python Packaging Authority

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

A maioria dos backends de construção inclui automaticamente arquivos de licença em pacotes. Consulte a documentação do seu backend para obter mais detalhes.

Incluindo outros arquivos#

Os arquivos listados acima serão incluídos automaticamente em sua distribuição fonte. Se você deseja incluir arquivos adicionais, veja a documentação para seu backend de construção.

Gerando arquivos de distribuição#

O próximo passo é gerar pacotes de distribuição para o pacote. Estes são arquivos que são enviados para o Índice de Pacotes do Python e podem ser instalados pelo pip.

Certifique-se de que você tenha a versão mais recente da construção do PyPA instalada:

python3 -m pip install --upgrade build
py -m pip install --upgrade build

Dica

Se você tiver problemas ao instalá-los, veja o tutorial Instalando pacotes.

Agora, execute este comando a partir do mesmo diretório no qual pyproject.toml está localizado:

python3 -m build
py -m build

Este comando deve produzir muito texto e, uma vez concluído, deve gerar dois arquivos no diretório dist:

dist/
├── example_package_YOUR_USERNAME_HERE-0.0.1-py3-none-any.whl
└── example_package_YOUR_USERNAME_HERE-0.0.1.tar.gz

O arquivo tar.gz é um distribuição fonte enquanto o arquivo .whl é uma distribuição construída. As versões pip mais recentes instalam preferencialmente distribuições construídas, mas irão recorrer às distribuições fonte se necessário. Você deve sempre enviar uma distribuição fonte e fornecer distribuições construídas para as plataformas com as quais seu projeto é compatível. Neste caso, nosso pacote de exemplo é compatível com Python em qualquer plataforma, portanto, apenas uma distribuição construída é necessária.

Enviando os arquivos de distribuição#

Finalmente, é hora de enviar seu pacote para o Índice de Pacotes do Python!

A primeira coisa que você precisa fazer é registrar uma conta no Test PyPI, que é uma instância separada do índice do pacote destinada a teste e experimentação. É ótimo para coisas como este tutorial, em que não queremos necessariamente enviar para o índice real. Para registrar uma conta, vá em https://test.pypi.org/account/register/ e conclua as etapas nessa página. Você também precisará verificar seu endereço de e-mail antes de enviar qualquer pacote. Para mais detalhes, veja Usando TestPyPI.

Para enviar seu projeto com segurança, você precisará de um token de API do PyPI. Crie um em https://test.pypi.org/manage/account/#api-tokens, definindo o “Escopo” como “Toda a conta”. Não feche a página antes de copiar e salvar o token – você não verá o token novamente.

Agora que você está registrado, você pode usar twine para enviar os pacotes de distribuição. Você precisará instalar o Twine:

python3 -m pip install --upgrade twine
py -m pip install --upgrade twine

Uma vez instalado, execute o Twine para enviar de todos os arquivos em dist:

python3 -m twine upload --repository testpypi dist/*
py -m twine upload --repository testpypi dist/*

Você será solicitado a fornecer um nome de usuário e uma senha. Para o nome de usuário, use __token__. Para a senha, use o valor do token, incluindo o prefixo pypi-.

Depois que o comando for concluído, você deverá ver uma saída semelhante a esta:

Uploading distributions to https://test.pypi.org/legacy/
Enter your username: __token__
Uploading example_package_YOUR_USERNAME_HERE-0.0.1-py3-none-any.whl
100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 8.2/8.2 kB • 00:01 • ?
Uploading example_package_YOUR_USERNAME_HERE-0.0.1.tar.gz
100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 6.8/6.8 kB • 00:00 • ?

Depois de enviado, seu pacote pode ser visto no Test PyPI; por exemplo: https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE.

Instalando seu pacote recém-enviado#

Você pode usar o pip para instalar seu pacote e verificar se ele funciona. Crie um ambiente virtual e instale seu pacote a partir do Test PyPI:

python3 -m pip install --index-url https://test.pypi.org/simple/ --no-deps example-package-YOUR-USERNAME-HERE
py -m pip install --index-url https://test.pypi.org/simple/ --no-deps example-package-YOUR-USERNAME-HERE

Certifique-se de especificar seu nome de usuário no nome do pacote!

pip deve instalar o pacote de Test PyPI e a saída deve ser semelhante a esta:

Collecting example-package-YOUR-USERNAME-HERE
  Downloading https://test-files.pythonhosted.org/packages/.../example_package_YOUR_USERNAME_HERE_0.0.1-py3-none-any.whl
Installing collected packages: example_package_YOUR_USERNAME_HERE
Successfully installed example_package_YOUR_USERNAME_HERE-0.0.1

Nota

Este exemplo usa o sinalizador --index-url para especificar Test PyPI em vez do PyPI real. Além disso, ele especifica --no-deps. Como o Test PyPI não tem os mesmos pacotes que o PyPI real, é possível que a tentativa de instalação de dependências falhe ou instale algo inesperado. Embora nosso pacote de exemplo não tenha nenhuma dependência, é uma boa prática evitar instalar dependências ao usar o Test PyPI.

Você pode testar se ele foi instalado corretamente importando o pacote. Certifique-se de que ainda está em seu ambiente virtual e execute o Python:

python3
py

e importe o pacote:

>>> from example_package_YOUR_USERNAME_HERE import example
>>> example.add_one(2)
3

Próximos passos#

Parabéns, você empacotou e distribuiu um projeto Python! ✨ 🍰 ✨

Lembre-se de que este tutorial mostrou como enviar o seu pacote para Test PyPI, que não é um armazenamento permanente. O sistema de teste ocasionalmente exclui pacotes e contas. É melhor usar Test PyPI para testes e experimentos como este tutorial.

Quando estiver pronto para carregar um pacote real para o Índice de Pacotes do Python, você pode fazer quase o mesmo que fez neste tutorial, mas com estas diferenças importantes:

  • Escolha um nome único e memorável para o seu pacote. Você não precisa acrescentar seu nome de usuário como fez no tutorial, mas você não pode usar um nome existente.

  • Registre uma conta em https://pypi.org – observe que esses são dois servidores separados e os detalhes de login do servidor de teste não são compartilhados com o servidor principal.

  • Use twine upload dist/* para enviar seu pacote e insira suas credenciais para a conta que você registrou no PyPI real. Agora que você está enviando o pacote em produção, você não precisa especificar --repository; o pacote será enviado para https://pypi.org/ por padrão.

  • Instale seu pacote a partir do PyPI real usando python3 -m pip install [seu-pacote].

Neste ponto, se você quiser ler mais sobre o empacotamento de bibliotecas Python, aqui estão algumas coisas que você pode fazer:

  • Read about advanced configuration for your chosen build backend: Hatchling, setuptools, Flit, PDM.

  • Look at the guides on this site for more advanced practical information, or the discussions for explanations and background on specific topics.

  • Considere as ferramentas de empacotamento que fornecem uma única interface de linha de comando para gerenciamento e empacotamento de projetos, como hatch, flit, pdm e poetry.


Notas