PythonExecutable

The PythonExecutable type represents an executable file containing the Python interpreter, Python resources to make available to the interpreter, and a default run-time configuration for that interpreter.

Instances are constructed from PythonDistribution instances using PythonDistribution.to_python_executable().

Methods

PythonExecutable.make_python_module_source()

This method creates a PythonModuleSource instance suitable for use with the executable being built.

Arguments are as follows:

name (string)
The name of the Python module. This is the fully qualified module name. e.g. foo or foo.bar.
source (string)
Python source code comprising the module.
is_package (bool)
Whether the Python module is also a package. (e.g. the equivalent of a __init__.py file or a module without a . in its name.

PythonExecutable.pip_download()

This method runs pip download <args> with settings appropriate to target the executable being built.

This always uses --only-binary=:all:, forcing pip to only download wheel based packages.

This method accepts the following arguments:

args
(list of string) Command line arguments to pass to pip download. Arguments will be added after default arguments added internally.

Returns a list of objects representing Python resources collected from wheels obtained via pip download.

PythonExecutable.pip_install()

This method runs pip install <args> with settings appropriate to target the executable being built.

args
List of strings defining raw process arguments to pass to pip install.
extra_envs
Optional dict of string key-value pairs constituting extra environment variables to set in the invoked pip process.

Returns a list of objects representing Python resources installed as part of the operation. The types of these objects can be PythonModuleSource, PythonPackageResource, etc.

The returned resources are typically added to a FileManifest or PythonExecutable to make them available to a packaged application.

PythonExecutable.read_package_root()

This method discovers resources from a directory on the filesystem.

The specified directory will be scanned for resource files. However, only specific named packages will be found. e.g. if the directory contains sub-directories foo/ and bar, you must explicitly state that you want the foo and/or bar package to be included so files from these directories will be read.

This rule is frequently used to pull in packages from local source directories (e.g. directories containing a setup.py file). This rule doesn’t involve any packaging tools and is a purely driven by filesystem walking. It is primitive, yet effective.

This rule has the following arguments:

path (string)
The filesystem path to the directory to scan.
packages (list of string)

List of package names to include.

Filesystem walking will find files in a directory <path>/<value>/ or in a file <path>/<value>.py.

Returns a list of objects representing Python resources found in the virtualenv. The types of these objects can be PythonModuleSource, PythonPackageResource, etc.

The returned resources are typically added to a FileManifest or PythonExecutable to make them available to a packaged application.

PythonExecutable.read_virtualenv()

This method attempts to read Python resources from an already built virtualenv.

Important

PyOxidizer only supports finding modules and resources populated via traditional means (e.g. pip install or python setup.py install). If .pth or similar mechanisms are used for installing modules, files may not be discovered properly.

It accepts the following arguments:

path (string)

The filesystem path to the root of the virtualenv.

Python modules are typically in a lib/pythonX.Y/site-packages directory (on UNIX) or Lib/site-packages directory (on Windows) under this path.

Returns a list of objects representing Python resources found in the virtualenv. The types of these objects can be PythonModuleSource, PythonPackageResource, etc.

The returned resources are typically added to a FileManifest or PythonExecutable to make them available to a packaged application.

PythonExecutable.setup_py_install()

This method runs python setup.py install against a package at the specified path.

It accepts the following arguments:

package_path
String filesystem path to directory containing a setup.py to invoke.
extra_envs={}
Optional dict of string key-value pairs constituting extra environment variables to set in the invoked python process.
extra_global_arguments=[]
Optional list of strings of extra command line arguments to pass to python setup.py. These will be added before the install argument.

Returns a list of objects representing Python resources installed as part of the operation. The types of these objects can be PythonModuleSource, PythonPackageResource, etc.

The returned resources are typically added to a FileManifest or PythonExecutable to make them available to a packaged application.

PythonExecutable.add_python_resource()

This method registers a Python resource of various types with the instance.

It accepts a resource argument which can be a PythonModuleSource, PythonPackageResource, or PythonExtensionModule and registers that resource with this instance.

The following arguments are accepted:

resource
The resource to add to the embedded Python environment.

This method is a glorified proxy to the various add_python_* methods. Unlike those methods, this one accepts all types that are known Python resources.

PythonExecutable.add_python_resources()

This method registers an iterable of Python resources of various types. This method is identical to PythonExecutable.add_python_resource() except the argument is an iterable of resources. All other arguments are identical.

PythonExecutable.filter_from_files()

This method filters all embedded resources (source modules, bytecode modules, and resource names) currently present on the instance through a set of resource names resolved from files.

This method accepts the following arguments:

files (array of string)
List of filesystem paths to files containing resource names. The file must be valid UTF-8 and consist of a \n delimited list of resource names. Empty lines and lines beginning with # are ignored.
glob_files (array of string)

List of glob matching patterns of filter files to read. * denotes all files in a directory. ** denotes recursive directories. This uses the Rust glob crate under the hood and the documentation for that crate contains more pattern matching info.

The files read by this argument must be the same format as documented by the files argument.

All defined files are first read and the resource names encountered are unioned into a set. This set is then used to filter entities currently registered with the instance.

PythonExecutable.to_embedded_resources()

Obtains a PythonEmbeddedResources instance representing resources to be made available to the Python interpreter.

See the PythonEmbeddedResources type documentation for more.