假設(shè)你很喜歡用同一段Python代碼，里面有幾個(gè)相關(guān)的小型函數(shù)，或者是含有幾百行代碼的中型模塊。程序員可能會(huì)把它復(fù)制到不同的項(xiàng)目或存儲(chǔ)庫(kù)中，或者從特別設(shè)置的實(shí)用工具代碼文件夾中導(dǎo)入這段代碼。

[[278378]]

這很正常。程序員在編寫代碼的過程中都會(huì)不斷積累這些個(gè)性化的小工具。相比其他編程語言來說，Python更容易積累這些語句——這些代碼非常實(shí)用。

如果無需復(fù)制，就可以輕松導(dǎo)入自己開發(fā)的小工具，并進(jìn)行更新和維護(hù)，豈不是更好嗎?如果不依賴于特定的文件或路徑，讓這些代碼在不同的環(huán)境、機(jī)器和語境中都適用?如果可以將這些個(gè)性化工具版本化，并使相關(guān)代碼清楚地反映出其依賴性呢?如果這個(gè)工具能為大眾所用呢?

沒錯(cuò)，它都可以做到。

當(dāng)然，這個(gè)概念不是第一次提了。這就是通常在編程語言中使用模塊、包和庫(kù)的原因，特別是在Python的開發(fā)環(huán)境中。它的實(shí)現(xiàn)可使Python功能更加強(qiáng)大;只需簡(jiǎn)單的pip install 和 import就能獲得BeautifulSoup的html解析功能或pandas的數(shù)據(jù)幀處理功能。

