A `meta path finder`_ that resolves indexed resources. See
See :ref:`oxidized_finder` for more high-level documentation.

This type implements the following interfaces:

* ``importlib.abc.MetaPathFinder``
* ``importlib.abc.Loader``
* ``importlib.abc.InspectLoader``
* ``importlib.abc.ExecutionLoader``

See the `importlib.abc documentation <https://docs.python.org/3/library/importlib.html#module-importlib.abc>`_
for more on these interfaces.

In addition to the methods on the above interfaces, the following methods
defined elsewhere in ``importlib`` are exposed:

* ``get_resource_reader(fullname: str) -> importlib.abc.ResourceReader``
* ``find_distributions(context: Optional[DistributionFinder.Context]) -> [Distribution]``

``ResourceReader`` is documented alongside other ``importlib.abc`` interfaces.
``find_distribution()`` is documented in
`importlib.metadata <https://docs.python.org/3/library/importlib.metadata.html>`_.

Instances have additional functionality beyond what is defined by
``importlib``. This functionality allows you to construct, inspect, and
manipulate instances.

.. py:attribute:: multiprocessing_set_start_method

    (``Opional[str]``) Value to pass to :py:func:`multiprocessing.set_start_method` on
    import of :py:mod:`multiprocessing` module.

    ``None`` means the method won't be called.

.. py:attribute:: origin

    (``str``) The path this instance is using as the anchor for relative path
    references.

.. py:attribute:: path_hook_base_str

    (``str``) The base path that the path hook handler on this instance
    will respond to.

    This value is often the same as ``sys.executable`` but isn't guaranteed
    to be that exact value.

.. py:attribute:: pkg_resources_import_auto_register

   (``bool``) Whether this instance will be registered via
   ``pkg_resources.register_finder()`` upon this instance importing the
   ``pkg_resources`` module.

.. py:method:: __new__(cls, relative_path_origin: Optional[os.PathLike]) -> OxidizedFinder

    Construct a new instance of :py:class:`OxidizedFinder`.

    New instances of :py:class:`OxidizedFinder` can be constructed like
    normal Python types:

    .. code-block:: python

        finder = OxidizedFinder()

    The constructor takes the following named arguments:

    ``relative_path_origin``
         A path-like object denoting the filesystem path that should be used as the
         *origin* value for relative path resources. Filesystem-based resources are
         stored as a relative path to an *anchor* value. This is that *anchor* value.
         If not specified, the directory of the current executable will be used.

    See the `python_packed_resources <https://docs.rs/python-packed-resources/0.1.0/python_packed_resources/>`_
    Rust crate for the specification of the binary data blob defining *packed
    resources data*.

    .. important::

        The *packed resources data* format is still evolving. It is recommended
        to use the same version of the ``oxidized_importer`` extension to
        produce and consume this data structure to ensure compatibility.

.. py:method:: index_bytes(data: bytes) -> None

    This method parses any bytes-like object and indexes the resources within.

.. py:method:: index_file_memory_mapped(path: pathlib.Path) -> None

    This method parses the given Path-like argument and indexes the resources
    within. Memory mapped I/O is used to read the file. Rust managed the
    memory map via the ``memmap`` crate: this does not use the Python
    interpreter's memory mapping code.

.. py:method:: index_interpreter_builtins() -> None

    This method indexes Python resources that are built-in to the Python
    interpreter itself. This indexes built-in extension modules and frozen
    modules.

.. py:method:: index_interpreter_builtin_extension_modules() -> None

    This method will index Python extension modules that are compiled into
    the Python interpreter itself.

.. py:method:: index_interpreter_frozen_modules() -> None

    This method will index Python modules whose bytecode is frozen into
    the Python interpreter itself.

.. py:method:: indexed_resources() -> List[OxidizedResource]

    This method returns a list of resources that are indexed by the
    instance. It allows Python code to inspect what the finder knows about.

    Any mutations to returned values are not reflected in the finder.

    See :ref:`oxidized_resource` for more on the returned type.

.. py:method:: add_resource(resource: OxidizedResource)

    This method registers an :ref:`oxidized_resource` instance with the finder,
    enabling the finder to use it to service lookups.

    When an ``OxidizedResource`` is registered, its data is copied into the
    finder instance. So changes to the original ``OxidizedResource`` are not
    reflected on the finder. (This is because :py:class:`OxidizedFinder`
    maintains an index and it is important for the data behind that index to
    not change out from under it.)

    Resources are stored in an invisible hash map where they are indexed by
    the ``name`` attribute. When a resource is added, any existing resource
    under the same name has its data replaced by the incoming
    ``OxidizedResource`` instance.

    If you have source code and want to produce bytecode, you can do something
    like the following:

    .. code-block:: python

        def register_module(finder, module_name, source):
            code = compile(source, module_name, "exec")
            bytecode = marshal.dumps(code)

            resource = OxidizedResource()
            resource.name = module_name
            resource.is_module = True
            resource.in_memory_bytecode = bytecode
            resource.in_memory_source = source

            finder.add_resource(resource)

