Python3快速入门（十八）——PyI

一、PyInstaller简介

1、PyInstaller简介

PyInstaller是一个跨平台的python应用打包工具，支持 windows/linux/MacOS三大主流平台，能够把 Python 脚本及其所在的 Python 解释器打包成可执行文件，从而允许最终用户在无需安装 Python 的情况下执行应用程序。
PyInstaller 制作出来的执行文件并不是跨平台的，如果需要为不同平台打包，就要在相应平台上运行PyInstaller进行打包。

2、PyInstaller安装

pip install PyInstaller

二、PyInstaller基础用法

1、PyInstaller使用

pyinstaller main.py
PyInstaller 最简单使用只需要指定作为程序入口的脚本文件。PyInstaller 执行打包程序后会在当前目录下创建下列文件和目录：
main.spec 文件，其前缀和脚本名相同，指定了打包时所需的各种参数；
build 子目录，其中存放打包过程中生成的临时文件。warnxxxx.txt文件记录了生成过程中的警告/错误信息。如果 PyInstaller 运行有问题，需要检查warnxxxx.txt文件来获取错误的详细内容。xref-xxxx.html文件输出 PyInstaller 分析脚本得到的模块依赖关系图。
dist子目录，存放生成的最终文件。如果使用单文件模式将只有单个执行文件；如果使用目录模式的话，会有一个和脚本同名的子目录，其内才是真正的可执行文件以及附属文件。

2、PyInstaller命令行选项

PyInstaller命令行选项可以通过帮助信息查看：
pyinstaller --help
-y | --noconfirm：直接覆盖输出文件，而无需提示，在多次重复运行命令时可避免反复确认。
-D | --onedir：生成包含执行文件的目录（默认行为）。
-F | --onefile：生成单一的可执行文件，不推荐使用。
-i | --icon [.ico | .exe | .icns]：为 Windows/Mac 平台的执行文件指定图标。
--version-file [filename]：添加文件版本信息。
-c | --console | --nowindowed：通过控制台窗口运行程序 并且分配标准输入/输出，（默认行为）。
-w | --windowed | --noconsole：不创建控制台窗口，也不分配标准输入/输出，主要用来运行 GUI 程序。没有输入输出会给调试带来一定困难，因此即便是 GUI 程序，建议在调试时禁用本选项，在最终发布时再打开。
--add-data [file:dir]：添加数据文件。如果有多个文件需要添加，本选项可以出现多次。参数的格式为文件名+输出目录名，用路径分隔符分割，在 Windows 下使用 ;，其它系统下则使用 :。 如果输出到和脚本相同的目录，则使用 . 作为输出目录。
--add-binary [file:dir]：添加二进制文件，即运行程序所需的.exe/.dll/.so 等。

3、单目录模式

单目录模式是 PyInstaller 将 Python 程序编译为同一个目录下的多个文件，其中 xxxx.exe 是程序入口点（xxxx 是脚本文件名称，可以通过命令行修改）。单目录模式是 PyInstaller 的默认模式，可以自己加上 -D 或者 --onedir 开关显式开启。
单目录模式打包生成的目录除可执行文件外，还包括 Python 解释器（PythonXX.dll）、系统运行库（ucrtbase.dll 以及其它 apixx.dll），以及一些编译后的 Python 模块（.pyd 文件）。

4、单文件模式

单文件模式是将整个程序编译为单一的可执行文件。需要在命令行添加 -F 或者 --onefile 开关开启。
Python脚本是解释型程序，而不是 原生的编译程序，并不能产生出真正单一的可执行文件。如果使用单文件模式，PyInstaller打包生成的是自动解压程序，需要先把所有文件解压到一个临时目录（通常名为_MEIxxxx，xxxx是随机数字），再从临时目录加载解释器和附属文件。程序运行完毕后，如果一切正常，会将临时目录再删除。
PyInstaller会对运行时的Python解释器修改。如果直接运行 Python 脚本，那么sys.frozen 变量不存在，如果通过 PyInstaller 生成的可执行文件运行，PyInstaller 会设置sys.frozen 变量为 True；如果使用单文件模式，sys._MEIPASS 变量包含了PyInstaller 自动创建的临时目录名。
单文件模式因为有临时目录和解压文件过程，所以程序启动速度会比较慢。如果程序运行到一半崩溃，则临时目录将没有机会被删除。

