[Python-checkins] cpython: Issue #26252: Add an example on how to register a finder

[brett.cannon]

https://hg.python.org/cpython/rev/dc24ab548e2b
changeset:   100594:dc24ab548e2b
parent:      100592:6fed752fd88e
user:        Brett Cannon <brett at python.org>
date:        Fri Mar 18 11:54:22 2016 -0700
summary:
  Issue #26252: Add an example on how to register a finder

files:
  Doc/library/importlib.rst |  34 +++++++++++++++++++++++++-
  1 files changed, 32 insertions(+), 2 deletions(-)


diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst
--- a/Doc/library/importlib.rst
+++ b/Doc/library/importlib.rst
@@ -1335,7 +1335,7 @@
   if spec is None:
       print("can't find the itertools module")
   else:
-      # If you chose to perform the actual import.
+      # If you chose to perform the actual import ...
       module = importlib.util.module_from_spec(spec)
       spec.loader.exec_module(module)
       # Adding the module to sys.modules is optional.
@@ -1359,11 +1359,41 @@
   # by name later.
   sys.modules[module_name] = module
 
+For deep customizations of import, you typically want to implement an
+:term:`importer`. This means managing both the :term:`finder` and :term:`loader`
+side of things. For finders there are two flavours to choose from depending on
+your needs: a :term:`meta path finder` or a :term:`path entry finder`. The
+former is what you would put on :attr:`sys.meta_path` while the latter is what
+you create using a :term:`path entry hook` on :attr:`sys.path_hooks` which works
+with :attr:`sys.path` entries to potentially create a finder. This example will
+show you how to register your own importers so that import will use them (for
+creating an importer for yourself, read the documentation for the appropriate
+classes defined within this package)::
+
+  import importlib.machinery
+  import sys
+
+  # For illustrative purposes only.
+  SpamMetaPathFinder = importlib.machinery.PathFinder
+  SpamPathEntryFinder = importlib.machinery.FileFinder
+  loader_details = (importlib.machinery.SourceFileLoader,
+                    importlib.machinery.SOURCE_SUFFIXES)
+
+  # Setting up a meta path finder.
+  # Make sure to put the finder in the proper location in the list in terms of
+  # priority.
+  sys.meta_path.append(SpamMetaPathFinder)
+
+  # Setting up a path entry finder.
+  # Make sure to put the path hook in the proper location in the list in terms
+  # of priority.
+  sys.path_hooks.append(SpamPathEntryFinder.path_hook(loader_details))
+
 Import itself is implemented in Python code, making it possible to
 expose most of the import machinery through importlib. The following
 helps illustrate the various APIs that importlib exposes by providing an
 approximate implementation of
-:func:`importlib.import_module` (Python 3.4 and newer for importlib usage,
+:func:`importlib.import_module` (Python 3.4 and newer for the importlib usage,
 Python 3.6 and newer for other parts of the code).
 ::
 

-- 
Repository URL: https://hg.python.org/cpython