Empacotando e distribuindo projetos¶

Esta seção cobre alguns detalhes adicionais sobre configuração, empacotamento e distribuição de projetos Python com setuptools que não são cobertos pelo tutorial introdutório em Empacotando projetos Python. Ele ainda assume que você já está familiarizado com o conteúdo da página Instalando pacotes.

A seção não visa cobrir as melhores práticas para o desenvolvimento de projetos Python como um todo. Por exemplo, ele não fornece orientação ou recomendações de ferramentas para controle de versão, documentação ou teste.

Para mais material de referência, veja Construindo e Distribuindo Pacotes na documentação setuptools, mas note que alguns conteúdos de aviso podem estar desatualizados. No caso de conflitos, dê preferência ao conselho do Guia de Usuário para Empacotamento de Python.

Conteúdo

Requisitos para empacotamento e distribuição
Configurando seu projeto
Trabalhando em “modo de desenvolvimento”
Empacotando seu projeto
- Distribuições fontes
- Wheels
  - Wheels de Puro Python
  - Wheels de Plataforma
Enviando seu Projeto para PyPI
- Criar uma conta
- Enviar suas distribuições

Requisitos para empacotamento e distribuição ¶

Primeiro, certifique-se de que você já cumpriu os requisitos para instalação de pacotes.

Instale “twine” 1:

Unix/macOS

python3 -m pip install twine

Windows

py -m pip install twine

Você precisará disso para enviar as distribuições do seu projeto para o PyPI (veja abaixo).

Configurando seu projeto ¶

Arquivos iniciais ¶

setup.py ¶

O arquivo mais importante é setup.py que existe na raiz do diretório do seu projeto. Para obter um exemplo, consulte o setup.py no projeto de exemplo PyPA.

setup.py tem duas funções principais:

É o arquivo onde vários aspectos do seu projeto são configurados. A principal característica do setup.py é que ele contém uma função global setup(). Os argumentos nomeados para esta função são como os detalhes específicos do seu projeto são definidos. Os argumentos mais relevantes são explicados em a seção abaixo de.
É a interface de linha de comando para executar vários comandos relacionados a tarefas de empacotamento. Para obter uma lista dos comandos disponíveis, execute python3 setup.py --help-commands.

setup.cfg ¶

setup.cfg é um arquivo ini que contém opções padrão para os comandos setup.py. Para obter um exemplo, consulte o setup.cfg no projeto de exemplo PyPA.

README.rst / README.md ¶

Todos os projetos devem conter um arquivo leia-me que cubra o objetivo do projeto. O formato mais comum é reStructuredText com uma extensão “rst”, embora isso não seja um requisito; múltiplas variantes do Markdown também são suportadas (veja o argumento long_description_content_type do setup()).

Para obter um exemplo, consulte o README.md do projeto de exemplo PyPA.

Nota

Projetos usando setuptools 0.6.27+ têm arquivos leia-me padrão (README.rst, README.txt ou README) incluídos nas distribuições de código-fonte por padrão. A biblioteca interna distutils adota este comportamento a partir do Python 3.7. Adicionalmente, setuptools 36.4.0+ incluirá um README.md se encontrado. Se você estiver usando setuptools, você não precisa listar seu arquivo leia-me em MANIFEST.in. Caso contrário, inclua para ser explícito.

MANIFEST.in ¶

Um MANIFEST.in é necessário quando você precisa empacotar arquivos adicionais que não são incluídos automaticamente em uma distribuição de código-fonte. Para obter detalhes sobre como escrever um arquivo MANIFEST.in, incluindo uma lista do que é incluído por padrão, consulte “Incluindo arquivos em distribuições de código-fonte com MANIFEST.in”.

No entanto, você pode não ter que usar um MANIFEST.in. Por exemplo, o projeto de amostra PyPA removeu seu arquivo de manifesto, uma vez que todos os arquivos necessários foram incluídos pelo setuptools 43.0.0 e mais recentes.

Nota

MANIFEST.in não afeta distribuições binárias como wheels.

LICENSE.txt ¶