另外，人人都可以將自己的代碼在PyPI上編寫和發(fā)布(PyPI是Python包的官方索引：http://pypi.python.org/pypi)，使它們與sklearn、requests或delorean(都是非常實(shí)用、流行的Python包)一樣簡(jiǎn)單易得。以下是它的幾點(diǎn)優(yōu)勢(shì):

• 即使只有很少人使用，共享自己的代碼仍是一件很有趣的事;程序員可以在工作、社群活動(dòng)或求職面試中分享并展示自己的勞動(dòng)成果。
• 通過強(qiáng)制性地整理和記錄代碼，公開給同行進(jìn)行評(píng)價(jià)，從而改進(jìn)代碼。
• 它還能彌補(bǔ)社群的不足。你會(huì)驚訝地發(fā)現(xiàn)，很多人會(huì)注意到你的序列化十分高效，比如將HTTP報(bào)頭序列化到JSON?；蛘甙l(fā)現(xiàn)自己創(chuàng)建的用來驗(yàn)證輸入MongoDB查詢文檔修飾符的工具有多么實(shí)用。

心動(dòng)了嗎?忘記那個(gè)舊的Python模塊，開始制作小型Python包吧。

步驟一：命名

首先是命名。好的名字通常比較簡(jiǎn)短，便于在pip install 或 import 完成之后輸入(盡管現(xiàn)在已經(jīng)出現(xiàn)了“自動(dòng)輸入”);還要包含足夠的信息便于理解，或者在安裝完成后之后提示其中的內(nèi)容。

requests負(fù)責(zé)處理HTTP請(qǐng)求、delorean負(fù)責(zé)日期和時(shí)間，sklearn負(fù)責(zé)提供機(jī)器學(xué)習(xí)框架，這些都是很好的例子。在為pandas管道包(由于pandas 通常以pd這樣較短別名導(dǎo)入，故使用pdpipe：https://github.com/shaypal5/pdpipe)和緩存包(cachier：https://github.com/shaypal5/cachier)命名時(shí)，筆者也嘗試過這些例子。

不過老實(shí)說，這些并不是固守的規(guī)則。流行的Python包都有pandas、 keras、 django、 boto、 jinja、 flask 和 pytorch等名稱，大家能記住這些名字，所以讀者也可以使用任何簡(jiǎn)短且可讀的名稱(例如，由于可讀性問題，筆者將“Scikit-Learn Wrappers for FastText”縮寫成了skift)。本文以chocobo為例。

步驟二：確定代碼包的基本結(jié)構(gòu)

接下來，通過幾個(gè)簡(jiǎn)短的步驟，制作一種通用的結(jié)構(gòu):

1.用代碼包的準(zhǔn)確名稱創(chuàng)建一個(gè)Github存儲(chǔ)庫(kù)，不要使用駝峰式或過多的個(gè)人發(fā)揮。然后在本地進(jìn)行復(fù)制。

2.在該存儲(chǔ)庫(kù)中新建一個(gè)文件夾，用代碼包的準(zhǔn)確名稱命名;這就是保存代碼包的文件夾。這是一種規(guī)范，只需記住外部的chocobo 文件夾(在本例中)就是存儲(chǔ)庫(kù)的文件夾，而內(nèi)部的chocobo 文件夾是包的文件夾。

3.將自己的模塊和涉及到的任何其他模塊放在內(nèi)部的chocobo文件夾中。如果存在缺失的部分，請(qǐng)?zhí)砑觃_init__.py 文件。

4.將用戶直接調(diào)用的重要對(duì)象(通常是函數(shù))從各自的模塊中導(dǎo)入至__init__.py文件。有了代碼包的命名空間，就可以使用這些函數(shù)、分類和變量了。如果愿意，也可以使用代碼包的API。

5.雖然不是強(qiáng)制規(guī)定，筆者強(qiáng)烈建議在代碼包或在存儲(chǔ)庫(kù)的根目錄中都應(yīng)包含一個(gè) .gitignore 文件。

示例：https://github.com/github/gitignore/blob/master/Python.gitignore

現(xiàn)在有了一個(gè)結(jié)構(gòu)，可以添加不同類型的文件組成代碼包;內(nèi)部文件夾保存的是包的代碼，外部文件夾保存的是輔助包文件和其他與存儲(chǔ)庫(kù)相關(guān)的文件。

因此，初始模塊chocobo.py如下所示:

"""My chocobo cooking script.""" 
import os 
def chocobo_roast(num_guests, hotness_level): 
 # amazing python code here 

新建存儲(chǔ)庫(kù)文件夾如下所示:

chocobo/ 
 chocobo/ 
 __init__.py 
 chocobo.py 
 .gitignore 

__init__.py 文件應(yīng)如下所示：

"""chocobo is a python package for delicious Chocobo recipes.""" 
from .chocobo import ( 
 chocobo_roast, 
) 

那么在完成封裝之后，chocobo包可以有這樣的使用方法:

"""I'm a script or a different package using chocobo.""" 
import chococbo 
def my_feast(num_guests): 
 snacks = bobbish() 
 main_course = chocobo.chocobo_roast(num_guests, 0) 
 dressing = szechuan_chicken_mcnugget_sauce() 

以上就是一些要點(diǎn)。

步驟三：許可問題

使用共享許可發(fā)布代碼是較為可取的;如果要將自己的代碼公開分享，程序員會(huì)想要在保留版權(quán)的前提下得到重用代碼的許可，或者讓那些擴(kuò)展自己代碼的人保證衍生代碼可以自由使用。獲得許可能輕松解決這些問題。

對(duì)于無足輕重的小項(xiàng)目，可以考慮MIT許可(https://choosealicense.com/licenses/mit/)。choosealicense.com(https://choosealicense.com/)提供了很多GitHub和開源社區(qū)中的實(shí)用建議。

無論選擇哪種許可，都比根本不用要好。很多時(shí)候，在沒有許可的情況下公開代碼還不如不公開;如果程序員不明確自己對(duì)代碼的所有權(quán)，大多數(shù)公司會(huì)因?yàn)榭赡茉斐傻姆杉m紛而放棄，從而失去許多潛在用戶。

選擇許可后，在存儲(chǔ)庫(kù)中創(chuàng)建LICENSE許可文件(不需要文件擴(kuò)展名)，并導(dǎo)入所選許可的確切文本。

步驟四：安裝文件

現(xiàn)在創(chuàng)建Python封裝工具所需的基本文件(以setuptools為例);setup.py.setup.py 包含了構(gòu)建和發(fā)行時(shí)使用的實(shí)際指令。

下面是一個(gè)初始模板(別擔(dān)心，稍后會(huì)進(jìn)行詳細(xì)檢查)

"""Setup for the chocobo package.""" 
import setuptools 
with open('README.md') as f: 
 README = f.read() 
setuptools.setup( 
 author="Shay Palachy", 
 author_email="shay.palachy@gmail.com", 
 name='chocobo', 
 license="MIT", 
 description='chocobo is a python package for delicious chocobo recipes.', 
 version='v0.0.3', 
 long_description=README, 
 url='https://github.com/shaypal5/chocobo', 
 packages=setuptools.find_packages(), 
 python_requires=">=3.5", 
 install_requires=['requests'], 
 classifiers=[ 
 # Trove classifiers 
 # (https://pypi.python.org/pypi?%3Aaction=list_classifiers) 
 'Development Status :: 4 - Beta', 
 'License :: OSI Approved :: MIT License', 
 'Programming Language :: Python', 
 'Programming Language :: Python :: 3.5', 
 'Programming Language :: Python :: 3.6', 
 'Topic :: Software Development :: Libraries', 
 'Topic :: Software Development :: Libraries :: Python Modules', 
 'Intended Audience :: Developers', 
 ], 
) 

首先，導(dǎo)入setuptools。這是一個(gè)非常有用代碼包，可輕松對(duì)Python包進(jìn)行發(fā)行，即使它不包括在標(biāo)準(zhǔn)庫(kù)中(類似的distutils是比不了的)，它仍然是當(dāng)今Python包發(fā)行的標(biāo)準(zhǔn)，應(yīng)該牢記于心。本文只使用了setuptools包中的兩個(gè)函數(shù):setup和find_packagges。

在導(dǎo)入setuptools之后，調(diào)用setup()函數(shù)之前，只需將README.md 文件的內(nèi)容讀入到全局變量 README中即可。

然后只需通過以下變量調(diào)用setuptools.setup() 函數(shù)即可:

• author:輸入姓名。
• author_email:輸入郵箱。
• name:代碼包的名稱，在本例中為“chocobo”。
• license:在本例中為字符串“MIT”，或選擇其他許可證。
• description:代碼包的簡(jiǎn)短介紹，控制在一行以內(nèi)。例如：“chocobo代碼包是制作美味chocobo的食譜”
• version:表示封裝的當(dāng)前版本的字符串。筆者在之后的文章中會(huì)介紹更簡(jiǎn)潔的處理方法，但是目前，只需要在想要發(fā)布新版本時(shí)手動(dòng)增加一個(gè)數(shù)字就可以了。通常的做法是將版本號(hào)前加入字母V，因此v1是第一個(gè)版本的版本字符串，但筆者建議將v0.0.1 視為等效版本字符串并使用此格式。后文將詳細(xì)介紹這種做法的意義。
• long_description:表示README的內(nèi)容。該部分是代碼包的詳細(xì)描述。也就是該頁(yè)面PyPI的內(nèi)容(示例：https://pypi.org/project/pdpipe/)。
• url:可鏈接到代碼包的主頁(yè)。如果讀者沒有專用的站點(diǎn)，那么存儲(chǔ)庫(kù)的URL是一個(gè)不錯(cuò)的選擇。
• packages: 又一次提到了setuptools!根據(jù)命令，這個(gè)參數(shù)獲取要生成和發(fā)行/安裝的所有代碼包的名稱數(shù)組。從技術(shù)上講，可以直接使用[“chocobo”]這個(gè)名字，但是最好是將其通用化，并使用setuptools 函數(shù)，它能處理更復(fù)雜的包和存儲(chǔ)庫(kù)結(jié)構(gòu)。有兩個(gè)可選參數(shù)可以作為輸入數(shù)據(jù)，where 和exclude，但在這里忽略不計(jì)。作為結(jié)果，where可鏈接至安裝文件所在的目錄，包括所有子目錄，一般來說這樣已經(jīng)足夠了。
• python_requires: 如果你的電腦支持Python的所有版本，就不必顧及此參數(shù)。如果不能，應(yīng)該選擇一個(gè)適當(dāng)?shù)闹怠募夹g(shù)上講，筆者不贊成使用未經(jīng)測(cè)試的版本，但保險(xiǎn)期間目前我們可以進(jìn)行適當(dāng)?shù)募僭O(shè)：

