Criando um README amigável para PyPI

Os arquivos README podem ajudar seus usuários a entender o seu projeto e podem ser usados para definir a descrição do seu projeto no PyPI. Este guia ajuda a criar um README em um formato amigável ao PyPI e inclui seu README em seu pacote para que apareça no PyPI.

Criando um arquivo README

Arquivos README para projetos Python são frequentemente chamados de README, README.txt, README.rst ou README.md.

Para que seu README seja exibido corretamente no PyPI, escolha uma linguagem de marcação suportada pelo PyPI. Os formatos suportados pelo renderizador de README do PyPI são:

É comum salvar seu arquivo README na raiz de seu projeto, no mesmo diretório que seu arquivo setup.py.

Incluindo seu README nos metadados do seu pacote

Para incluir o conteúdo do README como a descrição do pacote, defina os metadados Description e Description-Content-Type do seu projeto, normalmente no arquivo setup.py do seu projeto.

Ver também

Por exemplo, para definir esses valores em um arquivo setup.py do pacote, use long_description e long_description_content_type do setup().

Defina o valor de long_description para o conteúdo (não o caminho) do próprio arquivo README. Defina o long_description_content_type para um valor aceito no estilo Content-Type para a marcação do seu arquivo README, como text/plain, text/t-rst (para reStructuredText) ou text/markdown.

Nota

Se você estiver usando o Markdown do GitHub para escrever a descrição de um projeto, certifique-se de atualizar as seguintes ferramentas:

python3 -m pip install --user --upgrade setuptools wheel twine

py -m pip install --user --upgrade setuptools wheel twine

As versões mínimas exigidas das respectivas ferramentas são:

  • setuptools >= 38.6.0

  • wheel >= 0.31.0

  • twine >= 1.11.0

É recomendado que você use twine para enviar pacotes de distribuição do projeto:

twine upload dist/*

Por exemplo, veja este arquivo setup.py, que lê o conteúdo de README.md como long_description e identifica a marcação como Markdown do GitHub:

from setuptools import setup

# read the contents of your README file
from pathlib import Path
this_directory = Path(__file__).parent
long_description = (this_directory / "README.md").read_text()

setup(
    name='an_example_package',
    # other arguments omitted
    long_description=long_description,
    long_description_content_type='text/markdown'
)

Validando a marcação reStructuredText

Se o seu README for escrito em reStructuredText, qualquer marcação inválida irá impedi-lo de renderizar, fazendo com que o PyPI mostre apenas o código-fonte não tratado do README.

Observe que as extensões Sphinx usadas em docstrings, como diretivas e funções (por exemplo, “:py:func:`getattr`” ou “:ref:`my-reference-label`”), não são permitidas aqui e resultarão em mensagens de erro como “Error: Unknown interpreted text role "py:func".”.

Você pode verificar se há erros de marcação em seu README antes de enviar:

  1. Instale a versão mais recente do twine; versão 1.12.0 ou superior é necessária:

    python3 -m pip install --upgrade twine

    py -m pip install --upgrade twine

  2. Construa o sdist e o wheel para seu projeto conforme descrito em Empacotando seu projeto.

  3. Execute twine check no sdist e wheel:

    twine check dist/*

    Este comando relatará quaisquer problemas ao processar seu README. Se sua marcação renderizar corretamente, o comando produzirá Checking Distribution FILENAME: Passed.