This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: mistakes in docstrings in the import machinery
Type: behavior Stage: resolved
Components: Library (Lib) Versions: Python 3.6
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: brett.cannon Nosy List: Oren Milman, brett.cannon, python-dev
Priority: low Keywords: patch

Created on 2016-05-07 16:16 by Oren Milman, last changed 2022-04-11 14:58 by admin. This issue is now closed.

File name Uploaded Description Edit
issue.diff Oren Milman, 2016-05-07 16:16 proporsed patches diff file review
CPythonTestOutput.txt Oren Milman, 2016-05-07 16:16 test output of CPython without my patches (tested on my PC)
patchedCPythonTestOutput.txt Oren Milman, 2016-05-07 16:17 test output of CPython with my patches (tested on my PC)
Messages (4)
msg265076 - (view) Author: Oren Milman (Oren Milman) * Date: 2016-05-07 16:16
the proposed changes:
I believe there are some mistakes in the following docstrings:
    1. in Lib/importlib/
        - _module_repr - a typo
        - _exec - I believe 'Execute the module specified by the spec' is more accurate than 'Execute the spec'. 
        This docstring wasn't changed since this version of _exec was added in revision 90915 (this version of _exec replaced the one that was in _SpecMethods), so I guess the exact phrasing of that docstring wasn't already challenged.
        - _find_spec - I believe "Find a module's spec." is more accurate than "Find a module's loader.", as the function returns a spec and not a loader. It might be argued that ultimately the function does find a loader. However, we have the perfectly normal case where it is a namespace package, and _find_spec doesn't find any loader. 
        This docstring was the docstring of _find_module, and was left as is when _find_spec replaced _find_module in revision 87347 (which implemented PEP 451), so I guess the exact phrasing of that docstring (in the context of _find_spec) wasn't already challenged.
    2. in Lib/importlib/
        - PathFinder._path_hooks - It seems the function's docstring was left as is when issue #14605 was addressed, and thus, since revision 76566, the docstring is inaccurate. 
        - PathFinder.find_spec - I believe "Try to find a spec for 'fullname' on..." is more accurate than "find the module on..." (I took the phrasing from Doc\library\importlib.rst). 
        It seems this docstring was copied from PathFinder.find_module when it was added in revision 87347, and was never changed since, so I guess its exact phrasing wasn't already challenged. 
        - FileFinder.find_spec - It seems this docstring was copied from FileFinder.find_loader when it was added in revision 87347, and was never changed since. Again, I took the phrasing of my proposed new docstring from Doc\library\importlib.rst.

The patches diff is attached.

I played a little with the interpreter, and everything worked as usual. I also verified that CPython was indeed compiled with my patched frozen modules (made by _freeze_importlib.exe), by reading patched docstrings interactively via 'import _frozen_importlib' and 'import _frozen_importlib_external'.

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.
msg265077 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2016-05-07 16:34
Thanks for the thorough review, Oren! I'll have a look at the patch when I get a chance.
msg270001 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-07-08 18:09
New changeset d32517de5d8c by Brett Cannon in branch 'default':
Issue #26972: Fix some mistakes in importlib-related docstrings.
msg270003 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2016-07-08 18:11
Thanks for the patch, Oren! The only real change I made was to make sure the the one-sentence summary at the start of the docstring fit on a single line (when it spans line it can muck up editors and tools).
Date User Action Args
2022-04-11 14:58:30adminsetgithub: 71159
2016-07-08 18:11:18brett.cannonsetstatus: open -> closed
resolution: fixed
messages: + msg270003

stage: patch review -> resolved
2016-07-08 18:09:42python-devsetnosy: + python-dev
messages: + msg270001
2016-05-07 16:34:22brett.cannonsetpriority: normal -> low
assignee: brett.cannon
messages: + msg265077
2016-05-07 16:26:44SilentGhostsetnosy: + brett.cannon

type: behavior
stage: patch review
2016-05-07 16:17:34Oren Milmansetfiles: + patchedCPythonTestOutput.txt
2016-05-07 16:16:50Oren Milmansetfiles: + CPythonTestOutput.txt
2016-05-07 16:16:06Oren Milmancreate