三、PyInstaller规格文件

PyInstaller 在生成文件的同时会创建一个相应的.spec 文件，.spec 文件本质上是一个特殊的 Python 脚本，记录了生成所需的指令。

1、Spec文件生成

使用pyinstaller [options] xxx.py进行打包时，PyInstaller 会首先根据选项生成对应的 .spec 文件，然后执行 .spec 文件所指定的过程生成最终文件。因此，可以直接指定spec文件执行打包过程。
pyinstaller [options] xxx.spec

2、Spec文件格式

单目录模式生成的spec 文件格式如下：

a = Analysis(...)
pyz = PYZ(...)
exe = EXE(...)
coll = COLLECT(...)

单文件模式生成的spec 文件格式如下：

a = Analysis(...)
pyz = PYZ(...)
exe = EXE(...)

单文件模式是将所有内容统一打包到 .exe，而单目录模式除了生成 .exe 外，还需要拷贝其它附属文件。
Analysis用于分析脚本的引用关系，并将所有查找到的相关内容记录在内部结构中，供后续步骤使用；
PYZ将所有 Python 脚本模块编译为对应的 .pyd 并打包；
EXE:将打包后的 Python 模块及其它文件一起生成可执行的文件结构；
COLLECT:将引用到的附属文件拷贝到生成目录的对应位置。
如果数据文件很多导致 Analysis 太长，则可以提取为单独的变量。

data_files = [(...)]
a = Analysis(...,
             datas=data_files,
             ...)

可以为数据/二进制文件指定通配符，从而匹配同一类型的多个文件。

a = Analysis(...,
             datas=[('media/*.mp3', 'media')],
             ...)

可以将指定文件和指定目录打包进行打包，如下：

a = Analysis(...,
             datas=[('config.ini', '.'), ('data', 'data')],
             ...)

将config.ini文件打包当可执行文件当前目录下，将data目录打包到可执行文件当前目录下。

四、PyInstaller Hook机制

1、PyInstaller Hook简介

PyInstaller 使用递归方法，从入口的脚本文件逐个分析，获取依赖模块。
PyInstaller 能识别 ctypes、SWIG、Cython 等形式的模块调用，但文件名必须为字面值。但PyInstaller 无法识别动态和调用，例如 import、exec、eval,以及以变量为参数的调用。
当 PyInstaller 识别完所有模块后，会在内部构成一个树形结构表示调用关系图，调用关系在生成目标时也会一并输出（xref-xxxx.html 文件）。PYZ 步骤会将所有识别到的模块汇集起来，如果有必要会编译成.pyd，然后将文件打包。但仍然存在以下问题：
（1）由于动态模块调用未必可以自动识别到，因此不会打包到文件中，执行时肯定会出现问。
（2）有些模块并非是以模块的形式，而是通过文件系统去访问 .py 文件，代码在运行时同样会出现问题。
为了解决上述问题，PyInstaller引入了Hooks机制，对于两种问题引入了两种类型的 Hook。两种 Hook 主要是按照加载时间区分，第一种Hook在 PyInstaller 文档中没有明确的命名，是在生成过程中，导入特定模块时调用的，称为 Import Hook；第二种是Runtime Hook，是在执行文件启动期间、加载特定模块时调用的。

2、Import Hooks

PyInstaller 定义的所有 Hook 在 PyInstaller 安装目录的 hooks 子目录下，文件的命名均为 hook-[模块名].py 的形式，即为 Import Hook。
当 PyInstaller 生成过程中找到特定的导入模块，就会到hooks目录下查找是否存在对应的Hook，如果存在，则执行之。
hook-PyQt5.py文件如下：

import os

from PyInstaller.utils.hooks import collect_system_data_files
from PyInstaller.utils.hooks.qt import pyqt5_library_info, get_qt_binaries

