全面學習 Python 包:包的構建與分發

語言: CN / TW / HK

點選上方“ 濤哥聊Python ”,選擇“星標”公眾號

重磅乾貨,第一時間送達

1. 為什麼需要對專案分發打包?

平常我們習慣了使用 pip 來安裝一些第三方模組,這個安裝過程之所以簡單,是因為模組開發者為我們默默地為我們做了所有繁雜的工作,而這個過程就是 打包

打包,就是將你的原始碼進一步封裝,並且將所有的專案部署工作都事先安排好,這樣使用者拿到後即裝即用,不用再操心如何部署的問題(如果你不想對照著一堆部署文件手工操作的話)。

不管你是在工作中,還是業餘準備自己寫一個可以上傳到 PyPI 的專案,你都要學會如何打包你的專案。

Python 發展了這麼些年了,專案打包工具也已經很成熟了。他們都有哪些呢?

你可能聽過 disutils 、  distutilsdistutils2setuptools 等等,好像很熟悉,卻又很陌生,他們都是什麼關係呢?

2. 包分發的始祖:distutils

distutils 是 Python 的一個標準庫,從命名上很容易看出它是一個分發(distribute)工具(utlis),它是 Python 官方開發的一個分發打包工具,所有後續的打包工具,全部都是基於它進行開發的。

distutils 的精髓在於編寫 setup.py,它是模組分發與安裝的指導檔案。

那麼如何編寫 setup.py 呢?這裡面的內容非常多,我會在後面進行詳細的解析,請你耐心往下看。

你有可能沒寫過 setup.py ,但你絕對使用過 setup.py 來做一些事情,比如下面這條命令,我們經常用它來進行模組的安裝。

$ python setup.py install

這樣的安裝方法是通過原始碼安裝,與之對應的是通過二進位制軟體包的安裝,同樣我也會在後面進行介紹。

3. 分發工具升級:setuptools

setuptools 是 distutils 增強版,不包括在標準庫中。其擴充套件了很多功能,能夠幫助開發者更好的建立和分發 Python 包。大部分 Python 使用者都會使用更先進的 setuptools 模組。

distribute,或許你在其他地方也見過它,這裡也提一下。

distribute 是 setuptools 有一個分支版本,分支的原因可能是有一部分開發者認為 setuptools 開發太慢了。但現在,distribute 又合併回了 setuptools 中。因此,我們可以認為它們是同一個東西。

還有一個大包分發工具是 distutils2 ,其試圖嘗試充分利用distutils,detuptools 和 distribute 併成為 Python 標準庫中的標準工具。但該計劃並沒有達到預期的目的,且已經是一個廢棄的專案。

因此,setuptools 是一個優秀的,可靠的 Python 包安裝與分發工具。

那麼如何在一個乾淨的環境中安裝 setuptools 呢?

主要有兩種方法:

原始碼安裝:在 https://pypi.org/project/setuptools/#files 中下載 zip 包 解壓執行  python setup.py install 安裝 通過載入程式安裝:下載載入程式,它可以用來下載或者更新最新版本的 setuptools

$ wget http://peak.telecommunity.com/dist/ez_setup.py


# 安裝

$ python ez_setup.py


# 更新,以下兩種任選

$ python ez_setup.py U setuptools

$ pip install -U setuptools

4. easy_install 使用指南

當你安裝完 setuptools 後,就擁有了一個叫做 easy_install 的第三方管理工具,這也是它區分於 distutils 的一大改進。

這裡簡單介紹一下它的用法,雖然它已經用得非常少了。

先是包的安裝

# 通過包名,從PyPI尋找最新版本,自動下載、編譯、安裝

$ easy_install pkg_name


# 通過包名從指定下載頁尋找連結來安裝或升級包

$ easy_install -f http://pythonpaste.org/package_index.html


# 指定線上的包地址安裝

$ easy_install http://example.com/path/to/MyPackage-1.2.3.tgz


# 從本地的 .egg 檔案安裝

