Publique seu pacote Python no PyPI#

Nas lições anteriores de empacotamento Python, você aprendeu:

  1. O que é um pacote Python

  2. Como tornar seu código instalável.

Objetivos de Aprendizagem

Nesta lição você aprenderá como:

Você fará todo o trabalho de desenvolvimento nesta lição usando Hatch.

Depois que seu pacote estiver no PyPI, você pode publicá-lo no conda-forge (que é um channel no conda) usando Grayskull.

Você aprenderá como publicar no conda-forge na próxima lição.

Gráfico mostrando o workflow de alto nível de empacotamento. À esquerda você vê um gráfico com code, metadata e tests. Esses itens entram no seu pacote. Uma seta à direita leva a uma caixa build distribution files. Outra seta à direita leva a uma caixa publish to PyPI, que tem uma seta contendo sdist e wheel indicando que esses arquivos vão para o PyPI para hospedagem. A partir do PyPI há uma setacontendo sdist, pois você pode então conectar ao conda-forge para um build automatizado que envia distribuições do PyPI para o conda-forge.

Você precisa fazer o build do seu pacote Python para publicá-lo no PyPI (ou Conda). O processo de build organiza seu code e metadata em um formato de distribuição que pode ser enviado ao PyPI e subsequentemente baixado e instalado pelos usuários.#

TestPyPI vs PyPI#

Existem dois repositórios associados ao PyPI para os quais você pode enviar seu pacote Python.

  1. TestPyPI: TestPyPI é um repositório de pacotes fornecido pelo PyPI que você pode usar para testar se seu pacote pode ser enviado, baixado e instalado corretamente. Este é um ótimo lugar para praticar e aprender como publicar um pacote sem expor seu pacote incompleto no serviço real do PyPI.

  2. PyPI: Este é o repositório PyPI de produção, ao vivo, onde você pode publicar oficialmente seu pacote Python e de onde os usuários obterão seu pacote. IMPORTANTE: Publique seu pacote no PyPI somente quando estiver pronto para ser usado por outras pessoas e/ou confiante de que se tornará um pacote que você manterá. O PyPI não é um lugar para praticar aprender a publicar um pacote Python.

As etapas para publicar no TestPyPI vs. PyPI são semelhantes, com exceção de uma url diferente. Indicaremos onde elas diferem.

4 etapas para publicar um pacote Python no TestPyPI (ou PyPI)#

Nesta lição você aprenderá como publicar seu pacote no TestPyPI usandoHatch. Há 4 coisas que você precisa fazer para publicar seu pacote Python no TestPyPI. Você precisa:

  1. Criar um ambiente de desenvolvimento do pacote

  2. Fazer o build do seu pacote usando hatch build.Fazer o build de um pacote é o processo de transformar seu code em dois tipos de arquivos de distribuição: sdist e wheel. O arquivo de distribuição wheel é particularmente importante para usuários que usarão pip para instalar seu pacote.

  3. Criar uma conta no TestPyPI (ou PyPI): Você precisará criar uma conta no TestPyPI e um API token associado, que fornece permissões para você enviar seu pacote. Quando publicar seu pacote no PyPI depois, precisará de uma conta e token PyPI separados.

  4. Publicar no TestPyPI usando hatch publish

Em uma lição futura, você aprenderá como criar um workflow automatizado de GitHub Actions que publica uma versão atualizada do seu pacote no PyPI toda vez que você criar um release no GitHub.

Saiba mais sobre build de pacote Pythons no nosso guia

Etapa 1: Criar um ambiente de desenvolvimento de pacote Python#

A primeira etapa para fazer o build do seu pacote é criar um ambientede desenvolvimento. O ambiente Python conterá todas as dependências necessárias tanto para instalar quanto para trabalhar no seu pacote.

Use o Hatch para criar seu ambiente.

# This will create a default environment with your package installed in editable mode
> hatch env create
# If you have already created an environment this command will return Environment `default` already exists

Em seguida, visualize todos os ambientes atuais aos quais o hatch tem acesso:

> hatch env show
     Standalone
┏━━━━━━━━━┳━━━━━━━━━┓
┃ Name    ┃ Type    ┃
┡━━━━━━━━━╇━━━━━━━━━┩
│ default │ virtual │
└─────────┴─────────┘

Depois ative o ambiente. Observe que quando você chama um shell de um ambiente Hatch, ele instalará automaticamente seu pacote no ambiente em modo de desenvolvimento ou editable.

# Hatch shell can be used to activate your environment
> hatch shell
... Installing project in development mode
source "/Path/to/env/here/hatch/env/virtual/pyosPackage/Mk7F5Y0T/sphinx-2i2c-theme/bin/activate"

