# Python package guidelines (简体中文)

From ArchWiki
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.
翻译状态：本文是 Python package guidelines 的翻译。上次翻译日期：2017-09-13。如果英文版本有所更改，则您可以帮助同步翻译。

本文档描述了如何基于标准 PKGBUILDs 来为 Python 程序进行打包.

## 包命名

Python 3 的包应该使用 `python-modulename` 进行命名。如果软件包与 Python 某个生态系统(例如 pip 或 tox) 关系密切，请添加相应前缀。对于其他 Python 程序来说, 使用程序名就足够了。无论如何, 包的名字应该完全使用小写。

这同样适用于 Python 2，只需要修改前缀为 `python2-` (如果必须)。

### 带版本的软件包

如果你需要添加一个带版本的软件包，请使用这种格式： `python-模块名-版本`, 比如 `python-colorama-0.2.5`。这样，Python 的依赖`colorama==0.2.5` 就会成为名为 `python-colorama-0.2.5` 的 Arch 软件包。

## 安装方式

Python 的包通常使用 Python 语言自带的工具来安装, 例如 pip 或者 easy_install[失效链接 2021-05-17 ⓘ], 这些工具就像是能从在线源 (通常是 PyPI, Python 包索引 (Python Package Index) ) 获取源文件的软件包管理器一样，而且还能跟踪相关的文件状态。 (如需这两个工具的详细比较，请参见 pip vs easy_install).

然而，如果要想使用 PKGBUILD 文件来帮助安装 Python 软件包的话，标准化的 distutils 可以说是最方便的了。它会使用已下载源码包里面的 `setup.py` 接着就能很轻松地将文件安装到 `$pkgdir/usr/lib/python<python 版本>/site-packages/$pkgname` 这个文件夹下面了。

### distutils

这里有一个 distutils PKGBUILD 样本。他遵从下面的格式:

    <python 版本> setup.py install --root="$pkgdir/" --optimize=1

其中:

- 根据程序所使用的 Python 版本来使用 `python` 或者 `python2` 替换 <python 版本> 。
- `--root="$pkgdir/"` 选项是为了防止文件直接安装到主系统而不是打包目录中。如果直接安装到主系统中，会产生权限错误。
- `--optimize=1` 选项是用来编译生成 `.pyo` 文件，好让 pacman 更好的跟踪优化她们。

### setuptools

Python 包装机制已从 distutils 向 setuptools 迁移, 后者目前正处于活跃开发时期并且能直接在 `setup.py` 文件中替换前者。不过主要的区别在于，setuptools 并没有和 Python 主包打在一起，因此你必须将其指定为 `makedepends`。

如果成品包中存在导入 (import) 了 `pkg_resources` 模块 的二进制, 那么 setuptools 必须在分包函数 `package_*()` 中另外指定为 `depends`; 还有, 如果 PKGBUILD 只安装一个版本的 Python 包的话, setuptools 需要从 `makedepends` 移至 `depends`。

### pip

如果你需要使用 pip (由 python-pip 和 python2-pip 提供)， 例如 为了安装 wheel[失效链接 2021-05-17 ⓘ] 的Python包, 请记得传入下列参数:

    PIP_CONFIG_FILE=/dev/null pip install --isolated --root="$pkgdir" --ignore-installed --no-deps *.whl

- `PIP_CONFIG_FILE=/dev/null` 此参数会使 pip 忽略 `{/etc,~/.config}/pip.conf` 因为这个配置文件可能会向 pip 添加一些额外参数。
- `--isolated` 此参数会使 pip 忽略环境变量 (以及 `{/etc,~/.config}/pip/pip.conf`) 否则 pip 又会被添加一些额外参数。
- `--ignore-installed` 在 https://github.com/pypa/pip/issues/3063 处提出的问题解决之前，把这个参数加上吧 (不然的话 pip 会在有早期 `--user` 安装痕迹的情况下跳过安装).
- `--no-deps` 此参数能确保依赖不会跟着一起被打进主包里面去。

pip 不知道如何生成 `.pyo` 文件 (see https://github.com/pypa/pip/issues/2209). 为了生成 `.pyo` 文件，在使用 pip 安装后, 运行:

    python -O -m compileall "${pkgdir}/path/to/module

## 注意事项

绝大部分情况下， 你应该设置 `arch` 为 `any` ，因为绝大部分 Python 包是平台无关的。

请不要将文件安装到类似于 `tests` 这样名字的目录中, 因为这很容易与其他 Python 包发生文件冲突 (比方说, `/usr/lib/python2.7/site-packages/tests/`).

### PyPI 下载 URLs

PyPI 中像是这种格式 `https://pypi.python.org/packages/source/${_name:0:1}/${_name}/${_name}-${pkgver}.tar.gz`<footnote> 的 URL 已经在 2016 年静默失效了, 而新的格式需要一种只有从 PyPI 网站才能取得的不可预测的哈希码[1][失效链接 2021-05-17 ⓘ]。

在下游维护者向 PyPI 维护者抱怨了这个问题 [2][失效链接 2021-05-17 ⓘ] 之后, 一种新的稳定的格式出现了 [3][失效链接 2021-05-17 ⓘ]: PKGBUILD#source `source=()` 数值现在需要使用如下 URL 模板：

请注意，我们使用了自定义的 `$_name` 而不是 `$pkgname`，因为 Python 包通常都命名成这样： `python-$_name`。

源码包
  `https://files.pythonhosted.org/packages/source/${_name::1}/${_name}/${_name}-${pkgver}.tar.gz`
双版本 wheel 包 (Python 2 和 Python 3 都兼容)
  `https://files.pythonhosted.org/packages/py2.py3/${_name::1}/$_name/$_name-$pkgver-$_name-$pkgver-py2.py3-none-any.whl`
特定架构的 wheel 包
  对于特定架构的 wheel 包，可以使用 `source_x86_64=('...')` 来表示 x86_64 架构的下载地址。与此同时可以使用 `_py=py36` 来避免重复书写 Python 版本:
  `https://files.pythonhosted.org/packages/$_py/${_name::1}/$_name/$_name-$pkgver-$_py-${_py}m-manylinux1_x86_64.whl`

Category:

- Package development (简体中文)

Hidden category:

- Pages with dead links