导读

2022年如何创立Python 包？如何公布包？这就是本文所教您的。

1. 纲要

为了创立Python 包，须要编写实现性能的代码，而后须要将其公布到 PyPI。

现在，还能够设置各种其它配置，让过程更加容易：

  • 继续测试您的package；
  • 代码覆盖率报告；
  • per-commit hook（预提交挂钩）（例如，确保正确的代码格局）；
  • 每次公布新版本时主动公布到 PyPI；
  • ...

2. 包的作用

通常，如果您正在创立 Python 包，要么是因为有一些想要与别人分享的代码，要么是因为您对想要剖析享的货色有肯定的想法。

就本文而言，我想打包我最近写的自定义JSON编码器和解码器，它容许您扩大 JSON 规范。

3. 依赖

我将从设置包的依赖治理开始，我将应用 Poetry。Poetry目前正广泛应用于各大我的项目内，越来越成为支流。

3.1. 命名

[naming matters] [pydont-naming-matters]在编程中很重要。我心愿我的包被称为extendedjson。

在为您的包抉择名称时，请务必返回 PyPI 并查看它是否可用！

3.2. 初始化

在我的项目文件夹中，通过应用 Poetry创立一个新我的项目

poetry new .

这将创立如下目录构造：

extendedjson├───extendedjson│   └───__init__.py├───tests│   ├───__init__.py│   └───test_extendedjson.py├───pyproject.toml└───README.rst

看一下 pyproject.toml文件，它为我填写了一些默认信息：

[tool.poetry]name = "extendedjson"version = "0.1.0"description = ""authors = ["Rodrigo Girão Serrão <[email protected]>"][tool.poetry.dependencies]python = "^3.8"[tool.poetry.dev-dependencies]pytest = "^5.2"[build-system]requires = ["poetry-core>=1.0.0"]build-backend = "poetry.core.masonry.api"

TOML 文件蕴含包的设置和配置，方括号 []内的每个题目定义一个局部。例如，该文件以 [tool.poetry] 局部结尾，其中咱们为Poetry自身提供了一些配置选项。而后，咱们当初有包依赖项，相当于 Python。在那之后，咱们有特定于包开发的依赖项，即你在实现性能、测试代码等时所依赖的货色，但最终用户并不真正须要这些货色。最初，咱们看到了构建零碎的一些设置。

咱们将持续放弃默认设置，因为它们与我当初想要的统一。我惟一要更改的是文件README.rst，因为我更喜爱markdown文件而不是 reStructured文件。

创立新我的项目后，应用 Poetry在虚拟环境中装置所有依赖项：

poetry install

这将在您的根目录中创立一个poetry.lock文件，其中蕴含无关所有已装置依赖项的特定版本的信息。

4. Git

当初咱们曾经创立了我的项目构造，上面将初始化一个 GitHub 存储库来托管代码：

git initgit add *git commit -m "First commit"git branch -M maingit remote add origin https://github.com/mathspp/extendedjson.gitgit push -u origin main

4.1. pre-cm hooks

咱们要做的下一件事是设置一些commit hooks。

例如，咱们能够轻松地设置一个pre-commit hook，以确保文件不会在行尾存在额定的空白，或者能够将black设置为预提交挂钩，以确保所有代码始终正确格式化。

首先，增加 pre-commit 作为 Poetry 的开发依赖项：

poetry add -D pre-commit# -D 增加包作为开发依赖项。

而后，咱们提交更新的依赖项：

git add poetry.lock pyproject.tomlgit commit -m "Add pre-commit devt dependency."

当初，要设置pre-commit，在根目录中创立一个文件 .pre-commit-config.yaml，依照咱们想要的形式设置它。上面是我的.pre-commit-config.yaml文件的样子：

# See https://pre-commit.com for more information# See https://pre-commit.com/hooks.html for more hooksrepos:  - repo: https://github.com/pre-commit/pre-commit-hooks    rev: v4.0.1    hooks:      - id: check-toml      - id: check-yaml      - id: end-of-file-fixer      - id: mixed-line-ending  - repo: https://github.com/psf/black    rev: 22.3.0    hooks:      - id: black  - repo: https://github.com/PyCQA/isort    rev: 5.10.1    hooks:      - id: isort        args: ["--profile", "black"]

在此之后，装置钩子，而后运行一次。

pre-commit installpre-commit run all-files
确保在虚拟环境中操作这所有。

当初是时候将更改提交到仓库了，这些更改来自增加新依赖项，而后是运行预提交挂钩的更改：

git add pyproject.toml poetry.lock .pre-commit-config.yamlgit commit -m "Add pre-commit devt dependency."git add *git commit -m "Run all pre-commits."git push

5. License

为我的项目增加一个License，本我的项目的License抉择是MIT。这个操作能够在Github仓库页面进行操作，而后再其拉取到本地。