Visualize o que há no ambiente usando pip list:

➜ pip list
Package         Version      Editable project location
--------------- ------------ ----------------------------------------------------
numpy           1.26.3
pandas          2.1.4
pip             23.3.1
pyosPackage     0.1.0        /path/to/your/project/here/pyosPackage
python-dateutil 2.8.2
pytz            2023.3.post1
six             1.16.0
tzdata          2023.4

A qualquer momento você pode sair do ambiente usando exit.

➜ hatch shell
source "/Users/leahawasser/Library/Application Support/hatch/env/virtual/pyospackage/twO2iQR3/pyospackage/bin/activate"

# Notice here you're in the (pyospackage) environment which is the default
pyosPackage (☊ main) [✎ ×1 ] is 📦 v0.1.4 via 🐍 pyenv (pyospackage)
➜ exit

pyosPackage (☊ main) [✎ ×1 ] is 📦 v0.1.4 via 🐍 pyenv took 43s
➜

Hatch e ambientes#

Nos bastidores, quando o hatch cria um novo virtual environment, por padrão ele usa venv[1], que é a ferramenta padrão de gerenciamentode ambientes que vem com instalações Python.

O Hatch irá:

  1. Criar um novo virtualenv (venv) localizado no seu computador.

  2. Instalar seu pacote no ambiente em modo editable (semelhante a python-m pip install -e). Isso significa que instala tanto o seu projeto quanto as dependências do projeto declaradas no seu arquivo pyproject.toml.

Etapa 2: Fazer o build das distribuições sdist e wheel do seu pacote#

Depois de configurar seu ambiente de desenvolvimento, você está pronto para fazer o build do seu pacote usando Hatch. Lembre-se de que build é o processo de transformar a estrutura de arquivos do seu pacote Python em dois arquivos de distribuição:

  1. A distribuição wheel é uma versão pré-buildada do seu package. É útil para usuários, pois pode ser instalada diretamente usando uma ferramenta como pip. Este arquivo tem a extensão .whl.

  2. A source distribution contém os arquivos que compõem seu pacote em formato não buildado. Este arquivo terá a extensão .tar.gz.

Você usará o Hatch como ferramenta de Front end que faz o build do sdist e wheel do seu pacote usando o build back-end hatchling. O build back-end hatchling é usado porque você o declarou no seu arquivo pyproject.toml na lição anterior.

Para fazer o build do seu pacote, execute hatch build:

➜ hatch build
──────────────── sdist ─────────────────
dist/pyospackage-0.1.tar.gz
──────────────── wheel ─────────────────
dist/pyospackage-0.1-py3-none-any.whl

Saiba mais sobre build de pacote Python

Você pode saber mais sobre build na página de build do nosso guia de empacotamento.

O sdist é importante se você deseja publicar seu pacote no conda-forge. Você aprenderá sobre isso em uma lição posterior.

Parabéns — você criou os arquivos de distribuição do seu pacote Python #

Você fez o build do seu pacote Python e criou os arquivos de distribuição do pacote. A próxima etapa é configurar sua conta no TestPyPI para publicar seu pacote.

Etapa 3. Configure sua conta no TestPyPI#

Em seguida, você configurará uma conta no TestPyPI. Lembre-se de que você está usando o TestPyPI aqui em vez do PyPI real como forma de aprender com segurança como publicar um pacote sem «lançar» acidentalmente seu pacote antes que esteja pronto.

TestPyPI vs. PyPI

Se você tem um pacote sobre o qual está confiante de que pertence ao PyPI, todas as etapas abaixo também funcionarão para você. Quando publicar usando Hatch, você chamará hatch publish para publicar diretamente no PyPI em vez de hatch publish -r test, que publica no TestPyPI.

  1. Abra um navegador web e acesse o site do TestPyPI.

  2. Crie uma conta se ainda não tiver uma. Certifique-se de armazenar sua senha em um local seguro!

  3. Depois de configurar uma conta, faça login.

  4. Pesquise em https://test.pypi.org/ (e também em https://pypi.org/) para garantir que o nome do package que você selecionou ainda não existe. Se você estiver usando nosso pyosPackage de teste, sugerimos adicionar seu nome ou nome de usuário do GitHub ao final do nome do pacote para garantir queseja único.

Exemplo: pyosPackage_yourNameHere.

Como renomear seu pacote Python se o nome já estiver em uso no (test)PyPI