$ easy_install xxx.egg


# 在安裝時你可以新增額外的引數

指定安裝目錄:--install-dir=DIR, -d DIR

指定使用者安裝:--user

再者是包的升級

# 從 pypi 中搜索並升級包

$ easy_install --upgrade pkg_name


# 指定版本進行升級

$ easy_install "SomePackage==2.0"

最後是包的刪除

$ easy_install -m pkg_name

需要注意的是,這樣的刪除,僅是在 easy-install.pth 檔案中刪除,使其不能在 python 中使用 這個模組,但實際的包還在你的電腦中,若要刪除徹底,需要你手動刪除相關的 .egg 及 其他檔案。

預設情況下,easy_install 只會從 pypi 上下載相關軟體包,由於這個源在國外,下載包的速度並不理想,使用過pip的朋友自然會想,easy_install 是否能指定源進行安裝呢?

答案是,可以的。

編輯配置檔案 /root/.pydistutils.cfg

[easy_install]

index-url=http://mirrors.aliyun.com/pypi/simple/

find-links=http://mirrors.aliyun.com/pypi/simple/

以上僅介紹了 easy_install 的一些常用的方法,想要了解更多,你可以點選官方文件: https://setuptools.readthedocs.io/en/latest/easy_install.html

總結一句:setuptools 是官方提供的一個專業用於包分發的工具,若只從安裝的角度來看,它的功能確實簡單。它更大的意義是對包的分發很有用,定製化程式非常高,我們現在也還在用它進行版本包的釋出。

5. 原始碼包與二進位制包什麼區別?

Python 包的分發可以分為兩種:

1. 以原始碼包的方式釋出

原始碼包安裝的過程,是先解壓,再編譯,最後才安裝,所以它是跨平臺的,由於每次安裝都要進行編譯,相對二進包安裝方式來說安裝速度較慢。

原始碼包的本質是一個壓縮包,其常見的格式有:

格式 字尾
zip .zip
gztar .tar.gz
bztar .tar.bz2
ztar .tar.Z
tar .tar

1. 以二進位制包形式釋出

二進位制包的安裝過程省去了編譯的過程,直接進行解壓安裝,所以安裝速度較原始碼包來說更快。

由於不同平臺的編譯出來的包無法通用,所以在釋出時,需事先編譯好多個平臺的包。

二進位制包的常見格式有:

格式 字尾
egg .egg
wheel .whl

6. eggs 與 wheels 有什麼區別?

Egg 格式是由 setuptools 在 2004 年引入,而 Wheel 格式是由 PEP427 在 2012 年定義。Wheel 的出現是為了替代 Egg,它的本質是一個zip包,其現在被認為是 Python 的二進位制包的標準格式。

以下是 Wheel 和 Egg 的主要區別:

Wheel 有一個官方的 PEP427 來定義,而 Egg 沒有 PEP 定義 Wheel 是一種分發格式,即打包格式。而 Egg 既是一種分發格式,也是一種執行時安裝的格式,並且是可以被直接 import Wheel 檔案不會包含 .pyc 檔案 Wheel 使用和 PEP376 相容的 .dist-info 目錄,而 Egg 使用 .egg-info 目錄 Wheel 有著更豐富的命名規則。 Wheel 是有版本的。每個 Wheel 檔案都包含 wheel 規範的版本和打包的實現 Wheel 在內部被 sysconfig path type 管理,因此轉向其他格式也更容易

wheel 包可以通過 pip 來安裝,只不過需要先安裝 wheel 模組,然後再使用 pip 的命令。

$ pip install wheel

$ pip wheel --wheel-dir=/local/wheels pkg

7. 超詳細講解 setup.py 的編寫?

打包分發最關鍵的一步是編寫 setup.py 檔案。

以下是一個 setup.py 簡單的使用示例

from setuptools import setup, find_packages


