Setuptools.setup()接受哪些关键字参数？

2022-05-27 00:00:00 python pip setuptools distutils easy-install

问题描述

Setuptools.setUp()函数接受的关键字参数的完整列表是什么？(如果可能，请说明每个参数的含义。)

我在网上找遍了，我不敢相信这没有记录在案。

我找到了这些文档：

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

但即使我将它们组合在一起，它们也缺少其他参数，如

脚本
包
提供
过时

...我不知道还缺少多少参数。

setuptools.setup()函数接受的关键字参数的完整列表是什么？

解决方案

setuptools.setup()调用distutils.core.setup()并将其自己的**kwargs作为唯一参数传递，因此distutils接受的任何关键字也将被setuptools接受。如果我们查看distutils

    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',
                  )

大多数记录了here，但也有一些没有包括在表中：packages、package_dir、package_data、scripts、obsoletes、provides、py_modules和data_files。

setup_keywords元组中也缺少其中的一些。如果您对setup_keywords进行grep，则看起来它实际上并未在任何地方被引用...但这是另一天的故事。无论如何，下面是(希望是完整的)Python3.10的列表。

distutils.core.setup()关键字参数

(必填：名称、版本以及至少作者或维护者)

作者：

包作者的姓名(如果未提供Maintainer，则为必填项)

作者电子邮件：

包作者的电子邮件地址

分类器：

列表(请参阅：https://pypi.org/classifiers/)

data_files：

data_files选项可用于指定模块分发所需的其他文件：配置文件、消息目录、数据文件，以及不属于上述类别的任何文件。

data_files按以下方式指定(directory, files)对的序列：
setup(...,
     data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
                 ('config', ['cfg/data.cfg'])],
    )
序列中的每个(directory, files)对指定安装目录和要在其中安装的文件。文件中的每个文件名都是相对于setup.py脚本解释的。

说明：

包的简短摘要说明

download_url：

可以下载包的位置

关键词：

关键字列表(也接受字符串。如果逗号分隔，则将其拆分为列表)

许可证：

程序包的许可证(仅当许可证不在&trove分类器中列出时使用。请参阅：分类器)

Long_Description：

包的更长说明，由PyPI用来构建项目页面

维护者：

包维护者的姓名(如果未提供作者，则为必填项)

维护电子邮件：

包维护者的电子邮件地址

名称：

包的名称(distutils必需)

obsoletes：

包可以使用obsoletes关键字参数声明它废弃了其他包。其值类似于requires关键字的值：提供模块或包说明符的字符串列表。每个说明符由一个模块或包名组成，后面可选地跟一个或多个版本限定符。版本限定符位于模块或包名称后面的圆括号中

package_data：

可以使用setup()函数的package_data关键字参数将包数据添加到包中。该值必须是从包名到应复制到包中的相对路径名列表的映射。这些路径被解释为相对于包含包的目录(如果合适，将使用来自package_dir映射的信息)；也就是说，文件应该是源目录中包的一部分。

package_dir：

如果您使用不同的约定来布局您的源目录，那不成问题：您只需提供package_dir选项来告诉Distutils有关您的约定。例如，假设您将所有的Python源代码放在lib下，因此"根程序包"中的模块(即根本不在任何程序包中)位于lib中，foo程序包中的模块位于lib/foo中，以此类推。然后，您可以将
package_dir = {'': 'lib'}
在安装脚本中。该词典的关键字是包名，空的包名代表根包。这些值是相对于分发根目录的目录名。在这种情况下，当您说packages = ['foo']时，您承诺文件lib/foo/__init__.py存在。

另一种可能的约定是将foo包直接放在lib中，将foo.bar包放在lib/bar中，等等。这将在安装脚本中写为
package_dir = {'foo': 'lib'}
package_dir词典中的package: dir条目隐式应用于Package下的所有包，因此这里自动处理foo.bar案例。在本例中，HAVINGpackages = ['foo', 'foo.bar']告诉Distutils查找lib/__init__.py和lib/bar/__init__.py。(请记住，尽管package_dir是递归应用的，但您必须显式列出包中的所有包：Distutils不会递归扫描源代码树以查找包含__init__.py文件的任何目录。)

