回答问题

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

Answers

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

Most of these are documented here but some are not included in the table: packages, package_dir, package_data, scripts, obsoletes, provides,py_modules和数据_files。

setup_keywords元组中也缺少其中一些。如果你 grep 为setup_keywords它看起来不像它实际上在任何地方被引用......但这是另一天的故事。无论如何,这里是 Python 3.10 的(希望是完整的)列表。

---

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

(必填:name、version 以及 author 或 maintainer 中的至少一个)

作者:

包作者的名字(如果没有提供维护者,则需要)

作者_电子邮件:

包作者的电子邮件地址

分类器:

一个分类器列表(参见:https://pypi.org/classifiers/)

数据_files:

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

data_files指定(directory, files)对的序列,方式如下:

设置(...,

data_filesu003d[('位图', ['bm/b1.gif', 'bm/b2.gif']),

('config', ['cfg/data.cfg'])],

)

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

描述:

包装的简短摘要描述

下载_url:

可以下载包的位置

关键词:

关键字列表(也需要一个字符串。如果逗号分隔,则将其拆分为一个列表)

执照:

包的许可证(仅当许可证不是“trove 分类器”中列出的许可证时使用。请参阅:分类器)

详细描述:

包的详细描述,PyPI 用于构建项目页面

维护者:

包维护者的名字(如果没有提供作者,则需要)

维护者_email:

包维护者的电子邮件地址

姓名:

包名(distutils需要)

** 已弃用:**

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

包_data:

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

包_dir:

如果你使用不同的约定来布局你的源目录,那没问题:你只需要提供package_dir选项来告诉 Distutils 你的约定。例如,假设您将所有 Python 源代码保存在lib下,因此“根包”中的模块(即根本不在任何包中)在lib中,foo包中的模块在lib/foo中,等等。然后你会放

package_dir u003d {'': 'lib'}

在您的安装脚本中。这个字典的键是包名,一个空的包名代表根包。这些值是相对于您的分发根目录的目录名称。在这种情况下,当您说packages = ['foo']时,您承诺文件lib/foo/__init__.py存在。

另一种可能的约定是将foo包放在lib中,将foo.bar包放在lib/bar中,等等。这将在安装脚本中编写为

package_dir u003d {'foo': 'lib'}

package_dir字典中的package: dir条目隐式适用于 package 下的所有包,因此此处自动处理foo.bar情况。在这个例子中,拥有packages = ['foo', 'foo.bar']告诉 Distutils 去寻找lib/__init__.py和lib/bar/__init__.py。 (请记住,虽然package_dir递归地应用,但您必须明确列出包中的所有包:Distutils 不会递归地扫描您的源代码树以查找具有__init__.py文件的任何目录。)

包:

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

平台:

平台列表(也需要一个字符串。如果逗号分隔,则将其拆分为一个列表)

提供:

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

py_modules:

对于小型模块分发,您可能更喜欢列出所有模块而不是列出包——尤其是在“根包”中的单个模块的情况下(即根本没有包)。

py_modules u003d ['foo.py']

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

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

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

脚本:

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

脚本选项只是以这种方式处理的文件列表。从 PyXML 设置脚本:

设置(...,

脚本u003d['scripts/xmlproc_parse', 'scripts/xmlproc_val']

)

网址:

包的主页

版本:

本次发布版本(distutils要求)

---

setuptools.setup() 关键字参数

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

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

(由于setuptools.setup()调用distutils.core.setup(),相同的参数是必填:name,version,以及**author或maintainer**中的至少一个)

转换_2to3_doctests:

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

依赖_链接:

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

渴望_资源:

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

入口_points:

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

排除_package_data:

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

附加_要求:

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

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

包括\包\数据:

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

安装_要求:

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

命名空间_packages:

命名项目的“命名空间包”的字符串列表。命名空间包是可以跨多个项目发行版拆分的包。例如,Zope 3 的zope包是命名空间包,因为zope.interface和zope.publisher等子包可能会分开分发。 egg 运行时系统可以在运行时自动将此类子包合并为单个父包,只要你在每个包含命名空间包的任何子包的项目中声明它们,并且只要命名空间包的__init__.py不包含除命名空间声明。有关详细信息,请参阅下面有关命名空间包的部分。

包_数据:

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

项目_urls:

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

python_requires:

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

设置_要求:

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

测试_loader:

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

测试_套件:

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

测试_require:

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

使用_2to3:

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

使用_2to3_exclude_fixers:

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

使用_2to3_fixers:

在2to3转换期间搜索要使用的附加修复程序的模块列表。有关更多详细信息,请参阅使用 Setuptools 同时支持 Python 2 和 Python 3。

压缩_安全:

一个布尔值(True 或 False)标志,指定项目是否可以安全地安装并从 zip 文件运行。如果未提供此参数,则bdist_egg命令必须在每次构建 egg 时分析项目的所有内容以查找可能出现的问题。

zoz100027 * *

扩展

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

由于这个问题是关于setuptools.setup()的,所以我将只包括ext_modules的定义,但是Extension类](https://docs.python.org/3.7/distutils/apiref.html#distutils.core.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 实现的扩展。如果不需要编译器/链接器的额外指令,描述这个扩展非常简单:

从 distutils.core 导入设置,扩展

设置(名称u003d'foo',

版本u003d'1.0',

ext_modulesu003d[扩展('foo', ['foo.c'])],

)

---

杂项。

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

功能(已弃用):

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

long_description_content_type (根据制作 PyPI 友好的 README):

为您的 README 文件的标记设置一个可接受的 Content-Type-style 值,例如text/plain、text/x-rst(用于 reStructuredText)或text/markdown。

provides_extras(根据PEP566,列为“Provides-Extra”):

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