setup(

name="mytest",

version="1.0",

author="wangbm",

author_email="[email protected]",

description="Learn to Pack Python Module -->公眾號:Python程式設計時光",


# 專案主頁

url="http://python-online.cn/",


# 你要安裝的包,通過 setuptools.find_packages 找到當前目錄下有哪些包

packages=find_packages()

)

接下來,我將慢慢擴充這個setup函式,增加更多的引數,以便你能理解setup函式能做哪些事情。

程式分類資訊

classifiers 引數說明包的分類資訊。所有支援的分類列表見:https://pypi.org/pypi?%3Aaction=list_classifiers

示例:

from setuptools import setup, find_packages


setup(

classifiers = [

# 發展時期,常見的如下

# 3 - Alpha

# 4 - Beta

# 5 - Production/Stable

'Development Status :: 3 - Alpha',


# 開發的目標使用者

'Intended Audience :: Developers',


# 屬於什麼型別

'Topic :: Software Development :: Build Tools',


# 許可證資訊

'License :: OSI Approved :: MIT License',


# 目標 Python 版本

'Programming Language :: Python :: 2',

'Programming Language :: Python :: 2.7',

'Programming Language :: Python :: 3',

'Programming Language :: Python :: 3.3',

'Programming Language :: Python :: 3.4',

'Programming Language :: Python :: 3.5',

]

)

關於檔案的分發

from setuptools import setup, find_packages



setup(

name="mytest",

version="1.0",

author="wangbm",

author_email="[email protected]",

description="Learn to Pack Python Module",

url="http://python-online.cn/",

packages=find_packages(),


# 安裝過程中,需要安裝的靜態檔案,如配置檔案、service檔案、圖片等

data_files=[

('', ['conf/*.conf']),

('/usr/lib/systemd/system/', ['bin/*.service']),

],


# 希望被打包的檔案

package_data={

'':['*.txt'],

'bandwidth_reporter':['*.txt']

},

# 不打包某些檔案

exclude_package_data={

'bandwidth_reporter':['*.txt']

}

)

除了以上的引數配置之外,還可以使用一個叫做 MANIFEST.in 的檔案,來控制檔案的分發。

如下這是一個 MANIFEST.in 的樣例:

include *.txt

recursive-include examples *.txt *.py

prune examples/sample?/build

這些配置,規定了如下幾點

所有根目錄下的以 txt 為字尾名的檔案,都會分發 根目錄下的 examples 目錄 和 txt、py檔案都會分發 路徑匹配上 examples/sample?/build 不會分發

MANIFEST.in 需要放在和 setup.py 同級的頂級目錄下,setuptools 會自動讀取該檔案。

關於依賴包下載安裝

from setuptools import setup, find_packages



setup(

...


# 表明當前模組依賴哪些包,若環境中沒有,則會從pypi中下載安裝

install_requires=['docutils>=0.3'],


# setup.py 本身要依賴的包,這通常是為一些setuptools的外掛準備的配置

# 這裡列出的包,不會自動安裝。

setup_requires=['pbr'],


# 僅在測試時需要使用的依賴,在正常釋出的程式碼中是沒有用的。

# 在執行python setup.py test時,可以自動安裝這三個庫,確保測試的正常執行。

tests_require=[

'pytest>=3.3.1',

'pytest-cov>=2.5.1',

],


# 用於安裝setup_requires或tests_require裡的軟體包

# 這些資訊會寫入egg的 metadata 資訊中

dependency_links=[

"http://example2.com/p/foobar-1.0.tar.gz",

],


# install_requires 在安裝模組時會自動安裝依賴包

# 而 extras_require 不會,這裡僅表示該模組會依賴這些包

# 但是這些包通常不會使用到,只有當你深度使用模組時,才會用到,這裡需要你手動安裝

extras_require={

'PDF': ["ReportLab>=1.2", "RXP"],

'reST': ["docutils>=0.3"],

}

)


關於 install_requires , 有以下五種常用的表示方法:

