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

Question

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() 函数接受的关键字参数的完整列表是什么？

Answer 1

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

其中大部分记录在此处，但有些未包含在表中：packages、package_dir、package_data、scripts、obsoletes、provides、py_modules和data_files。

其中一些也从setup_keywords元组中丢失。如果您搜索setup_keywords它，看起来它实际上并没有在任何地方被引用......但那是另一天的故事。无论如何，这是 Python 3.10 的（希望是完整的）列表。

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

（必填：姓名、版本，以及至少作者或维护者之一）

作者：

包作者的名字（如果没有提供维护者，则需要）

作者_电子邮件：

包作者的电子邮件地址

分类器：

一个列表分类的（参见：https://pypi.org/classifiers/）

数据文件：

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

data_files(directory, files)按以下方式指定对的序列：

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

(directory, files)序列中的每一对都指定了安装目录和要在那里安装的文件。files 中的每个文件名都是相对于setup.py脚本解释的。

描述：

包的简短摘要说明

下载地址：

可以下载包的位置

关键词：

关键字列表（也需要一个字符串。如果以逗号分隔，则将其拆分为一个列表）

执照：

包的许可证（仅当许可证不是“宝藏分类器”中列出的许可证时才使用。参见：分类器）

详细描述：

包的更长描述，由 PyPI 用于构建项目页面

维护者：

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

维护者电子邮件：

包维护者的电子邮件地址

姓名：

包的名称（由 要求distutils）

过时：

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

包数据：

可以使用函数的package_data关键字参数将包数据添加到包中setup()。该值必须是从包名称到应复制到包中的相对路径名称列表的映射。路径被解释为相对于包含包的目录（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这里会自动处理这种情况。在这个例子中，packages = ['foo', 'foo.bar']had 告诉 Distutils 寻找lib/__init__.py和lib/bar/__init__.py。（请记住，虽然package_dir递归应用，但您必须明确列出包中的所有包：Distutils 不会递归扫描您的源树以查找任何包含__init__.py文件的目录。）

包：

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

平台：

平台列表（也需要一个字符串。如果以逗号分隔，则将其拆分为一个列表）

提供：

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

py_modules：

对于小模块分发，您可能更喜欢列出所有模块而不是列出包——尤其是单个模块进入“根包”的情况（即，根本没有包）。

py_modules = ['foo.py']

这是一个稍微复杂的例子：

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

这描述了两个模块，其中一个在“root”包中，另一个在pkg包中。同样，默认的包/目录布局意味着这两个模块可以在mod1.py和 中找到pkg/mod2.py，并且也pkg/__init__.py存在。同样，您可以使用该package_dir选项覆盖包/目录对应关系。

脚本：

脚本是包含 Python 源代码的文件，旨在从命令行启动。脚本不需要 Distutils 做任何非常复杂的事情。唯一巧妙的功能是，如果脚本的第一行以#!“python”开头并包含单词“python”，则 Distutils 将调整第一行以引用当前解释器的位置。默认情况下，它会替换为当前的解释器位置。该--可执行文件（或-e）选项将允许解释路径被明确覆盖。

脚本选项只是要以这种方式处理的文件列表。从 PyXML 安装脚本：

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

网址：

包的主页

版本：

此版本的版本（需要distutils）

setuptools.setup() 关键字参数

还有更多的论点，即setuptools.setup()会接受，超越那些通过使用distutils。

