pyproject.toml specification#

Aviso

This is a technical, formal specification. For a gentle, user-friendly guide to pyproject.toml, see Escrevendo seu pyproject.toml.

The pyproject.toml file acts as a configuration file for packaging-related tools (as well as other tools).

Nota

This specification was originally defined in PEP 518 and PEP 621.

The pyproject.toml file is written in TOML. Three tables are currently specified, namely [build-system], [project] and [tool]. Other tables are reserved for future use (tool-specific configuration should use the [tool] table).

Declaring build system dependencies: the [build-system] table#

The [build-system] table declares any Python level dependencies that must be installed in order to run the project’s build system successfully.

A tabela [build-system] é usada para armazenar dados relacionados a construção. Inicialmente, apenas uma chave da tabela é válida e é obrigatória para a tabela: requires. Esta chave deve ter um valor de uma lista de strings que representam dependências necessárias para executar o sistema de construção. As strings nesta lista seguem a especificação de especificadores de versão.

An example [build-system] table for a project built with setuptools is:

[build-system]
# Minimum requirements for the build system to execute.
requires = ["setuptools"]

Build tools are expected to use the example configuration file above as their default semantics when a pyproject.toml file is not present.

Tools should not require the existence of the [build-system] table. A pyproject.toml file may be used to store configuration details other than build-related data and thus lack a [build-system] table legitimately. If the file exists but is lacking the [build-system] table then the default values as specified above should be used. If the table is specified but is missing required fields then the tool should consider it an error.

To provide a type-specific representation of the resulting data from the TOML file for illustrative purposes only, the following JSON Schema would match the data format:

{
    "$schema": "http://json-schema.org/schema#",

    "type": "object",
    "additionalProperties": false,

    "properties": {
        "build-system": {
            "type": "object",
            "additionalProperties": false,

            "properties": {
                "requires": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            },
            "required": ["requires"]
        },

        "tool": {
            "type": "object"
        }
    }
}

Declaring project metadata: the [project] table#

The [project] table specifies the project’s core metadata.

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 (isso inclui dados referenciados pelo metadados, por exemplo, o conteúdo de arquivos referenciados pelos metadados). Os metadados dinâmicos são listados por meio da chave dynamic (definido posteriormente nesta especificação) e representam os metadados que uma ferramenta fornecerá posteriormente.

The lack of a [project] table implicitly means the build backend will dynamically provide all keys.

As únicas chaves que precisam ser definidos estaticamente são:

  • name

As chaves que são obrigatórias, mas podem ser especificadas estaticamente ou listadas como dinâmicas são:

  • version

Todas as outras chaves são consideradas opcionais e podem ser especificadas estaticamente, listadas como dinâmicas ou não especificadas.

A lista completa de chaves permitidas na tabela [project] são:

  • authors

  • classifiers

  • dependencies

  • description

  • dynamic

  • entry-points

  • gui-scripts

  • keywords

  • license

  • maintainers

  • name

  • optional-dependencies

  • readme

  • requires-python

  • scripts

  • urls

  • version

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 definido na especificação de especificadores de versão.

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

description#

The summary description of the project in one line. Tools MAY error if this includes multiple lines.

readme#

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

A chave 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 presumir 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 esta chave como dynamic. Para todos os sufixos não reconhecidos quando um tipo de conteúdo não é fornecido, as ferramentas DEVEM levantar um erro.

A chave 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 na chave readme também possui uma chave 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.

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

Estas chaves aceitam um vetor de tabelas com 2 chaves: name e email. Ambos os valores devem ser strings. O valor name DEVE ser um nome de e-mail válido (ou seja, o que quer que possa ser colocado como um nome, antes de um e-mail, em RFC 822) e não conter vírgulas. O valor email DEVE ser um endereço de email válido. Ambas as chaves são opcionais, mas ao menos uma das chaves deve ser especificada na tabela.

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 chaves listadas por esta PEP foram intencionalmente não especificadas 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 a chave 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 a chave estaticamente ou listá-la em dynamic (backends de construção DEVEM gerar um erro, caso contrário , ou seja, não deve ser possível que uma chave obrigatória não seja listada 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 a chave mais tarde.

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

  • Se os metadados não listam uma chave 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 uma chave 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) .

Arbitrary tool configuration: the [tool] table#

The [tool] table is where any tool related to your Python project, not just build tools, can have users specify configuration data as long as they use a sub-table within [tool], e.g. the flit tool would store its configuration in [tool.flit].

A mechanism is needed to allocate names within the tool.* namespace, to make sure that different projects do not attempt to use the same sub-table and collide. Our rule is that a project can use the subtable tool.$NAME if, and only if, they own the entry for $NAME in the Cheeseshop/PyPI.

Histórico#

  • May 2016: The initial specification of the pyproject.toml file, with just a [build-system] containing a requires key and a [tool] table, was approved through PEP 518.

  • November 2020: The specification of the [project] table was approved through PEP 621.