Especificações de metadados principais#
Os campos definidos nas especificações a seguir devem ser considerados válidos, completos e não sujeitos a alterações. Os campos obrigatórios são:
Metadata-VersionNameVersion
Todos os outros campos são opcionais.
O formato de arquivo padrão para metadados (incluindo em wheels e projetos instalados) é baseado no formato de cabeçalhos de e-mail. No entanto, os formatos de e-mail foram revisados várias vezes e não é especificado exatamente qual RFC de e-mail se aplica aos metadados do pacote. Na ausência de uma definição precisa, o padrão prático é definido pelo que o módulo da biblioteca padrão email.parser pode analisar usando a política compat32.
Sempre que os metadados são serializados para um fluxo de bytes (por exemplo, para salvar em um arquivo), as strings devem ser serializadas usando a codificação UTF-8.
Embora a PEP 566 tenha definido uma maneira de transformar metadados em um dicionário compatível com JSON, isso ainda não é usado como um formato de intercâmbio padrão. A necessidade de ferramentas para trabalhar com anos de pacotes existentes torna difícil mudar para um novo formato.
Nota
Interpretando metadados antigos: Na PEP 566, a especificação do formato do campo do especificador de versão foi relaxada para aceitar a sintaxe usada por ferramentas de publicação populares (nomeadamente para remover o requisito de que os especificadores de versão devem estar entre parênteses). Os consumidores de metadados podem querer usar regras de formatação mais relaxadas, mesmo para arquivos de metadados que são nominalmente inferiores à versão 2.1.
Metadata-Version#
Novo na versão 1.0.
Versão do formato de arquivo; valores válidos são “1.0”, “1.1”, “1.2”, “2.1”, “2.2” e “2.3”.
Ferramentas automatizadas que consomem metadados DEVEM avisar se metadata_version é maior que a versão mais alta à qual oferecem suporte, e DEVEM falhar se metadata_version tem uma versão maior do que a versão mais alta à qual oferecem suporte (como descrito na especificação de especificadores de versão, a versão principal é o valor antes do primeiro ponto).
Para uma compatibilidade mais ampla, as ferramentas de construção PODEM escolher produzir metadados de distribuição usando a versão de metadados mais baixa que inclui todos os campos necessários.
Exemplo:
Metadata-Version: 2.3
Nome#
Novo na versão 1.0.
Alterado na versão 2.1: Added restrictions on format from the name format.
The name of the distribution. The name field is the primary identifier for a distribution. It must conform to the name format specification.
Exemplo:
Name: BeagleVote
Para propósitos de comparação, os nomes devem ser normalizados antes da comparação.
Versão#
Novo na versão 1.0.
Uma string contendo o número da versão da distribuição. Este campo deve estar no formato especificado na especificação de especificadores de versão.
Exemplo:
Version: 1.0a2
Dynamic (vários usos)#
Novo na versão 2.2.
Uma string contendo o nome de outro campo de metadados principal. Os nomes dos campos Name, Version e Metadata-Version não podem ser especificados neste campo.
Quando encontrados nos metadados de uma distribuição fonte, as seguintes regras se aplicam:
Se um campo não estiver marcado como
Dynamic, então o valor do campo em qualquer wheel construído a partir do sdist DEVE corresponder ao valor do sdist. Se o campo não estiver no sdist e não estiver marcado comoDynamic, ele NÃO DEVE estar presente no wheel.Se um campo for marcado como
Dynamic, ele pode conter qualquer valor válido em um wheel construído a partir do sdist (incluindo não estar presente).
Se a versão dos metadados sdist for anterior à versão 2.2, todos os campos devem ser tratados como se tivessem sido especificados com Dynamic (ou seja, não há restrições especiais sobre os metadados dos wheels construídos a partir do sdist).
Em qualquer contexto que não seja uma distribuição fonte, Dynamic é apenas para informação e indica que o valor do campo foi calculado no tempo de construção do wheel, e pode não ser o mesmo que o valor no sdist ou em outros wheels para o projeto.
Detalhes completos da semântica de Dynamic são descritos na PEP 643.
Platform (vários usos)#
Novo na versão 1.0.
Uma especificação da plataforma que descreve um sistema operacional suportado pela distribuição que não está listado nos classificadores Trove de “Operating System”. Veja “Classifier” abaixo.
Exemplos:
Platform: ObscureUnix
Platform: RareDOS
Supported-Platform (vários usos)#
Novo na versão 1.1.
As distribuições binárias contendo um arquivo PKG-INFO usarão o campo Supported-Platform em seus metadados para especificar o sistema operacional e a CPU para os quais a distribuição binária foi compilada. A semântica do campo Supported-Platform não é especificada nesta PEP.
Exemplo:
Supported-Platform: RedHat 7.2
Supported-Platform: i386-win32-2791
Summary#
Novo na versão 1.0.
Um resumo de uma linha do que a distribuição faz.
Exemplo:
Summary: A module for collecting votes from beagles.
Descrição#
Novo na versão 1.0.
Alterado na versão 2.1: Este campo pode ser especificado no corpo da mensagem.
Uma descrição mais longa da distribuição que pode ter vários parágrafos. Software que lida com metadados não deve presumir nenhum tamanho máximo para este campo, embora as pessoas não devam incluir seu manual de instruções como a descrição.
O conteúdo deste campo pode ser escrito usando a marcação reStructuredText [1]. Para programas que funcionam com metadados, o suporte à marcação é opcional; os programas também podem exibir o conteúdo do campo como está. Isso significa que os autores devem ser conservadores na marcação que usam.
Para oferecer suporte a linhas vazias e linhas com indentação em relação ao formato do RFC 822, qualquer caractere CRLF deve ser sufixado por 7 espaços seguidos por um caractere de encadeamento ou pipe (“|”). Como resultado, o campo Description é codificado em um campo dobrado que pode ser interpretado pelo analisador RFC822 [2].
Exemplo:
Description: This project provides powerful math functions
|For example, you can use `sum()` to sum numbers:
|
|Example::
|
| >>> sum(1, 2)
| 3
|
Esta codificação implica que quaisquer ocorrências de um CRLF seguido por 7 espaços e um caractere pipe devem ser substituídos por um único CRLF quando o campo é desdobrado usando um leitor de RFC822.
Alternativamente, a descrição da distribuição pode ser fornecida no corpo da mensagem (ou seja, após uma linha completamente em branco após os cabeçalhos, sem recuo ou outra formatação especial necessária).
Description-Content-Type#
Novo na versão 2.1.
Uma string informando a sintaxe de marcação (se houver) usada na descrição da distribuição, para que as ferramentas possam renderizar a descrição de maneira inteligente.
Historicamente, o PyPI oferecia suporte a descrições em texto simples e reStructuredText (reST), e poderia renderizar reST em HTML. No entanto, é comum que os autores da distribuição escrevam a descrição em Markdown (RFC 7763) visto que tantos sites de hospedagem de código renderizam READMEs de Markdown, e os autores reutilizariam o arquivo para a descrição. O PyPI não reconhecia o formato e, portanto, não conseguia processar a descrição corretamente. Isso resultava em muitos pacotes no PyPI com descrições mal renderizadas quando Markdown é deixado como texto simples, ou pior, era tentado ser renderizado como reST. Este campo permite que o autor da distribuição especifique o formato de sua descrição, abrindo a possibilidade para PyPI e outras ferramentas serem capazes de renderizar Markdown e outros formatos.
O formato deste campo é o mesmo do cabeçalho Content-Type em HTTP (ou seja: RFC 1341). Resumidamente, isso significa que ele tem uma parte do tipo/subtipo e então pode opcionalmente ter uma série de parâmetros:
Formato:
Description-Content-Type: <type>/<subtype>; charset=<charset>[; <param_name>=<param value> ...]
A parta tipo/subtipo tem apenas alguns poucos valores válidos:
text/plaintext/x-rsttext/markdown
O parâmetro charset pode ser usado para especificar a codificação de caracteres da descrição. O único valor válido é UTF-8. Se omitido, é considerado UTF-8.
Outros parâmetros podem ser específicos para o subtipo escolhido. Por exemplo, para o subtipo markdown, existe um parâmetro opcional variant que permite especificar a variante do Markdown em uso (o padrão é GFM se não for especificado). Atualmente, duas variantes são reconhecidas:
GFMpara GitHub-flavored MarkdownCommonMarkpara CommonMark
Exemplo:
Description-Content-Type: text/plain; charset=UTF-8
Exemplo:
Description-Content-Type: text/x-rst; charset=UTF-8
Exemplo:
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Exemplo:
Description-Content-Type: text/markdown
Se um Description-Content-Type não for especificado, as aplicações devem tentar renderizá-lo como text/x-rst; charset=UTF-8 e volta para text/plain se não for válido primeiro.
Se um Description-Content-Type é um valor não reconhecido, então o tipo de conteúdo presumido ser text/plain (embora PyPI provavelmente rejeite qualquer coisa com um valor não reconhecido).
Se o Description-Content-Type for text/markdown e variant não for especificado ou estiver definido com um valor não reconhecido, então a presume-se variant ser GFM .
Portanto, para o último exemplo acima, o charset padrão é UTF-8 e o variant padrão GFM e, portanto, é equivalente ao exemplo anterior.
Keywords#
Novo na versão 1.0.
Uma lista de palavras-chave adicionais, separadas por vírgulas, a serem usadas para auxiliar na busca pela distribuição em um catálogo maior.
Exemplo:
Keywords: dog,puppy,voting,election
Nota
A especificação anteriormente mostrava palavras-chave separadas por espaços, mas distutils e setuptools a implementaram com vírgulas. Essas ferramentas foram amplamente utilizadas por muitos anos, então era mais fácil atualizar a especificação para corresponder ao padrão de fato.
Home-page#
Novo na versão 1.0.
Uma string contendo a URL para a página da distribuição.
Exemplo:
Home-page: http://www.example.com/~cschultz/bvote/
Download-URL#
Novo na versão 1.1.
Uma string contendo a URL a partir da qual esta versão da distribuição pode ser baixada. (Isso significa que a URL não pode ser algo como “…/BeagleVote-latest.tgz”, mas deve ser “…/BeagleVote-0.45.tgz”.)
Mantenedor#
Novo na versão 1.2.
Uma string contendo o nome do mantenedor, no mínimo; informações de contato adicionais podem ser fornecidas.
Observe que este campo deve ser usado quando um projeto está sendo mantido por alguém que não seja o autor original: ele deve ser omitido se for idêntico a Author.
Exemplo:
Maintainer: C. Schultz, Universal Features Syndicate,
Los Angeles, CA <cschultz@peanuts.example.com>
Maintainer-email#
Novo na versão 1.2.
Uma string contendo o endereço de e-mail do mantenedor. Ela pode conter um nome e endereço de e-mail nas formas válidas para um cabeçalho From: do RFC-822.
Observe que este campo deve ser usado quando um projeto está sendo mantido por alguém que não seja o autor original: ele deve ser omitido se for idêntico a Author-email.
Exemplo:
Maintainer-email: "C. Schultz" <cschultz@example.com>
De acordo com RFC-822, este campo pode conter vários endereços de e-mail separados por vírgula:
Maintainer-email: cschultz@example.com, snoopy@peanuts.com
License#
Novo na versão 1.0.
Texto indicando a licença cobrindo a distribuição onde a licença não é uma seleção dos classificadores Trove “License”. Veja “Classifier “ abaixo. Este campo também pode ser usado para especificar uma versão particular de uma licença que é nomeada através do campo Classifier, ou para indicar uma variação ou exceção a tal licença.
Exemplos:
License: This software may only be obtained by sending the
author a postcard, and then the user promises not
to redistribute it.
License: GPL version 3, excluding DRM provisions
Classifier (vários usos)#
Novo na versão 1.1.
Cada entrada é uma string que fornece um único valor de classificação para a distribuição. Os classificadores são descritos na PEP 301, e o Python Package Index publica uma lista dinâmica de classificadores atualmente definidos.
Este campo pode ser seguido por um marcador de ambiente após um ponto e vírgula.
Exemplos:
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console (Text Based)
Requires-Dist (vários usos)#
Novo na versão 1.2.
Alterado na versão 2.1: A especificação do formato de campo foi relaxada para aceitar a sintaxe usada por ferramentas de publicação populares.
Cada entrada contém uma string nomeando algum outro projeto distutils requerido por esta distribuição.
O formato de uma string de requisito contém de uma a quatro partes:
Um nome de projeto, no mesmo formato do campo
Name:. A única parte obrigatória.Uma lista separada por vírgulas de nomes “extras”. Estes são definidos pelo projeto requerido, referindo-se a recursos específicos que podem precisar de dependências extras. Os nomes DEVEM estar em conformidade com as restrições especificadas pelo campo
Provides-Extra:.Um especificador de versão. As ferramentas que analisam o formato devem aceitar parênteses opcionais em torno disso, mas as ferramentas que o geram não devem usar parênteses.
Um marcador de ambiente após um ponto e vírgula. Isso significa que o requisito só é necessário nas condições especificadas.
Veja a PEP 508 para detalhes completos do formato permitido.
Os nomes dos projetos devem corresponder aos nomes encontrados no Python Package Index.
Os especificadores de versão devem seguir as regras descritas em Especificadores de versão.
Exemplos:
Requires-Dist: pkginfo
Requires-Dist: PasteDeploy
Requires-Dist: zope.interface (>3.5.0)
Requires-Dist: pywin32 >1.0; sys_platform == 'win32'
Requires-Python#
Novo na versão 1.2.
Este campo especifica a(s) versão(ões) do Python com as quais a distribuição é compatível. As ferramentas de instalação podem observar isso ao escolher qual versão de um projeto instalar.
O valor deve estar no formato especificado em Especificadores de versão.
For example, if a distribution uses f-strings then it may prevent installation on Python < 3.6 by specifying:
Requires-Python: >=3.6
Este campo não pode ser seguido por um marcador de ambiente.
Requires-External (vários usos)#
Novo na versão 1.2.
Alterado na versão 2.1: A especificação do formato de campo foi relaxada para aceitar a sintaxe usada por ferramentas de publicação populares.
Cada entrada contém uma string que descreve alguma dependência no sistema de que a distribuição deve ser usada. Este campo tem como objetivo servir como uma dica para os mantenedores do projeto downstream, e não tem semântica que seja significativa para a distribuição distutils.
O formato de uma string de requisito é o nome de uma dependência externa, opcionalmente seguido por uma declaração de versão entre parênteses.
Este campo pode ser seguido por um marcador de ambiente após um ponto e vírgula.
Como eles se referem a lançamentos de software não-Python, os números de versão para este campo não são obrigados a estar em conformidade com o formato especificado na especificação de especificadores de versão: eles devem corresponder ao esquema de versão usado pela dependência externa.
Observe que não há uma regra específica sobre as strings a serem usadas.
Exemplos:
Requires-External: C
Requires-External: libpng (>=1.5)
Requires-External: make; sys_platform != "win32"
Project-URL (vários usos)#
Novo na versão 1.2.
Uma string contendo uma URL navegável para o projeto e um rótulo para ele, separados por uma vírgula.
Exemplo:
Project-URL: Bug Tracker, http://bitbucket.org/tarek/distribute/issues/
O rótulo é um texto livre limitado a 32 caracteres.
Provides-Extra (vários usos)#
Novo na versão 2.1.
Alterado na versão 2.3: A PEP 685 restringiu os valores válidos para serem inequívocos (ou seja, sem necessidade de normalização). Para versões de metadados mais antigas, as restrições de valor foram alinhadas com Name: e as regras de normalização foram introduzidas.
Uma string contendo o nome de um recurso opcional. Um nome válido consiste apenas em letras ASCII minúsculas e números ASCII e hífen. Deve começar e terminar com uma letra ou número. Hífenes não podem ser seguidos por outro hífen. Os nomes são limitados àqueles que correspondem ao seguinte regex (que elimina ambiguidade):
^[a-z0-9]+(-[a-z0-9]+)*$
O nome especificado pode ser usado para tornar uma dependência condicional ao fato de o recurso opcional ter sido solicitado.
Exemplo:
Provides-Extra: pdf
Requires-Dist: reportlab; extra == 'pdf'
Uma segunda distribuição requer uma dependência opcional, colocando-a entre colchetes, e pode solicitar vários recursos, separando-os com uma vírgula (,). Os requisitos são avaliados para cada recurso solicitado e adicionados ao conjunto de requisitos para a distribuição.
Exemplo:
Requires-Dist: beaglevote[pdf]
Requires-Dist: libexample[test, doc]
Dois nomes de recursos test e doc são reservados para marcar dependências que são necessárias para executar testes automatizados e gerar documentação, respectivamente.
É válido especificar Provides-Extra: sem referenciá-lo em qualquer Requer-Dist:.
Ao escrever dados para versões de metadados mais antigas, os nomes DEVEM ser normalizados seguindo as mesmas regras usadas para o campo Name: ao realizar comparações. Ferramentas que escrevem metadados DEVEM gerar um erro se duas entradas Provides-Extra: colidirem após serem normalizadas.
Ao ler dados para versões de metadados mais antigas, as ferramentas DEVEM avisar quando os valores para este campo seriam inválidos em versões de metadados mais recentes. Se um valor for inválido seguindo as regras para Name: em qualquer versão de metadados principais, o usuário DEVE ser avisado e o valor ignorado para evitar ambiguidade. As ferramentas PODEM optar por gerar um erro ao ler um nome inválido para versões de metadados mais antigas.
Campos raramente usados#
Os campos nesta seção são raramente usados atualmente, já que seu design foi inspirado por mecanismos comparáveis em sistemas de gerenciamento de pacotes Linux, e não está claro como as ferramentas devem interpretá-los no contexto de um servidor de indexação aberto, como PyPI.
Como resultado, as ferramentas de instalação populares os ignoram completamente, o que significa que há pouco incentivo para os editores de pacotes configurá-los apropriadamente. No entanto, eles são retidos na especificação de metadados, pois ainda são potencialmente úteis para fins informativos e também podem ser usados para o propósito originalmente pretendido em combinação com um repositório de pacotes com curadoria.
Provides-Dist (vários usos)#
Novo na versão 1.2.
Alterado na versão 2.1: A especificação do formato de campo foi relaxada para aceitar a sintaxe usada por ferramentas de publicação populares.
Cada entrada contém uma string nomeando um projeto Distutils que está contido nesta distribuição. Este campo deve incluir o projeto identificado no campo Name, seguido da versão: Nome (Versão).
Uma distribuição pode fornecer nomes adicionais, por exemplo, para indicar que vários projetos foram agrupados. Por exemplo, distribuições de código-fonte do projeto ZODB historicamente incluíram o projeto transaction, que agora está disponível como uma distribuição separada. Instalar tal distribuição de código-fonte satisfaz os requisitos para ZODB e transaction.
Uma distribuição também pode fornecer um nome de projeto “virtual”, que não corresponde a nenhum projeto distribuído separadamente: tal nome pode ser usado para indicar uma capacidade abstrata que pode ser fornecida por um de vários projetos. Por exemplo, vários projetos podem fornecer ligações (bindings) de RDBMS para uso por um determinado ORM: cada projeto pode declarar que fornece ORM-bindings, permitindo que outros projetos dependam apenas de ter no máximo um deles instalado.
Uma declaração de versão pode ser fornecida e deve seguir as regras descritas em Especificadores de versão. O número da versão da distribuição estará implícito se nenhum for especificado.
Este campo pode ser seguido por um marcador de ambiente após um ponto e vírgula.
Exemplos:
Provides-Dist: OtherProject
Provides-Dist: AnotherProject (3.4)
Provides-Dist: virtual_package; python_version >= "3.4"
Obsoletes-Dist (vários usos)#
Novo na versão 1.2.
Alterado na versão 2.1: A especificação do formato de campo foi relaxada para aceitar a sintaxe usada por ferramentas de publicação populares.
Cada entrada contém uma string que descreve a distribuição de um projeto distutils que esta distribuição torna obsoleta, o que significa que os dois projetos não devem ser instalados ao mesmo tempo.
Declarações de versão podem ser fornecidas. Os números de versão devem estar no formato especificado em Especificadores de versão.
Este campo pode ser seguido por um marcador de ambiente após um ponto e vírgula.
O uso mais comum deste campo será no caso de alteração do nome de um projeto, por exemplo, Gorgon 2.3 é incluído no Torqued Python 1.0. Quando você instala o Torqued Python, a distribuição Gorgon deve ser removida.
Exemplos:
Obsoletes-Dist: Gorgon
Obsoletes-Dist: OtherProject (<3.0)
Obsoletes-Dist: Foo; os_name == "posix"
Campos descontinuados#
Requires#
Novo na versão 1.1.
Obsoleto desde a versão 1.2: em favor de Requires-Dist
Cada entrada contém uma string descrevendo algum outro módulo ou pacote requerido por este pacote.
O formato de uma string de requisito é idêntico ao de um nome de módulo ou pacote utilizável com a instrução import, opcionalmente seguida por uma declaração de versão dentro de parênteses.
Uma declaração de versão é uma série de operadores condicionais e números de versão, separados por vírgulas. Os operadores condicionais devem ser um dos “<”, “>”’, “<=”, “>=”, “=”, e “!=”. Os números da versão devem estar no formato aceito pela classe distutils.version.StrictVersion: dois ou três componentes numéricos separados por ponto, com uma tag “pre-release” opcional no final que consiste na letra ‘a’ ou ‘b’ seguida de um número. Os números da versão do exemplo são “1.0”, “2.3a2”, “1.3.99”.
Qualquer número de operadores condicionais pode ser especificado, por exemplo, a string “>1.0, !=1.3.4, <2.0” é uma declaração de versão válida.
Todos os seguintes são possíveis strings de requisito: “rfc822”, “zlib (>=1.1.4)”, “zope”.
Não há nenhuma lista canônica de quais strings devem ser usadas; a comunidade Python é livre para escolher seus próprios padrões.
Exemplos:
Requires: re
Requires: sys
Requires: zlib
Requires: xml.parsers.expat (>1.0)
Requires: psycopg
Provides#
Novo na versão 1.1.
Obsoleto desde a versão 1.2: em favor de Provides-Dist
Cada entrada contém uma string descrevendo um pacote ou módulo que será fornecido por este pacote uma vez instalado. Essas strings devem corresponder às usadas nos campos Requirements. Uma declaração de versão pode ser fornecida (sem um operador de comparação); o número de versão do pacote será implícito se nenhum for especificado.
Exemplos:
Provides: xml
Provides: xml.utils
Provides: xml.utils.iso8601
Provides: xml.dom
Provides: xmltools (1.3)
Obsoletes#
Novo na versão 1.1.
Obsoleto desde a versão 1.2: em favor de Obsoletes-Dist
Cada entrada contém uma string descrevendo um pacote ou módulo que este pacote torna obsoleta, o que significa que os dois projetos não devem ser instalados ao mesmo tempo. Declarações de versão pode ser fornecidas.
O uso mais comum deste campo será no caso de alteração do nome de um projeto, por exemplo, Gorgon 2.3 é incluído no Torqued Python 1.0. Quando você instala o Torqued Python, o pacote Gorgon deve ser removido.
Exemplo:
Obsoletes: Gorgon
Histórico#
March 2001: Core metadata 1.0 was approved through PEP 241.
April 2003: Core metadata 1.1 was approved through PEP 314:
February 2010: Core metadata 1.2 was approved through PEP 345.
February 2018: Core metadata 2.1 was approved through PEP 566.
Added
Description-Content-TypeandProvides-Extra.Added canonical method for transforming metadata to JSON.
Restricted the grammar of the
Namefield.
October 2020: Core metadata 2.2 was approved through PEP 643.
Adicionado o campo
Dinâmico.
March 2022: Core metadata 2.3 was approved through PEP 685.
Restricted extra names to be normalized.