setuptools.setup 的 name 参数值如何影响结果？

Question

我最近收到了一组 Python 代码，由一个学术实验室的研究生编写，由一个 Python 脚本和脚本使用的大约六个单文件 Python 模块组成。所有这些文件（脚本和模块）都在同一个目录中。

我想用来pip在虚拟环境中安装此代码，所以我尝试setup.py为它编写一个文件，这是我以前从未做过的。

我让这个装置工作起来，我对我投入的大部分东西有一个模糊的理解setup.py。

对此的一个例外是函数name关键字的值setuptools.setup。

根据我找到的文档，这个参数应该是“包的名称”，但我并没有告诉我它的价值最终是如何重要的。换句话说，这个值是否只对人类读者重要，还是它实际上会影响pip install该命令安装的方式或代码是否有效？

因此，我不知道该给这个参数什么值，所以我只是想出了一个听起来合理的名字，但没有尝试让它与代码库中的其他东西相匹配。令我惊讶的是，什么都没坏！我的意思是pip安装完成没有错误，并且安装的代码在虚拟环境中正确执行。

我进行了一些实验，似乎我提出的几乎任何值都同样可以。

为了下面的描述，假设我给name参数赋值whatever。然后，据我所知，这唯一的影响是在与文件相同的目录中whatever.egg-info/创建了一个具有该名称的子目录（通过pip？）setup.py，并且该子目录包含两个包含字符串的文件whatever。

这些文件之一是whatever.egg-info/PKG-INFO，其中包含行

Name: whatever

另一个是whatever.egg-info/SOURCES.txt，它列出了几个相对路径，包括一些以whatever.egg-info/.

---

也许这是一个包装问题太简单了，价值name不重要？

问：谁能给我一个简单的例子，其中setuptools.setup'sname参数的错误值会导致pip install或安装的代码失败？

Answer 1

前言： Python 术语表将包定义为“可以包含子模块或递归子包的 Python 模块”。setuptools 等创建的通常称为可以捆绑一个或多个包的发行版（因此参数setup(packages=...)）。我将使用这个含义来表示术语“包”和“分发”我将在下面的文本中

\n\n

该name参数决定了如何在整个 Python 生态系统中识别您的发行版。它与发行版的实际布局（即其包）无关，也与这些包中定义的任何模块无关。

\n

该文档准确地指定了合法发行版名称的组成部分：

\n

\n

发行版的名称。名称字段是发行版的主要标识符。有效名称仅由 ASCII 字母和数字、句点、下划线和连字符组成。它必须以字母或数字开头和结尾。发行版名称仅限于与以下正则表达式匹配的名称（使用 运行re.IGNORECASE）：^([A-Z0-9]|[A-Z0-9][A-Z0-9._-]*[A-Z0-9])$。

\n

\n

（历史：此规范在PEP 566中进行了细化，以与PEP 508中的定义保持一致。在PEP 345之前，松散地指定了发行版名称，没有施加任何限制。）

\n

除了上述限制之外，还需要考虑其他一些方面：

\n

\n
• 当您打算通过PyPI分发您的发行版时，_和之间没有区别-，即hello_world和hello-world被认为是相同的发行版。您还需要确保 PyPI 上尚未采用发行版名称，否则您将无法上传它（如果它被废弃的项目占用，您可以尝试在为了能够使用该名称；有关更多信息，请参阅PEP 541）。
\n
• 最重要的是，您应该确保发行版名称在您的工作环境中是唯一的，即它不会与其他发行版的名称冲突。假设您已经在虚拟环境中安装了requestsrequests项目，并且您决定也为您的发行版命名。然后安装您的发行版将删除已经存在的安装（即相应的软件包），您将无法再访问它。
\n

\n

顶级包名称

\n

上面的第二个要点也适用于您的发行版中顶级包的名称。假设您有以下分布布局：

\n

.\n\xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 setup.py\n\xe2\x94\x94\xe2\x94\x80\xe2\x94\x80 testpkg\n    \xe2\x94\x94\xe2\x94\x80\xe2\x94\x80 __init__.py\n    \xe2\x94\x94\xe2\x94\x80\xe2\x94\x80 a.py\n

\n

其中setup.py包含：

\n

.\n\xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 setup.py\n\xe2\x94\x94\xe2\x94\x80\xe2\x94\x80 testpkg\n    \xe2\x94\x94\xe2\x94\x80\xe2\x94\x80 __init__.py\n    \xe2\x94\x94\xe2\x94\x80\xe2\x94\x80 a.py\n

\n

__init__.py并且a.py只是空文件。testpkg安装该发行版后，您可以通过导入（顶级包）来访问它。

\n

现在假设您有一个不同的发行版，但name=\'dist-b\'使用相同的发行packages=[\'testpkg\']版并提供一个模块b.py（而不是a.py）。发生的情况是，第二次安装是在已经存在的安装上执行的，即使用相同的物理目录（即testpkg执行的，即使用相同的物理目录（即恰好是两个发行版使用的包），可能会替换已经存在的模块，尽管两个发行版实际上都已安装：

\n

$ pip freeze | grep dist-*\ndist-a @ file:///tmp/test-a\ndist-b @ file:///tmp/test-b\n$ python\n>>> import testpkg\n>>> import testpkg.a\n>>> import testpkg.b\n

\n

现在卸载第一个发行版 ( dist-a) 也会删除第二个发行版的内容：

\n

$ pip uninstall dist-a\n$ python\n>>> import testpkg\nModuleNotFoundError: No module named \'testpkg\'\n

\n

因此，除了发行版名称之外，确保其顶级包不与已安装项目的包冲突也很重要。这些顶级包充当发行版的命名空间。因此，最好选择一个与顶级包的名称相似的发行版名称 - 通常这些名称被选择为相同的。

\n