Obrigatório

  1. Pesquise nos locais de publicação para garantir que seu novo nome não esteja em uso (TestPyPI, PyPI, conda-forge)

  2. Atualize o nome do projeto no seu arquivo pyproject.toml (por exemplo,name = "pyospackage_yourNameHere")

  3. Atualize o nome da pasta do module para ser o mesmo (por exemplo, src/pyospackage_yourNameHere)

  4. Faça rebuild do seu projeto (hatch build)

  5. Publique seu pacote para reservar o nome (continue este tutorial!)

  • Atualize o nome do repositório GitHub para alinhar com o novo nome do pacote

  • Atualize a pasta local do projeto para corresponder ao novo nome do pacote (por exemplo, pyospackage_yourNameHere/src)

  • Atualize menções ao nome do repositório em outros arquivos (por exemplo, README.md)

Configurar autenticação de 2 fatores (2FA)

A autenticação de 2 fatores é um processo de login seguro que permite usar um dispositivo de backup ao qual somente você tem acesso para validar que a pessoa que está fazendo login é realmente você. Ela resolve o problema de phishing de senhas, em que outra pessoa obtém acesso a uma senha e consegue entrar na sua conta.

Isso importa no PyPI porque alguém poderia fazer login na sua conta e fazer upload de uma versão do seu pacote com problemas de segurança. Esses problemas afetarão todos os seus usuários quando eles baixarem e instalarem essa versão do pacote.

A autenticação de 2 fatores é obrigatória para autenticação no PyPI a partir de 1 de janeiro de 2024.

Passo 4. Criar um token de upload do pacote#

Para fazer upload do seu pacote para o TestPyPI (ou PyPI), você precisará criar um token para a sua conta primeiro e, em seguida, criar um token específico para o pacote. (Se você já concluiu esta etapa anteriormente, pode reutilizar os tokens quando fizer upload do pacote novamente.)

Por que criar tokens específicos para o pacote?

O ideal é criar um token específico para o pacote. Quando você cria um token para toda a conta, isso permite que qualquer pessoa com acesso à conta acesse todos os seus projetos no TestPyPI (ou PyPI). Ao criar um token específico para o pacote, você limita o escopo do token apenas ao seu pacote. Essa é uma forma segura de configurar tudo, especialmente se você estiver colaborando com outras pessoas no desenvolvimento do pacote.

Siga os passos abaixo para criar seu token#

  • Faça login no TestPyPI e acesse as configurações da sua conta

  • Role até a seção API tokens

  • Clique no botão Add API Token

    • Se você é novo no TestPyPI e ainda não tem nenhum pacote lá, OU se você tem outros pacotes no TestPyPI mas está fazendo upload de um pacote novo, será necessário criar um token para toda a conta.

  • Ao criar o token, copie o valor do token e armazene-o em um local seguro antes de fechar o navegador.

Seu token deve se parecer com algo assim:

pypi-abunchofrandomcharactershere...

Ele deve começar com pypi, seguido de um hífen e uma sequência de caracteres.

Fazer upload para o TestPyPI usando Hatch#

Depois de ter o token, você está pronto para publicar no TestPyPI.

  • Execute hatch publish -r test

-r significa repository. Neste caso, como você está publicando no TestPyPI, usará -r test. O Hatch então pedirá um nome de usuário e credenciais.

  • Digite a palavra __token__ como nome de usuário. Isso informa ao TestPyPI que você está usando um valor de token em vez de um nome de usuário.

  • Cole o valor do seu token do TestPyPI no prompt Enter your credentials:

❯ hatch publish -r test
Enter your username: __token__
Enter your credentials: <paste-your-token-value-here>
dist/pyospackage-0.1-py3-none-any.whl ... already exists
dist/pyospackage-0.1.tar.gz ... already exists

Se suas credenciais forem válidas e você já tiver executado hatch build e, portanto, tiver seus 2 arquivos de distribuição em um diretório dist/, o Hatch publicará seu pacote no TestPyPI.

O Hatch também tem um sistema de cache, então depois que você inserir suas credenciais, ele as lembrará.

Instalar seu pacote a partir do TestPyPI#

Quando o upload do seu pacote estiver concluído, você pode instalá-lo a partir do TestPyPI. Você encontra as instruções de instalação na página inicial do TestPyPI do pacote que acabou de fazer upload.

Uma captura de tela da página do TestPyPI para pyosPackage. No topo aparece pyosPackage 0.1.0 com as instruções de instalação via pip abaixo. A página inicial do pacote exibe informações do arquivo README do pacote.

Esta é uma página inicial de exemplo para o pyosPackage que acabou de ser enviado. Observe que no topo da página há instruções de como instalar o pacote a partir do TestPyPI. Você pode simplesmente copiar esse código e usá-lo para instalar seu pacote localmente a partir do TestPyPI.#

