打包 python 項目
本教程將指導您介紹如何打包一個簡單的 python 項目。它將向您展示如何添加創建包所需的文件和結構, 如何生成包, 以及如何將其上載到 python 包索引。
一個簡單的項目
本教程使用一個名為的簡單項目。如果您不熟悉 python 的模塊和導入包, 請花幾分鍾時間閱讀python 文檔中的包和模塊。即使您已經有一個要打包的項目, 我們也建議您按照本教程進行操作, 同時使用此示例包, 然后嘗試使用您自己的包。example_pkg
若要在本地創建此項目, 請創建以下文件結構:
/packaging_tutorial
/example_pkg
__init__.py
創建此結構后, 您需要在頂級文件夾中運行本教程中的所有命令, 因此請務必這樣做。cd packaging_tutorial
您還應該編輯並將以下代碼放在其中:example_pkg/__init__.py
name = "example_pkg"
這只是為了讓您可以在本教程的稍后部分驗證它是否正確安裝。
創建包文件
現在, 您將創建一些文件來打包此項目並准備分發。創建下面列出的新文件-您將在以下步驟中向其中添加內容。
/packaging_tutorial
/example_pkg
__init__.py
setup.py
LICENSE
README.md
創建設置.
setup.py是設置工具的生成腳本。它告訴設置工具有關您的包 (如名稱和版本) 以及要包括哪些代碼文件。
打開並輸入以下內容。您應該更新包名稱以包括您的用戶名 (例如,。如果您希望:setup.pyexample-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 上使用。請務必使用您的用戶名更新此內容,因為這可確保您在上載包時不會遇到任何名稱沖突。_-version是軟件包版本, 請參閱 pep 440 有關版本的更多詳細信息。author並用於識別包裹的作者。author_emaildescription是一個簡短的, 一句話的總結包。long_description是包的詳細說明。這顯示在 python 包索引上的包詳細信息包中。在這種情況下, 加載長說明, 從這是一個常見的模式。README.mdlong_description_content_type告訴索引用於長描述的標記類型。在這種情況下, 是馬克當。url是項目主頁的 url。對於許多項目, 這只是一個指向 github、GitHub、bitwb 或類似代碼托管服務的鏈接。packages是應包含在分發包中的所有 python 導入包的列表。我們可以使用自動發現所有包和子包, 而不是手動列出每個包。在這種情況下, 包的列表將是示例 _ pkg , 因為這是唯一存在的包。find_packages()classifiers告訴索引, 並提供有關包的其他元數據。在這種情況下, 包只與 python 3 兼容, 是根據 mit 許可證授權的, 並且是獨立於 os 的。您應始終至少包括包的 python 版本、包可用的許可證以及包將使用的操作系統。有關分類器的完整列表, 請參閱https://pypi.org/classifiers/。
這里提到的還有更多的東西。有關詳細信息, 請參閱打包和分發項目 。
創建 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.
創建許可證
對於上載到 python 包索引的每個包都包含許可證非常重要。這將告知安裝您的軟件包的用戶可以使用您的軟件包的條款。有關選擇許可證的幫助, 請參閱https://choosealicense.com/。選擇許可證后, 打開並輸入許可證文本。例如, 如果您選擇了 mit 許可證:LICENSE
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.
生成分發存檔
下一步是為包生成分發包 。這些是上載到包索引的存檔, 可以通過點安裝。
請確保您擁有最新版本的:setuptoolswheel
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
注解
如果您在這里遇到麻煩, 請復制輸出並將包裝問題歸檔,我們將盡最大努力為您提供幫助!
該文件是源存檔 , 而該文件是生成的分發。較新的點版本優先安裝生成的發行版, 但如果需要, 將返回到源存檔。您應該始終上傳源存檔, 並為項目與之兼容的平台提供生成的存檔。在這種情況下, 我們的示例包在任何平台上都與 python 兼容, 因此只需要一個構建的分發。tar.gz.whl
上傳分發檔案
最后, 是時候將您的包上傳到 python 包索引了!
您需要做的第一件事是在測試 pypi上注冊一個帳戶。測試 pypi 是用於測試和實驗的包索引的一個單獨實例。這對於像本教程這樣的東西來說是很好的, 我們不一定想上傳到真正的索引。若要注冊帳戶, 請轉到 https://test.pypi.org/account/register/並完成該頁面上的步驟。您還需要先驗證您的電子郵件地址, 然后才能上傳任何軟件包。有關測試 pypi 的詳細信息, 請參閱使用 testypi。
現在您已經注冊, 您可以使用線上傳分發包。您需要安裝 twine:
python3 -m pip install --user --upgrade twine
安裝完成后, 運行 twine 上傳以下所有存檔:dist
python3 -m twine upload --repository-url https://test.pypi.org/legacy/ dist/*
系統將提示您輸入在測試 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
安裝新上傳的軟件包
您可以使用 pip 安裝您的包, 並驗證它是否有效。創建新的虛擬程序 (有關詳細說明, 請參閱安裝包 ), 並從 testpypi 安裝包:
python3 -m pip install --index-url https://test.pypi.org/simple/ 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
您可以通過導入模塊並引用前面輸入的屬性來測試它是否已正確安裝。name__init__.py
運行 python 解釋器 (確保您仍在虛擬化中):
python
然后導入模塊並打印出屬性。無論您在哪個名稱中為分發包 (在本例中為) 指定的內容 , 這都應該是相同的, 因為您的導入包是相同的。namesetup.pyexample-pkg-your-usernameexample_pkg
>>> import example_pkg >>> example_pkg.name 'example_pkg'
后續步驟
恭喜您, 您已經打包並分發了一個 python 項目!
請記住, 本教程向您展示了如何將包上載到 test pypi, 這不是永久存儲。測試系統偶爾會刪除包和帳戶。如果您想將您的包上傳到真正的 python 包索引, 您可以通過注冊 https://pypi.org 上的帳戶並遵循相同的說明來完成, 但是, 使用它來上傳您的包並輸入您的帳戶的憑據注冊在真正的 pypi。您可以使用真正的 pypi 安裝您的軟件包。twine upload dist/*pip install [your-package]
在這一點上, 如果你想閱讀更多關於打包 python 庫, 這里有一些你可以做的事情: