Declarando os metadados do projeto

A PEP 621 especifica como escrever metadados principais de um projeto em um arquivo pyproject.toml para ferramentas relacionadas ao empacotamento consumirem. Ele define a seguinte especificação como a fonte canônica para o formato usado.

Existem dois tipos de metadados: estáticos e dinâmicos. Metadados estáticos são especificados diretamente no arquivo pyproject.toml e não podem ser especificados ou alterados por uma ferramenta. Os metadados dinâmicos são listados por meio do campo dynamic (definido posteriormente nesta especificação) e representam os metadados que uma ferramenta fornecerá posteriormente.

Os campos definidos nesta especificação DEVEM estar em uma tabela chamada [project] no arquivo pyproject.toml. Nenhuma ferramenta pode adicionar campos a esta tabela que não sejam definidos por esta especificação. Para ferramentas que desejam armazenar suas próprias configurações em pyproject.toml, eles podem usar a tabela [tool] conforme definido na especificação da declaração de dependências de construção. A falta de uma tabela [project] implicitamente significa que o backend da construção fornecerá dinamicamente todos os campos.

Os únicos campos que precisam ser definidos estaticamente são:

  • name

Os campos que são obrigatórios, mas podem ser especificados ou estaticamente ou listados como dinâmicos são:

  • version

Todos os outros campos são considerados opcionais e podem ser especificados estaticamente, listados como dinâmicos ou não especificados.

name

O nome do projeto.

As ferramentas DEVEM normalizar este nome, conforme especificado por PEP 503, assim que for lido para consistência interna.

version

A versão do projeto conforme suportado pela PEP 440.

Os usuários DEVEM preferir especificar versões já normalizadas.

description

A descrição resumida do projeto.

readme

A descrição completa do projeto (isto é, o README).

O campo aceita uma string ou uma tabela. Se for uma string, então é um caminho relativo ao pyproject.toml para um arquivo texto contendo a descrição completa. As ferramentas DEVEM assumir que a codificação do arquivo é UTF-8. Se o caminho do arquivo termina com um sufixo .md, ou sua versão em caixa alta, então as ferramentas DEVEM presumir que o tipo de conteúdo é text/markdown. Se o caminho do arquivo termina em .rst, então as ferramentas DEVEM presumir que o tipo de conteúdo é text/x-rst. Se uma ferramenta reconhece mais extensões do que esta PEP, elas podem inferir o tipo de conteúdo para o usuário sem especificar este campo como dunamic. Para todos os sufixos não reconhecidos quando um tipo de conteúdo não é fornecido, as ferramentas DEVEM levantar um erro.

O campo readme também pode receber uma tabela. A chave file tem um valor string que representa um caminho relativo a pyproject.toml para um arquivo contendo a descrição completa. A chave text tem um valor de string que é a descrição completa. Essas chaves são mutuamente exclusivas, portanto, as ferramentas DEVEM levantar um erro se os metadados especificarem ambas as chaves.

Uma tabela especificada no campo readme também possui um campo content-type que recebe uma string especificando o tipo de conteúdo da descrição completa. Uma ferramenta DEVE levantar um erro se os metadados não especificarem esse campo na tabela. Se os metadados não especificarem o parâmetro charset, será considerado UTF-8. As ferramentas PODEM oferecer suporte a outras codificações, se assim o desejarem. As ferramentas PODEM oferecer suporte a tipos de conteúdo alternativos que podem transformar em um tipo de conteúdo conforme suportado pelos metadados principais. Caso contrário, as ferramentas DEVEM levantar um erro para tipos de conteúdo não suportados.

requires-python

Os requisitos de versão do Python do projeto.

license

A tabela pode ter uma de duas chaves. A chave file tem um valor de string que é um caminho de arquivo relativo a pyproject.toml para o arquivo que contém a licença do projeto. As ferramentas DEVEM presumir que a codificação do arquivo é UTF-8. A chave text tem um valor de string que é a licença do projeto. Essas chaves são mutuamente exclusivas, portanto, uma ferramenta DEVE levantar um erro se os metadados especificarem ambas as chaves.

authors/maintainers

As pessoas ou organizações consideradas “autoras” do projeto. O significado exato está aberto à interpretação – pode listar os autores originais ou primários, mantenedores atuais ou proprietários do pacote.

