Resource Scanning APIs

The oxidized_importer module exposes functions and Python types to facilitate scanning for and collecting Python resources.

find_resources_in_path(path)

The oxidized_importer.find_resources_in_path() function will scan the specified filesystem path and return an iterable of objects representing found resources. Those objects will be 1 of the types documented in oxidized_importer Python Resource Types.

Only directories can be scanned.

To discover all filesystem based resources that Python’s PathFinder meta path finder would (with the exception of .zip files), try the following:

import os
import oxidized_importer
import sys

resources = []
for path in sys.path:
    if os.path.isdir(path):
        resources.extend(oxidized_importer.find_resources_in_path(path))

OxidizedResourceCollector Python Type

The oxidized_importer.OxidizedResourceCollector type provides functionality for turning instances of Python resource types into a collection of OxidizedResource for loading into an OxidizedFinder instance. It exists as a convenience, as working with individual OxidizedResource instances can be rather cumbersome.

Instances can be constructed by passing an allowed_locations=<list[str]> argument defining locations that resources can be loaded from. The accepted string values are in-memory and filesystem-relative.

e.g. to create a collector that only marks resources for in-memory loading:

import oxidized_importer

collector = oxidized_importer.OxidizedResourceCollector(
    allowed_locations=["in-memory"]
)

Instances of OxidizedResourceCollector have the following properties:

allowed_locations (list[str])

Exposes allowed locations where resources can be loaded from.

Methods are documented in the following sections.

add_in_memory(resource)

OxidizedResourceCollector.add_in_memory(resource) adds a Python resource type (PythonModuleSource, PythonModuleBytecode, etc) to the collector and marks it for loading via in-memory mechanisms.

add_filesystem_relative(prefix, resource)

OxidizedResourceCollector.add_filesystem_relative(prefix, resource) adds a Python resource type (PythonModuleSource, PythonModuleBytecode, etc) to the collector and marks it for loading via a relative path next to some origin path (as specified to the OxidizedFinder). That relative path can have a prefix value prepended to it. If no prefix is desired and you want the resource placed next to the origin, use an empty str for prefix.

oxidize()

OxidizedResourceCollector.oxidize() takes all the resources collected so far and turns them into data structures to facilitate later use.

The return value is a tuple of (List[OxidizedResource], List[Tuple[pathlib.Path, bytes, bool]]).

The first element in the tuple is a list of OxidizedResource instances.

The second is a list of 3-tuples containing the relative filesystem path for a file, the content to write to that path, and whether the file should be marked as executable.