如果您曾经使用setup.py指令码释出过一个python包，那么您可能会发现编写指令码来发布包比编写包本身要困难。

Python 开发人员认识到了这一点，并且有一些工具采用了一种更现代的方法来构建包。Poetry 和 Flit 是构建Python 包的两种流行工具。

（此处已新增圈子卡片，请到今日头条客户端检视）因为我使用了Poetry作为一个Python依赖性管理工具，所以我决定玩转它的包管理功能。

为了获得使用Poetry释出包的实践经验，我最近释出了Flake8 Markdown，一个用 Flake8 在Markdown档案中lint Python 程式码的工具。

本文将介绍我对Flake8 Markdown的pyproject.toml和codebase所做的更改，以使其可以在 PyPI（python包索引）上释出。

资讯 已释出版本请检视Flake8 Markdown 仓库。

建立一个包

我们收到邮件了! 不管怎样，我们有一个包裹 (package，双关语---译者注)。让我们开启它:

开箱即用，Poetry为我们提供了一个简单的包结构和 pyproject.toml 档案:

0.1.0的包版本Python 的最小版本(在我的例子中是^3.7)pytest 支援和一个单元测试资讯关于 pyproject.toml的资讯和背景，见 PEP 518。如果我们将这个包按原样释出在 Python包索引(PyPI)上，那么这个包看起来就不怎么样，所以让我们让它看起来像值得安装的东西。

自定义包

以下是完成的 pyproject.toml:

资讯有关自定义Poetry包的可用部分的完整列表，请参阅 Poetry\'s pyproject.toml 文件。 让我们从上到下逐步进行更改。version

Version 描述了一个包的当前版本。我尝试遵循语义版本控制，所以当更新向后不相容时很明显。

注一旦一个包的版本存在于pypi上，就不可能使用相同的版本号上传不同的程式码。在释出Pypi上的版本之前，请确保使用 TestPyPI 进行测试更改。description

这个简短的描述出现在 pip search 和 PyPI搜寻结果 中。

license

许可证出现在包的 PyPI 页面的“Meta”部分。

我用 Github 的 choosealicense.com 找到了一个合适的许可证，并选定 MIT。Poetry 还列出了其他常见的许可证 和推荐的记号。

readme

Poetry建立了一个 README.rst 档案，但我更喜欢用 Markdown 编写文件。 README 的内容在 PyPI 上显示为专案描述，因此很好地解释为什么以及如何使用你的包。 我的 README 包括：

盾牌（因为它们看起来很漂亮）引言安装使用行为准则历史记录（大致遵循保留一个变更日志）homepage and repository

这些出现在包的 PyPI 页面的 Project 连结部分：

如果你的包有一个单独的文件网站，那么还有一个 documentation 属性。

keywords

这些出现在 PyPI 页面的 Meta 部分：

classifiers

“Trove分类器”作为 PyPI 包的类别，可以用来过滤 PyPI 上的包。它们出现在 PyPI 页面的“分类器”部分：

完整列表见 PyPI 分类器页面。

[tool.poetry.dependencies]

“依赖项”部分展示了Poetry的一个最佳特征。

当使用普通的 pip 或 Pipenv管理包时，通常在两个位置指定包：dev和部署依赖项的requirements.txt或Pipfile，以及执行时/安装依赖项的setup.py。

Poetry对所有依赖项使用pyproject.toml，这简化了依赖项管理。

这部分包括两个更改：

将最低的 Python 版本从3.7更新到3.6，以获得更广泛的相容性新增flake8作为依赖项[tool.poetry.scripts]

Scripts 是“安装包时将被安装的指令码或可执行档案”。换句话说，开发人员可以在这里根据函式建立CLI命令。

指令码的形式为：

Flake8 markdown — 包含你的惊喜 — 有一个名为flake8 markdown的CLI命令：

在安装 flake8-markdown 包之后, 执行 flake8-markdown 将从 flake8_markdown/__init__.py呼叫 main() 函式。

资讯 要使包成为一个可执行模组，比如python -m flake8-markdown，它需要一个 __main__.py模组。在Flake8 Markdown中， __main__.py 档案汇入并执行与上述指令码相同的 main() 函式。

释出包

TestPyPI 是“一个独立的Python包索引例项，它允许您在不影响实际索引的情况下尝试分发工具和程序”。将包上传到TestPyPI 并从那里安装，可以帮助包维护人员避免传送损坏的包版本。

让我们看看如何将包上载到TestPyPI。

注在将包上载到测试包索引之前，您需要注册一个TestPyPI 账户。首先，构建包：

接下来，将测试PyPI新增为备用包储存库：

现在，把包释出到TestPyPI：

最后，通过在 testpypi.pypi.org 上检视包并在独立的虚拟环境中安装测试版本，验证包的外观和工作是否符合预期：

PyPI

如果这个包在测试PyPI上看起来很好，并且正常启动，那么释出到PyPI就非常简单：

注在将包上传到包索引之前，你需要注册一个PyPI账户 。此账户与TestPyPI上的任何账户都是独立的。

总结

很愉快，我决定写一首关于它的诗：

浮动Python程式码 用Poetry集结 云端之旅Poetry 诗歌。怎么样？

英文原文：https://johnfraney.ca/posts/2019/05/28/create-publish-python-package-poetry/

译者：青书