Trait PythonBinaryBuilder

pub trait PythonBinaryBuilder {
    // Required methods
    fn clone_trait(&self) -> Arc<dyn PythonBinaryBuilder>;
    fn name(&self) -> String;
    fn libpython_link_mode(&self) -> LibpythonLinkMode;
    fn target_triple(&self) -> &str;
    fn vc_runtime_requirements(
        &self,
    ) -> Option<(String, VcRedistributablePlatform)>;
    fn cache_tag(&self) -> &str;
    fn python_packaging_policy(&self) -> &PythonPackagingPolicy;
    fn host_python_exe_path(&self) -> &Path;
    fn target_python_exe_path(&self) -> &Path;
    fn apple_sdk_info(&self) -> Option<&AppleSdkInfo>;
    fn windows_runtime_dlls_mode(&self) -> &WindowsRuntimeDllsMode;
    fn set_windows_runtime_dlls_mode(&mut self, value: WindowsRuntimeDllsMode);
    fn tcl_files_path(&self) -> &Option<String>;
    fn set_tcl_files_path(&mut self, value: Option<String>);
    fn windows_subsystem(&self) -> &str;
    fn set_windows_subsystem(&mut self, value: &str) -> Result<()>;
    fn licenses_filename(&self) -> Option<&str>;
    fn set_licenses_filename(&mut self, value: Option<String>);
    fn packed_resources_load_mode(&self) -> &PackedResourcesLoadMode;
    fn set_packed_resources_load_mode(
        &mut self,
        load_mode: PackedResourcesLoadMode,
    );
    fn iter_resources<'a>(
        &'a self,
    ) -> Box<dyn Iterator<Item = (&'a String, &'a PrePackagedResource)> + 'a>;
    fn index_package_license_info_from_resources<'a>(
        &mut self,
        resources: &[PythonResource<'a>],
    ) -> Result<()>;
    fn pip_download(
        &mut self,
        env: &Environment,
        verbose: bool,
        args: &[String],
    ) -> Result<Vec<PythonResource<'_>>>;
    fn pip_install(
        &mut self,
        env: &Environment,
        verbose: bool,
        install_args: &[String],
        extra_envs: &HashMap<String, String>,
    ) -> Result<Vec<PythonResource<'_>>>;
    fn read_package_root(
        &mut self,
        path: &Path,
        packages: &[String],
    ) -> Result<Vec<PythonResource<'_>>>;
    fn read_virtualenv(
        &mut self,
        path: &Path,
    ) -> Result<Vec<PythonResource<'_>>>;
    fn setup_py_install(
        &mut self,
        env: &Environment,
        package_path: &Path,
        verbose: bool,
        extra_envs: &HashMap<String, String>,
        extra_global_arguments: &[String],
    ) -> Result<Vec<PythonResource<'_>>>;
    fn add_distribution_resources(
        &mut self,
        callback: Option<ResourceAddCollectionContextCallback<'_>>,
    ) -> Result<Vec<AddResourceAction>>;
    fn add_python_module_source(
        &mut self,
        module: &PythonModuleSource,
        add_context: Option<PythonResourceAddCollectionContext>,
    ) -> Result<Vec<AddResourceAction>>;
    fn add_python_package_resource(
        &mut self,
        resource: &PythonPackageResource,
        add_context: Option<PythonResourceAddCollectionContext>,
    ) -> Result<Vec<AddResourceAction>>;
    fn add_python_package_distribution_resource(
        &mut self,
        resource: &PythonPackageDistributionResource,
        add_context: Option<PythonResourceAddCollectionContext>,
    ) -> Result<Vec<AddResourceAction>>;
    fn add_python_extension_module(
        &mut self,
        extension_module: &PythonExtensionModule,
        add_context: Option<PythonResourceAddCollectionContext>,
    ) -> Result<Vec<AddResourceAction>>;
    fn add_file_data(
        &mut self,
        file: &File,
        add_context: Option<PythonResourceAddCollectionContext>,
    ) -> Result<Vec<AddResourceAction>>;
    fn filter_resources_from_files(
        &mut self,
        files: &[&Path],
        glob_patterns: &[&str],
    ) -> Result<()>;
    fn requires_jemalloc(&self) -> bool;
    fn requires_mimalloc(&self) -> bool;
    fn requires_snmalloc(&self) -> bool;
    fn licensed_components(&self) -> Result<LicensedComponents>;
    fn add_licensed_component(
        &mut self,
        component: LicensedComponent,
    ) -> Result<()>;
    fn to_embedded_python_context(
        &self,
        env: &Environment,
        opt_level: &str,
    ) -> Result<EmbeddedPythonContext<'_>>;
}

