PyInstaller hook sample documentation

This package demonstrates defining a library which includes PyInstaller hooks along with tests for those hooks. It is intended to provide a guide for integrating PyInstaller hooks and tests into a package. All source is available on Github. A brief walkthrough:

• This package provides the pyi_hooksample library, implemented in pyi_hooksample/ __init__.py - Hook sample package, which defines two functions:

  • do_import, which uses importlib to import the _hidden.py - A hidden import module. Since PyInstaller only performs static analysis, it cannot detect this import.

  • print_message, which relies on a data file to work correctly. PyInstaller must be instructed to include this file when freezing for the program to run correctly.

• Therefore, this package also provides a hook to fix these two problems. It also registers this hook with PyInstaller, so that all PyInstaller builds will have this hook available if needed.

• Finally, it provides a short test script to ensure the hooks work correctly. This is also registered with PyInstaller, which enables running this test in two locations:

  • This package can run tests to ensure the hook produces a working executable when frozen by PyInstaller. For example, CI testing via Travis invokes these tests.

  • PyInstaller can also run this test during its development process, ensuring that any updates to PyInstaller don’t break this package’s freeze process. After integrating this approach in your library, post an issue so the PyInstaller team can add your package to the list of packages covered by CI.

Contents

• pyi_hooksample/ __init__.py - Hook sample package
• __pyinstaller/ __init__.py - Provide PyInstaller hooks
• test_basic.py - Tests for this module
• setup.cfg - Configuration accompanying setup.py
• .travis.yml - Travis CI test setup

Installation

From a terminal/command prompt:

1. Upgrade pip:

   python -m pip install -U pip
   

2. Install this package with the optional test and docs requirements:

   pip install -e .[test,docs]
   

3. Run the tests; see also notes on this:

   python -m PyInstaller.utils.run_tests --include_only pyi_hooksample.
   

4. Build the docs:

   sphinx-build -d _build/doctrees . _build
   

License

Copyright © 2020 PyInstaller Development Team

This file is part of PyInstaller Hook Sample.

PyInstaller Hook Sample is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

PyInstaller Hook Sample is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with PyInstaller Hook Sample. If not, see <http://www.gnu.org/licenses/>.

SPDX-License-Identifier: GPL-3.0-or-later