1. 'argparse' ,只包含包名。這種形式只檢查包的存在性,不檢查版本。方便,但不利於控制風險。 2. 'setuptools==38.2.4' ,指定版本。這種形式把風險降到了最低,確保了開發、測試與部署的版本一致,不會出現意外。缺點是不利於更新,每次更新都需要改動程式碼。 3. 'docutils >= 0.3' ,這是比較常用的形式。當對某個庫比較信任時,這種形式可以自動保持版本為最新。 4. 'Django >= 1.11, != 1.11.1, <= 2' ,這是比較複雜的形式。如這個例子,保證了Django的大版本在1.11和2之間,也即1.11.x;並且,排除了已知有問題的版本1.11.1(僅舉例)。對於一些大型、複雜的庫,這種形式是最合適的。 5. 'requests[security, socks] >= 2.18.4' ,這是包含了額外的可選依賴的形式。正常安裝requests會自動安裝它的 install_requires 中指定的依賴,而不會安裝 securitysocks 這兩組依賴。這兩組依賴是定義在它的 extras_require 中。這種形式,用在深度使用某些庫時。

關於安裝環境的限制

有些庫並不是在所以的 Python 版本中都適用的,若一個庫安裝在一個未相容的 Python 環境中,理論上不應該在使用時才報錯,而應該在安裝過程就使其失敗,提示禁止安裝。

這樣的功能,可以使用 python_requires 來實現。

setup(

...

python_requires='>=2.7, <=3',

)

生成可執行檔案的分發

from setuptools import setup, find_packages



setup(

name="mytest",

version="1.0",

author="wangbm",

author_email="[email protected]",

description="Learn to Pack Python Module",

url="http://python-online.cn/",

packages=find_packages(),


# 用來支援自動生成指令碼,安裝後會自動生成 /usr/bin/foo 的可執行檔案

# 該檔案入口指向 foo/main.py 的main 函式

entry_points={

'console_scripts': [

'foo = foo.main:main'

]

},


# 將 bin/foo.sh 和 bar.py 指令碼,生成到系統 PATH中

# 執行 python setup.py install 後

# 會生成 如 /usr/bin/foo.sh 和 如 /usr/bin/bar.py

scripts=['bin/foo.sh', 'bar.py']

)

上面的 scripts 裡有的指令碼中有 sh 和  py 字尾,那麼安裝後,setuptools 會原封不動的移動到 /usr/bin 中,並新增可執行許可權。

若你想對這些檔案再作一些更改,比如去掉多餘的字尾,可以這樣做

from setuptools.command.install_scripts import install_scripts


class InstallScripts(install_scripts):


def run(self):

setuptools.command.install_scripts.install_scripts.run(self)


# Rename some script files

for script in self.get_outputs():

if basename.endswith(".py") or basename.endswith(".sh"):

dest = script[:-3]

else:

continue

print("moving %s to %s" % (script, dest))

shutil.move(script, dest)


setup(

...

scripts=['bin/foo.sh', 'bar.py'],


cmdclass={

"install_scripts": InstallScripts

}

)

ext_modules

ext_modules 引數用於構建 C 和 C++ 擴充套件擴充套件包。其是 Extension 例項的列表,每一個 Extension 例項描述了一個獨立的擴充套件模組,擴充套件模組可以設定擴充套件包名,標頭檔案、原始檔、連結庫及其路徑、巨集定義和編輯引數等。如:

setup(

# other arguments here...

ext_modules=[

Extension('foo',

glob(path.join(here, 'src', '*.c')),

libraries = [ 'rt' ],

include_dirs=[numpy.get_include()])

]

)

詳細瞭解可參考: https://docs.python.org/3.6/distutils/setupscript.html#preprocessor-options

setup.py 的引數非常多,能夠不借助文件寫好一個setup.py好像沒那麼簡單。為了備忘,我整理了 setup 函式常用的一些引數:

引數 說明
name 包名稱
version 包版本
author 程式的作者
author_email 程式的作者的郵箱地址
maintainer 維護者
maintainer_email 維護者的郵箱地址
url 程式的官網地址
license 程式的授權資訊
description 程式的簡單描述
long_description 程式的詳細描述
platforms 程式適用的軟體平臺列表
classifiers 程式的所屬分類列表
keywords 程式的關鍵字列表
packages 需要處理的包目錄(通常為包含 __init__.py 的資料夾)
py_modules 需要打包的 Python 單檔案列表
download_url 程式的下載地址
cmdclass 新增自定義命令
package_data 指定包內需要包含的資料檔案
include_package_data 自動包含包內所有受版本控制(cvs/svn/git)的資料檔案
exclude_package_data 當 include_package_data 為 True 時該選項用於排除部分檔案
data_files 打包時需要打包的資料檔案,如圖片,配置檔案等
ext_modules 指定擴充套件模組
scripts 指定可執行指令碼,安裝時指令碼會被安裝到系統 PATH 路徑下
package_dir 指定哪些目錄下的檔案被對映到哪個原始碼包
requires 指定依賴的其他包
provides 指定可以為哪些模組提供依賴
install_requires 安裝時需要安裝的依賴包
entry_points 動態發現服務和外掛,下面詳細講
setup_requires 指定執行 setup.py 檔案本身所依賴的包
dependency_links 指定依賴包的下載地址
extras_require 當前包的高階/額外特性需要依賴的分發包
zip_safe 不壓縮包,而是以目錄的形式安裝

更多引數可見: https://setuptools.readthedocs.io/en/latest/setuptools.html

8. 打包輔助神器PBR 是什麼?

