Quais argumentos de palavra-chave o setuptools.setup () aceita?

Qual é a lista completa de argumentos de palavras-chave que a função setuptools.setup () aceita? (Inclua uma descrição do que cada argumento significa, se possível.)

Eu olhei por toda a web e não acredito que isso não esteja documentado.

Encontrei estes documentos:

• https://docs.python.org/3.7/distutils/setupscript.html#additional-meta-data
• https://setuptools.readthedocs.io/en/latest/setuptools.html#new-and-changed-setup-keywords

Mas mesmo quando eu os combino, faltam outros argumentos, como

• scripts
• pacotes
• fornece
• obsoletos

... e não sei quantos argumentos estão faltando.

Qual é a lista completa de argumentos de palavras-chave que a função setuptools.setup () aceita?

setuptools.setup()chama distutils.core.setup()e passa a si próprio **kwargscomo o único parâmetro, portanto, qualquer palavra-chave que distutilsaceite também será aceita por setuptools. Se formos olhardistutils

    setup_keywords = ('distclass', 'script_name', 'script_args', 
                      'options', 'name', 'version', 'author', 
                      'author_email', 'maintainer', 'maintainer_email', 
                      'url', 'license', 'description', 
                      'long_description', 'keywords', 'platforms', 
                      'classifiers', 'download_url', 'requires', 
                      'provides', 'obsoletes',
                  )

A maioria deles está documentada aqui, mas alguns não estão incluídos na tabela: packages , package_dir , package_data , scripts , obsoletos , proviodes , py_modules e data_files .

Alguns deles também estão ausentes da setup_keywordstupla. E se você deseja setup_keywords, não parece que ele seja realmente referenciado em qualquer lugar ... Mas isso é uma história para outro dia. Enfim, aqui está a lista (espero que completa).

argumentos da palavra-chave distutils.core.setup ()

( Necessário : nome , versão e pelo menos um dos autores ou mantenedores )

autor:

nome do autor do pacote (necessário se o mantenedor não for fornecido)

author_email:

endereço de email do autor do pacote

classificadores:

uma lista de classificadores (consulte: https://pypi.org/classifiers/ )

data_files :

A data_filesopção pode ser usada para especificar arquivos adicionais necessários à distribuição do módulo: arquivos de configuração, catálogos de mensagens, arquivos de dados, qualquer coisa que não se encaixe nas categorias anteriores.

data_filesespecifica uma sequência de (directory, files)pares da seguinte maneira:

setup(...,
      data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
                  ('config', ['cfg/data.cfg'])],
     )

Cada (directory, files)par na sequência especifica o diretório de instalação e os arquivos a serem instalados nele. Cada nome de arquivo nos arquivos é interpretado em relação ao setup.pyscript.

descrição:

breve descrição resumida do pacote

download_url:

local onde o pacote pode ser baixado

palavras-chave:

uma lista de palavras-chave (também usa uma sequência. Se separada por vírgula, é dividida em uma lista)

licença:

licença para o pacote (use apenas se a licença não estiver listada nos "classificadores trove". Consulte: Classificadores)

longa descrição:

descrição mais longa do pacote, usada pelo PyPI para construir a página do projeto

mantenedor:

nome do mantenedor do pacote (obrigatório se o autor não for fornecido)

mantenedor_e-mail:

endereço de e-mail do mantenedor do pacote

nome:

nome do pacote (exigido por distutils)

obsoletos :

Um pacote pode declarar que obsoleta outros pacotes usando o obsoletesargumento keyword. O valor para isso é semelhante ao da requirespalavra-chave: uma lista de strings que fornecem especificadores de módulo ou pacote. Cada especificador consiste em um nome de módulo ou pacote opcionalmente seguido por um ou mais qualificadores de versão. Qualificadores de versão são dados entre parênteses após o nome do módulo ou pacote

package_data :

Os dados do pacote podem ser adicionados aos pacotes usando o package_dataargumento keyword para a setup()função O valor deve ser um mapeamento do nome do pacote para uma lista de nomes de caminhos relativos que devem ser copiados no pacote. Os caminhos são interpretados como relativos ao diretório que contém o pacote (as informações do package_dirmapeamento são usadas, se apropriado); ou seja, espera-se que os arquivos façam parte do pacote nos diretórios de origem.

