PythonExecutable

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

licenses_filename

(str)

The filename to use / write for an auto-generated report of software component licensing relevant to the built executable.

The file will contain a bill-of-materials of all the known software components in the built binary. This includes information about the Python distribution, extension modules and libraries used by the Python distribution, 3rd party Python packages, and Rust crates.

Each component is annotated with licensing information, including the license text, if available.

All content in the file is best effort.

If None, no file will be written.

Default: COPYING.txt

packed_resources_load_mode

(str)

Defines how the packed Python resources data (see Python Packed Resources) is written and loaded at run-time by the embedded Python interpreter.

The following values/patterns can be defined:

none

No resources data will be serialized or loaded at run-time. (Use this if you are using Python’s filesystem based module importer and don’t want to use PyOxidizer’s custom importer.)

embedded:<filename>

The packed resources data will be embedded in the binary and loaded from a memory address at run-time.

filename denotes the path of the on-disk file used at build time. This file is written to the artifacts directory that PyOxidizer writes required build files to.

binary-relative-memory-mapped:<filename>

The packed resources data will be written to a file relative to the built binary and loaded from there at run-time using memory mapped I/O.

The default is embedded:packed-resources.

tcl_files_path

(Optional[str])

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_runtime_dlls_mode

(str)

Controls how Windows runtime DLLs should be managed when building the binary.

Windows binaries often have a dependency on various runtime DLLs, such as vcruntime140.dll. The built executable will need access to these DLLs or it won’t work.

This setting controls whether to install required Windows runtime DLLs next to the built binary at build time. For example, if you are producing a myapp.exe, this setting can automatically install a vcruntime140.dll next to that binary.

The following values are recognized:

never

Never install Windows runtime DLLs.

when-present

Install Windows runtime DLLs when they can be located. Do nothing if they can’t be found.

always

Install Windows runtime DLLs and fail if they can’t be located.

This setting is ignored when the built binary does not have a dependency on Windows runtime DLLs.

See Distribution Considerations for Windows for more on runtime DLL requirements.

windows_subsystem

(str)

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.

make_python_module_source(name: str, source: str, is_package: bool) → PythonModuleSource

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

Arguments are as follows:

name

The name of the Python module. This is the fully qualified module name. e.g. foo or foo.bar.

source

Python source code comprising the module.

is_package

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.

pip_download(args: list[str]) → list[Any]

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

pip_install(args: list[str], extra_envs: Optional[dict[str, str]]) → list[Any]

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 starlark_tugger.FileManifest or PythonExecutable to make them available to a packaged application.

read_package_root(path: str, packages: list[str]) → list[Any]

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

The filesystem path to the directory to scan.

packages

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 starlark_tugger.FileManifest or PythonExecutable to make them available to a packaged application.

read_virtualenv(path: str) → list[Any]

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

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 starlark_tugger.FileManifest or PythonExecutable to make them available to a packaged application.

setup_py_install(package_path: str, extra_envs: dict[str, str] = {}, extra_global_arguments: dict[str, str] = {}) → list[Any]

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 starlark_tugger.FileManifest or PythonExecutable to make them available to a packaged application.

add_python_resource(resource: Union[PythonModuleSource, PythonPackageResource, PythonExtensionModule])

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.

add_python_resources(resources: list[Union[PythonModuleSource, PythonPackageResource, PythonExtensionModule])

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

add_cargo_manifest_licensing(manifest_path: str, all_features: bool = False, features=None)

Register software component licensing for a package defined in a Cargo.toml manifest.

This method accepts the following arguments:

manifest_path

Filesystem path of Cargo.toml to process.

all_features

Whether to activate all crate features when determining licensing info.

features

List of strings denoting explicit features to enable.

Ignored if all_features is enabled.

filter_resources_from_files(files: list[str], glob_files: list[str])

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

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

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.

to_embedded_resources()

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

See the PythonEmbeddedResources type documentation for more.

to_file_manifest(prefix: str) → starlark_tugger.FileManifest

This method transforms the PythonExecutable instance to a starlark_tugger.FileManifest. The starlark_tugger.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

The directory prefix of files in the starlark_tugger.FileManifest. Use . to denote no prefix.

to_wix_bundle_builder(id_prefix: str, product_name: str, product_version: str, product_manufacturer: str, msi_builder_callback: Callable) → starlark_tugger.WiXBundleBuilder

This method transforms the PythonExecutable instance into a starlark_tugger.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 starlark_tugger.WiXMSIBuilder.__init__() for usage.

product_name

See starlark_tugger.WiXMSIBuilder.__init__() for usage.

product_version

See starlark_tugger.WiXMSIBuilder.__init__() for usage.

product_manufacturer

See starlark_tugger.WiXMSIBuilder.__init__() for usage.

msi_builder_callback

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

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

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

Important

PythonExecutable.windows_runtime_dlls_mode can result in DLLs being installed next to the binary in addition to being installed as part of the installer. When using this method, you probably want to set .windows_runtime_dlls_mode = "never" to prevent the redundant installation.

to_wix_msi_builder(id_prefix: str, product_name: str, product_version: str, product_manufacturer: str) → starlark_tugger.WiXMSIBuilder

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

This method accepts the following arguments:

id_prefix

See starlark_tugger.WiXMSIBuilder.__init__() for usage.

product_name

See starlark_tugger.WiXMSIBuilder.__init__() for usage.

product_version

See starlark_tugger.WiXMSIBuilder.__init__() for usage.

product_manufacturer

See starlark_tugger.WiXMSIBuilder.__init__() for usage.

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

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

build(target: str) → starlark_tugger.ResolvedTarget

Produces a binary executable embedding Python using the settings configured on this instance.

target

The name of the target being built.

Under the covers, this will generate a temporary Rust project and invoke cargo, Rust’s build tool, for generating an executable. The end result of this process is a single executable embedding a Python interpreter.

Upon successful generation of a binary, the produced binary will be assessed for code signing with the python-executable-creation action.

write_licenses(path)

Writes software component licensing info to the file specified via path.

The file will contain a bill of materials of all software components included in the resulting binary and licensing information related to them. This includes license texts, when available.

Licensing info is best effort.