Description

# `pyinstaller-hooks-contrib`: The PyInstaller community hooks repository What happens when (your?) package doesn't work with PyInstaller? Say you have data files that you need at runtime? PyInstaller doesn't bundle those. Your package requires others which PyInstaller can't see? How do you fix that? In summary, a "hook" file extends PyInstaller to adapt it to the special needs and methods used by a Python package. The word "hook" is used for two kinds of files. A runtime hook helps the bootloader to launch an app, setting up the environment. A package hook (there are several types of those) tells PyInstaller what to include in the final app - such as the data files and (hidden) imports mentioned above. This repository is a collection of hooks for many packages, and allows PyInstaller to work with these packages seamlessly. ## Installation `pyinstaller-hooks-contrib` is automatically installed when you install PyInstaller, or can be installed with pip: ```commandline pip install -U pyinstaller-hooks-contrib ``` ## I can't see a hook for `a-package` Either `a-package` works fine without a hook, or no-one has contributed hooks. If you'd like to add a hook, or view information about hooks, please see below. ## Hook configuration (options) Hooks that support configuration (options) and their options are documented in [Supported hooks and options](hooks-config.rst). ## I want to help! If you've got a hook you want to share then great! The rest of this page will walk you through the process of contributing a hook. If you've been here before then you may want to skip to the [summary checklist](#summary) **Unless you are very comfortable with `git rebase -i`, please provide one hook per pull request!** **If you have more than one then submit them in separate pull requests.** ### Setup [Fork this repo](https://github.com/pyinstaller/pyinstaller-hooks-contrib/fork) if you haven't already done so. (If you have a fork already but its old, click the **Fetch upstream** button on your fork's homepage.) Clone and `cd` inside your fork by running the following (replacing `bob-the-barnacle` with your github username): ``` git clone https://github.com/bob-the-barnacle/pyinstaller-hoooks-contrib.git cd pyinstaller-hooks-contrib ``` Create a new branch for you changes (replacing `foo` with the name of the package): You can name this branch whatever you like. ``` git checkout -b hook-for-foo ``` If you wish to create a virtual environment then do it now before proceeding to the next step. Install this repo in editable mode. This will overwrite your current installation. (Note that you can reverse this with `pip install --force-reinstall pyinstaller-hooks-contrib`). ``` pip install -e . pip install -r requirements-test.txt pip install flake8 pyinstaller ``` Note that on macOS and Linux, `pip` may by called `pip3`. If you normally use `pip3` and `python3` then use `pip3` here too. You may skip the 2^nd line if you have no intention of providing tests (but please do provide tests!). ### Add the hook Standard hooks live in the [_pyinstaller_hooks_contrib/stdhooks/](../master/_pyinstaller_hooks_contrib/stdhooks/) directory. Runtime hooks live in the [_pyinstaller_hooks_contrib/rthooks/](../master/_pyinstaller_hooks_contrib/rthooks/) directory. Simply copy your hook into there. If you're unsure if your hook is a runtime hook then it almost certainly is a standard hook. Please annotate (with comments) anything unusual in the hook. *Unusual* here is defined as any of the following: * Long lists of `hiddenimport` submodules. If you need lots of hidden imports then use [`collect_submodules('foo')`](https://pyinstaller.readthedocs.io/en/latest/hooks.html#PyInstaller.utils.hooks.collect_submodules). For bonus points, track down why so many submodules are hidden. Typical causes are: * Lazily loaded submodules (`importlib.importmodule()` inside a module `__getattr__()`). * Dynamically loaded *backends*. * Usage of `Cython` or Python extension modules containing `import` statements. * Use of [`collect_all()`](https://pyinstaller.readthedocs.io/en/latest/hooks.html#PyInstaller.utils.hooks.collect_all). This function's performance is abismal and [it is broken by design](https://github.com/pyinstaller/pyinstaller/issues/6458#issuecomment-1000481631) because it confuses packages with distributions. Check that you really do need to collect all of submodules, data files, binaries, metadata and dependencies. If you do then add a comment to say so (and if you know it - why). Do not simply use `collect_all()` just to *future proof* the hook. * Any complicated `os.path` arithmetic (by which I simply mean overly complex filename manipulations). #### Add the copyright header All source files must contain the copyright header to be covered by our terms and conditions. If you are **adding** a new hook (or any new python file), copy/paste the appropriate cop