Cada pacote deve incluir um arquivo de licença detalhando os termos de distribuição. Em muitas jurisdições, os pacotes sem uma licença explícita não podem ser legalmente usados ou distribuídos por ninguém que não seja o detentor dos direitos autorais. Se não tiver certeza de qual licença escolher, você pode usar recursos como Escolha uma licença do GitHub ou consultar um advogado.

Para obter um exemplo, consulte o LICENSE.txt do projeto de exemplo PyPA.

<seu pacote>¶

Embora não seja obrigatório, a prática mais comum é incluir seus módulos e pacotes Python em um único pacote de nível superior que tem o mesmo name do seu projeto, ou algo muito próximo.

Para obter um exemplo, consulte o pacote de exemplo que está incluído no projeto de exemplo PyPA.

Argumentos de setup()¶

Como mencionado acima, o principal recurso do setup.py é que ele contém uma função global setup(). Os argumentos nomeados para esta função são como os detalhes específicos do seu projeto são definidos.

Os argumentos mais relevantes são explicados a seguir. A maioria dos fragmentos fornecidos são retirados do setup.py contido no projeto de exemplo PyPA.

`name`¶

name='sample',

Este é o nome do seu projeto, determinando como ele está listado no PyPI. Conforme PEP 508, nomes de projetos válidos devem:

Consistir apenas em letras ASCII, dígitos, sublinhados (_), hífenes (-) e/ou pontos (.) e
Começar e terminar com uma letra ou dígito ASCII.

A comparação de nomes de projetos não diferencia maiúsculas de minúsculas e trata sequências arbitrariamente longas de sublinhados, hífenes e/ou pontos como iguais. Por exemplo, se você registrar um projeto chamado cool-stuff, os usuários poderão baixá-lo ou declarar uma dependência dele usando qualquer uma das seguintes formas de escrever:

Cool-Stuff
cool.stuff
COOL_STUFF
CoOl__-.-__sTuFF

`version`¶

version='1.2.0',

Esta é a versão atual do seu projeto, permitindo que seus usuários determinem se têm ou não a versão mais recente e indiquem em quais versões específicas eles testaram seu próprio software.

As versões são exibidas em PyPI para cada lançamento se você publicar seu projeto.

Veja Escolhendo um esquema de versionamento para mais informações sobre maneiras de usar versões para transmitir informações de compatibilidade para seus usuários.

Se o código do projeto em si precisa de acesso em tempo de execução para a versão, a maneira mais simples é manter a versão em setup.py e seu código. Se você preferir não duplicar o valor, existem algumas maneiras de gerenciar isso. Consulte a seção de tópicos avançados “Fonte única da versão”.

`description`¶

description='A sample Python project',
long_description=long_description,
long_description_content_type='text/x-rst',

Da uma descrição curta e longa para seu projeto.

Esses valores serão exibidos no PyPI se você publicar seu projeto. No pypi.org, a interface do usuário exibe description no banner cinza e long_description na seção chamada “Descrição do Projeto”.

description também é exibido em listas de projetos. Por exemplo, ele é visível nas páginas de resultados de pesquisa, como https://pypi.org/search/?q=jupyter, nas listas da página inicial de projetos populares e novos lançamentos e na lista de projetos que você mantém no perfil de sua conta (como https://pypi.org/user/jaraco/).

Um tipo de conteúdo pode ser especificado com o argumento long_description_content_type, que pode ser um de text/plain, text/x-rst ou text/markdown, correspondendo a nenhuma formatação, reStructuredText (reST), e o dialeto Markdown com sabor do GitHub de Markdown respectivamente.

`url`¶

url='https://github.com/pypa/sampleproject',

Fornece o URL da página inicial do seu projeto.

`author`¶

author='A. Random Developer',
author_email='author@example.com',

Fornece detalhes sobre o autor.

`license`¶

license='MIT',

O argumento license não precisa indicar a licença sob a qual seu pacote está sendo lançado, embora você possa opcionalmente fazer isso se desejar. Se você estiver usando uma licença padrão bem conhecida, sua indicação principal pode e deve ser por meio do argumento classifiers. Existem classificadores para todas as principais licenças de código aberto.

