如何開發自己的 Python 庫

本教程翻譯自pypi官方文檔 (有刪改)，將指導讀者如何打包一個簡單的Python項目。

一個簡單的項目

本教程使用一個名為的簡單項目example_pkg。如果您不熟悉Python的模塊和導入包，請花幾分鐘時間閱讀包含文件包和模塊的Python文檔。即使您已經有一個要打包的項目，我們仍然建議您按照本示例包使用此示例包，然後嘗試使用自己的包。

要在本地創建此項目，請創建以下文件結構：

/packaging_tutorial /example_pkg __init__.py

創建此結構後，您將需要在頂級文件夾中運行本教程中的所有命令 - 所以一定要確保。cdpackaging_tutorial

編輯example_pkg/__init__.py並在其中放入以下代碼：

name = "example_pkg"

這只是為了您可以在本教程後面驗證它是否正確安裝。

1 . 創建包文件

您現在將創建一些文件來打包此項目並準備分發。創建下面列出的新文件 - 您將在以下步驟中向其添加內容。

/packaging_tutorial /example_pkg __init__.py setup.py LICENSE README.md

2 . 創建的setup.py

setup.py是setuptools的構建腳本。它告訴setuptools你的包（例如名稱和版本）以及要包含的代碼文件。

打開setup.py並輸入以下內容。您應該更新軟體包名稱以包含您的用戶名（例如，example-pkg-theacodes如果您願意，可以個性化其他值）：

import setuptools

with open("README.md", "r") as fh:
long_description = fh.read()

setuptools.setup(
name="example-pkg-your-username",
version="0.0.1",
author="Example Author",
author_email="[email protected]",
description="A small example package",
long_description=long_description,
long_description_content_type="text/markdown",
url="https://github.com/pypa/sampleproject",
packages=setuptools.find_packages(),
classifiers=[
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
],
)

setup()需要幾個論點。此示例包使用相對最小的集：

name是包的分發名稱。只要包含字母，數字_和，就可以是任何名稱-。它也不能在pypi.org上使用。請務必使用您的用戶名更新此內容，因為這可確保您在上傳程序包時不會遇到任何名稱衝突。
version 是包版本看 PEP 440有關版本的更多詳細信息。
author並author_email用於識別包的作者。
description 是一個簡短的，一句話的包的總結。
long_description是包的詳細說明。這顯示在Python Package Index的包詳細信息包中。在這種情況下，載入長描述README.md是一種常見模式。
long_description_content_type告訴索引什麼類型的標記用於長描述。在這種情況下，它是Markdown。
url是項目主頁的URL。對於許多項目，這只是一個指向GitHub，GitLab，Bitbucket或類似代碼託管服務的鏈接。
packages是應包含在分發包中的所有Python 導入包的列表。我們可以使用自動發現所有包和子包，而不是手動列出每個包。在這種情況下，包列表將是example_pkg，因為它是唯一存在的包。find_packages()
classifiers告訴索引並點一些關於你的包的其他元數據。在這種情況下，該軟體包僅與Python 3兼容，根據MIT許可證進行許可，並且與操作系統無關。您應始終至少包含您的軟體包所使用的Python版本，軟體包可用的許可證以及您的軟體包將使用的操作系統。有關分類器的完整列表，請參閱 https://pypi.org/classifiers/。

除了這裡提到的還有很多。有關詳細信息，請參閱打包和分發項目。

3 . 創建README.md

打開README.md並輸入以下內容。可以自定義此項，放入一些對項目的介紹。

# Example Package

This is a simple example package. You can use

