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).
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
#
Tipo TOML: string
Campo correspondente dos metadados principais: 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
#
Tipo TOML: string
Campo correspondente dos metadados principais: 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
#
Tipo TOML: string
Campo correspondente dos metadados principais: Summary
The summary description of the project in one line. Tools MAY error if this includes multiple lines.
readme
#
Tipo TOML: string ou tabela
Campos correspondente dos metadados principais: Description e Description-Content-Type
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
#
Tipo TOML: string
Campo correspondente dos metadados principais: Requires-Python
Os requisitos de versão do Python do projeto.
license
#
Tipo TOML: tabela
Campo correspondente dos metadados principais: 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.
keywords
#
Tipo TOML: vetor de strings
Campo correspondente dos metadados principais: Keywords
As palavras-chave do projeto.
classifiers
#
Tipo TOML: vetor de strings
Campo correspondente dos metadados principais: Classifier
Classificadores Trove que se aplicam ao projeto.
urls
#
Tipo TOML: tabela com chaves e valores de strings
Campo correspondente dos metadados principais: Project-URL
Uma tabela de URLs onde a chave é o rótulo da URL e o valor é a URL em si.
Pontos de entrada#
Tipo TOML: tabela (
[project.scripts]
,[project.gui-scripts]
e[project.entry-points]
)
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
#
Tipo TOML: Vetor de strings da PEP 508 (
dependencies
) e uma tabela com valores de vetores de strings da PEP 508 (optional-dependencies
)Campo correspondente dos metadados principais: Requires-Dist e Provides-Extra
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
#
Tipo TOML: vetor de string
Campo correspondente dos metadados principais: 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
emdynamic
.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.