Describes a generic way to build a Python binary.

Binary here means an executable or library containing or linking to a Python interpreter. It also includes embeddable resources within that binary.

Concrete implementations can be turned into build artifacts or binaries themselves.

Required Methods

fn clone_trait(&self) -> Arc<dyn PythonBinaryBuilder>

Clone self into a Box’ed trait object.

fn name(&self) -> String

The name of the binary.

fn libpython_link_mode(&self) -> LibpythonLinkMode

How the binary will link against libpython.

fn target_triple(&self) -> &str

Rust target triple the binary will run on.

fn vc_runtime_requirements(&self) -> Option<(String, VcRedistributablePlatform)>

Obtain run-time requirements for the Visual C++ Redistributable.

If None, there is no dependency on vcruntimeXXX.dll files. If Some, the returned tuple declares the VC++ Redistributable major version string (e.g. 14) and the VC++ Redistributable platform variant that is required.

fn cache_tag(&self) -> &str

Obtain the cache tag to apply to Python bytecode modules.

fn python_packaging_policy(&self) -> &PythonPackagingPolicy

Obtain the PythonPackagingPolicy for the builder.

fn host_python_exe_path(&self) -> &Path

Path to Python executable that can be used to derive info at build time.

The produced binary is effectively a clone of the Python distribution behind the returned executable.

fn target_python_exe_path(&self) -> &Path

Path to Python executable that is native to the target architecture.

fn apple_sdk_info(&self) -> Option<&AppleSdkInfo>

Apple SDK build/targeting information.

fn windows_runtime_dlls_mode(&self) -> &WindowsRuntimeDllsMode

Obtain how Windows runtime DLLs will be handled during builds.

See the enum’s documentation for behavior.

This setting is ignored for binaries that don’t need the Windows runtime DLLs.

fn set_windows_runtime_dlls_mode(&mut self, value: WindowsRuntimeDllsMode)

Set the value for windows_runtime_dlls_mode().

fn tcl_files_path(&self) -> &Option<String>

The directory to install tcl/tk files into.

fn set_tcl_files_path(&mut self, value: Option<String>)

Set the directory to install tcl/tk files into.

fn windows_subsystem(&self) -> &str

The value of the windows_subsystem Rust attribute for the generated Rust project.

fn set_windows_subsystem(&mut self, value: &str) -> Result<()>

Set the value of the windows_subsystem Rust attribute for generated Rust projects.

fn licenses_filename(&self) -> Option<&str>

Obtain the path of a filename to write containing a licensing report.

fn set_licenses_filename(&mut self, value: Option<String>)

Set the path of a filename to write containing a licensing report.

fn packed_resources_load_mode(&self) -> &PackedResourcesLoadMode

How packed Python resources will be loaded by the binary.

fn set_packed_resources_load_mode(&mut self, load_mode: PackedResourcesLoadMode)

Set how packed Python resources will be loaded by the binary.

fn iter_resources<'a>( &'a self, ) -> Box<dyn Iterator<Item = (&'a String, &'a PrePackagedResource)> + 'a>

Obtain an iterator over all resource entries that will be embedded in the binary.

This likely does not return extension modules that are statically linked into the binary. For those, see builtin_extension_module_names().

fn index_package_license_info_from_resources<'a>( &mut self, resources: &[PythonResource<'a>], ) -> Result<()>

Resolve license metadata from an iterable of PythonResource and store that data.

The resolved license data can later be used to ensure packages conform to license restrictions. This method can safely be called on resources that aren’t added to the instance / resource collector: it simply registers the license metadata so it can be consulted later.

fn pip_download( &mut self, env: &Environment, verbose: bool, args: &[String], ) -> Result<Vec<PythonResource<'_>>>

Runs pip download using the binary builder’s settings.

Returns resources discovered from the Python packages downloaded.