[Github-flavored Markdown](https://guides.github.com/features/mastering-markdown/)

to write your content.

4 . 創建許可證

上傳到Python Package Index的每個包都包含許可證，這一點很重要。這告訴用戶安裝你的軟體包可以使用您的軟體包的條款。有關選擇許可證的幫助，請訪問https://choosealicense.com/。選擇許可證後，打開 LICENSE並輸入許可證文本。例如，如果您選擇了MIT許可證：

Copyright (c) 2018 The Python Packaging Authority Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

5 . 生成分發檔案

下一步是為包生成分發包。這些是上傳到包索引的檔案，可以通過pip安裝。

確保您擁有setuptools並wheel 安裝了最新版本：

python3 -m pip install --user --upgrade setuptools wheel

如果您在安裝它們時遇到問題，請參閱安裝包教程。

現在從setup.py位於的同一目錄運行此命令：

python3 setup.py sdist bdist_wheel

此命令應輸出大量文本，一旦完成，應在dist目錄中生成兩個文件：

dist/ example_pkg_your_username-0.0.1-py3-none-any.whl example_pkg_your_username-0.0.1.tar.gz

6 . 上傳 PYPI

最後，是時候將您的包上傳到Python Package Index了！

您需要做的第一件事是在Test PyPI上註冊一個帳戶。Test PyPI是用於測試和實驗的包索引的單獨實例。這對於像我們不一定想要上傳到真實索引的本教程那樣很棒。要註冊帳戶，請訪問

test.pypi.org

並完成該頁面上的步驟。在您上傳任何套餐之前，您還需要驗證您的電子郵件地址。有關Test PyPI的更多詳細信息，請參閱使用TestPyPI。

現在您已註冊，您可以使用twine上傳分發包。你需要安裝Twine：

python3 -m pip install --user --upgrade twine

安裝完成後，運行Twine以上傳所有存檔dist：

python3 -m twine upload --repository-url https://test.pypi.org/legacy/ dist/*

系統將提示您輸入使用Test PyPI註冊的用戶名和密碼。命令完成後，您應該看到與此類似的輸出：

Uploading distributions to https://test.pypi.org/legacy/ Enter your username: [your username] Enter your password: Uploading example_pkg_your_username-0.0.1-py3-none-any.whl 100%|█████████████████████| 4.65k/4.65k [00:01<00:00, 2.88kB/s] Uploading example_pkg_your_username-0.0.1.tar.gz 100%|█████████████████████| 4.25k/4.25k [00:01<00:00, 3.05kB/s]

上傳後，您的軟體包應該可以在TestPyPI上查看，例如，

https://test.pypi.org/project/example-pkg-your-username?

test.pypi.org

安裝新上傳的軟體包

您可以使用pip來安裝包並驗證它是否有效。創建一個新的virtualenv（請參閱安裝包以獲取詳細說明）並從TestPyPI安裝包：

python3 -m pip install --index-url https://test.pypi.org/simple/ --no-deps example-pkg-your-username

確保在包名中指定您的用戶名！

pip應該從Test PyPI安裝包，輸出應該如下所示：

Collecting example-pkg-your-username Downloading https://test-files.pythonhosted.org/packages/.../example-pkg-your-username-0.0.1-py3-none-any.whl Installing collected packages: example-pkg-your-username Successfully installed example-pkg-your-username-0.0.1

注意

此示例使用--index-urlflag指定TestPyPI而不是實時PyPI。另外，它指定--no-deps。由於TestPyPI與實時PyPI沒有相同的軟體包，因此嘗試安裝依賴項可能會失敗或安裝意外事件。雖然我們的示例包沒有任何依賴關係，但在使用TestPyPI時避免安裝依賴項是一種很好的做法。

您可以通過導入模塊並引用先前name放置的屬性來測試它是否已正確安裝__init__.py。

運行Python解釋器（確保你仍然在你的virtualenv中）：

python

然後導入模塊並列印出name屬性。這應該是一樣的，不管你的名字你給您的分發包中setup.py（在這種情況下，example-pkg-your-username），因為你的導入包是example_pkg。

>>> import example_pkg >>> example_pkg.name example_pkg

後續步驟

恭喜，您已經打包並分發了一個Python項目！ ????

請記住，本教程向您展示了如何將程序包上傳到Test PyPI，它不是永久存儲。測試系統偶爾會刪除軟體包和帳戶。如果您想將軟體包上傳到真正的Python軟體包索引，可以通過在https://pypi.org上註冊帳戶並按照相同的說明進行操作，但是，使用上傳軟體包並輸入您的帳戶憑據在真正的PyPI上註冊。您可以使用真正的PyPI安裝軟體包。twine uploaddist/*pip install [your-package]

在這一點上，如果你想閱讀更多關於包裝的Python庫，你可以做以下事情：