每個軟件開發員和數據科學家都難免要做程序包。本文推薦一篇Python開源程序包的製作指南,希望這個包含了具體操作步驟的指南能讓你在構建程序包時不用花那麼多耐心和時間。(適用於macOS系統的Python3.7版本)
嘗試著自己去構建美麗的東西吧!
第1步:制定計劃
我們的最終目的是製作一個很簡單的Python庫,它能夠讓用戶輕鬆地將Jupyter筆記本轉換為HTML文件或Python腳本。
程序包的第一個迭代可以讓用戶調用print語句的函數。
既然我們已經知道想做什麼了,接下來要給包命名。
第2步:命名
命名並不簡單。名字要取得獨特,簡短且好記,要全部都是小寫字母,絕對不能有破折號或其他標點符號,下劃線也不行。給包命名的時候,還需要在GitHub,Google 和PyPI上確認這個名字是否可用。
如果你對包期望很高,希望在某一天它在GitHub上會有10000顆星星,那你還得確認這個名字是否能用於社交網絡。在本文的示例中,我們把包命名為notebookc, 因為它能用於各種平臺,簡短而且有描述意義。
第3步:檢查配置
確保你安裝配置了Python3.7,GitHub和 Homebrew。需要的話,可以在下面下載:
Python
下載安裝Python3.7:https://www.python.org/downloads/
GitHub
免費註冊GitHub賬戶:https://github.com/join
安裝Git:https://help.github.com/articles/set-up-git/
Homebrew
Homebrew是Mac系統特有的程序包管理器。(安裝說明:https://brew.sh/)。
Venv
如果使用的是Python3.6版本,建議用venv來創建虛擬環境以構建程序包。用Python來管理虛擬環境的方法很多,可遵循的建議也有很多。
從Python3.3版本起,Python就自帶venv了,但要注意,從Python3.4的版本開始,venv才能在虛擬環境中安裝pip和setuptools。
用下列命令在Python3.7中創建虛擬環境:
python3.7-m venv my_env
用你喜歡的名字替換 my_env,激活虛擬環境:
sourcemy_env/bin/activate
現在可以在終端提示的最左端看到 (my_env) ,或者看到你給虛擬環境取的名字。
完成之後,使用deactivate停用虛擬環境。
之後,在GitHub上進行設置。
第4步:在GitHub上創建組織
GitHub在版本控制註冊上是市場領導者,其他的包括GitLab 和Bitbucket也很受歡迎。本指南中我們是用GitHub。
按照提示,在GitHub上創建一個新組織。我們將組織命名為notebooktoall。你可以在個人帳戶下創建知識庫(repository),但我們的目標之一是學習如何為更大的群體創建一個開源項目。
第5步:創建GitHub知識庫
創建一個新的知識庫。
從下拉列表中添加gitignore,為你的知識庫選擇Python。gitignore文件的內容與要從Git知識庫中剔除的文件夾和文件類型相匹配。你可以之後再修改gitignore以剔除其他不必要或敏感的文件。
建議從下拉列表的添加許可證(Add alicense)中選擇一個許可證,它決定了使用知識庫內容的用戶能做什麼。一些許可證會比較寬鬆,如果沒有選擇許可證,系統會採用默認的版權法。
本文的項目選的是通用公共許可證v3.0(GeneralPublic Licens v3.0 ),因為它用的廣泛,而且可以“保證終端用戶運行、學習、共享和修改軟件的自由”——來自維基百科。
第6步:複製和添加目錄
選擇要在本地複製知識庫的位置,然後按下面的說明運行:
複製git https://github.com/notebooktoall/notebookc.git
替代組織和知識庫。
使用桌面圖形用戶界面(GUI)或代碼編輯器進入項目文件夾,或者用cd my-project的命令行進入項目文件夾,然後用 ls—A查看文件。初始文件夾和文件如下:
.git
.gitignore
LICENSE
README.rst
為主項目文件創建一個子文件夾,建議子文件夾的命名與程序包的相同,並確認名稱不包含空格。
在子文件夾中創建一個名為 __init__.py的文件,這個文件可以先空著。將文件導入到子文件夾時,這個文件是必需的。
創建另一個與子文件夾同名的文件,並在文件名後添加.py。我的文件名是notebook .py。你可以按自己心意給這個Python文件命名。
現在notebookc目錄內容如下:
.git
.gitignore
LICENSE
README.rst
notebookc/__init__.py
notebookc/notebookc.py
第7步:創建和安裝requirements_dev.txt
在項目目錄頂端創建一個requirements_dev.txt文件。通常把這個文件命名為requirements.txt。這樣命名強調了這些程序包全部是開發員安裝的。
在requirements_dev.txt裡,要安裝特定版本的pip和wheel。
pip==19.0.3
wheel==0.33.1
注意,這裡用兩個等號以及版本號指明瞭應安裝的程序包的確切版本。
將特定版本的程序包安裝到requirements_dev.txt中。
如果合作開發員要分裂項目知識庫,用pip來安裝特定requirements_dev.txt程序包,就要用和你一樣版本的包。此外,在創建文件的時候,Read TheDocs可使用這個文件來安裝程序包。
在已經激活的虛擬環境中,使用以下命令將程序包安裝到requirements_dev.txt:
pipinstall -r requirements_dev.txt
第8步:代碼和提交
作為示例,我們先創建一個很簡單的函數。你可以之後再建一個很牛的函數。
在主文件中鍵入以下內容:
(我們要鍵入的是 notebookc/notebookc/notebookc.py)
def convert(my_name):
"""
Print a lineabout converting a notebook.
Args:
my_name(str): person's name
Returns:
None
"""
print(f"I'll convert a notebook for you some day, {my_name}.")
這就是我們建的函數啦。
文檔字符串(docstrings)以三個連續的雙引號開始並結束。在以後的文章中,它們會被用於自動創建文檔。
現在提交修改。
第9步:創建setup.py
setup.py文件是程序包的構建腳本文件。Setuptools的setup函數可構建要上傳到PyPI的程序包。Setuptools裡有程序包的信息,版本號以及用戶所需要的其他程序包的信息。
以下是本文的setup.py文件示例:
from setuptools import setup, find_packages
with open("README.md", "r") asreadme_file:
readme =readme_file.read()
requirements = ["ipython>=6","nbformat>=4", "nbconvert>=5","requests>=2"]
setup(
name="notebookc",
version="0.0.1",
author="Jeff Hale",
author_email="[email protected]",
description="A package to convert your Jupyter Notebook",
long_description=readme,
long_description_content_type="text/markdown",
url="https://github.com/your_package/homepage/",
packages=find_packages(),
install_requires=requirements,
classifiers=[
"Programming Language :: Python :: 3.7",
"License :: OSI Approved :: GNU General Public License v3(GPLv3)",
],
)
注意,long_description是README.md文件內容裡的。
在setuptools.setup.install_requiresincludes中指定的 requirements列表包括了程序包運作所需的所有依賴程序包。
與requirements_dev.txt開發所需的包不同,這個包列表應儘可能地寬鬆。
將install_requires的包列表限制在只能安裝需要的包,你肯定不想用戶安裝不必要的包。注意,只需要列出不屬於Python標準庫裡的包即可。如果用戶要用你的包的話,就必須要安裝Python。
這個包不需要任何外部依賴,因此你可以剔除上面列出的四個包。如果共同開發員要分裂項目知識庫,用pip安裝特定包的話,要用和你一樣版本的包。
將代碼提交到本地Git知識庫。現在萬事俱備,可以開始建程序包了!
第10步:構建首個版本
Twine是一個公用程序組,可以在PyPI上安全地發佈Python包。將Twine包添加到 requirements_dev.txt 的下一個空行中,如下所示:
twine==1.13.0
然後重新安裝requirements_dev.txt包以將Twine安裝到虛擬環境中。
pipinstall -r requirements_dev.txt
然後運行下列命令,創建包文件:
pythonsetup.py sdist bdist_wheel
過程中會創建許多隱藏的文件夾:dist, build等,我創建的是notebookc.egg-info。我們看下dist文件夾中的文件。.whl文件是Wheel文件,即創建的分佈。.tar.gz文件是源代碼壓縮文檔。
Wheel
在用戶的設備上,pip會像wheels一樣在任何可能的時候安裝程序包。Wheel在安裝的時候更快。當pip不能安裝wheel時,它就會回到源代碼壓縮文檔。
讓我們準備好上傳wheel和源代碼壓縮文檔吧。
第11步:創建TestPyPI帳號
PyPI是Python Package Index的縮寫,它是Python官方程序包管理器。pip可以從PyPI中抓取沒有在本地安裝的文件。
PyPI
TestPyPI是PyPI中運行的一個測試版本。注意,在測試站點上傳和在官方站點上傳的密碼是不同的。
創建TestPyPI帳戶:https://test.pypi.org/account/register/。
第12步:在TestPyPI上發佈
Twine
用Twine將你的程序包安全地發佈到TestPyPI上。鍵入下列命令——無需修改。
twineupload --repository-url https://test.pypi.org/legacy/ dist/*
系統會提示你輸入用戶名和密碼。記住,TestPyPI和PyPI 的密碼是不同的。
需要的話,就修正包的錯誤,在setup.py中創建新的版本號,刪除舊版本的build, dist和 egg 文件夾。用pythonsetup.py sdist bdist_wheel重建,用Twine重新上傳。在TestPyPI上的版本號沒什麼意義,這並不是大事,因為你是唯一用這些版本的包的人。
成功上傳程序包之後,確認它可以被安裝使用。
第13步:確認安裝和使用
在終端創建另一個標籤,並創建另一個虛擬環境。
python3.7-m venv my_env
激活它
source my_env/bin/activate
如果你已經將包上傳到PyPI 官方網站,接下來就要用pip安裝這個程序包。可以在PyPI檢索到該程序包,然後用修改過的命令安裝它。
從TestPyPI安裝程序包的官方指導如下:
可以通過— index-url flag命令pip在TestPyPI上下載安裝包,而不用在PyPI 上下載。
pip install--index-url https://test.pypi.org/simple/ my_package
如果你要允許pip在PyPI上下載其他的包,可以命令— extra-index-url指向PyPI。如果你測試的程序包有依賴包,這將會非常有用。
pipinstall --index-url https://test.pypi.org/simple/ --extra-index-urlhttps://pypi.org/simple my_package
如果你的程序包有包依賴,用上面提到的第二個命令,並替換你的程序包名稱。
你應該看一下安裝到虛擬環境的程序包的最新版本。
為了確認程序包可以使用,用python在終端啟動IPyon會話。
導入函數並用字符串參數調用函數。我的代碼如下:
fromnotebookc.notebookc import convert
convert(“Jeff”)
隨後可以看到下面的輸出:
I’llconvert a notebook for you some day, Jeff.
確認可以用了。
好了,現在把作品上傳到Git Hub吧。
第14步:上傳到GitHub
確保你的代碼已提交。
notebookc項目文件夾如下所示:
.git
.gitignore
LICENSE
README.md
requirements_dev.txt
setup.py
notebookc/__init__.py
notebookc/notebookc.py
剔除你不想上載的虛擬環境。在創建知識庫時選擇的Python的 .gitignore文件可使構件不被列入索引。
你可能需要刪除虛擬環境文件夾。
用git pushorigin my_branch.將本地分支傳到GitHub。
第15步:創建與合併PR
在瀏覽器中打開Github,可以看到拉入請求選項。長按綠色按鈕創建併合並你的PR,並刪除遠程特徵分支。
回到終端,使用gitbranch -d my_feature_branch刪除本地特徵分支。
回顧:製作程序包的15個步驟
1. 制定計劃
2. 命名
3. 檢查配置
4. 在GitHub上創建組織
5. 創建GitHub知識庫
6. 複製和添加目錄
7. 創建和安裝requirements_dev.txt
8. 代碼和提交
9. 創建 setup.py
10. 構建首個版本
11. 創建TestPyPI賬號
12. 在TestPyPI上發佈
13. 確認安裝和使用
14. 上傳到 GithHub
15. 創建與合併PR
閱讀更多 讀芯術 的文章