package_dir :

Se você usar uma convenção diferente para organizar seu diretório de origem, não há problema: basta fornecer a package_diropção de informar o Distutils sobre sua convenção. Por exemplo, digamos que você mantenha todo o código-fonte do Python abaixo lib, para que os módulos do “pacote raiz” (ou seja, nenhum pacote) estejam lib, os módulos no foopacote estejam lib/fooe assim por diante. Então você colocaria

package_dir = {'': 'lib'}

no seu script de instalação. As chaves deste dicionário são nomes de pacotes e um nome de pacote vazio representa o pacote raiz. Os valores são nomes de diretório relativos à sua raiz de distribuição. Nesse caso, quando você diz packages = ['foo'], promete que o arquivo lib/foo/__init__.pyexiste.

Outra convenção possível é colocar o foopacote corretamente lib, o foo.barpacote lib/baretc. Isso deve ser escrito no script de instalação como

package_dir = {'foo': 'lib'}

Uma package: direntrada no package_dirdicionário se aplica implicitamente a todos os pacotes abaixo do pacote, portanto, o foo.barcaso é tratado automaticamente aqui. Neste exemplo, ter packages = ['foo', 'foo.bar']instruído os Distutils a procurar lib/__init__.pye lib/bar/__init__.py. (Lembre-se de que, embora package_dirse aplique recursivamente, você deve listar explicitamente todos os pacotes nos pacotes: o Distutils não examinará recursivamente sua árvore de origem procurando por qualquer diretório com um __init__.pyarquivo.)

pacotes :

Os dados do pacote podem ser adicionados aos pacotes usando o package_dataargumento keyword para a setup()função O valor deve ser um mapeamento do nome do pacote para uma lista de nomes de caminhos relativos que devem ser copiados no pacote. Os caminhos são interpretados como relativos ao diretório que contém o pacote (as informações do package_dirmapeamento são usadas, se apropriado); ou seja, espera-se que os arquivos façam parte do pacote nos diretórios de origem. Eles podem conter padrões glob também.

plataformas:

uma lista de plataformas (também pega uma sequência. Se separada por vírgula, é dividida em uma lista)

fornece :

Agora que podemos especificar dependências, também precisamos especificar o que fornecemos que outras distribuições podem exigir. Isso é feito usando o providesargumento de palavra - chave para setup().

py_modules :

Para uma distribuição de módulo pequeno, você pode preferir listar todos os módulos em vez de listar pacotes - especialmente o caso de um único módulo incluído no "pacote raiz" (ou seja, nenhum pacote).

py_modules = ['foo.py']

Aqui está um exemplo um pouco mais envolvido:

py_modules = ['mod1', 'pkg.mod2']

Isso descreve dois módulos, um no pacote "root" e o outro no pkgpacote. Novamente, o layout padrão do pacote / diretório implica que esses dois módulos podem ser encontrados em mod1.pye pkg/mod2.py, e isso também pkg/__init__.pyexiste. E, novamente, você pode substituir a correspondência do pacote / diretório usando a package_diropção

scripts :

Scripts são arquivos que contêm o código-fonte Python, que devem ser iniciados na linha de comando. Os scripts não exigem que o Distutils faça algo muito complicado. O único recurso inteligente é que, se a primeira linha do script começar com #!e contiver a palavra “python”, o Distutils ajustará a primeira linha para se referir ao local atual do intérprete. Por padrão, ele é substituído pelo local atual do intérprete. A opção --executável (ou -e) permitirá que o caminho do intérprete seja substituído explicitamente.

A opção de scripts é simplesmente uma lista de arquivos a serem manipulados dessa maneira. No script de instalação do PyXML:

    setup(...,
          scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val']
          )

url:

página inicial do pacote

versão:

versão deste release (requerido por distutils)

argumentos da palavra-chave setuptools.setup ()

Existem ainda mais argumentos que setuptools.setup()aceitarão, além daqueles que são usados ​​por distutils.

