Struct python_packaging::resource_collection::PythonResourceCollector

pub struct PythonResourceCollector { /* fields omitted */ }

Type used to collect Python resources so they can be serialized.

We often want to turn Python resource primitives (module source, bytecode, etc) into a collection of Resource so they can be serialized to the Python packed resources format. This type exists to facilitate doing this.

This type is not only responsible for tracking resources but also for enforcing policies on where those resources can be loaded from and what types of resources are allowed. This includes tracking the licensing metadata for indexed resources.

Implementations

impl PythonResourceCollector

pub fn new(
    allowed_locations: Vec<AbstractResourceLocation>,
    allowed_extension_module_locations: Vec<AbstractResourceLocation>,
    allow_new_builtin_extension_modules: bool,
    allow_files: bool,
    cache_tag: &str
) -> Self

Construct a new instance of the collector.

The instance is associated with a resources policy to validate that added resources conform with rules.

We also pass a Python bytecode cache tag, which is used to derive filenames.

pub fn allowed_locations(&self) -> &Vec<AbstractResourceLocation>

Obtain locations that resources can be loaded from.

pub fn all_top_level_module_names(&self) -> BTreeSet<String>

Obtain a set of all top-level Python module names registered with the collector.

The returned values correspond to packages or single file modules without children modules.

pub fn check_policy(&self, location: AbstractResourceLocation) -> Result<()>

Validate that a resource add in the specified location is allowed.

pub fn filter_resources_mut<F>(&mut self, filter: F) -> Result<()> where
    F: Fn(&PrePackagedResource) -> bool, 

Apply a filter function on resources in this collection and mutate in place.

If the filter function returns true, the item will be preserved.

pub fn iter_resources(
    &self
) -> impl Iterator<Item = (&String, &PrePackagedResource)>

Obtain an iterator over the resources in this collector.

pub fn generate_license_report(&self) -> Result<ResourcesLicenseReport>

Generate a summary of licensing information for resources in the collection.

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

Register a licensed software component to this collection.

pub fn add_python_module_source(
    &mut self,
    module: &PythonModuleSource,
    location: &ConcreteResourceLocation
) -> Result<()>

Add Python module source with a specific location.

pub fn add_python_module_source_with_context(
    &mut self,
    module: &PythonModuleSource,
    add_context: &PythonResourceAddCollectionContext
) -> Result<()>

Add Python module source using an add context to influence operation.

All of the context’s properties are respected. This includes doing nothing if include is false, not adding source if store_source is false, and automatically deriving a bytecode request if the optimize_level_* fields are set.

This method is a glorified proxy to other add_* methods: it simply contains the logic for expanding the context’s wishes into function calls.

pub fn add_python_module_bytecode(
    &mut self,
    module: &PythonModuleBytecode,
    location: &ConcreteResourceLocation
) -> Result<()>

Add Python module bytecode to the specified location.

pub fn add_python_module_bytecode_with_context(
    &mut self,
    module: &PythonModuleBytecode,
    add_context: &PythonResourceAddCollectionContext
) -> Result<()>

Add Python module bytecode using an add context.

This takes the context’s fields into consideration when adding the resource. If include is false, this is a no-op. The context must also have an optimize_level_* field set corresponding with the optimization level of the passed bytecode, or this is a no-op.

pub fn add_python_module_bytecode_from_source(
    &mut self,
    module: &PythonModuleBytecodeFromSource,
    location: &ConcreteResourceLocation
) -> Result<()>

Add Python module bytecode derived from source code to the collection.

pub fn add_python_module_bytecode_from_source_with_context(
    &mut self,
    module: &PythonModuleBytecodeFromSource,
    add_context: &PythonResourceAddCollectionContext
) -> Result<()>

Add Python module bytecode from source using an add context to influence operations.

This method respects the settings of the context, including include and the optimize_level_* fields.

PythonModuleBytecodeFromSource defines an explicit bytecode optimization level, so this method can result in at most 1 bytecode request being added to the collection.

pub fn add_python_package_resource(
    &mut self,
    resource: &PythonPackageResource,
    location: &ConcreteResourceLocation
) -> Result<()>

Add resource data to a given location.

Resource data belongs to a Python package and has a name and bytes data.

pub fn add_python_package_resource_with_context(
    &mut self,
    resource: &PythonPackageResource,
    add_context: &PythonResourceAddCollectionContext
) -> Result<()>

Add a Python package resource using an add context.

The fields from the context will be respected. This includes not doing anything if include is false.

pub fn add_python_package_distribution_resource(
    &mut self,
    resource: &PythonPackageDistributionResource,
    location: &ConcreteResourceLocation
) -> Result<()>

Add a Python package distribution resource to a given location.

pub fn add_python_package_distribution_resource_with_context(
    &mut self,
    resource: &PythonPackageDistributionResource,
    add_context: &PythonResourceAddCollectionContext
) -> Result<()>

Add a Python package distribution resource using an add context.

The fields from the context will be respected. This includes not doing anything if include is false.

pub fn add_python_extension_module_with_context(
    &mut self,
    extension_module: &PythonExtensionModule,
    add_context: &PythonResourceAddCollectionContext
) -> Result<Option<LibPythonBuildContext>>

Add a Python extension module using an add context.

pub fn add_builtin_python_extension_module(
    &mut self,
    module: &PythonExtensionModule
) -> Result<()>

Add a built-in extension module.

Built-in extension modules are statically linked into the binary and cannot have their location defined.

pub fn add_python_extension_module(
    &mut self,
    module: &PythonExtensionModule,
    location: &ConcreteResourceLocation
) -> Result<()>

Add a Python extension module shared library that should be imported from memory.

pub fn add_shared_library(
    &mut self,
    library: &SharedLibrary,
    location: &ConcreteResourceLocation
) -> Result<()>

Add a shared library to be loaded from a location.

pub fn add_file_data(
    &mut self,
    file: &File,
    location: &ConcreteResourceLocation
) -> Result<()>

pub fn add_file_data_with_context(
    &mut self,
    file: &File,
    add_context: &PythonResourceAddCollectionContext
) -> Result<()>

pub fn find_dunder_file(&self) -> Result<BTreeSet<String>>

Searches for Python sources for references to file.

file usage can be problematic for in-memory modules. This method searches for its occurrences and returns module names having it present.

pub fn compile_resources(
    &self,
    compiler: &mut dyn PythonBytecodeCompiler
) -> Result<CompiledResourcesCollection<'_>>

Compiles resources into a finalized collection.

This will take all resources collected so far and convert them into a collection of Resource plus extra file install rules.

Missing parent packages will be added automatically.

Trait Implementations

impl Clone for PythonResourceCollector

fn clone(&self) -> PythonResourceCollector

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PythonResourceCollector

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.