.. py:currentmodule:: oxidized_importer

.. _oxidized_finder:

===================================
``OxidizedFinder`` Meta Path Finder
===================================

:py:class:`OxidizedFinder` is a Python type implementing a custom and
fully-featured :ref:`meta path finder <oxidized_importer_meta_path_finders>`.
*Oxidized* is in its name because it is implemented in Rust.

Unlike traditional *meta path finders* which have to dynamically
discover resources (often by scanning the filesystem),
:py:class:`OxidizedFinder` instances maintain an *index* of known
resources. When a resource is requested, :py:class:`OxidizedFinder`
can retrieve that resource by effectively performing 1 or 2 lookups
in a Rust ``HashMap``. This makes resource resolution extremely efficient,
as no filesystem probing or other explicit I/O is performed.

Instances of :py:class:`OxidizedFinder` are optionally bound to binary
blobs holding *packed resources data*. This is a custom serialization format
for expressing Python modules (source and bytecode), Python extension
modules, resource files, shared libraries, etc. This data format
along with a Rust library for interacting with it are defined by the
`python-packed-resources <https://crates.io/crates/python-packed-resources>`_
crate.

When an :py:class:`OxidizedFinder` instance is created, the *packed resources
data* is parsed into a Rust data structure. On a modern machine, parsing
this resources data for the entirety of the Python standard library
takes ~1 ms.

:py:class:`OxidizedFinder` instances can index *built-in* extension modules
and *frozen* modules, which are compiled into the Python interpreter. This
allows :py:class:`OxidizedFinder` to subsume functionality normally provided by
the ``BuiltinImporter`` and ``FrozenImporter`` *meta path finders*,
allowing you to potentially replace ``sys.meta_path`` with a single
instance of :py:class:`OxidizedFinder`.

.. _oxidized_finder_in_pyoxidizer:

``OxidizedFinder`` in PyOxidizer Applications
=============================================

When running from an application built with PyOxidizer (or using the
``pyembed`` crate directly), an :py:class:`OxidizedFinder` instance will
(likely) be automatically registered as the first element in
``sys.meta_path`` when starting a Python interpreter.

You can verify this inside a binary built with PyOxidizer::

   >>> import sys
   >>> sys.meta_path
   [<OxidizedFinder object at 0x7f16bb6f93d0>]

Contrast with a typical Python environment::

   >>> import sys
   >>> sys.meta_path
   [
       <class '_frozen_importlib.BuiltinImporter'>,
       <class '_frozen_importlib.FrozenImporter'>,
       <class '_frozen_importlib_external.PathFinder'>
   ]

The :py:class:`OxidizedFinder` instance will (likely) be associated with
resources data embedded in the binary.

This :py:class:`OxidizedFinder` instance is constructed very early during Python
interpreter initialization. It is registered on ``sys.meta_path`` before
the first ``import`` requesting a ``.py``/``.pyc`` is performed, allowing
it to service every ``import`` except those from the very few *built-in
extension modules* that are compiled into the interpreter and loaded as
part of Python initialization (e.g. the ``sys`` module).

If :py:class:`OxidizedFinder` is being installed on ``sys.meta_path``, its
:py:meth:`path_hook <OxidizedFinder.path_hook>` method will be registered
as the first item on ``sys.path_hooks``.

If filesystem importing is disabled, all entries of ``sys.meta_path`` and
``sys.path_hooks`` not related to :py:class:`OxidizedFinder` will be removed.

Python API
==========

See :py:class:`OxidizedFinder` for the Python API documentation.