6. 测试

当初我将尝试将空包上传到 test PyPI存储库 。这让每个人都能够测试他们的打包或公布工作流程，而不会弄乱实在的存储库。

6.1. 配置test 仓库

首先，让Poetry 配置这个测试存储库：

poetry config repositories.testpypi https://test.pypi.org/legacy/

这使得 Poetry 晓得存储库，咱们称之为 testpypi。

6.2. 获取API key

接下来，须要获取一个 API密钥，以便Poetry 能够真正推送到testpypi 存储库。为此，您须要在TestPyPI上创立一个帐户，而后在您的帐户设置下创立一个新的 API密钥。

获取您的API 密钥后，您能够通过配置 Poetry以应用它：

poetry config http-basic.testpypi __token__ pypi-your-api-token-here

6.3. 构建和上传你的包

上传包之前的步骤是构建它！构建包后，您能够尝试将其上传到 TestPyPI：

poetry buildpoetry publish -r testpypi

一旦你实现了，假如一切顺利，你的包应该在 TestPyPI上

6.4. 疏忽dist

当您构建包时，会创立一个文件夹dist，您能够在其中找到 Poetry为您构建的货色。

咱们不想将这些推送到GitHub，因而咱们将文件夹 dist增加到 .gitignore文件中。

7. 填充

接下来咱们要做的是用实在代码代替之前的空包，而后将其公布到真正的 PyPI 存储库。

7.1. 增加代码

因而，我将从获取我的custom JSON encoder and decoder mechanism开始，并将其放入extendedjson/__init__.py文件中。

7.2. changelog

接下来，我想将这个变动记录在一个changelog中，所以我会再增加一个开发依赖。Scriv 是一个命令行工具，用于帮忙开发人员保护有用的变更日志。

此步骤齐全是可选的

再一次，应用 Poetry 增加开发依赖项：

poetry add -D scriv[toml]

接下来，我在我的文件pyproject.toml中配置 scriv 以将 markdown 文件用于更改日志片段，创立更改日志片段所在的目录 changelog.d，当初我能够创立一个片段来跟踪我的代码更改：

scriv create

Scriv当初将创立一个小文件，我应该在其中记下我所做的更改。

### Added- Classes `ExtendedEncoder` and `ExtendedDecoder` to allow extension of the JSON format.

7.3. 提交

提交之前所做的所有：

git add pyproject.toml poetry.lock changelog.d/.gitkeepgit commit -m "Add scriv as devt dependency."git add changelog.d/* extendedjson/__init__.pygit commit -m "Add ExtendedEncoder and ExtendedDecoder."

8. 公布

当初咱们有了要散发的实在代码，能够将它公布到实在的 PyPI 存储库！

8.1. 配置PyPI

因为Poetry 是用Python 构建的，所以配置 PyPI 比TestPyPI容易一点。只需转到您的 PyPI 帐户，获取一个 API 密钥，而后通知Poetry应用它：

poetry config pypi-token.pypi pypi-your-token-here

8.2. bulid

当初能够公布咱们的代码，但咱们必须先构建它，咱们应用标记--build：

poetry publish --build

就这样！当初你能够从 PyPI中获取extendedjson！

8.3. 测试

装置模块，导入它，退出 Python，而后卸载它：

9. 公布release

让咱们为0.1.0 版筹备一个GitHub 版本。

9.1. 筹备

我将首先在 README文件中增加一些信息，该文件目前为空。我还将通过指定让 Poetry晓得包信息在其中

readme = "README.md"  # pyproject.toml文件中

第一句将简要形容extendedjson 的用处，还将其增加为Poetry 配置下的我的项目形容。接下来，我将增加一个简短的示例并链接到我在其中写的无关代码的文章。

最初，我将应用scriv 将更改日志片段收集到我将应用的 CHANGELOG文件中：

scriv collect

而后，我将从 README 文件中提取短句并将其作为存储库形容。我还将增加一些主题标签。

9.2. Tag

在所有这些更改都到位并提交之后，让咱们标记提交历史以阐明这个工夫点是版本 0.1.0：

git tag -a v0.1.0 -m "Initial version."

应用命令 scriv github-release进行公布。

创立标签后，公布非常简单！只需转到存储库中的/tags页面，而后单击标签旁边的三个点：它将有一个选项来创立该标签的公布。

总结

本文带您走过了一遍构建Python包的全副过程，如：创立我的项目，依赖治理，Git治理，打包，公布等。更加进阶的操作还有设置自动化测试和代码覆盖率等。（看浏览状况更新前面两局部的内容）

心愿本文对您有所帮忙，如果有任何问题，欢送与小编探讨，最好是能点个赞，或者转发分享，谢谢。

本文由mdnice多平台公布