关于程序员:保姆教程构建与发布Python包

导读

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 init
git add *
git commit -m "First commit"
git branch -M main
git remote add origin https://github.com/mathspp/extendedjson.git
git 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.toml
git 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 hooks
repos:
  - 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 install
pre-commit run all-files

确保在虚拟环境中操作这所有。

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

git add pyproject.toml poetry.lock .pre-commit-config.yaml
git 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 build
poetry 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/.gitkeep
git commit -m "Add scriv as devt dependency."
git add changelog.d/* extendedjson/__init__.py
git 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 多平台公布