While taking a look on the import mechanisms I've seen in the documentation that find_module has been deprecated for find_spec, but on different parts of the documentation there are still references to find_module, as in the definition of sys.meta_path (https://docs.python.org/3/library/sys.html#sys.meta_path).

Shouldn't it be (example on this case) a list of finder objects that have their find_spec() methods called, instead of find_module method?

I've been taking a look on _bootstrap.py and I can see we call find_spec:

for finder in sys.meta_path:
    with _ImportLockContext():
        try:
            find_spec = finder.find_spec

If you agree with me that this is wrong I'll submit a patch to fix it.

You're right, it should be find_spec.

Added changes on both places where there was still references to find_module without specifying that has been deprecated.

I also ran into confusion with this while trying to write an import hook.

Attached is my shot at a docs patch. I've done a slightly larger rewording, trying to make it easier to understand, and added more links between parts of the docs.

I left mentions of the deprecated find_module and find_loader methods in the 'finder' glossary entry, but for sys.meta_path I have only described find_spec() - it does still fall back to the deprecated methods, but I thought that trying to explain that would make the description of meta_path harder to follow.

Thanks for adding that link to ModuleSpec, it is definitely needed to make sense of a lot of stuff.

I left some review comments and questions.

If the behaviour of sys.meta_path has changed, I think it needs a “New/changed in version X” notice. If it makes the modern description hard to follow, maybe keep it in a separate paragraph.

Updated patch attached, responding to Martin's suggestions.

I'm not quite sure what to do about the 'finder' glossary entry. 'Finder' now seems to be a more abstract classification covering two distinct kinds of thing: *meta path finders* and *path entry finders*. They have similar methods (find_spec, find_module), but with slightly different signatures. Is 'finder' a sufficiently meaningful concept to remain in the glossary, or should we take it out and be explicit about what type of finder is meant elsewhere in the docs?

The generic "finder" glossary entry should be rather generic and then point to "meta path finder" and "path entry finder" for dis-ambiguity (and both of those terms are already in the glossary).

That's basically what I was aiming for. Should the description be briefer and more generic?

I vote for more generic; left a review to that effect.

Third revision of patch responding to Brett's suggestions.

LGTM; I will commit it when I have a chance.

Thanks Brett :-)

New changeset 88cee7d16ccb by Brett Cannon in branch '3.5':
Issue #23936: Clarify what finders are.
https://hg.python.org/cpython/rev/88cee7d16ccb

New changeset 1b1900d2a537 by Brett Cannon in branch 'default':
Merge for issue #23936
https://hg.python.org/cpython/rev/1b1900d2a537

Thanks for the bug report, Raúl, and the patch, Thomas!