packages：

可以使用setup()函数的package_data关键字参数将包数据添加到包中。该值必须是从包名到应复制到包中的相对路径名列表的映射。这些路径被解释为相对于包含包的目录(如果合适，将使用来自package_dir映射的信息)；也就是说，文件应该是源目录中包的一部分。它们还可能包含全局图案。

平台：

平台列表(也接受字符串。如果逗号分隔，则将其拆分为列表)

provides：

既然我们可以指定依赖项，我们还需要能够指定我们提供了其他发行版可能需要的内容。这是使用setup()的provides关键字参数完成的。

py_modules：

对于较小的模块分发，您可能更喜欢列出所有模块，而不是列出包--尤其是在"根包"中包含单个模块的情况下(即根本没有包)。
py_modules = ['foo.py']
这里有一个稍微复杂一些的示例：
py_modules = ['mod1', 'pkg.mod2']
描述了两个模块，一个在"根"包中，另一个在pkg包中。同样，默认的包/目录布局意味着这两个模块可以在mod1.py和pkg/mod2.py中找到，并且pkg/__init__.py也存在。同样，您可以使用package_dir选项覆盖包/目录对应关系。

scripts：

脚本是包含Python源代码的文件，旨在从命令行启动。脚本不需要Distutil来做任何非常复杂的事情。唯一聪明的特性是，如果脚本的第一行以#!开头并且包含单词"python"，Distutils将调整第一行以引用当前的解释器位置。默认情况下，它被替换为当前的解释器位置。--可执行文件(或-e)选项将允许显式覆盖解释程序路径。

脚本选项只是要以这种方式处理的文件的列表。从PyXML安装脚本：
    setup(...,
          scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val']
          )

url：

包的主页

版本：

此版本的版本(distutils需要)

setuptools.setup()关键字参数

除了distutils使用的参数外，setuptools.setup()还将接受更多参数。

虽然它名为"New and Changed Setup Keywords"(对我来说这是一个版本更改日志)，但简介文本说这些是setupTools"；添加或更改的setUp()[的关键字参数]，所以我相信该链接实际上提供了一个完整的列表。为了完整起见，我将在此处添加它。

(由于setuptools.setup()调用distutils.core.setup()，因此必选：名称、版本以及作者或维护者中至少一个)

convert_2to3_doctests：

需要用2to3转换的doctest源文件列表。有关更多详细信息，请参阅通过SetupTools同时支持Python2和Python3。

依赖关系链接：

指定满足依赖项时要搜索的URL的字符串列表。如果需要安装由setup_requires或tests_require指定的包，将使用这些链接。它们还将写入EasyInstall等工具的EasyInstall元数据中，以便在安装.egg文件时使用。

EAGER_RESOURCES：

命名资源的字符串列表，这些资源应该一起提取，如果需要其中任何一个，或者如果导入了项目中包含的任何C扩展。仅当项目将作为zipfile安装，并且需要将列出的所有资源作为一个单元解压缩到文件系统时，此参数才有用。这里列出的资源应该是‘/’分隔的路径，相对于源根目录，因此要在包bar.baz中列出资源foo.png，应该在此参数中包括字符串bar/baz/foo.png。如果您一次只需要获取一个资源，或者您没有任何访问项目中其他文件(如数据文件或共享库)的C扩展名，那么您可能不需要这个参数，也不应该干扰它。有关此参数如何工作的更多详细信息，请参阅下面关于自动资源提取的部分。

Entry_Points：

将入口点组名称映射到定义入口点的字符串或字符串列表的字典。入口点用于支持动态发现项目提供的服务或插件。有关此参数格式的详细信息和示例，请参阅服务和插件的动态发现。此外，此关键字还用于支持自动脚本创建。