O campo “maintainers” é semelhante a “authors” no sentido de que seu significado exato está aberto à interpretação.

These fields accept an array of tables with 2 keys: name and email. Both values must be strings. The name value MUST be a valid email name (i.e. whatever can be put as a name, before an email, in RFC 822) and not contain commas. The email value MUST be a valid email address. Both keys are optional, but at least one of the keys must be specified in the table.

O uso dos dados para preencher metadados principais deve ser feito da seguinte forma:

  1. Se somente name for fornecido, o valor vai em Author ou Maintainer conforme apropriado.

  2. Se somente email é fornecido, o valor vai em Author-email ou Maintainer-email conforme apropriado.

  3. Se email e name são fornecidos, o valor vai em Author-email ou Maintainer-email conforme apropriado, com o formado {name} <{email}>.

  4. Vários valores devem ser separados por vírgulas.

keywords

As palavras-chave do projeto.

classifiers

Classificadores Trove que se aplicam ao projeto.

urls

Uma tabela de URLs onde a chave é o rótulo da URL e o valor é a URL em si.

Pontos de entrada

Existem três tabelas relacionadas aos pontos de entrada. A tabela [project.scripts] corresponde ao grupo console_scripts na especificação de pontos de entrada. A chave da tabela é o nome do ponto de entrada e o valor é a referência do objeto.

A tabela [project.gui-scripts] corresponde ao grupo gui_scripts na especificação de pontos de entrada. Seu formato é o mesmo que [project.scripts].

A tabela [project.entry-points] é uma coleção de tabelas. O nome de cada subtabela é um grupo de pontos de entrada. A chave e a semântica do valor são iguais a [project.scripts]. Os usuários NÃO DEVEM criar subtabelas aninhadas, mas sim manter os grupos de pontos de entrada em apenas um nível de profundidade.

Backends de construção DEVEM levantar um erro se os metadados definem uma tabela [project.entry-points.console_scripts] ou [project.entry-points.gui_scripts], pois elas seriam ambíguas perante [project.scripts] e [project.gui-scripts], respectivamente.

dependencies/optional-dependencies

As dependências (opcionais) do projeto.

Para dependencies, é uma chave cujo valor é um array de strings. Cada string representa uma dependência do projeto e DEVE ser formatada como uma string válida PEP 508. Cada string mapeia diretamente para um Requires-Dist.

Para optional-dependencies, é uma tabela onde cada chave especifica um extra e cujo valor é um vetor de strings. As strings dos vetores devem ser strings válidas da PEP 508. As chaves DEVEM ser valores válidos para Provides-Extra. Cada valor no vetor torna-se assim uma entrada correspondente de Requer-Dist para os metadados correspondentes de Provides-Extra.

dynamic

Especifica quais campos listados por esta PEP foram intencionalmente não especificados para que outra ferramenta possa/vai fornecer tais metadados dinamicamente. Isso delineia claramente quais metadados são propositalmente não especificados e espera-se que permaneçam não especificados em comparação a serem fornecidos por meio de ferramentas posteriormente.

  • Um backend de construção DEVE respeitar metadados especificados estaticamente (o que significa que os metadados não listam o campo em dynamic).

  • Um backend de construção DEVE gerar um erro se os metadados especificarem name em dynamic.

  • Se a especificação de metadados principais lista um campo como “Required”, então os metadados DEVEM especificar o campo estaticamente ou listá-lo em dynamic (backends de construção DEVEM gerar um erro, caso contrário , ou seja, não deve ser possível que um campo obrigatório não seja listado de alguma forma na tabela [project]).

  • Se a especificação de metadados principais listar um campo como “Optional”, os metadados PODEM listá-lo em dynamic se a expectativa for um backend de construção fornecerá os dados para o campo mais tarde.

  • Os backends de construção DEVEM levantar um erro se os metadados especificarem um campo estaticamente, além de serem listados em `` dynamic``.

  • Se os metadados não listam um campo em dynamic, então um backend de construção NÃO PODE preencher os metadados necessários em nome do usuário (ou seja, dynamic é a única maneira de permitir que uma ferramenta preencha metadados e o usuário deve optar pelo preenchimento).

  • Os backends de construção DEVEM levantar um erro se os metadados especificarem um campo em dynamic, mas o backend de construção não foi capaz de determinar os dados para ele (omitir os dados, se determinado como o valor exato, é aceitável) .