py2app includes a mechanism for working around package incompatibilities, and stripping unwanted dependencies automatically. These are called recipes.
A future version of py2app will support packaging of Python Eggs. Once this is established, recipes will be obsolete since eggs contain all of the metadata needed to build a working standalone application.
Common causes for incompatibility¶
Some Python packages are written in such a way that they aren’t compatible with being packaged. There are two main causes of this:
__import__or otherwise importing code without usage of the
- Requiring in-package data files
- All codecs in the package are imported.
- Several of its internal components are automatically imported
- A dependency on
pytz.zoneinfo.UTCis implied, and the
matplotlibpackage is included in its entirety out of the zip file.
numpypackage is included in its entirety out of the zip file.
- Locates and includes all image plugins (Python modules that end with
ImagePlugin.py), removes unwanted dependencies on
- The implicit references on the several modules are removed (
- Several data files that are included in the zip file where
pygamecan find them (
- If the installed version of PyOpenGL reads a
versionfile to determine its version, then the
OpenGLpackage is included in its entirety out of the zip file.
numpypackages are included in their entirety out of the zip file.
sipis detected, then all sip-using packages are included (e.g. PyQt).
py2app currently searches for recipes only in the
A recipe is an object that implements a
- The py2app command instance (a subclass of
setuptools.Command). See the source for
A recipe should return either
None or a
If a recipe returns
None it should not have performed any actions with
side-effects, and it may be called again zero or more times.
If a recipe returns a
dict instance, it will not be called again. The
dict may have any of these optional string keys:
- A list of filter functions to be called with every module in the
modulegraph during flattening. If the filter returns False, the module
and any of its dependencies will not be included in the output. This is
similar in purpose to the
excludesoption, but can be any predicate (e.g. to exclude all modules in a given path).
- Used to include data files inside the
site-packages.zip. This is a list of 2-tuples:
[(subdir, files), ...].
subdiris the path within
filesis the list of files to include in that directory.
- A list of package names to be included in their entirety outside of the
- A list of additional Python scripts to run before initializing the main script. This is often used to monkey-patch included modules so that they work in a frozen environment. The prescripts may be module names, file names, or file-like objects containing Python code (e.g. StringIO). Note that if a file-like object is used, it will not currently be scanned for additional dependencies.