排除程序包数据：

将包名称映射到应从包目录中排除的GLOB模式列表的字典。您可以使用它来削减INCLUDE_PACKAGE_DATA包含的任何多余文件。有关完整的说明和示例，请参阅下面关于包括数据文件的部分。

附加要求：

将"Extras"(项目的可选功能)的名称映射到字符串或字符串列表的词典，指定必须安装哪些其他发行版才能支持这些功能。有关此参数格式的详细信息和示例，请参阅下面关于声明依赖项的部分。

注意：对于extras_require字典，在54.1.0之前的版本中，如果在键中使用破折号，则会将转换为下划线。更高版本允许使用破折号，如果用户使用的别名包含应使用下划线的破折号，则会发出警告。author-email而不是author_email)，并且在这种情况下仍执行转换。在未来，这种转换将不再自动完成。

Include_Package_Data：

如果设置为True，则告诉setupTools自动包括它在MANIFEST.in文件指定的包目录中找到的任何数据文件。有关详细信息，请参阅下面关于包括数据文件的部分。

安装要求：

指定在安装此发行版时需要安装哪些其他发行版的字符串或字符串列表。有关此参数格式的详细信息和示例，请参阅下面关于声明依赖项的部分。

NAMESPACE_PACKAGE：

命名项目的"命名空间包"的字符串列表。命名空间包是可以跨多个项目发行版拆分的包。例如，Zope3的zope包是一个命名空间包，因为像zope.interface和zope.publisher这样的子包可能是分开分发的。只要您在包含命名空间包的任何子包的每个项目中声明它们，并且只要命名空间包的__init__.py不包含除命名空间声明之外的任何代码，EGG运行时系统就可以在运行时自动将这些子包合并到单个父包中。有关详细信息，请参阅下面关于命名空间包的部分。

Package_Data：

将包名称映射到GLOB模式列表的词典。有关完整的说明和示例，请参阅下面关于包括数据文件的部分。如果您正在使用INCLUDE_PACKAGE_DATA，则不需要使用此选项，除非您需要添加由安装脚本和构建过程生成的文件。(因此不在源代码管理中，或者是您不希望包含在源代码分发中的文件。)

project_urls：

URL名称到超链接的任意映射，与简单的url和ownload_url选项提供的文档相比，允许在何处找到各种资源的更具可扩展性的文档。

Python_Requires：

与版本说明符(如PEP 440中定义的)对应的字符串，用于指定PEP 345中定义的Requires-Python。

Setup_Requires：

指定安装脚本运行所需的其他分发版本的字符串或字符串列表。在处理其余的安装脚本或命令之前，setupTools将尝试获取这些脚本或命令(甚至使用EasyInstall下载它们)。如果将distutils扩展用作构建过程的一部分，则需要此参数；例如，处理setup()参数并将其转换为蛋信息元数据文件的扩展。 (注意：setup_requires中列出的项目不会自动安装在运行安装脚本的系统上。如果它们在本地还不可用，则只需将它们下载到./.eggs目录。如果希望安装它们，并且在运行安装脚本时可用，则应将它们添加到install_requires和setup_requires中。)

测试加载器：

如果您希望使用一种不同于setupTools通常使用的方式来查找要运行的测试，您可以在此参数中指定一个模块名称和类名。命名类必须是不带参数的可实例化类，并且其实例必须支持在Pythonunittest模块的TestLoader类中定义的loadTestsFromNames()方法。SetupTools将只在names参数中传递一个测试"name"：为test_suite参数提供的值。您指定的加载器可以以它喜欢的任何方式解释此字符串，因为test_suite字符串中可能包含的内容没有任何限制。模块名称和类名必须用:分隔。此参数的默认值为setuptools.command.test:ScanningLoader。如果希望使用默认的unittest行为，则可以将unittest:TestLoader指定为test_loader参数。这将阻止对子模块和子包进行自动扫描。您在此处指定的模块和类可能包含在另一个包中，只要您使用TESTS_REQUIRED选项确保在运行测试命令时包含加载器类的包可用。

