Packaging Python Projects¶
本教程將指導您如何打包一個簡單的Python項目。它將向您展示如何添加必要的文件和結構來創建包，如何構建包以及如何將其上載到Python包索引。
A simple project
本教程使用名為example_pkg的簡單項目。如果您不熟悉Python的模塊和導入包，請花幾分鍾時間閱讀包含文件包和模塊的Python文檔。即使您已經有一個要打包的項目，我們仍然建議您按照本示例包使用此示例包，然后嘗試使用自己的包。 要在本地創建此項目，請創建以下文件結構：
/packaging_tutorial
/example_pkg
__init__.py
創建此結構后，您將需要在頂級文件夾中運行本教程中的所有命令 - 因此請務必使用cd packaging_tutorial。 您還應該編輯example_pkg / __ init__.py並將以下代碼放在其中：
name = "example_pkg"
這只是為了讓您可以在本教程后面驗證它是否正確安裝，並且PyPI不會使用它。
Creating the package files
您現在將創建一些文件來打包此項目並准備分發。創建下面列出的新文件 - 您將在以下步驟中向其添加內容。
/packaging_tutorial
/example_pkg
__init__.py
setup.py
LICENSE
README.md
Creating 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="author@example.com", 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上使用。請務必使用您的用戶名更新此內容，因為這樣可確保您不會嘗試上傳與上傳程序包時已存在的程序包相同的程序包。 版本是包版本，請參閱PEP 440以獲取有關版本的更多詳細信息。 author和author_email用於標識包的作者。 描述是包的簡短的一句話摘要。 long_description是包的詳細描述。這顯示在Python Package Index的包詳細信息包中。在這種情況下，從README.md加載長描述，這是一種常見模式。 long_description_content_type告訴索引用於長描述的標記類型。在這種情況下，它是Markdown。 url是項目主頁的URL。對於許多項目，這只是一個指向GitHub，GitLab，Bitbucket或類似代碼托管服務的鏈接。 packages是應包含在分發包中的所有Python導入包的列表。我們可以使用find_packages（）自動發現所有包和子包，而不是手動列出每個包。在這種情況下，包列表將是example_pkg，因為它是唯一存在的包。 分類器為索引提供一些關於包的其他元數據。在這種情況下，該軟件包僅與Python 3兼容，根據MIT許可證進行許可，並且與操作系統無關。您應始終至少包含您的軟件包所使用的Python版本，軟件包可用的許可證以及您的軟件包將使用的操作系統。有關分類器的完整列表，請參閱https://pypi.org/classifiers/。 除了這里提到的還有很多。有關詳細信息，請參閱打包和分發項目。
Creating 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.
Creating a LICENSE
上傳到Python Package Index的每個包都包含許可證，這一點很重要。這告訴用戶安裝您的軟件包可以使用您的軟件包的條款。有關選擇許可證的幫助，請訪問：http：//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.
生成分發檔案
下一步是為包生成分發包。這些是上傳到包索引的檔案，可以通過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
Note
如果您遇到麻煩，請復制輸出並提出有關包裝問題的問題，我們會盡力為您提供幫助！
tar.gz文件是源存檔，而.whl文件是構建的分發。較新的pip版本優先安裝構建的發行版，但如果需要，將回退到源代碼存檔。您應該始終上傳源存檔並為項目兼容的平台提供構建的存檔。在這種情況下，我們的示例包在任何平台上都與Python兼容，因此只需要一個構建的發行版。
Uploading the distribution archives
最后，是時候將您的包上傳到Python Package Index了！ 您需要做的第一件事是在Test PyPI上注冊一個帳戶。 Test PyPI是用於測試和實驗的包索引的單獨實例。這對於像我們不一定想要上傳到真實索引的本教程這樣的東西很棒。要注冊帳戶，請訪問https://test.pypi.org/account/register/並完成該頁面上的步驟。在您上傳任何套餐之前，您還需要驗證您的電子郵件地址。有關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上查看，例如
Installing your newly uploaded package
您可以使用pip來安裝包並驗證它是否有效。創建一個新的virtualenv（請參閱安裝包以獲取詳細說明）並從TestPyPI安裝包：
python3 -m pip install --index-url https://test.pypi.org/simple/ --no-deps example-pkg-your-username
Make sure to specify your username in the package name
確保在包名中指定您的用戶名！ 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
Note
此示例使用--index-url標志指定TestPyPI而不是實時PyPI。另外，它指定--no-deps。由於TestPyPI與實時PyPI沒有相同的包，因此嘗試安裝依賴項可能會失敗或安裝意外的事情。雖然我們的示例包沒有任何依賴關系，但在使用TestPyPI時避免安裝依賴項是一種很好的做法。
您可以通過導入模塊並引用之前放在__init__.py中的name屬性來測試它是否已正確安裝。
運行Python解釋器（確保你仍然在你的virtualenv中）：
python
然后導入模塊並打印出name屬性。無論您在setup.py中給出的分發包名稱是什么（在本例中為example-pkg-your-username），這都應該是相同的，因為您的import包是example_pkg。
>>> import example_pkg >>> example_pkg.name 'example_pkg'
Next steps
Congratulations, you’ve packaged and distributed a Python project! ✨ 🍰 ✨
請記住，本教程向您展示了如何將程序包上傳到Test PyPI，它不是永久存儲。測試系統偶爾會刪除軟件包和帳戶。最好使用Test PyPI進行測試和實驗，如本教程。
當您准備將真實包上傳到Python包索引時，您可以像在本教程中那樣執行相同操作，但具有以下重要差異：
-
為您的包裝選擇一個令人難忘的獨特名稱。您不必像在教程中那樣附加用戶名。 在https://pypi.org上注冊一個帳戶 - 請注意，這些是兩個獨立的服務器，並且測試服務器的登錄詳細信息不與主服務器共享。 使用twine upload dist / *上傳您的包並輸入您在真實PyPI上注冊的帳戶的憑據。 使用pip install [your-package]從真實的PyPI安裝包。 - 在這一點上，如果你想閱讀更多關於包裝的Python庫，你可以做以下事情：
- 閱讀有關使用setuptools在打包和分發項目中打包庫的更多信息。
- 閱讀包裝二進制擴展。
- 考慮諸如flit，hatch和poetry之類的setuptools的替代方案。