(1) 如果讀者正在使用Python2，特別是Python2.7版本，可以得出以下兩點(diǎn)結(jié)論：(a)你獨(dú)樹一幟，十分優(yōu)秀(b)你的電腦配置只需支持Python2.7即可，所以可以使用“>=2.7”這個(gè)字符來編輯這個(gè)參數(shù)。另外，時(shí)代在進(jìn)步，試試Python3吧。

(2) 如果讀者使用的是Python3，那么任何Python版本都大于或等于用來開發(fā)代碼包的版本。以此類推，如果使用的是Python3.5，那么應(yīng)該設(shè)置成“>=3.5”。

• install_requires: 此處列出的是所有非標(biāo)準(zhǔn)庫(kù)代碼包的使用前提。例如，如果chocobo 需要requests和 pytz 才能運(yùn)行的話，那么該參數(shù)應(yīng)設(shè)置為:[“ requests”，“pytz”]。
• classifiers: 連同其他成千上萬個(gè)代碼包一起，你的代碼包也會(huì)很快PyPI上線。為了進(jìn)行區(qū)分，作者可以向PyPI提供一個(gè)列表，列出trove分類器來對(duì)每個(gè)版本進(jìn)行分類，描述其用途、支持的系統(tǒng)和開發(fā)進(jìn)度。然后，社區(qū)成員可以使用這些標(biāo)準(zhǔn)化的分類器，根據(jù)自己的需求來查找項(xiàng)目(盡管不確定誰會(huì)進(jìn)行這項(xiàng)操作)。