fn pip_install( &mut self, env: &Environment, verbose: bool, install_args: &[String], extra_envs: &HashMap<String, String>, ) -> Result<Vec<PythonResource<'_>>>

Runs pip install using the binary builder’s settings.

Returns resources discovered as part of performing an install.

fn read_package_root( &mut self, path: &Path, packages: &[String], ) -> Result<Vec<PythonResource<'_>>>

Reads Python resources from the filesystem.

fn read_virtualenv(&mut self, path: &Path) -> Result<Vec<PythonResource<'_>>>

Read Python resources from a populated virtualenv directory.

fn setup_py_install( &mut self, env: &Environment, package_path: &Path, verbose: bool, extra_envs: &HashMap<String, String>, extra_global_arguments: &[String], ) -> Result<Vec<PythonResource<'_>>>

Runs python setup.py install using the binary builder’s settings.

Returns resources discovered as part of performing an install.

fn add_distribution_resources( &mut self, callback: Option<ResourceAddCollectionContextCallback<'_>>, ) -> Result<Vec<AddResourceAction>>

Add resources from the Python distribution to the builder.

This method should likely be called soon after object construction in order to finish adding state from the Python distribution to the builder.

The boundary between what distribution state should be initialized at binary construction time versus this method is not well-defined and is up to implementations. However, it is strongly recommended for the division to be handling of core/required interpreter state at construction time and all optional/standard library state in this method.

callback defines an optional function which can be called between resource creation and adding that resource to the builder. This gives the caller an opportunity to influence how resources are added to the binary builder.

fn add_python_module_source( &mut self, module: &PythonModuleSource, add_context: Option<PythonResourceAddCollectionContext>, ) -> Result<Vec<AddResourceAction>>

Add a PythonModuleSource to the resources collection.

The location to load the resource from is optional. If specified, it will be used. If not, an appropriate location based on the resources policy will be chosen.

fn add_python_package_resource( &mut self, resource: &PythonPackageResource, add_context: Option<PythonResourceAddCollectionContext>, ) -> Result<Vec<AddResourceAction>>

Add a PythonPackageResource to the resources collection.

The location to load the resource from is optional. If specified, it will be used. If not, an appropriate location based on the resources policy will be chosen.

fn add_python_package_distribution_resource( &mut self, resource: &PythonPackageDistributionResource, add_context: Option<PythonResourceAddCollectionContext>, ) -> Result<Vec<AddResourceAction>>

Add a PythonPackageDistributionResource to the resources collection.

The location to load the resource from is optional. If specified, it will be used. If not, an appropriate location based on the resources policy will be chosen.

fn add_python_extension_module( &mut self, extension_module: &PythonExtensionModule, add_context: Option<PythonResourceAddCollectionContext>, ) -> Result<Vec<AddResourceAction>>

Add a PythonExtensionModule to make available.

The location to load the extension module from can be specified. However, different builders have different capabilities. And the location may be ignored in some cases. For example, when adding an extension module that is compiled into libpython itself, the location will always be inside libpython and it isn’t possible to materialize the extension module as a standalone file.

fn add_file_data( &mut self, file: &File, add_context: Option<PythonResourceAddCollectionContext>, ) -> Result<Vec<AddResourceAction>>

Add a File to the resource collection.

fn filter_resources_from_files( &mut self, files: &[&Path], glob_patterns: &[&str], ) -> Result<()>

Filter embedded resources against names in files.

files is files to read names from.

glob_patterns is file patterns of files to read names from.

fn requires_jemalloc(&self) -> bool

Whether the binary requires the jemalloc library.

fn requires_mimalloc(&self) -> bool

Whether the binary requires the Mimalloc library.

fn requires_snmalloc(&self) -> bool

Whether the binary requires the Snmalloc library.

fn licensed_components(&self) -> Result<LicensedComponents>

Obtain software licensing information.

fn add_licensed_component(&mut self, component: LicensedComponent) -> Result<()>

Add a licensed software component to the instance.

Calling this effectively conveys that the software will be built into the final binary and its licensing should be captured in order to generate a licensing report.

fn to_embedded_python_context( &self, env: &Environment, opt_level: &str, ) -> Result<EmbeddedPythonContext<'_>>

Obtain an EmbeddedPythonContext instance from this one.

Implementors

impl PythonBinaryBuilder for StandalonePythonExecutableBuilder