[Python-checkins] cpython: Issue #15640: Document importlib.abc.Finder as deprecated.

[brett.cannon]

http://hg.python.org/cpython/rev/4bbb1ff4f7ea
changeset:   78620:4bbb1ff4f7ea
user:        Brett Cannon <brett at python.org>
date:        Fri Aug 17 14:08:24 2012 -0400
summary:
  Issue #15640: Document importlib.abc.Finder as deprecated.

The code for the class itself isn't deprecated for
backwards-compatibility reasons, but the class shouldn't be directly
inherited by anyone anymore as the API is no longer as widely valid as
it used to be.

files:
  Doc/library/importlib.rst |  49 +++++++++++++-------------
  Misc/NEWS                 |   2 +
  2 files changed, 27 insertions(+), 24 deletions(-)


diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst
--- a/Doc/library/importlib.rst
+++ b/Doc/library/importlib.rst
@@ -124,7 +124,7 @@
 ABC hierarchy::
 
     object
-     +-- Finder
+     +-- Finder (deprecated)
      |    +-- MetaPathFinder
      |    +-- PathEntryFinder
      +-- Loader
@@ -133,15 +133,16 @@
                +-- ExecutionLoader --+
                                      +-- FileLoader
                                      +-- SourceLoader
-                                          +-- PyLoader
-                                          +-- PyPycLoader
+                                          +-- PyLoader (deprecated)
+                                          +-- PyPycLoader (deprecated)
 
 
 .. class:: Finder
 
-   An abstract base class representing a :term:`finder`.  Finder
-   implementations should derive from (or register with) the more specific
-   :class:`MetaPathFinder` or :class:`PathEntryFinder` ABCs.
+   An abstract base class representing a :term:`finder`.
+
+   .. deprecated:: 3.3
+      Use :class:`MetaPathFinder` or :class:`PathEntryFinder` instead.
 
    .. method:: find_module(fullname, path=None)
 
@@ -656,30 +657,30 @@
 
 .. class:: PathFinder
 
-    :term:`Finder` for :data:`sys.path` and package ``__path__`` attributes.
-    This class implements the :class:`importlib.abc.MetaPathFinder` ABC.
+   A :term:`Finder` for :data:`sys.path` and package ``__path__`` attributes.
+   This class implements the :class:`importlib.abc.MetaPathFinder` ABC.
 
-    Only class methods are defined by this class to alleviate the need for
-    instantiation.
+   Only class methods are defined by this class to alleviate the need for
+   instantiation.
 
-    .. classmethod:: find_module(fullname, path=None)
+   .. classmethod:: find_module(fullname, path=None)
 
-        Class method that attempts to find a :term:`loader` for the module
-        specified by *fullname* on :data:`sys.path` or, if defined, on
-        *path*. For each path entry that is searched,
-        :data:`sys.path_importer_cache` is checked. If a non-false object is
-        found then it is used as the :term:`finder` to look for the module
-        being searched for. If no entry is found in
-        :data:`sys.path_importer_cache`, then :data:`sys.path_hooks` is
-        searched for a finder for the path entry and, if found, is stored in
-        :data:`sys.path_importer_cache` along with being queried about the
-        module. If no finder is ever found then ``None`` is both stored in
-        the cache and returned.
+     Class method that attempts to find a :term:`loader` for the module
+     specified by *fullname* on :data:`sys.path` or, if defined, on
+     *path*. For each path entry that is searched,
+     :data:`sys.path_importer_cache` is checked. If a non-false object is
+     found then it is used as the :term:`finder` to look for the module
+     being searched for. If no entry is found in
+     :data:`sys.path_importer_cache`, then :data:`sys.path_hooks` is
+     searched for a finder for the path entry and, if found, is stored in
+     :data:`sys.path_importer_cache` along with being queried about the
+     module. If no finder is ever found then ``None`` is both stored in
+     the cache and returned.
 
    .. classmethod:: invalidate_caches()
 
-        Call :meth:`importlib.abc.PathEntryFinder.invalidate_caches` on all
-        finders stored in :attr:`sys.path_importer_cache`.
+     Calls :meth:`importlib.abc.PathEntryFinder.invalidate_caches` on all
+     finders stored in :attr:`sys.path_importer_cache`.
 
 
 .. class:: FileFinder(path, \*loader_details)
diff --git a/Misc/NEWS b/Misc/NEWS
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -41,6 +41,8 @@
 Documentation
 -------------
 
+- Issue #15640: Document importlib.abc.Finder as deprecated.
+
 - Issue #15630: Add an example for "continue" stmt in the tutorial. Patch by
   Daniel Ellis.
 

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