# Ensure PyQt5 is importable before adding info depending on it.
if pyqt5_library_info.version:
    hiddenimports = [
        # PyQt5.10 and earlier uses sip in an separate package;
        'sip',
        # PyQt5.11 and later provides SIP in a private package. Support both.
        'PyQt5.sip'
    ]

    # Collect the ``qt.conf`` file.
    datas = [x for x in
             collect_system_data_files(pyqt5_library_info.location['PrefixPath'],
                                       'PyQt5')
             if os.path.basename(x[0]) == 'qt.conf']

    # Collect required Qt binaries.
    binaries = get_qt_binaries(pyqt5_library_info)

hiddenimports是PyInstaller 用来描述并非通过 import 明确导入，而是通过其它动态机制加载的模块。

3、Runtime Hooks

Runtime Hooks均位于 PyInstaller 安装目录下的loader\rthooks 子目录下，并且命名方式是 pyi_rth_[模块名称].py（rth 代表 run time hook）。
loader\rthooks.dat内容是一个字典，记录了系统中所有支持的 Runtime Hooks。rthooks.dat文件如下：

{
    'certifi':    ['pyi_rth_certifi.py'],
    'Django':     ['pyi_rth_djanGo.py'],
    'enchant':    ['pyi_rth_enchant.py'],
    'gi':         ['pyi_rth_gi.py'],
    'gi.repository.Gio':    ['pyi_rth_gio.py'],
    'gi.repository.GLib':   ['pyi_rth_glib.py'],
    'gi.repository.GdkPixbuf':    ['pyi_rth_gdkpixbuf.py'],
    'gi.repository.Gtk':    ['pyi_rth_gtk.py'],
    'gi.repository.Gst':    ['pyi_rth_gstreamer.py'],
    'gst':        ['pyi_rth_gstreamer.py'],
    'kivy':       ['pyi_rth_kivy.py'],
    'kivy.lib.gstplayer': ['pyi_rth_gstreamer.py'],
    'matplotlib': ['pyi_rth_mplconfig.py', 'pyi_rth_mpldata.py'],
    'osgeo':      ['pyi_rth_osgeo.py'],
    'pkg_resources':  ['pyi_rth_pkgres.py'],
    'PyQt4':      ['pyi_rth_qt4plugins.py'],
    'PyQt5':      ['pyi_rth_pyqt5.py'],
    'PyQt5.QtWEBEngineWidgets': ['pyi_rth_pyqt5webengine.py'],
    'PySide':      ['pyi_rth_qt4plugins.py'],
    'PySide2':      ['pyi_rth_pyside2.py'],
    'PySide2.QtWebEngineWidgets': ['pyi_rth_pyside2webengine.py'],
    '_tkinter':    ['pyi_rth__tkinter.py'],
    'traitlets':  ['pyi_rth_traitlets.py'],
    'twisted.internet.Reactor':        ['pyi_rth_twisted.py'],
    'usb':        ['pyi_rth_usb.py'],
    'win32com':   ['pyi_rth_win32comgenpy.py'],
    'multiprocessing': ['pyi_rth_multiprocessing.py'],
    'nltk': ['pyi_rth_nltk.py'],
}

Runtime Hooks 是在执行文件运行期间执行的。PyInstaller 修改了模块加载机制，当运行期间加载任何模块时，PyInstaller 会检查是否有对应的 Runtime Hook，如果有，则运行相应Hook。因此，Runtime Hooks 是和脚本一起编译到可执行文件中的。
pyi_rth_pyqt5.py文件如下：

import os
import sys

# The path to Qt's components may not default to the wheel layout for
# self-compiled PyQt5 installations. Mandate the wheel layout. See
# ``utils/hooks/qt.py`` for more details.
pyqt_path = os.path.join(sys._MEIPASS, 'PyQt5', 'Qt')
os.environ['QT_PLUGIN_PATH'] = os.path.join(pyqt_path, 'plugins')
os.environ['QML2_IMPORT_PATH'] = os.path.join(pyqt_path, 'qml')

五、错误调试

使用PyInstaller进行打包时，最常见的错误是Failed to execute script xxx，通常做法是先使用pyinstaller -c xxx.py将应用打包为控制台应用，在命令行执行相应可执行程序查看错误输出，进而逐个排除错误。