Como exemplo, confira nossa página inicial do pyosPackage da pyOpenSci no TestPyPI. Observe que a página contém informações sobre a versão atual do pacote e também instruções de instalação, como segue:

python -m pip install -i https://test.pypi.org/simple/ pyosPackage

Importante

Publicar no TestPyPI vs PyPI Embora você possa instalar a partir do TestPyPI, não é recomendado publicar no TestPyPI como forma permanentede instalar seu pacote. Na verdade, você não pode, porque o TestPyPI pode excluir contas depois de algum tempo. O TestPyPI é um lugar perfeito para aprender a publicar seu pacote e testar o processode instalação. Mas seu objetivo final deve ser publicar no PyPI depois que você tiver definido seu workflow e seu pacote estiver pronto para deploy.

Hora de instalar seu pacote#

  • No seu computador, ative o ambiente de desenvolvimento em que deseja instalar o pacote recém-publicado.

  • Execute as instruções de instalação do seu pacote a partir do TestPyPI.

> conda activate pyospkg-dev
> pip install -i https://test.pypi.org/simple/ youPackageNameHere
> conda list

> hatch shell
> pip install -i https://test.pypi.org/simple/ youPackageNameHere
> pip list

O valor de ferramentas ponta a ponta como hatch, flit e poetry

Nesta lição você está usando Hatch e hatchling para criar, fazer build e publicar seu pacote Python. Clique aqui para saber mais sobre outras ferramentas de empacotamento no ecossistema.

Token específico do pacote vs trusted publisher#

Para a manutenção de longo prazo do seu pacote, você tem duas opções relacionadas à publicação no PyPI.

  1. Você pode criar um token específico do pacote que usará para publicar seu pacote (manualmente) no PyPI. Essa é uma ótima opção se você não quiser automatizar seu workflow de publicação no PyPI.

  2. Você também pode criar um workflow de publicação automatizado no GitHub usando GitHub Actions. Essa é uma ótima forma de facilitar o processo de publicação e também suporta uma equipe de mantenedores em crescimento. Nesse caso, sugerimos que você não se preocupe com o token e, em vez disso, configure um GitHub Actions específico que publique seu pacote quando você fizer um release. Você pode então criar um workflow de «trusted publisher» no PyPI.

Trusted Publishing

Embora seja possível publicar a partir do GitHub Actions usando tokens, recomendamos a abordagem Trusted Publishing, pois ela também oferece benefícios significativos de segurança e usabilidade.

No aspecto de usabilidade, quando o Trusted Publishing está habilitado, os usuários não precisam mais criar manualmente API tokensno PyPI e armazená-los no workflow de release do GitHub.

No aspecto de segurança, o Trusted Publishing reduz um risco relacionado ao fato de o API token ser de longa duração: com API tokens, assim que um atacante obtém acesso a ele, pode publicar muitos packages e versões em seu nome (dependendo do escopo do token), até que você descubra o comprometimento do token e rotacione a credencial. O Trusted Publishing evita esse problema ao gerar tokens de curta duração que expiram automaticamente.

Por esses benefícios, recomenda-se que os usuários usem somente o workflow de release do GitHub Actions para publicar pacotes.

Você aprenderá a criar o workflow automatizado de trusted publisher em uma lição seguinte.

OPCIONAL: Se você quiser usar um workflow de publicação manual baseado em token#

Se você planeja usar seu token regularmente para publicar no PyPI, recomendamos fortemente repetir os passos acima para criar um token específico para o seu novo pacote.

Para fazer isso:

  1. Acesse o TestPyPI.

  2. Navegue até a seção «Your Projects» da sua conta

  3. Clique no botão manage do projeto para o qual deseja adicionar um token

  4. Acesse settings

  5. Clique em «Create a token for your-pacote-name-here»

  6. Crie o token e siga os passos acima para publicar seu pacote usando o token específico do repository.

E pronto!

Trusted Publishing em vez de publicação baseada em token

O Trusted Publishing gerará tokens de curta duração, com escopo no projeto, sob demanda, somente quando um workflow de release específico for acionado. Isso resolve todos os problemas de segurança e usabilidade associados ao armazenamento de credenciais em arquivos/secrets do GitHub.

Você publicou seu pacote no TestPyPI!#

Parabéns. Você publicou com sucesso seu pacote no TestPyPI. Se você tem um pacote pronto para uso no mundo real no PyPI de verdade, pode seguir os mesmos passos (com as diferenças mencionadas acima) para publicá-lo no PyPI.

Depois de publicar no PyPI, você pode adicionar facilmente seu pacote ao ecossistema conda-forge usando a ferramenta grayskull.

Você aprenderá a fazer isso na próxima lição.

Notas de rodapé#