导读
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 <5621605+RodrigoGiraoSerrao@users.noreply.github.com>"]
[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上
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！
PyPI
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多平台发布
网友评论