pbr 是 setuptools 的輔助工具,最初是為 OpenStack 開發(https://launchpad.net/pbr),基於d2to1。

pbr 會讀取和過濾setup.cfg中的資料,然後將解析後的資料提供給  setup.py 作為引數。包含如下功能:

1. 從git中獲取Version、AUTHORS and ChangeLog資訊 2. Sphinx Autodoc。pbr 會掃描project,找到所有模組,生成stub files 3. Requirements。pbr會讀取requirements.txt,生成setup函式需要的 install_requires/tests_require/dependency_links

這裡需要注意,在 requirements.txt 檔案的頭部可以使用: --index https://pypi.python.org/simple/ ,這一行把一個抽象的依賴宣告如 requests==1.2.0 轉變為一個具體的依賴宣告 requests 1.2.0 from pypi.python.org/simple/

4.  long_description。從README.rst, README.txt or README file中生成 long_description 引數

使用pbr很簡單:

from setuptools import setup


setup(

setup_requires=['pbr'],

pbr=True,

)


使用pbr時,setup.cfg中有一些配置。在[files]中,有三個key: packages :指定需要包含的包,行為類似於setuptools.find_packages  namespace_packages :指定namespace packages  data_files : 指定目的目錄和原始檔路徑,一個示例:

[files]

data_files =

etc/pbr = etc/pbr/*

etc/neutron =

etc/api-paste.ini

etc/dhcp-agent.ini

etc/init.d = neutron.init


[entry_points] 段跟 setuptools 的方式相同。

到此,我講了三種編寫使用 setup.py 的方法

使用命令列引數指定,一個一個將引數傳遞進去(極不推薦) 在 setup.py 中的setup函式中指定(推薦使用) 使用 pbr ,在 setup.cfg 中指定(易於管理,更推薦)

9. 如何使用 setup.py 構建包

1、構建原始碼釋出包。

用於釋出一個 Python 模組或專案,將原始碼打包成 tar.gz (用於 Linux 環境中)或者 zip 壓縮包(用於 Windows 環境中)

$ python setup.py sdist

那這種包如何安裝呢?

答案是,使用下一節即將介紹的 setuptools 中提供的  easy_install 工具。

$ easy_install xxx.tar.gz

使用 sdist 將根據當前平臺建立預設格式的存檔。在類 Unix 平臺上,將建立字尾後為 .tar.gz 的 gzip 壓縮的tar檔案分發包,而在Windows上為 ZIP 檔案。

當然,你也可以通過指定你要的釋出包格式來打破這個預設行為

$ python setup.py sdist --formats=gztar,zip

你可以指定的格式有哪些呢?

建立一個壓縮的tarball和一個zip檔案。可用格式為:

格式 描述
zip 壓縮檔( .zip
gztar gzip壓縮的tar檔案( .tar.gz
bztar bzip2格式的tar檔案( .tar.bz2
xztar xz的tar檔案( .tar.xz
ztar 壓縮的tar檔案( .tar.Z
tar tar檔案( .tar

對以上的格式,有幾點需要注意一下:

在版本3.5中才添加了對  xztar 格式的支援 zip 格式需要你事先已安裝相應的模組:zip程式或zipfile模組(已成為Python的標準庫) ztar 格式正在棄用,請儘量不要使用

另外,如果您希望歸檔檔案的所有檔案歸root擁有,可以這樣指定

python setup.py sdist --owner=root --group=root

2、構建二進位制分發包。

在windows中我們習慣了雙擊 exe 進行軟體的安裝,Python 模組的安裝也同樣支援 打包成 exe 這樣的二進位制軟體包。

$ python setup.py bdist_wininst

而在 Linux 中,大家也習慣了使用 rpm 來安裝包,對此你可以使用這條命令實現 rpm 包的構建

$ python setup.py bdist_rpm

若你喜歡使用 easy_install 或者 pip 來安裝離線包。你可以將其打包成 egg 包

$ python setup.py bdist_egg

若你的專案,需要安裝多個平臺下,既有 Windows 也有 Linux,按照上面的方法,多種格式我們要執行多次命令,為了方便,你可以一步到位,執行如下這條命令,即可生成多個格式的進位制包

$ python setup.py bdist

10. 如何使用 setup.py 安裝包

正常情況下,我們都是通過以上構建的原始碼包或者二進位制包進行模組的安裝。

但在編寫 setup.py 的過程中,可能不能一步到位,需要多次除錯,這時候如何測試自己寫的 setup.py 檔案是可用的呢?

這時候你可以使用這條命令,它會將你的模組安裝至系統全域性環境中

$ python setup.py install

如若你的專案還處於開發階段,頻繁的安裝模組,也是一個麻煩事。

這時候你可以使用這條命令安裝,該方法不會真正的安裝包,而是在系統環境中建立一個軟連結指向包實際所在目錄。這邊在修改包之後不用再安裝就能生效,便於除錯。

$ python setup.py develop

11. 如何釋出包到 PyPi?

通過上面的學習,你一定已經學會了如何打包自己的專案,若你覺得自己開發的模組非常不錯,想要 share 給其他人使用,你可以將其上傳到 PyPi (Python Package Index)上,它是 Python 官方維護的第三方包倉庫,用於統一儲存和管理開發者釋出的 Python 包。

如果要釋出自己的包,需要先到 pypi 上註冊賬號。然後建立 ~/.pypirc 檔案,此檔案中配置 PyPI 訪問地址和賬號。如的.pypirc檔案內容請根據自己的賬號來修改。

典型的 .pypirc 檔案

[distutils]

index-servers = pypi


[pypi]

username:xxx

password:xxx

然後使用這條命令進行資訊註冊,完成後,你可以在 PyPi 上看到專案資訊。

$ python setup.py register

註冊完了後,你還要上傳原始碼包,別人才使用下載安裝

$ python setup.py upload

或者也可以使用 twine 工具註冊上傳,它是一個專門用於與 pypi 進行互動的工具,詳情可以參考官網: https://www.ctolib.com/twine.html ,這裡不詳細講了。

參考閱讀

http://blog.konghy.cn/2018/04/29/setup-dot-py/

https://note.qidong.name/2018/01/python-setup-requires/

比啃西瓜書更高效的“機器學習”方法

一戰賺了1090億,恐怖的頭條CEO張一鳴!

王垠受邀面試阿里P9,被P10面跪後網上怒發文,慘打325的P10趙海平迴應了!