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().

Attributes

The following sections describe the attributes available on each instance.

tcl_files_path

(Optional[string])

Defines a directory relative to that of the built executable in which to install tcl/tk files.

If set to a value, tcl/tk files present in the Python distribution being used will be installed next to the build executable and the embedded Python interpreter will automatically set the TCL_LIBRARY environment variable to load tcl files from this directory.

If None (the default), no tcl/tk files will be installed.

windows_subsystem

(string)

Controls the value to use for the Rust #![windows_subsystem = "..."] attribute added to the autogenerated Rust program to build the executable.

This attribute only has meaning on Windows. It effectively controls the value passed to the linker’s /SUBSYSTEM flag.

Rust only supports certain values but PyOxidizer does not impose limitations on what values are used. Common values include:

console

Win32 character-mode application. A console window will be opened when the application runs.

This value is suitable for command-line executables.

windows

Application does not require a console and may provide its own windows.

This value is suitable for GUI applications that do not wish to launch a console window on start.

Default is console.

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.

PythonExecutable.to_file_manifest()

This method transforms the PythonExecutable instance to a FileManifest. The FileManifest is populated with the build executable and any file-based resources that are registered with the resource collector. A libpython shared library will also be present depending on build settings.

This method accepts the following arguments:

prefix
(string) The directory prefix of files in the FileManifest. Use . to denote no prefix.

PythonExecutable.to_wix_bundle_builder()

This method transforms the PythonExecutable instance into a WiXBundleBuilder instance. The returned value can be used to generate a Windows .exe installer. This installer will install the Visual C++ Redistributable as well as an MSI for the build application.

This method accepts the following arguments:

id_prefix
See Constructors for usage.
product_name
See Constructors for usage.
product_version
See Constructors for usage.
product_manufacturer
See Constructors for usage.
msi_builder_callback

(function) A callable function that can be used to modify the WiXMSIBuilder constructed for the application.

The function will receive the WiXMSIBuilder as its single argument. The return value is ignored.

The returned value can be further customized before it is built. See WiXBundleBuilder type documentation for more.

PythonExecutable.to_wix_msi_builder()

This method transforms the PythonExecutable instance into a WiXMSIBuilder instance. The returned value can be used to generate a Windows MSI installer.

This method accepts the following arguments:

id_prefix
See Constructors for usage.
product_name
See Constructors for usage.
product_version
See Constructors for usage.
product_manufacturer
See Constructors for usage.

The MSI installer configuration can be customized. See the WiXMSIBuilder type documentation for more.

The MSI installer will not materialize the Visual C++ Runtime DLL(s).