.. py:method:: add_resources(resources: List[OxidizedResource]

    This method is syntactic sugar for calling ``add_resource()`` for every
    item in an iterable. It is exposed because function call overhead in Python
    can be non-trivial and it can be quicker to pass in an iterable of
    ``OxidizedResource`` than to call ``add_resource()`` potentially hundreds
    of times.

.. py:method:: serialize_indexed_resources(ignore_builtin=true, ignore_frozen=true) -> bytes

    This method serializes all resources currently indexed by the instance
    into an opaque ``bytes`` instance. The returned data can be fed into a
    separate :py:class:`OxidizedFinder` instance by passing it to
    :py:meth:`OxidizedFinder.__new__`.

    Arguments:

    ``ignore_builtin`` (bool)
       Whether to ignore ``builtin`` extension modules from the serialized data.

       Default is ``True``

    ``ignore_frozen`` (bool)
       Whether to ignore ``frozen`` extension modules from the serialized data.

       Default is ``True``.

    Entries for *built-in* and *frozen* modules are ignored by default because
    they aren't portable, as they are compiled into the interpreter and aren't
    guaranteed to work from one Python interpreter to another. The serialized
    format does support expressing them. Use at your own risk.

.. py:method:: path_hook(path: Union[str, bytes, os.PathLike[AnyStr]]) -> OxidizedPathEntryFinder

    Implements a *path hook* for obtaining a
    `PathEntryFinder <https://docs.python.org/3/library/importlib.html#importlib.abc.PathEntryFinder>`_
    from a ``sys.path`` entry. See :ref:`oxidized_finder_path_hooks` for details.

    Raises ``ImportError`` if the given path isn't serviceable. The exception
    should have ``.__cause__`` set to an inner exception with more details on why
    the path was rejected.

  :classmethod:

  Resolve the instance for the given package name.

  :classmethod:

  Resolve instances for all known packages.

  Attempt to read metadata file given its filename.

  :type: email.message.EmailMessage

  Return the parsed metadata for this distribution.

  :type: str

  Return the ``Name`` metadata for this distribution package.

  :type: str

  Return the normalized version of the ``Name``.

  :type: str

  Return the ``Version`` metadata for this distribution package.

 Resolve entry points for this distribution package.

  Not implemented. Always raises when called.

  Generated requirements specified for this distribution.

  Search for modules visible to the instance.

  Invoke the same method on the :py:class:`OxidizedFinder` instance with
  which the :class:`OxidizedPathEntryFinder` instance was constructed.

  Iterate over the visible modules. This method complies with
  ``pkgutil.iter_modules``'s protocol.

  Returns a ``list`` instead of a generator.

  Always raises ``NotImplementedError``.

  Please leave a comment in
  `#384 <https://github.com/indygreg/PyOxidizer/issues/384>`_ if you would like
  this functionality implemented.

  Always raises ``NotImplementedError``.

  This behavior appears to be allowed given code in ``pkg_resources``.
  However, it means that ``pkg_resources.resource_filename()`` will not
  work. Please leave a comment in
  `#383 <https://github.com/indygreg/PyOxidizer/issues/383>`_ if you would like
  this functionality implemented.

  Returns a ``list`` instead of a generator.

  A ``bool`` indicating if this resource is a Python module. Python modules
  are backed by source or bytecode.

  A ``bool`` indicating if this resource is a Python extension module
  built-in to the Python interpreter.

  A ``bool`` indicating if this resource is a Python module whose bytecode
  is frozen into the Python interpreter.

  A ``bool`` indicating if this resource is a Python extension module.

  A ``bool`` indicating if this resource is a shared library.

  The ``str`` name of the resource.

  A ``bool`` indicating if this resource is a Python package.

  A ``bool`` indicating if this resource is a Python namespace package.

  ``bytes`` or ``None`` holding Python module source code that should be
  imported from memory.

  ``bytes`` or ``None`` 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.

  ``bytes`` or ``None`` 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.

  ``bytes`` or ``None`` 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.

  ``bytes`` or ``None`` holding native machine code defining a Python extension
  module shared library that should be imported from memory.

  ``dict[str, bytes]`` or ``None`` holding resource files to make available to
  the ``importlib.resources`` APIs via in-memory data access. The ``name`` of
  this object will be a Python package name. Keys in this dict are virtual
  filenames under that package. Values are raw file data.

  ``dict[str, bytes]`` or ``None`` holding resource files to make available to
  the ``importlib.metadata`` API via in-memory data access. The ``name`` of
  this object will be a Python package name. Keys in this dict are virtual
  filenames. Values are raw file data.

  ``bytes`` or ``None`` holding a shared library that should be imported from
  memory.

  ``list[str]`` or ``None`` 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.

  ``pathlib.Path`` or ``None`` holding the relative path to Python module
  source that should be imported from the filesystem.

  ``pathlib.Path`` or ``None`` holding the relative path to Python module
  bytecode that should be imported from the filesystem.

  ``pathlib.Path`` or ``None`` holding the relative path to Python module
  bytecode at optimization level 1 that should be imported from the filesystem.

  ``pathlib.Path`` or ``None`` holding the relative path to Python module
  bytecode at optimization level 2 that should be imported from the filesystem.

  ``pathlib.Path`` or ``None`` holding the relative path to a Python extension
  module that should be imported from the filesystem.

  ``dict[str, pathlib.Path]`` or ``None`` holding resource files to make
  available to the ``importlib.resources`` APIs via filesystem access. The
  ``name`` 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.

  ``dict[str, pathlib.Path]`` or ``None`` holding resource files to make
  available to the ``importlib.metadata`` APIs via filesystem access. The
  ``name`` 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.

  Construct an instance by defining locations that resources can be loaded
  from.

  The accepted string values are ``in-memory`` and ``filesystem-relative``.

  (``list[str]``) Exposes allowed locations where resources can be loaded from.

  Adds a Python resource type (:py:class:`PythonModuleSource`,
  :py:class:`PythonModuleBytecode`, etc) to the collector and marks it for
  loading via in-memory mechanisms.

  Adds a Python resource type (:py:class:`PythonModuleSource`,
  :py:class:`PythonModuleBytecode`, etc) to the collector and marks it for
  loading via a relative path next to some *origin* path (as specified to the
  :py:class:`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``.

  Takes all the resources collected so far and turns them into data
  structures to facilitate later use.

  The first element in the returned tuple is a list of
  :py:class:`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.

  Construct an instance from zip archive data.

  The source argument can be any bytes-like object. A reference to the
  original Python object will be kept and zip I/O will be performed against
  the memory tracked by that object. It is possible to trigger an
  out-of-bounds memory read if the source object is mutated after being
  passed into this function.

  The ``path`` argument denotes the path to the zip archive. This path will
  be advertised in ``__file__`` attributes. If not defined, the path of the
  current executable will be used.

  Construct an instance from a filesystem path.

  The source represents the path to a file containing zip archive data.
  The file will be opened using Rust file I/O. The content of the file
  will be read lazily.

  If you don't already have a copy of the zip data and the zip file will
  be immutable for the lifetime of the constructed instance, this method
  may yield better performance than opening the file, reading its content,
  and calling :py:meth:`OxidizedZipFinder.from_zip_data` because it may
  incur less overall I/O.

  (``str``) The fully qualified Python module name. e.g.
  ``my_package.foo``.

  (``bytes``) The source code of the Python module.

  Note that source code is stored as ``bytes``, not ``str``. Most Python
  source is stored as ``utf-8``, so you can ``.encode("utf-8")`` or
  ``.decode("utf-8")`` to convert between ``bytes`` and ``str``.

  (``bool``) Whether this module is a Python package.

  (``str``) The fully qualified Python module name.

  (``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.

  (``int``) The bytecode optimization level. Either ``0``, ``1``, or ``2``.

  (``bool``) Whether this module is a Python package.

  (``str``) The name of the leaf-most Python package this resource is
  associated with.

  With :py:class:`OxidizedFinder`, an ``importlib.abc.ResourceReader``
  associated with this package will be used to load the resource.

  (``str``) The name of the resource within its ``package``. This is
  typically the filename of the resource. e.g. ``resource.txt`` or
  ``child/foo.png``.

  (``bytes``) The raw binary content of the resource.

  (``str``) The name of the Python package this resource is associated with.

  (``str``) Version string of Python package this resource is associated with.

  (``str``) The name of the resource within the metadata distribution. This
  is typically the filename of the resource. e.g. ``METADATA``.

  (``bytes``) The raw binary content of the resource.

  (``str``) The name of the extension module.