O argumento license é mais comumente usado para indicar diferenças de licenças conhecidas ou para incluir sua própria licença exclusiva. Como regra geral, é uma boa ideia usar uma licença padrão bem conhecida, tanto para evitar confusão quanto porque algumas organizações evitam software cuja licença não é aprovada.

`classifiers`¶

classifiers=[
    # How mature is this project? Common values are
    #   3 - Alpha
    #   4 - Beta
    #   5 - Production/Stable
    'Development Status :: 3 - Alpha',

    # Indicate who your project is intended for
    'Intended Audience :: Developers',
    'Topic :: Software Development :: Build Tools',

    # Pick your license as you wish (should match "license" above)
    'License :: OSI Approved :: MIT License',

    # Specify the Python versions you support here. In particular, ensure
    # that you indicate whether you support Python 2, Python 3 or both.
    'Programming Language :: Python :: 2',
    'Programming Language :: Python :: 2.7',
    'Programming Language :: Python :: 3',
    'Programming Language :: Python :: 3.6',
    'Programming Language :: Python :: 3.7',
    'Programming Language :: Python :: 3.8',
    'Programming Language :: Python :: 3.9',
],

Fornece uma lista de classificadores que categorizam seu projeto. Para obter uma lista completa, consulte https://pypi.org/classifiers/.

Embora a lista de classificadores seja frequentemente usada para declarar quais versões do Python um projeto suporta, essas informações são usadas apenas para pesquisar e navegar por projetos no PyPI, não para instalar projetos. Para realmente restringir em quais versões do Python um projeto pode ser instalado, use o argumento python_requires.

Para evitar que um pacote seja enviado para PyPI, use o classificador especial 'Private :: Do Not Upload'. PyPI sempre rejeitará pacotes com classificadores começando com "Private ::'.

`keywords`¶

keywords='sample setuptools development',

Lista as palavras-chave que descrevem seu projeto.

`project_urls`¶

project_urls={
    'Documentation': 'https://packaging.python.org/tutorials/distributing-packages/',
    'Funding': 'https://donate.pypi.org',
    'Say Thanks!': 'http://saythanks.io/to/example',
    'Source': 'https://github.com/pypa/sampleproject/',
    'Tracker': 'https://github.com/pypa/sampleproject/issues',
},

Lista URLs relevantes adicionais sobre seu projeto. Este é o lugar para se conectar a rastreadores de bugs, repositórios fontes ou onde oferecer suporte ao desenvolvimento de pacotes. A string da chave é o texto exato que será exibido no PyPI.

`packages`¶

packages=find_packages(include=['sample', 'sample.*']),

Defina packages para uma lista de todos pacotes em seu projeto, incluindo seus subpacotes, sub-subpacotes, etc. Embora os pacotes possam ser listados manualmente, setuptools.find_packages() encontra-os automaticamente. Use o argumento nomeado include para encontrar apenas os pacotes fornecidos. Use o argumento nomeado exclude para omitir pacotes que não devem ser lançados e instalados.

`py_modules`¶

py_modules=["six"],

Se o seu projeto contém qualquer módulo Python de arquivo único que não faz parte de um pacote, defina py_modules para uma lista dos nomes dos módulos (menos a extensão .py) para fazer o setuptools ficar ciente deles.

`install_requires`¶

install_requires=['peppercorn'],

“install_requires” deve ser usado para especificar quais dependências um projeto precisa minimamente para ser executado. Quando o projeto é instalado pelo pip, esta é a especificação que é usada para instalar suas dependências.

Para mais informações sobre como usar “install_requires”, veja install_requires vs Arquivos de requisitos.

`python_requires`¶

Se o seu projeto só funciona em certas versões do Python, definir o argumento python_requires para a string apropriada especificadora de versão da PEP 440 impedirá pip de instalar o projeto em outras versões do Python. Por exemplo, se seu pacote for apenas para Python 3+, escreva:

python_requires='>=3',

Se o seu pacote for para Python 2.6, 2.7 e todas as versões do Python 3 começando com 3.3, escreva:

python_requires='>=2.6, !=3.0.*, !=3.1.*, !=3.2.*',

E por aí vai.

Nota

