python 項目打包

使用setuptools打包

當我們寫一個完整的項目，需要該項目文件中打包成分發包共享給他人或者上傳到pypi社區以供他人下載。這就需要對該項目進行打包分發。

項目文件

這是一個已寫好的項目文件包，叫做my_pkg，它的目錄結構如下：

tutorial/
    my_pkg/
        __init__.py
        main.py
        utils/
            __init__.py
            other.py

在my_pkg中有兩個文件和一個子包utils，現在我們需要對這個my_pkg進行打包。

創建包文件和setup.py文件

my_pkg是將打包的Python包文件，在my_pkg的同級目錄下分別創建以下文件：

• setup.py ---- 打包腳本文件，執行該腳本將自動完成打包
• LICENCE ---- 許可證文件
• README ---- 包的介紹和說明

創建后文件目錄結構如下：

tutorial/
    my_pkg/
        __init__.py
        main.py
        utils/
            __init__.py
            other.py
    setup.py
    LICENCE
    README

setup.py配置

打開setup.py文件，寫入以下內容

import setuptools      # 導入setuptools, 基於setuptools模塊進行打包分發

# 將readme文件中內容加載進來，作為對包的詳細說明（可以不需要）
with open("README.md", "r") as fh:  
    long_description = fh.read()

# 調用setuptools的setup進行打包，通過參數配置指定包的信息，這是打包的關鍵設置
setuptools.setup(
    name="my_pkg", # 這是該包的名字，將來可能使用pip install 該包名直接下載
    version="0.0.1",   #版本號，
    author="Example Author",  #作者
    author_email="[e-mail]", # 作者郵箱
    description="A small example package", # 包簡短的描述
    long_description=long_description,     # 詳細的描述，這里使用從readme中讀取的內容
    long_description_content_type="text/markdown",  # 詳細描述來源文件的文件類型，這里使用markdomn
    url="https://github.com/pypa/my_pkg",  # 可以將項目上傳到github,gitlab等，在此指定鏈接地址以供下載。

    # 指定需要打包的內容，輸入需要打包包名字符串列表，打包時不會自動獲取子包，需要手動指定，例如：["my_pkg", "mypkg.utils"]
    packages=setuptools.find_packages(), # 使用該函數可以自動打包該同級目錄下所有包
    
    classifiers=[    # 指定一些包的元數據信息，例如使用的協議，操作系統要求
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
    python_requires='>=3.6',   # 該包的Python版本要求
)

setup.py中除了上述內容，還可以添加包括以下的信息

name              package name
version (-V)      package version
fullname          <package name>-<version>
author            the author's name
author-email      the author's email address
maintainer        the maintainer's name
maintainer-email  the maintainer's email address
contact           the maintainer's name if known, else the author's
contact-email     the maintainer's email address if known       
url               the URL for this package
license           the license of the package
licence           for --license
description       the package description
long-description  the long package description
platforms         the list of platforms
classifiers       the list of classifiers
keywords          the list of keywords
provides          the list of packages/modules provided
requires          the list of packages/modules required
obsoletes         the list of packages/modules made obsolete

setup.py配置完成后，就可以執行這個文件進行打包了（在命令行使用Python解釋器指定參數執行，不能直接執行），在此之前還有LICENCE和README兩個文件需要完善（也可以不做處理，不影響打包執行）。

README

這個文件是該包的詳細說明文件，包括各種信息，例如該包如何安裝，需要的環境，如何使用等詳細內容。

LICENCE

指定許可證信息，開源軟件都遵循了不同的開源協議，這些協議規定了使用者使用該包后必須遵守的原則，可以查看不同開源協議內容 https://choosealicense.com/ ，選則一個協議，復制對應的協議內容到該文件中即可：

示例選擇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.

通過setup.py生成分發包

setup.py文件配置完成后，就可以通過Python執行進行打包，使用cmd命令行工具打開終端，cd 到setup.py文件所在目錄(windows 可以在文件資源管理器中的setup.py目錄上方路徑中直接cmd，直接在該目錄打開終端)

打包成wheel二進制包

這需要最新的setuptools 和 wheel包。執行以下命令更新

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

執行該setup.py文件並指定參數，指定打包為wheel二進制文件。

python setup.py sdist bdist_wheel

執行該命令后，該目錄下會多出三個目錄。在dist目錄下就是我們打包好的源代碼文件（tar.gz）和wheel二進制文件(.whl)。

build
dist/
    my_pkg-0.0.1.tar.gz              # 被打包內容所有原代碼，按照原有的層級結構
    my_pkg-0.0.1-py3-none-any-whl    # 可以通過pip install 直接安裝
my_pkg.egg-info

現在我們可以及將這個dist文件夾中的內容共享給他人，也可以上傳pypi社區供他人下載安裝，在得到這個dist包后，可以通過pip安裝命令直接安裝內部的.whl文件。

pip install my_pkg-0.0.1-py3-none-any-whl

該命令會將這個包安裝到python安裝目錄下/Lib/site-packages目錄下，使用pip list命令可以看到在列表中出現了名為my_pkg的包名，安裝成功。該包可以使用了。

如果將該包上傳到pypi社區供他人下載，需要注意自己包名不要和其他貢獻者的包名相同，如何判斷是否重復，嘗試在未上傳前使用pip isntall 包名 進行安裝，若沒有找到找到該package表示該名可用，也可以上pypi官網搜索。上傳成功后，直接使用pip install 包名進行安裝。上傳pypi過程見官網示例https://packaging.python.org/tutorials/packaging-projects/#uploading-the-distribution-archives

打包為源碼包-sdist

通過wheel二進制文件打包是目前較為流行的方式。除了wheel二進制文件，我們還可以使用Python源代碼壓縮文件形式進行打包。同樣在setup.py同級目錄下，進入cmd命令行，執行命令

python setup.py sdist

將會在創建dist和my_pkg.egg.info目錄。我們只關心dist目錄，該目錄下有一個壓縮文件，這個壓縮文件包含了打包后的全部源碼。

dist/
    my_pkg-0.0.1.tar.gz

將該文件發送給他人，可以直接使用pip install my_pkg-0.0.1.tar.gz直接安裝該包，同樣在使用pip list可以查看到該包名。

另外，還可以解壓該源碼包，在setup.py目錄執行python setup.py install安裝該包。

二進制安裝程序-bdist

打包為二進制安裝包，生成目標操作系統的安裝程序。

生成windows 安裝程序

針對windows環境下，以下三條命令均可

python setup.py bdist_wininst
Python setup.py bdist_msi
python setup.py bdist --format=msi

創建一個dist目錄，生成一個安裝程序，在Windows上直接雙擊即可安裝該包。

生成rpm包

python setup.py bdist_rpm
python setup.py bdist -- format=rpm

在Linux系統中使用rpm命令進行安裝。

生成壓縮文件

python setup.py bdist --format=zip
python setup.py bdist --format=gztar