Embora seja chamado de "Palavras-chave de instalação novas e alteradas" (o que para mim sugere um registro de alterações da versão), o texto de introdução diz que esses são "argumentos de palavras-chave para setup () [que são] adicionados ou alterados por setuptools", portanto, acredito que o link realmente fornece uma lista completa. Vou adicioná-lo aqui para completar.

(Desde as setuptools.setup()chamadas distutils.core.setup(), os mesmos parâmetros são necessários : nome , versão e pelo menos um dos autores ou mantenedores )

convert_2to3_doctests:

Lista de arquivos de origem doctest que precisam ser convertidos com 2to3. Consulte Suporte ao Python 2 e Python 3 com Setuptools para obter mais detalhes.

dependency_links:

Uma lista de cadeias de nomes de URLs a serem pesquisadas ao satisfazer dependências. Esses links serão usados ​​se necessário para instalar pacotes especificados por setup_requires ou tests_require. Eles também serão gravados nos metadados do ovo para serem usados ​​por ferramentas como o EasyInstall para a instalação de um arquivo .egg.

eager_resources:

Uma lista de seqüências de nomes de recursos que devem ser extraídos juntos, se algum deles for necessário ou se quaisquer extensões C incluídas no projeto forem importadas. Esse argumento é útil apenas se o projeto for instalado como um arquivo zip e for necessário que todos os recursos listados sejam extraídos para o sistema de arquivos como uma unidade. Os recursos listados aqui devem ser caminhos separados por '/', relativos à raiz de origem, para listar um recurso foo.png no pacote bar.baz, você deve incluir a string bar / baz / foo.png nesse argumento. Se você só precisa obter recursos, um de cada vez, ou não possui extensões C que acessam outros arquivos no projeto (como arquivos de dados ou bibliotecas compartilhadas), provavelmente NÃO precisa desse argumento e não deve mexer com isso. Para mais detalhes sobre como esse argumento funciona,

pontos de entrada:

Um dicionário que mapeia nomes de grupos de pontos de entrada para cadeias ou listas de cadeias que definem os pontos de entrada. Os pontos de entrada são usados ​​para oferecer suporte à descoberta dinâmica de serviços ou plugins fornecidos por um projeto. Consulte Descoberta dinâmica de serviços e plug-ins para obter detalhes e exemplos do formato desse argumento. Além disso, essa palavra-chave é usada para oferecer suporte à criação automática de scripts.

exclude_package_data:

Um dicionário que mapeia nomes de pacotes para listas de padrões glob que devem ser excluídos dos diretórios de pacotes. Você pode usar isso para reduzir todos os arquivos em excesso incluídos por include_package_data. Para obter uma descrição completa e exemplos, consulte a seção abaixo em Incluindo arquivos de dados.

extras_require:

Um dicionário que mapeia nomes de "extras" (recursos opcionais do seu projeto) para cadeias ou listas de cadeias especificando quais outras distribuições devem ser instaladas para suportar esses recursos. Consulte a seção abaixo em Declarando dependências para obter detalhes e exemplos do formato desse argumento.

include_package_data:

Se definido como True, isso instrui o setuptools a incluir automaticamente todos os arquivos de dados encontrados nos diretórios do pacote especificados pelo arquivo MANIFEST.in. Para mais informações, consulte a seção abaixo em Incluindo arquivos de dados.

install_requires:

Uma cadeia ou lista de cadeias especificando quais outras distribuições precisam ser instaladas quando essa é. Consulte a seção abaixo em Declarando dependências para obter detalhes e exemplos do formato desse argumento.

namespace_packages:

Uma lista de strings nomeando os "pacotes de namespace" do projeto. Um pacote de namespace é um pacote que pode ser dividido em várias distribuições de projeto. Por exemplo, o pacote zope do Zope 3 é um pacote de namespace, porque subpacotes como zope.interface e zope.publisher podem ser distribuídos separadamente. O sistema egg runtime pode mesclar automaticamente esses subpacotes em um pacote pai único em tempo de execução, desde que você os declare em cada projeto que contenha subpacotes do pacote de namespace e enquanto o init .py do pacote de namespace não contenha nenhum código diferente de uma declaração de espaço para nome. Consulte a seção abaixo em Pacotes de namespace para obter mais informações.