O suporte para esse recurso é relativamente recente. As distribuições de código-fonte e wheels do seu projeto (veja Empacotando seu projeto) devem ser construídas usando pelo menos a versão 24.2.0 do setuptools para que o argumento python_requires seja reconhecido e os metadados apropriados gerados.

Além disso, apenas as versões 9.0.0 e superiores do pip reconhecem os metadados de python_requires. Usuários com versões anteriores do pip serão capazes de baixar e instalar projetos em qualquer versão do Python, independentemente dos valores de python_requires dos projetos.

`package_data`¶

package_data={
    'sample': ['package_data.dat'],
},

Frequentemente, arquivos adicionais precisam ser instalados em um pacote. Esses arquivos geralmente são dados intimamente relacionados à implementação do pacote ou arquivos de texto contendo documentação que pode ser do interesse dos programadores que usam o pacote. Esses arquivos são chamados de “dados do pacote”.

O valor deve ser um mapeamento do nome do pacote para uma lista de nomes de caminhos relativos que devem ser copiados para o pacote. Os caminhos são interpretados como relativos ao diretório que contém o pacote.

Para mais informações, veja Incluindo arquivos de dados da documentação do setuptools.

`data_files`¶

data_files=[('my_data', ['data/data_file'])],

Embora configurar Dados de pacote seja suficiente para a maioria das necessidades, em alguns casos você pode precisar colocar arquivos de dados fora de seus pacotes. A diretiva data_files permite que você faça isso. É mais útil se você precisar instalar arquivos que são usados por outros programas, que podem não ter conhecimento dos pacotes Python.