虽然它被称为“新的和更改的设置关键字”（对我来说建议一个版本更改日志），但介绍性文字说这些是“设置（）的关键字参数 [由 setuptools 添加或更改”，所以我相信链接实际上提供一个完整的清单。为了完整起见，我将在此处添加它。

（由于setuptools.setup()调用distutils.core.setup()，相同的参数是必需的：名称，版本，以及至少作者或维护者之一）

convert_2to3_doctests：

需要转换的 doctest 源文件列表2to3。有关更多详细信息，请参阅使用 Setuptools 支持 Python 2 和 Python 3。

依赖链接：

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

渴望资源：

应该一起提取的命名资源的字符串列表，如果需要它们中的任何一个，或者是否导入了项目中包含的任何 C 扩展。此参数仅在项目将作为 zipfile 安装时才有用，并且需要将所有列出的资源作为一个单元提取到文件系统中。此处列出的资源应该是 '/' 分隔的路径，相对于源根目录，因此要列出foo.pngpackage中的资源bar.baz，您需要包含字符串bar/baz/foo.png在这个论点中。如果您一次只需要获取一个资源，或者您没有任何访问项目中其他文件（例如数据文件或共享库）的 C 扩展名，则您可能不需要这个参数，不应该乱七八糟用它。有关此参数如何工作的更多详细信息，请参阅下面有关自动资源提取的部分。

入口点：

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

exclude_package_data:

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

extras_require:

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

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

include_package_data:

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

安装要求：

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

命名空间_包：

命名项目“命名空间包”的字符串列表。命名空间包是一个可以拆分到多个项目发行版的包。例如，Zope 3 的zope包是一个命名空间包，因为子包喜欢zope.interface和zope.publisher可能是分开分发的。Egg 运行时系统可以在运行时自动将这些子包合并为一个父包，只要你在每个包含命名空间包的任何子包的项目中声明它们，并且只要命名空间包的__init__.py不包含任何代码，只要命名空间声明。有关更多信息，请参阅下面有关命名空间包的部分。

包数据：

将包名称映射到 glob 模式列表的字典。有关完整的说明和示例，请参阅以下有关包含数据文件的部分。如果您使用 include_package_data，则不需要使用此选项，除非您需要添加由安装脚本和构建过程生成的 eg 文件。（因此不在源代码管理中，或者是您不想包含在源代码分发中的文件。）

项目网址：

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

python_需要：

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

设置要求：

一个字符串或字符串列表，指定需要存在哪些其他发行版才能运行安装脚本。setuptools 将在处理其余的安装脚本或命令之前尝试获取这些（甚至使用 EasyInstall 下载它们）。如果您在构建过程中使用 distutils 扩展，则需要此参数；例如，处理setup()参数并将它们转换为 EGG-INFO 元数据文件的扩展。（注意： 中列出的项目setup_requires不会自动安装在运行安装脚本的系统上。./.eggs如果它们不是本地可用的，它们只是简单地下载到目录中。如果你想安装它们，以及运行安装脚本时可用，您应该将它们添加到install_requires和setup_requires.)

测试加载器：

如果您想使用与 setuptools 通常使用的不同的方式来查找要运行的测试，您可以在此参数中指定模块名称和类名称。命名类必须是可实例化的，没有参数，并且它的实例必须支持loadTestsFromNames()Pythonunittest模块的TestLoader类中定义的方法。Setuptools 将仅通过names参数中的一个测试“名称” ：为参数提供的值test_suite。您指定的加载器可以按照它喜欢的任何方式解释这个字符串，因为对test_suite字符串中可能包含的内容没有限制。模块名和类名必须用:. 此参数的默认值为setuptools.command.test:ScanningLoader。如果要使用默认unittest行为，可以指定unittest:TestLoader为test_loader取而代之的说法。这将阻止自动扫描子模块和子包。您在此处指定的模块和类可能包含在另一个包中，只要您使用 tests_require 选项来确保在运行 test 命令时包含加载器类的包可用。

测试套件：

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

测试要求：

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

使用_2to3：

2to3在构建过程中将源代码从 Python 2 转换为 Python 3 。有关更多详细信息，请参阅使用 Setuptools 支持 Python 2 和 Python 3。

use_2to3_exclude_fixers：

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

use_2to3_fixers：

用于搜索2to3转换期间要使用的其他固定器的模块列表。有关更多详细信息，请参阅使用 Setuptools 支持 Python 2 和 Python 3。

zip_safe：

一个布尔值（真或假）标志，指定项目是否可以从 zip 文件安全安装和运行。如果未提供此参数，则该bdist_egg命令每次构建鸡蛋时都必须分析项目的所有内容以查找可能的问题。

扩展

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

由于这个问题是关于setuptools.setup()具体的，我将只包括 的定义ext_modules，但该类的文档Extension提供了完整的细节。为了完整起见，这是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'])],
         )

杂项

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

功能（已弃用）：

将选项名称映射到setuptools.Feature对象的字典。功能是分发的一部分，可以根据用户选项、功能间依赖关系和当前系统的可用性来包含或排除。所有设置命令都将忽略排除的功能，包括源代码和二进制分发版，因此您可以从同一源代码树创建多个分发版。

long_description_content_type (Per Making a PyPI-friendly README ):

将 README 文件的标记设置为可接受的 Content-Type-style 值，例如text/plain, text/x-rst（对于 reStructuredText）或text/markdown.

provides_extras（每PEP566，列为“提供-EXTRA” ）：

包含可选功能名称的字符串。必须是有效的 Python 标识符。可用于根据是否已请求可选功能来建立依赖关系。