在 python 存储库名称和包名称中使用连字符/破折号

2022-01-13 00:00:00 python scikit-learn pip pypi package

问题描述

我正在尝试使我的 git 存储库 pip 可安装.为此，我正在重组 repo 以遵循正确的约定.通过查看其他存储库，我的理解是，我应该将所有源代码放在与存储库名称同名的包中.例如.如果我的存储库名为 myrepo，那么源代码将全部放入一个也称为 myrepo 的包中.

I am trying to make my git repository pip-installable. In preparation for that I am restructuring the repo to follow the right conventions. My understanding from looking at other repositories is that I should put all my source code in a package that has the same name as the repository name. E.g. if my repository is called myrepo, then the source code would all go into a package also called myrepo.

为了便于阅读，我的存储库中有一个连字符:例如我的仓库.所以如果我想为它创建一个同名的包，它也会有一个连字符.在本教程中 它说 python 包不要使用连字符"名字.但是，我见过一些完善的软件包，例如 scikit-learn，它们的名称中有连字符.我注意到的一件事是，在 scikit-learn 存储库中，包名称与存储库名称不同，而是称为 sklearn.

My repository has a hyphen in it for readability: e.g. my-repo. So if I wanted to make a package for it with the same name, it would have a hyphen in it as well. In this tutorial it says "don't use hyphens" for python package names. However I've seen well-established packages such as scikit-learn that have hyphens in their name. One thing that I have noticed though is that in the scikit-learn repo, the package name is not the same as the repo name and is instead called sklearn.

我认为我上面的讨论归结为以下问题:

I think my discussion above boils down to the following questions:

  1. 打包repo的时候，repository的名字和package的名字是什么关系?名字不匹配时有什么要注意的吗?
  2. 可以在包名中使用连字符吗?存储库名称呢?
  3. 如果 scikit-learn 的包名是 sklearn，那么我安装它时怎么会使用 pip install scikit-learnpip install sklearn的?
  1. When packaging a repo, what is the relationship between the repository's name and the package's name? Is there anything to beware of when having names that don't match?
  2. Is it okay to have hyphens in package names? What about in repository names?
  3. If the package name for scikit-learn is sklearn, then how come when I install it I do pip install scikit-learn instead of pip install sklearn?

解决方案

为了回答你的第一点，让我改写 我的回答 换一个问题.

To answer your 1st point let me rephrase my answer to a different question.

误解的最大来源是包"这个词.严重超载.游戏中有 4 个不同的名称——存储库名称、用于开发的目录名称(包含 setup.py 的目录名称)、包含 的目录名称__init__.py 和其他可导入模块，PyPI 的分发名称.这 4 个通常相同或相似，但这不是必需的.

The biggest source of misunderstanding is that the word "package" is heavily overloaded. There are 4 different names in the game — the name of the repository, the name of the directory being used for development (the one that contains setup.py), the name of the directory containing __init__.py and other importable modules, the name of distribution at PyPI. Quite often these 4 are the same or similar but that's not required.

存储库和开发目录的名称可以是任何名称，它们的名称不起任何作用.当然，正确命名它们很方便，但这只是方便.

The names of the repository and development directory can be any, their names don't play any role. Of course it's convenient to name them properly but that's only convenience.

包含 Python 文件的目录名称是要导入的包的名称.一旦包被命名为导入，名称通常会卡住并且无法更改.

The name of the directory with Python files name the package to be imported. Once the package is named for import the name usually stuck and cannot be changed.

发行版的名称在 PyPI 中提供了一个页面和发行版文件的名称(源发行版、鸡蛋、轮子).这是 setup(name='distribution') 调用中的名称.

The name of the distribution gives one a page at PyPI and the name of distribution files (source distribution, eggs, wheels). It's the name one puts in setup(name='distribution') call.

让我展示详细的真实示例.我一直在维护一个名为 CheetahTemplate 的模板库.我在名为 cheetah3/ 的开发目录中开发它.PyPI 的分布称为 Cheetah3；这是我放入 setup(name='Cheetah3').顶级模块是 Cheetah 因此有一个import Cheetah.Template 或 from Cheetah import Template;这意味着我有一个目录 cheetah3/Cheetah/.

Let me show detailed real example. I've been maintaining a templating library called CheetahTemplate. I develop it in the development directory called cheetah3/. The distribution at PyPI is called Cheetah3; this is the name I put into setup(name='Cheetah3'). The top-level module is Cheetah hence one does import Cheetah.Template or from Cheetah import Template; that means that I have a directory cheetah3/Cheetah/.

2 的答案是:您可以在存储库名称和 PyPI 分发名称中使用破折号，但不能在包(包含 __init__.py 文件的目录)名称和模块(.py 文件)名称，因为你不能在 Python 中编写 import xy-zzy，这将是减法和 SyntaxError.

The answer to 2 is: you can have dashes in repository names and PyPI distribution names but not in package (directories with __init__.py files) names and module (.py files) names because you cannot write in Python import xy-zzy, that would be subtraction and SyntaxError.

第 3 点:站点和存储库名称是 scikit-learn，以及 发行版名称，但可导入的包(带有 __init__.py 的顶级目录)是 sklearn.

Point 3: The site and the repository names are scikit-learn, as well as the distribution name, but the importable package (the top-level directory with __init__.py) is sklearn.

PEP 8 与该问题无关，因为它不讨论分发，只讨论可导入的包和模块.

PEP 8 has nothing to do with the question as it doesn't talk about distribution, only about importable packages and modules.

相关文章