Cada par (directory, files) na sequência especifica o diretório de instalação e os arquivos a serem instalados nele. O directory deve ser um caminho relativo (embora isso possa mudar no futuro, consulte relatório de problema #92 do wheel) e é interpretado em relação ao prefixo de instalação (sys.prefix do Python para uma instalação padrão; site.USER_BASE para uma instalação do usuário). Cada nome de arquivo em files é interpretado em relação ao script setup.py no topo da distribuição do código-fonte do projeto.

Para obter mais informações, consulte a seção distutils em Instalando arquivos adicionais.

Nota

Ao instalar pacotes como ovo, data_files não é suportado. Então, se seu projeto usa setuptools, você deve usar pip para instalá-lo. Alternativamente, se você deve usar python setup.py, então você precisa passar a opção --old-and-unmanageable.

`scripts`¶

Embora setup() tenha suporte a uma palavra-chave scripts para apontar para scripts pré-fabricados para instalar, o recomendado A abordagem para obter compatibilidade entre plataformas é usar pontos de entrada console_scripts (veja abaixo).

`entry_points`¶

entry_points={
  ...
},

Use esta palavra-chave para especificar quaisquer plugins que seu projeto fornece para quaisquer pontos de entrada nomeados que podem ser definidos por seu projeto ou outros dos quais você depende.

Para obter mais informações, consulte a seção sobre Comportamento de Publicidade da documentação do setuptools.

O ponto de entrada mais comumente usado é “console_scripts” (veja abaixo).

`console_scripts`¶

entry_points={
    'console_scripts': [
        'sample=sample:main',
    ],
},

Use pontos de entrada de console_script para registrar suas interfaces de script. Você pode então deixar o conjunto de ferramentas lidar com o trabalho de transformar essas interfaces em scripts reais 2. Os scripts serão gerados durante a instalação do seu distribuição.

Para mais informações, veja Entry Points (pontos de entrada, em português) da documentação do setuptools.

Escolhendo um esquema de versionamento ¶

Conformidade de padrões para interoperabilidade ¶

Diferentes projetos Python podem usar diferentes esquemas de controle de versão com base nas necessidades daquele projeto específico, mas todos eles são obrigados a cumprir com o esquema públicode versão flexível especificado na PEP 440 para serem suportados em ferramentas e bibliotecas como pip e setuptools.

Aqui estão alguns exemplos de números de versão compatíveis:

2.0.dev1  # Development release
2.0a1     # Alpha Release
2.0b1     # Beta Release
2.0rc1    # Release Candidate
2.0       # Final Release
2.0.post1 # Post Release
10       # Date based release
        # Serial release

Para acomodar ainda mais as variações históricas nas abordagens de numeração de versão, PEP 440 também define uma técnica abrangente para normalização de versão que mapeia grafias variantes de diferentes números de versão para uma forma canônica padronizada.

Opções de esquema ¶

Versionamento semântico (preferencial)¶

Para novos projetos, o esquema de controle de versão recomendado é baseado em Versionamento semântico, mas adota uma abordagem diferente para lidar com pré-lançamentos e metadados de compilação.

A essência do versionamento semântico é um esquema de numeração MAIOR.MENOR.MANUTENÇÃO de 3 partes, onde o autor do projeto incrementa:

Versão PRINCIPAL quando eles fazem alterações de API incompatíveis,
Versão MENOR quando adicionam funcionalidade de maneira compatível com versões anteriores, e
Versão MANUTENÇÃO quando eles fazem correções de bugs compatíveis com versões anteriores.

Adotar essa abordagem como autor do projeto permite que os usuários façam uso dos especificadores de “lançamentos compatíveis”, onde name ~= X.Y requer pelo menos a versão X.Y, mas também permite qualquer versão posterior com uma versão PRINCIPAL correspondente.

Projetos Python que adotam versões semânticas devem obedecer às cláusulas 1-8 da especificação de Versionamento Semântico 2.0.0.

Versionamento baseado em data ¶

O versionamento semântico não é uma escolha adequada para todos os projetos, como aqueles com uma cadência de lançamento baseada em tempo regular e um processo de descontinuidade que fornece avisos para vários lançamentos antes da remoção de um recurso.

Uma vantagem principal do versionamento baseado em data é que é simples dizer quantos anos o conjunto de recursos básicos de uma determinada versão recebe apenas o número da versão.

Os números de versão para projetos baseados em data normalmente assumem a forma de ANO.MÊS (por exemplo, 12.04, 15.10).

Versionamento serial ¶

Este é o esquema de versionamento mais simples possível e consiste em um único número que é incrementado a cada versão.

Embora o versionamento serial seja muito fácil de gerenciar como desenvolvedor, é o mais difícil de rastrear como usuário final, pois os números de versão serial transmitem pouca ou nenhuma informação sobre compatibilidade com versões anteriores da API.

Esquemas híbridos ¶

Combinações dos esquemas acima são possíveis. Por exemplo, um projeto pode combinar o versionamento baseado em data com o versionamento serial para criar um esquema de numeração ANO.SÉRIE que transmite prontamente a idade aproximada de um lançamento, mas não se compromete com uma cadência de lançamento particular dentro do ano.

Versionamento de pré-lançamento ¶

Independentemente do esquema de versionamento base, os pré-lançamentos para uma determinada versão final podem ser publicados como:

zero ou mais versões dev (denotadas com um sufixo “.devN”)
zero ou mais versões alfa (denotadas com um sufixo “.aN”)
zero ou mais versões beta (denotadas com um sufixo “.bN”)
zero ou mais candidatos a lançamento (denotados com um sufixo “.rcN”)

pip e outros instaladores de pacotes Python modernos ignoram os pré-lançamentos por padrão ao decidir quais versões de dependências instalar.

Identificadores de versão local ¶

Identificadores de versão pública são projetados para suportar distribuição via PyPI. As ferramentas de distribuição de software do Python também suportam a noção de um identificador de versão local, que pode ser usado para identificar compilações de desenvolvimento local não destinadas à publicação, ou variantes modificadas de uma versão mantida por um redistribuidor.

Um identificador de versão local assume a forma <identificador de versão pública>+<rótulo de versão local>. Por exemplo:

1.2.0.dev1+hg.5.b11e5e6f0b0b  # 5th VCS commit since 1.2.0.dev1 release
1.2.1+fedora.4                # Package with downstream Fedora patches applied

Trabalhando em “modo de desenvolvimento”¶

Você pode instalar um projeto em modo “editável” ou “desenvolvedor” enquanto trabalha nele. Quando instalado como editável, um projeto pode ser editado no local sem reinstalação: alterações nos arquivos fonte Python em projetos instalados como editáveis serão refletidas na próxima vez que um processo de interpretador for iniciado.

Para instalar um pacote Python no modo “editável”/”desenvolvedor” mude o diretório para a raiz do diretório do projeto e execute:

python3 -m pip install -e .

O sinalizador de linha de comando do pip -e é abreviação de --editable, e . refere-se ao diretório de trabalho atual, então juntos, isso significa instalar o diretório atual (ou seja, seu projeto) em modo editável. Isso também instalará quaisquer dependências declaradas com install_requires e quaisquer scripts declarados com console_scripts. As dependências serão instaladas no modo usual e não editável.

Você também pode querer instalar algumas de suas dependências no modo editável. Por exemplo, supondo que seu projeto requer “foo” e “bar”, mas você deseja “bar” instalado do VCS no modo editável, então você poderia construir um arquivo de requisitos como:

-e .
-e bar @ git+https://somerepo/bar.git

A primeira linha diz para instalar seu projeto e todas as dependências. A segunda linha substitui a dependência “bar”, de modo que seja preenchida a partir do VCS, não PyPI.

Se, no entanto, você quiser “bar” instalado de um diretório local em modo editável, o arquivo de requisitos deve ser semelhante a este, com os caminhos locais no topo do arquivo:

-e /path/to/project/bar
-e .

Caso contrário, a dependência será resolvida pelo PyPI, devido à ordem de instalação do arquivo de requisitos. Para mais informações sobre os arquivos de requisitos, consulte a seção Requirements File na documentação do pip. Para obter mais informações sobre as instalações de VCS, consulte a seção VCS Support da documentação do pip.

Por último, se você não deseja instalar nenhuma dependência, pode executar:

python3 -m pip install -e . --no-deps

Para mais informações, veja a seção Development Mode na documentação do setuptools..

Empacotando seu projeto ¶

Para ter seu projeto instalável de um Índice de Pacotes como o PyPI, você precisará criar uma Distribuição (também conhecida como “Pacote”) para seu projeto.

Antes de compilar wheels e sdists para seu projeto, você precisará instalar o pacote build:

Unix/macOS

python3 -m pip install build

Windows

py -m pip install build

Distribuições fontes ¶

Minimamente, você deve criar uma Distribuição Fonte:

Unix/macOS

python3 -m build --sdist

Windows

py -m build --sdist

Uma “distribuição fonte” é não construída (ou seja, não é uma Distribuição Construída) e requer uma etapa de construção quando instalada pelo pip. Mesmo se a distribuição for puro Python (ou seja, não contém extensões), ainda envolve uma etapa de construção para construir os metadados de instalação de setup.py e/ou setup.cfg.

Wheels ¶

Você também deve criar uma wheel para o seu projeto. Uma wheel é um pacote construído que pode ser instalado sem a necessidade de passar pelo processo de “construção”. Instalar wheel é substancialmente mais rápido para o usuário final do que instalar a partir de uma distribuição original.

Se o seu projeto for puro Python, você criará uma “Wheel de Python Puro” (consulte a seção abaixo).

Se o seu projeto contém extensões compiladas, então você criará o que é chamado de *Wheel de Plataforma* (veja a seção abaixo).

Nota

Se o seu projeto também tiver suporte a Python 2 e não contiver extensões C, você deve criar o que é chamado de Wheel Universal adicionando o seguinte ao seu arquivo setup.cfg:

[bdist_wheel]
universal=1

Use esta configuração apenas se o seu projeto não tiver extensões C e tiver suporte ao Python 2 e 3.

Wheels de Puro Python ¶

Wheels de Python Puro contêm nenhuma extensão compilada e, portanto, só exigem um único wheel Python.

Para construir o wheel:

Unix/macOS

python3 -m build --wheel

Windows

py -m build --wheel

O pacote wheel detectará que o código é puro Python, e construirá um wheel cujo nome pode ser usado em qualquer instalação do Python 3. Para obter detalhes sobre a nomenclatura de arquivos wheel, consulte PEP 425.

Se você executar build sem --wheel ou --sdist, ele irá construir os dois arquivos para você; isso é útil quando você não precisa de vários wheels.

Wheels de Plataforma ¶

Wheels de Plataforma são wheels que são específicos para uma certa plataforma, como Linux, macOS ou Windows, geralmente em razão de conter extensões compiladas.

Para construir o wheel:

Unix/macOS

python3 -m build --wheel

Windows

py -m build --wheel

O pacote wheel detectará que o código não é puro Python e construirá um wheel cujo nome só pode ser usado na plataforma em que foi construído. Para obter detalhes sobre a nomenclatura de arquivos wheel, consulte PEP 425.

Nota

PyPI oferece suporte atualmente a envios de wheels de plataforma do Windows, macOS e da ABI multidistro manylinux*. Detalhes sobre o último estão definidos em PEP 513.

Enviando seu Projeto para PyPI ¶

Quando você executou o comando para criar sua distribuição, um novo diretório dist/ foi criado no diretório raiz do seu projeto. É onde você encontrará seus arquivos de distribuição para enviar.

Nota

Esses arquivos são criados apenas quando você executa o comando para criar sua distribuição. Isso significa que a qualquer momento que você alterar a fonte do seu projeto ou a configuração no arquivo setup.py, você precisará reconstruir esses arquivos novamente antes de distribuir as alterações para PyPI.

Nota

Antes de lançar no repositório principal do PyPI, você pode preferir treinar com o site de teste do PyPI que é redefinido em uma base semirregular. Veja Usando TestPyPI sobre como definir sua configuração para usá-lo.

Aviso

Em outros recursos, você pode encontrar referências ao uso de python setup.py register e python setup.py upload. Esses métodos de registro e envio de um pacote são fortemente desencorajados, pois podem usar uma conexão HTTP de texto simples ou HTTPS não verificada em algumas versões Python, permitindo que seu nome de usuário e senha sejam interceptados durante a transmissão.

Dica

O analisador de reStructuredText usado no PyPI não é Sphinx! Além disso, para garantir a segurança de todos os usuários, certos tipos de URLs e diretivas são proibidos ou removidos (por exemplo, a diretiva .. raw::). Antes de tentar enviar sua distribuição, você deve verificar se suas descrições breves/longas fornecidas no setup.py são válidas. Você pode fazer isso executando twine check em todos arquivos do seu pacote:

twine check dist/*

Criar uma conta ¶

Primeiro, você precisa de uma conta de usuário do PyPI. Você pode criar uma conta usando o formulário no site do PyPI.

Agora você criará um token de API do PyPI para que possa enviar o seu projeto com segurança.

Acesse https://pypi.org/manage/account/#api-tokens e crie um novo token de API; não limite seu escopo a um projeto específico, já que você está criando um novo projeto.

Não feche a página antes de copiar e salvar o token – você não verá o token novamente.

Nota

Para evitar ter que copiar e colar o token toda vez que você enviar, você pode criar um arquivo $HOME/.pypirc:

[pypi]
username = __token__
password = <the token value, including the `pypi-` prefix>

Esteja ciente de que isso armazena seu token em texto simples.

Para mais detalhes, veja a especificação do .pypirc.

Enviar suas distribuições ¶

Assim que tiver uma conta, você pode enviar suas distribuições para o PyPI usando twine.

O processo de envio de uma versão é o mesmo, independentemente de o projeto já existir ou não no PyPI – se ainda não existir, será criado automaticamente quando a primeira versão for carregada.

Para a segunda versão e as subsequentes, PyPI requer apenas que o número da versão da nova versão seja diferente de todas as versões anteriores.

twine upload dist/*

Você pode ver se o seu pacote foi enviado com sucesso navegando para a URL https://pypi.org/project/<projetoexemplo> onde projetoexemplo é o nome do seu projeto que você enviou. O seu projeto pode demorar um ou dois minutos para aparecer no site.

1: Dependendo da sua plataforma, isso pode exigir acesso de root ou de administrador. pip está atualmente considerando mudar isso tornando as instalações de usuário o comportamento padrão.
2: Especificamente, a abordagem “console_script” gera arquivos .exe no Windows, que são necessários por causa dos arquivos .exe de casos especiais do sistema operacional. Recursos de execução de script como PATHEXT e o Inicializador do Python para Windows permitem que scripts sejam usados em muitos casos, mas não em todos.