這里有所有可能用到的分類器：https://pypi.python.org/pypi?%3Aaction=list_classifiers

建議從以下幾個(gè)開始：

• “Development Status :: 3 — Alpha”
• “License :: OSI Approved :: MIT License”
• “ Programming Language :: Python”
• “ Programming Language :: Python :: 3.5”
• “ Programming Language :: Python :: 3.6”
• “ Programming Language :: Python :: 3.7”
• “Topic :: Software Development :: Libraries”
• “Topic :: Software Development :: Libraries :: Python Modules”
• “Intended Audience :: Developers”

以上就是這一環(huán)節(jié)的全部?jī)?nèi)容。

[[278379]]

步驟五：建立發(fā)行文件

Python包位于發(fā)行文件中，這些文件會(huì)統(tǒng)一被上傳到一個(gè)服務(wù)器中(通常是PyPI全局服務(wù)器)，供公眾下載。

本文不會(huì)詳細(xì)介紹發(fā)行格式。筆者將使用標(biāo)準(zhǔn)方法(https://packaging.python.org/tutorials/packaging-projects/)構(gòu)建兩個(gè)文件：源發(fā)行文件(基本上包含了代碼包)和wheel發(fā)行文件(wheel build distribution file)。

首先，確保安裝了最新版本的setuptools 以及 wheel：

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

要構(gòu)建發(fā)行文件，只需在setup.py所在的存儲(chǔ)庫(kù)的根目錄中運(yùn)行以下命令:

python setup.py sdist bdist_wheel

在這一步，需要Python運(yùn)行setup.py這個(gè)腳本，并向它發(fā)送兩個(gè)參數(shù)，生成源文件(參數(shù)sdist)，以及wheel工具來構(gòu)建發(fā)行文件(參數(shù)bdist_wheel)。

運(yùn)行此命令時(shí)，將在調(diào)用目錄中創(chuàng)建三個(gè)文件夾: build, dist 和 chocobo.egg-info。對(duì)于.gitignore 文件來說，這三個(gè)可以忽略不計(jì)。如果這些目錄已經(jīng)存在(例如，該命令之前已經(jīng)運(yùn)行過了，最好用rm -rf build dist將這些目錄刪除掉，因?yàn)閐ist 下的任何有效代碼包文件都將被上傳。

要上傳的兩個(gè)文件位于dist 文件夾中:分別為chocobo-0.0.3-py-none.any.whl (構(gòu)建發(fā)行;是一個(gè)wheel 文件)和chocobo-0.0.3.tar.gz (源發(fā)行;是一個(gè)壓縮的tar 文件)。創(chuàng)建成功后，我們繼續(xù)上傳的步驟!

步驟六：上傳

剩下的步驟就是將代碼包上傳到PyPI全局服務(wù)器!然而，用戶必須先在PyPI網(wǎng)站上注冊(cè)。按照注冊(cè)的步驟填寫用戶名和密碼。

如果想在上傳到PyPI全局服務(wù)器之前測(cè)試包，程序員也可以在測(cè)試PyPI網(wǎng)站上注冊(cè)一個(gè)用戶。

現(xiàn)在，用于上傳的Python包將在.pypirc文本文件中查找PyPI用戶名和密碼(通過PyPI服務(wù)器進(jìn)行驗(yàn)證)，該文件通常位于主文件夾中。創(chuàng)建后按如下所示進(jìn)行填寫(testpypi 部分視具體情況而定):

[distutils] 
index-servers = 
 pypi 
 testpypi 
[pypi] 
username: teapot48 
password: myPYPIpassword 
[testpypi] 
repository: https://test.pypi.org/legacy/ 
username: teapot48 
password: MYtestPYPIpassword 

本文依照最新的方法將文件上傳到PyPI服務(wù)器中，并使用twine(上傳Python包的實(shí)用工具)，而不是使用過時(shí)的python setup.py upload 。只需運(yùn)行:

twine upload dist/*

如果想在PyPI服務(wù)器上進(jìn)行測(cè)試，只需運(yùn)行 twine upload — repository testpypi dist/*

不論如何，上傳.whl 文件時(shí)都應(yīng)該能看到一個(gè)進(jìn)度條，上傳.tar.gz 文檔時(shí)應(yīng)該也能看到一個(gè)進(jìn)度條，然后上傳就完成了。

現(xiàn)在可以在PyPI官方網(wǎng)站上看到自己的Python包頁(yè)面了，大家也都能看到!

示例：https://pypi.org/project/birch/

大功告成!