package_data:

Um dicionário de mapeamento de nomes de pacotes para listas de padrões glob. Para obter uma descrição completa e exemplos, consulte a seção abaixo em Incluindo arquivos de dados. Você não precisa usar esta opção se estiver usando include_package_data, a menos que precise adicionar, por exemplo, arquivos gerados pelo script de instalação e processo de compilação. (Portanto, eles não estão no controle de origem ou são arquivos que você não deseja incluir na sua distribuição de origem.)

project_urls:

Um mapa arbitrário de nomes de URL para hiperlinks, permitindo uma documentação mais extensível de onde vários recursos podem ser encontrados do que as opções simples de url e download_url.

python_requires:

Uma sequência correspondente a um especificador de versão (conforme definido no PEP 440) para a versão do Python, usada para especificar o Requer-Python definido no PEP 345.

setup_requires:

Uma sequência ou lista de sequências especificando quais outras distribuições precisam estar presentes para que o script de instalação seja executado. O setuptools tentará obtê-los (mesmo indo para baixá-los usando o EasyInstall) antes de processar o restante do script ou dos comandos de instalação. Este argumento é necessário se você estiver usando extensões distutils como parte do seu processo de construção; por exemplo, extensões que processam argumentos setup () e os transformam em arquivos de metadados EGG-INFO. (Nota: os projetos listados em setup_requires NÃO serão instalados automaticamente no sistema em que o script de instalação está sendo executado. Eles são simplesmente baixados no diretório ./.eggs, se ainda não estiverem disponíveis localmente. Se você deseja que eles sejam instalados , além de estar disponível quando o script de instalação é executado, você deve adicioná-los a install_requires e setup_requires.)

test_loader:

Se você deseja usar uma maneira diferente de encontrar testes para executar do que o que as ferramentas de configuração normalmente usam, você pode especificar um nome de módulo e nome de classe neste argumento. A classe nomeada deve ser instanciada sem argumentos e suas instâncias devem suportar o método loadTestsFromNames (), conforme definido na classe TestLoader do módulo unittest Python. As ferramentas de instalação passarão apenas um "nome" de teste no argumento de nomes: o valor fornecido para o argumento test_suite. O carregador que você especificar pode interpretar essa sequência da maneira que desejar, pois não há restrições sobre o que pode estar contido em uma sequência test_suite. O nome do módulo e o nome da classe devem ser separados por um:. O valor padrão desse argumento é "setuptools.command.test: ScanningLoader". Se você deseja usar o comportamento unittest padrão, pode especificar "unittest: TestLoader" como seu argumento test_loader. Isso impedirá a verificação automática de sub-módulos e subpacotes. O módulo e a classe que você especificar aqui podem estar contidos em outro pacote, desde que você use a opção tests_require para garantir que o pacote que contém a classe loader esteja disponível quando o comando test for executado.

suíte de teste:

Uma string que nomeia uma subclasse unittest.TestCase (ou um pacote ou módulo contendo um ou mais deles, ou um método dessa subclasse) ou que nomeie uma função que pode ser chamada sem argumentos e retorna um unittest.TestSuite. Se o conjunto nomeado for um módulo e o módulo tiver uma função adicional_tests (), ele será chamado e os resultados serão adicionados aos testes a serem executados. Se o conjunto nomeado for um pacote, quaisquer sub-módulos e subpacotes serão adicionados recursivamente ao conjunto de testes geral. A especificação desse argumento permite o uso do comando test para executar o conjunto de testes especificado, por exemplo, via setup.py test. Veja a seção no comando de teste abaixo para mais detalhes.

tests_require:

Se os testes do seu projeto precisarem de um ou mais pacotes adicionais além dos necessários para instalá-lo, você poderá usar esta opção para especificá-los. Deve ser uma sequência ou lista de sequências que especifica quais outras distribuições precisam estar presentes para que os testes do pacote sejam executados. Ao executar o comando test, o setuptools tentará obtê-los (até o ponto de baixá-los usando o EasyInstall). Observe que esses projetos necessários não serão instalados no sistema em que os testes são executados, mas somente serão baixados no diretório de instalação do projeto se ainda não estiverem instalados localmente.

