homepage

the proposed changes:
1. it seems there is some mix-up with the terms 'importer' and 'finder' (and rarely also 'loader') in the import system and in related code (I guess most of it is just relics from the time before PEP 302).
The rational is simply https://docs.python.org/3/glossary.html#term-importer, which means (as I understand it) that the only place where 'importer' is appropriate is where the described object is guaranteed to be both a finder and loader object (i.e. currently only any of the following: BuiltinImporter, FrozenImporter, ZipImporter, mock_modules, mock_spec, TestingImporter).
Note: At first I pondered about also changing local variable names and even the name of a static C function, so I posted a question to the core-mentorship mailing list, and ultimately accepted (of course) the answer - https://mail.python.org/mailman/private/core-mentorship/2016-April/003541.html - fix only docs.
these proposed changes are in the following files:
 - Python/import.c (also changed the line saying that get_path_importer returning None tells the caller it should fall back to the built-in import mechanism, as it is no longer true, according to https://docs.python.org/3/reference/import.html#path-entry-finders. As I understand it, the last is indeed the right one)
 - Doc/c-api/import.rst (also changed the parallel doc of the aforementioned comment in Python/import.c)
 - Lib/pkgutil.py
 - Doc/Library/pkgutil.rst
 - Lib/runpy.py (also changed the function comment of _get_module_details, which specified wrong return values)
 - Lib/test/test_pkgutil.py
 
2. While scanning every CPython file that contains the string 'importer', Anaconda (a Sublime Package for Python) found two local variable assignments which were never used. I commented both out (and added a comment stating why). I would be happy to change those two tiny fixes if needed. 
these proposed changes are in the following files:
 - Lib/test/test_importlib/import_/test_meta_path.py
 - Lib/test/test_importlib/util.py
diff:
The patches diff is attached.
tests:
I built the changed *.rst files, and they looked fine.
I played a little with the interpreter, and everything worked as usual.
In addition, I run 'python -m test' (on my 64-bit Windows 10) before and after applying the patch, and got quite the same output.
the outputs of both runs are attached.

Thanks for the patch. I left two review comments about unused variables on Rietveld.

thanks for the review!
I replied to both of your comments, though I am not sure what is expected of me in the rest of the process.
Whatever it is, I would be happy to help as much as I can.

Oren: If you have extra changes to make on the same topic, it is probably best to make a new patch that combines both the original changes plus the new changes.
Brett: Since you were responsible for the two dead assignments, your input would be helpful. Perhaps you meant to add extra code and forgot, or perhaps they are just useless and we can remove them.
I skimmed over PEP 302, and it seems it uses the term "importer" more or less to mean what the current glossary terms "finder". I.e. the first object to help with importing a module. Or maybe it means the system behind both the finder and loader stages, even if one object does not perform both steps. I don’t know much about this, but another option could be to redefine "importer" as it is more generally used.

Except for some trailing spaces I have just found in my original proposed patches, I don't have any extra changes to add. So as soon as Brett answers about those two assignments, I would update and upload the patches diff file.
With regard to terminology, I believe 'Explicit is better than implicit' fits here.
IMHO using (in the code and docs) each of the three terms explicitly, with accordance to the glossary (https://docs.python.org/3/glossary.html#term-finder, https://docs.python.org/3/glossary.html#term-loader, https://docs.python.org/3/glossary.html#term-importer, all of which were first added back in revision 51025, BTW), makes the import mechanism clearer (than using 'importer' as an ambiguous term).

Also, Brett was the one who added the three terms to the glossary in https://hg.python.org/cpython/rev/ea5767ebd903, and a clarification of 'finder' in https://hg.python.org/cpython/rev/88cee7d16ccb, so I guess his input in this matter also would be helpful.
(If both of you think the other way, I am probably wrong :) )

New changeset c65f34dafcc1 by Brett Cannon in branch 'default':
Issue #26896: Disambiguate uses of "importer" with "finder".
https://hg.python.org/cpython/rev/c65f34dafcc1 

Thanks for the patch, Oren! Only change I made was deleting the lines you commented out in the tests.

That's awesome! Thanks :)

The documentation changes made as part of this issue were applicable to 3.5 branch too. 
I had to touch the docs in this area as part of issue20842, and ended up with two patches one for 3.5 and another 3.6.
I think, it is a good idea to backport the change to 3.5 branch.

It sounds like you have a backport ready, Senthil. Is that true? If so then go ahead and apply the changes.
You're right it could be backported, I just didn't due to laziness/lack of time.

Hi Brett, I backported only portions of the patch some this issue that were applicable to the issue that I was fixing. I will backport remain portions so that everything will be consistent now.

New changeset 7537ca1c2aaf by Senthil Kumaran in branch '3.5':
[backport to 3.5] - issue26896 - Disambiguate uses of "importer" with "finder".
https://hg.python.org/cpython/rev/7537ca1c2aaf