導讀

2022年如何創建python 包？如何發布包？這就是本文[1]所教您的。

1. 大綱

為了創建Python 包，需要編寫實現功能的代碼，然後需要將其發布到 PyPI。

如今，還可以設置各種其它配置，讓過程更加容易：

• 持續測試您的package；
• 代碼覆蓋率報告；
• per-comMIT hook（預提交掛鈎）（例如，確保正確的代碼格式）；
• 每次發布新版本時自動發布到 PyPI；
• ...

2. 包的作用

通常，如果您正在創建 Python 包，要麼是因為有一些想要與他人分享的代碼，要麼是因為您對想要分析享的東西有一定的想法。

就本文而言，我想打包我最近寫的自定義JSON編碼器和解碼器，它允許您擴展JSON標準。

3. 依賴

我將從設置包的依賴管理開始，我將使用 Poetry。Poetry目前正廣泛應用於各大項目內，越來越成為主流。

3.1. 命名

[naming matters] [pydont-naming-matters]在編程中很重要。我希望我的包被稱為extendedjson。

在為您的包選擇名稱時，請務必前往 PyPI[2] 並檢查它是否可用！

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[3] 是一個命令行工具，用於幫助開發人員維護有用的變更日誌。

此步驟完全是可選的

再一次，使用 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管理，打包，發布等。更加進階的操作還有設置自動化測試和代碼覆蓋率等。（看閱讀情況更新後面兩部分的內容）

希望本文對您有所幫助，如果有任何問題，歡迎與小編討論，最好是能點個讚，或者轉發分享，謝謝。

參考資料

[1]Source: https://mathspp.com/blog/how-to-create-a-python-package-in-2022

[2]PyPI: https://pypi.org/

[3]scriv: https://pypi.org/project/scriv/