use_2to3:

Converta o código-fonte do Python 2 para o Python 3 com 2to3 durante o processo de compilação. Consulte Suporte ao Python 2 e Python 3 com Setuptools para obter mais detalhes.

use_2to3_exclude_fixers :

Por padrão, a conversão usa todos os fixadores no lib2to3.fixerspacote. Para usar fixadores adicionais, o parâmetro use_2to3_fixerspode ser configurado para uma lista de nomes de pacotes que contêm fixadores. Para excluir fixadores, o parâmetro use_2to3_exclude_fixerspode ser definido como nomes de fixadores a serem ignorados.

use_2to3_fixers :

Uma lista de módulos para procurar fixadores adicionais a serem usados ​​durante a conversão 2to3. Consulte Suporte ao Python 2 e Python 3 com Setuptools para obter mais detalhes.

zip_safe:

Um sinalizador booleano (Verdadeiro ou Falso) especificando se o projeto pode ser instalado e executado com segurança a partir de um arquivo zip. Se esse argumento não for fornecido, o comando bdist_egg terá que analisar todo o conteúdo do seu projeto para possíveis problemas sempre que criar um ovo.

Extensões

Construir uma extensão (em vez de um módulo Python puro) é mais complicado, pois requer essencialmente que você especifique os parâmetros e argumentos necessários para criar com êxito a extensão a partir dos Carquivos de origem. Isso é feito através da ext_modulespalavra - chave, que nada mais é do que uma lista de Extensioninstâncias (importáveis ​​de distutils.core). Os argumentos da palavra-chave aceitos pelo Extensionconstrutor da classe são o vetor de entrada para especificar as etapas de compilação para compilar a extensão.

Como essa pergunta é setuptools.setup()específica, incluirei apenas a definição de ext_modules, mas a documentação da Extensionclasse fornece detalhes completos. Para completar, esta é a lista de palavras-chave aceitas para o Extensionconstrutor:

    extension_keywords = ('name', 'sources', 'include_dirs',
                          'define_macros', 'undef_macros',
                          'library_dirs', 'libraries', 
                          'runtime_library_dirs', 'extra_objects', 
                          'extra_compile_args', 'extra_link_args',
                          'swig_opts', 'export_symbols', 'depends', 
                          'language')

ext_modules :

Uma lista de instâncias de extensão, cada uma descrevendo um único módulo de extensão. Suponha que sua distribuição inclua uma única extensão, chamada foo e implementada por foo.c. Se não forem necessárias instruções adicionais para o compilador / vinculador, descrever esta extensão é bastante simples:

   from distutils.core import setup, Extension
   setup(name='foo',
         version='1.0',
         ext_modules=[Extension('foo', ['foo.c'])],
         )

Misc.

Finalmente, existem ainda mais kwargs que podem ser implementados em setuptools.distoutros locais, mas por algum motivo nunca foram adicionados a nenhuma documentação principal do setuptools / distutils:

recursos (descontinuados):

uma opção de mapeamento de dicionário nomeia para objetos 'setuptools.Feature'. Os recursos são uma parte da distribuição que pode ser incluída ou excluída com base nas opções do usuário, dependências entre recursos e disponibilidade no sistema atual. Os recursos excluídos são omitidos em todos os comandos de configuração, incluindo distribuições de origem e binárias, para que você possa criar várias distribuições a partir da mesma árvore de origem.

long_description_content_type (por "Criando um README compatível com PyPI ):

defina como um valor aceito no estilo Tipo de conteúdo para a marcação do arquivo LEIA-ME, como texto / sem formatação, texto / x-rst (para reStructuredText) ou texto / redução.

provides_extras (Per PEP566, listados como "Fornece-Extra" ):

Uma sequência que contém o nome de um recurso opcional. Deve ser um identificador Python válido. Pode ser usado para tornar uma dependência condicional se o recurso opcional foi solicitado.