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.

classification
Title: Tutorial is unclear on multiple imports of a module.
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, ezio.melotti, jamesob, python-dev, r.david.murray, roysmith
Priority: normal Keywords: easy, patch

Created on 2012-08-07 18:11 by roysmith, last changed 2022-04-11 14:57 by admin. This issue is now closed.

Files
File name Uploaded Description Edit
module_multi_exec_doc_27.patch jamesob, 2013-03-26 00:33 2.7 patch review
Messages (5)
msg167628 - (view) Author: Roy Smith (roysmith) Date: 2012-08-07 18:11
Opening this bug at Ben Finney's request.  See https://groups.google.com/forum/?fromgroups#!topic/comp.lang.python/wmDUrpW2ZCU for the full thread discussing the problem.  Here's a significant excerpt:

-------------------------------------------------
The tutorial is misleading on this. It it says plainly: 

    A module can contain executable statements as well as function 
    definitions. […] They are executed only the *first* time the module 
    is imported somewhere. 

    <URL:http://docs.python.org/tutorial/modules.html> 

but it doesn't make clear that a module can exist in the ‘sys.modules’ 
list multiple times under different names. 
-------------------------------------------------


Also note:

--------------------------------------------------
The footnote to that is wrong too: 

> [1]        In fact function definitions are also ‘statements’ that are ‘executed’; the execution of a module-level function enters the function name in the module’s global symbol table. 

I think what it's supposed to say is "... the execution of a module-level def statement ..." 
---------------------------------------------------
msg167629 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2012-08-07 18:29
Well, I don't think a full discussion of the subtlety about a module appearing under multiple names belongs in the tutorial, but I think the sentence could be amended to say "Statements in a module are executed only the *first* time the module name is encountered in an import statement".

The other is indeed a bug (IMO the sentence is missing the word 'definition', as in 'execution of a function definition').
msg185256 - (view) Author: jamesob (jamesob) Date: 2013-03-26 00:33
Howdy; attached is a patch containing the doc changes. I figured that some elaboration was in addition to what r.david.murray recommended, so I've included a brief allusion to the problem of equivalent paths.
msg187524 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-04-21 21:14
New changeset 9df9931fae96 by R David Murray in branch '3.3':
#15575: Clarify tutorial description of when modules are executed.
http://hg.python.org/cpython/rev/9df9931fae96

New changeset dac847938326 by R David Murray in branch 'default':
#15575: Clarify tutorial description of when modules are executed.
http://hg.python.org/cpython/rev/dac847938326

New changeset a1421d28393b by R David Murray in branch '2.7':
#15575: Clarify tutorial description of when modules are executed.
http://hg.python.org/cpython/rev/a1421d28393b
msg187525 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2013-04-21 21:17
Thanks, James.  I wound up going with a different wording for the "elaboration": since the concept of running a python file as a script is mentioned just a bit earlier, I added a parenthetical that the statements are also executed if the module is run as a script.
History
Date User Action Args
2022-04-11 14:57:33adminsetgithub: 59780
2013-04-21 21:17:06r.david.murraysetstatus: open -> closed
resolution: fixed
messages: + msg187525

stage: needs patch -> resolved
2013-04-21 21:14:50python-devsetnosy: + python-dev
messages: + msg187524
2013-03-26 00:33:18jamesobsetfiles: + module_multi_exec_doc_27.patch

nosy: + jamesob
messages: + msg185256

keywords: + patch
2013-03-14 08:11:08ezio.melottisetkeywords: + easy
nosy: + ezio.melotti

stage: needs patch
2012-08-07 18:29:48r.david.murraysetnosy: + r.david.murray
messages: + msg167629
2012-08-07 18:11:02roysmithcreate