测试套件：

命名unittest.TestCase子类(或包含一个或多个子类的包或模块，或此类子类的方法)的字符串，或命名可以不带参数调用并返回unittest.TestSuite的函数。如果命名的套件是一个模块，并且该模块有一个additional_tests()函数，则会调用该函数并将结果添加到要运行的测试中。如果命名套件是一个包，则任何子模块和子包都会递归添加到整个测试套件中。指定此参数允许使用测试命令运行指定的测试套件，例如通过setup.py测试。有关更多详细信息，请参阅下面有关测试命令的部分。

测试要求：

如果您的项目测试除了安装所需的包之外还需要一个或多个其他包，您可以使用此选项来指定它们。它应该是一个字符串或字符串列表，指定需要存在哪些其他发行版才能运行包的测试。当您运行测试命令时，setupTools将尝试获取它们(甚至使用EasyInstall下载它们)。请注意，这些必需的项目不会安装在运行测试的系统上，而只有在尚未在本地安装它们的情况下才会下载到项目的安装目录。

Use_2to3：

在构建过程中使用2to3将源代码从Python2转换为Python3。有关更多详细信息，请参阅通过SetupTools同时支持Python2和Python3。

use_2to3_exclude_fixers：

默认情况下，转换使用lib2to3.fixers包中的所有修复程序。要使用其他修复程序，可以将参数use_2to3_fixers设置为包含修复程序的包的名称列表。要排除修复程序，可以将参数use_2to3_exclude_fixers设置为要跳过的修复程序名称。

use_2to3_fixers：

用于搜索要在2to3转换期间使用的其他修复程序的模块列表。有关更多详细信息，请参阅通过SetupTools同时支持Python2和Python3。

ZIP_SAFE：

一个布尔值(True或False)标志，指定是否可以安全地安装项目并从Zip文件运行。如果未提供此参数，bdist_egg命令将不得不在每次生成鸡蛋时分析项目的所有内容，以查找可能存在的问题。

扩展

构建扩展(而不是纯的Python模块)要复杂得多，因为它本质上要求您指定必要的参数和参数，以便从C源文件成功构建扩展。这是通过ext_modules关键字实现的，它只是一个Extension实例列表(可从distutils.core导入)。Extension类构造函数接受的关键字参数是用于指定编译扩展的构建步骤的输入向量。

由于此问题具体是关于setuptools.setup()的，我将仅包括ext_modules的定义，但documentation for the Extension class提供了完整的详细信息。为完整起见，以下是Extension构造函数的可接受关键字列表：

    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：

扩展实例列表，每个扩展实例描述一个扩展模块。假设您的发行版只包含一个名为foo并由foo.c实现的扩展名。如果不需要编译器/链接器的额外指令，则描述此扩展非常简单：
   from distutils.core import setup, Extension
   setup(name='foo',
         version='1.0',
         ext_modules=[Extension('foo', ['foo.c'])],
         )

其他

最后，甚至还有更多的kwarg可以在setuptools.dist和其他地方实现，但由于某种原因从未添加到任何主要的setupTools/distutils文档中：

功能(已弃用)：

将选项名称映射到setuptools.Feature对象的词典。功能是分发的一部分，可以根据用户选项、功能间相关性和当前系统上的可用性来包括或排除这些功能。所有安装命令(包括源代码和二进制分发版本)中都省略了排除的功能，因此您可以从同一源代码树创建多个分发版本。

long_description_content_type(PERMaking a PyPI-friendly README)：

设置为自述文件标记的可接受的Content-Type-Style值，例如text/plain、text/x-rst(表示reStruredText)或text/markdown。

提供附加服务(按PEP566, listed as "Provides-Extra")：

包含可选功能名称的字符串。必须是有效的Python标识符。可用于使依赖项以是否已请求可选功能为条件。

相关文章