oxidized_importer
Python Resource Types¶
The oxidized_importer
module defines Python types beyond
OxidizedFinder
. This page documents those types and their APIs.
Important
All types are backed by Rust structs and all properties return copies of the data. This means that if you mutate a Python variable that was obtained from an instance’s property, that mutation won’t be reflected in the backing Rust struct.
OxidizedResource
¶
The OxidizedResource
Python type represents a resource that is indexed
by a OxidizedFinder
instance.
Each instance represents a named entity with associated metadata and data. e.g. an instance can represent a Python module with associated source and bytecode.
New instances can be constructed via OxidizedResource()
. This will return
an instance whose name = ""
and all properties will be None
or
false
.
Properties¶
The following properties/attributes exist on OxidizedResource
instances:
is_module
A
bool
indicating if this resource is a Python module. Python modules are backed by source or bytecode.is_builtin_extension_module
A
bool
indicating if this resource is a Python extension module built-in to the Python interpreter.is_frozen_module
A
bool
indicating if this resource is a Python module whose bytecode is frozen into the Python interpreter.is_extension_module
A
bool
indicating if this resource is a Python extension module.is_shared_library
A
bool
indicating if this resource is a shared library.name
The
str
name of the resource.is_package
A
bool
indicating if this resource is a Python package.is_namespace_package
A
bool
indicating if this resource is a Python namespace package.in_memory_source
bytes
orNone
holding Python module source code that should be imported from memory.in_memory_bytecode
bytes
orNone
holding Python module bytecode that should be imported from memory.This is raw Python bytecode, as produced from the
marshal
module..pyc
files have a header before this data that will need to be stripped should you want to move data from a.pyc
file into this field.in_memory_bytecode_opt1
bytes
orNone
holding Python module bytecode at optimization level 1 that should be imported from memory.This is raw Python bytecode, as produced from the
marshal
module..pyc
files have a header before this data that will need to be stripped should you want to move data from a.pyc
file into this field.in_memory_bytecode_opt2
bytes
orNone
holding Python module bytecode at optimization level 2 that should be imported from memory.This is raw Python bytecode, as produced from the
marshal
module..pyc
files have a header before this data that will need to be stripped should you want to move data from a.pyc
file into this field.in_memory_extension_module_shared_library
bytes
orNone
holding native machine code defining a Python extension module shared library that should be imported from memory.in_memory_package_resources
dict[str, bytes]
orNone
holding resource files to make available to theimportlib.resources
APIs via in-memory data access. Thename
of this object will be a Python package name. Keys in this dict are virtual filenames under that package. Values are raw file data.in_memory_distribution_resources
dict[str, bytes]
orNone
holding resource files to make available to theimportlib.metadata
API via in-memory data access. Thename
of this object will be a Python package name. Keys in this dict are virtual filenames. Values are raw file data.in_memory_shared_library
bytes
orNone
holding a shared library that should be imported from memory.shared_library_dependency_names
list[str]
orNone
holding the names of shared libraries that this resource depends on. If this resource defines a loadable shared library, this list can be used to express what other shared libraries it depends on.relative_path_module_source
pathlib.Path
orNone
holding the relative path to Python module source that should be imported from the filesystem.relative_path_module_bytecode
pathlib.Path
orNone
holding the relative path to Python module bytecode that should be imported from the filesystem.relative_path_module_bytecode_opt1
pathlib.Path
orNone
holding the relative path to Python module bytecode at optimization level 1 that should be imported from the filesystem.relative_path_module_bytecode_opt1
pathlib.Path
orNone
holding the relative path to Python module bytecode at optimization level 2 that should be imported from the filesystem.relative_path_extension_module_shared_library
pathlib.Path
orNone
holding the relative path to a Python extension module that should be imported from the filesystem.relative_path_package_resources
dict[str, pathlib.Path]
orNone
holding resource files to make available to theimportlib.resources
APIs via filesystem access. Thename
of this object will be a Python package name. Keys in this dict are filenames under that package. Values are relative paths to files from which to read data.relative_path_distribution_resources
dict[str, pathlib.Path]
orNone
holding resource files to make available to theimportlib.metadata
APIs via filesystem access. Thename
of this object will be a Python package name. Keys in this dict are filenames under that package. Values are relative paths to files from which to read data.
OxidizedResource
Resource Types¶
Each OxidizedResource
instance describes a particular type of resource.
If a resource identifies as a type, it sets one of the following is_*
attributes to True
:
is_module
A Python module. These typically have source or bytecode attached.
Modules can also be packages. In this case, they can hold additional data, such as a mapping of resource files.
is_builtin_extension_module
A built-in extension module. These represent Python extension modules that are compiled into the application and don’t exist as separate shared libraries.
is_frozen_module
A frozen Python module. These are Python modules whose bytecode is compiled into the application.
is_extension_module
A Python extension module. These are shared libraries that can be loaded to provide additional modules to Python.
is_shared_library
A shared library. e.g. a
.so
or.dll
.
PythonModuleSource
¶
The oxidized_importer.PythonModuleSource
type represents Python module
source code. e.g. a .py
file.
Instances have the following properties:
module
(str
)The fully qualified Python module name. e.g.
my_package.foo
.source
(bytes
)The source code of the Python module.
Note that source code is stored as
bytes
, notstr
. Most Python source is stored asutf-8
, so you can.encode("utf-8")
or.decode("utf-8")
to convert betweenbytes
andstr
.is_package
(bool
)This this module is a Python package.
PythonModuleBytecode
¶
The oxidized_importer.PythonModuleBytecode
type represents Python
module bytecode. e.g. what a .pyc
file holds (but without the header
that a .pyc
file has).
Instances have the following properties:
module
(str
)The fully qualified Python module name.
bytecode
(bytes
)The bytecode of the Python module.
This is what you would get by compiling Python source code via something like
marshal.dumps(compile(source, "exe"))
. The bytecode does not contain a header, like what would be found in a.pyc
file.optimize_level
(int
)The bytecode optimization level. Either
0
,1
, or2
.is_package
(bool
)Whether this module is a Python package.
PythonExtensionModule
¶
The oxidized_importer.PythonExtensionModule
type represents a
Python extension module. This is a shared library defining a Python
extension implemented in native machine code that can be loaded into
a process and defines a Python module. Extension modules are typically
defined by .so
, .dylib
, or .pyd
files.
Instances have the following properties:
name
(str
)The name of the extension module.
Note
Properties of this type are read-only.
PythonPackageResource
¶
The oxidized_importer.PythonPackageResource
type represents a non-module
resource file. These are files that live next to Python modules that
are typically accessed via the APIs in importlib.resources
.
Instances have the following properties:
package
(str
)The name of the leaf-most Python package this resource is associated with.
With
OxidizedFinder
, animportlib.abc.ResourceReader
associated with this package will be used to load the resource.name
(str
)The name of the resource within its
package
. This is typically the filename of the resource. e.g.resource.txt
orchild/foo.png
.data
(bytes
)The raw binary content of the resource.
PythonPackageDistributionResource
¶
The oxidized_importer.PythonPackageDistributionResource
type represents
a non-module resource file living in a package distribution directory
(e.g. <package>-<version>.dist-info
or <package>-<version>.egg-info
).
These resources are typically accessed via the APIs in importlib.metadata
.
Instances have the following properties:
package
(str
)The name of the Python package this resource is associated with.
version
(str
)Version string of Python package this resource is associated with.
name
(str
)The name of the resource within the metadata distribution. This is typically the filename of the resource. e.g.
METADATA
.data
(bytes
)The raw binary content of the resource.