classification
Title: Possibly ambiguous phrasing in tutorial/modules#more-on-modules
Type: behavior Stage: needs patch
Components: Documentation Versions: Python 3.6, Python 3.5, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Piotr.Kuchta, ashwch, berker.peksag, docs@python, eric.araujo, ezio.melotti, jeffknupp, nitika
Priority: normal Keywords: patch

Created on 2013-03-07 23:55 by Piotr.Kuchta, last changed 2016-06-01 03:35 by berker.peksag.

Files
File name Uploaded Description Edit
issue17383.patch nitika, 2014-03-16 20:04
Messages (13)
msg183715 - (view) Author: Piotr Kuchta (Piotr.Kuchta) Date: 2013-03-07 23:55
In the 2.7 tutorial, chapter on modules:

 http://docs.python.org/2/tutorial/modules.html#more-on-modules 

I think the last sentence in this paragraph is incorrect:

"Modules can import other modules. It is customary but not required to place all import statements at the beginning of a module (or script, for that matter). The imported module names are placed in the importing module’s global symbol table."

This is not true:

>>> def foo(): import sys
... 
>>> foo()
>>> sys.path
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'sys' is not defined
msg183716 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-03-07 23:58
It should probably say that they are placed in the namespace where they get imported, but I'm not sure if the concept of namespace has been covered yet at that point of the tutorial.  The sentence probably assume that the modules are getting imported at the beginning of the module (as suggested in the previous sentence), but even in that case I wouldn't use 'global symbol table'.
msg183742 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2013-03-08 15:12
Text sounds correct to me.  It says that imports should happen at the beginning of a module, and that the names of imported modules are placed in the module namespace.  There is an implicit logical link between the two sentences, and the wording of “symbol table” may be not great at this stage of the tuto, but I don’t see that the text can be interpreted to mean that imports in a function will change the global namespace.  Of course, *I* don’t see it because I’m not the target audience of the tutorial; if you know that import creates an assignment and that assignments have scopes, it’s logical that importing in a function does not create a global name, but beginners reading the tutorial may not know these things yet.  So we could add an example of a module importing and using another module.  If there is a part of the tuto where imports in functions are mentioned (and discouraged), then an example or comment there could also clarify that the imported module name is only local to the function.
msg183744 - (view) Author: Jeff Knupp (jeffknupp) * Date: 2013-03-08 16:02
I think Piotr's point is the wording of the last sentence is ambiguous. The second statement reads "It is customary *but not required* to place all import statements at the beginning of a module...". The third seems to state that regardless of whether or not you followed the custom, module names are always placed in the global symbol table.

I think the last two sentences need to be rewritten to remove ambiguity. If, at this point, we only want to explain that importing a module makes that modules names available then that's what the documentation should say (even more so if the term "symbol table" hasn't been introduced yet, which would effectively render the entire block useless).
msg183745 - (view) Author: Piotr Kuchta (Piotr.Kuchta) Date: 2013-03-08 16:26
Jeff, thank you: that was exactly what I wanted to point out. The three sentences read in order imply that it doesn't matter whether you import a module at the top level of a script/module or in a function, because the effect is the same, namely the imported symbols end up in the global symbol table, and that obviously is not true.
msg183746 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2013-03-08 16:29
> It is customary *but not required* to place all import statements at the
> beginning of a module...". The third seems to state that regardless of
> whether or not you followed the custom, module names are always placed in
> the global symbol table

Yes. Not following the usage means placing imports in the middle of the module for example, but it does not imply imports in functions.
msg183747 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2013-03-08 16:32
Ah, we have it: the tutorial distinguishes between “it’s customary to put imports near the top of the file” vs. “later in the file”, and you interpret it as “it’s customary to put imports at the module top level” vs. “import in any scope e.g. functions”.  These are actually two different things, covered in different part of the docs: importing at module scope is very much recommended, as imports in functions can lead to nasty side-effects; and then there’s the style issue of putting imports at the beginning of the file, which is what the section we discuss is about.
msg183748 - (view) Author: Jeff Knupp (jeffknupp) * Date: 2013-03-08 16:45
Of the "two different things", the first (the scope of imported names) is never covered in the documentation. As a result, the text in question seems to imply an import statement can *only* be in module scope. 

From the reader's perspective: "If I wanted to import something in a class or function it obviously can't be at the top of the file, so I guess I can't do that." The tutorial doesn't disabuse them of this notion.
msg183751 - (view) Author: Piotr Kuchta (Piotr.Kuchta) Date: 2013-03-08 16:56
Eric, when you say 'the tutorial distinguishes between “it’s customary to put imports near the top of the file” vs. “later in the file”' the last bit is just your interpretation. The tutorial doesn't say "later in the file". Anyway, 'later in the file' does not mean 'later in the file at the top level'.

For me an opposite to "top of the file" is "anywhere else in the file, including functions' and class' definitions later in the file".

Clearly, there is an ambiguity here. And I can tell you that people do get confused by that part of documentation. I know it from discussions with my colleagues at work. Also, I asked a question on StackOverflow, where I quoted the tutorial and gave that example of importing in a function body: http://stackoverflow.com/q/15283821/300886
You can see in the comments that people were surprised seeing the NameError! For me it is clear that this part of the tutorial should be improved.
msg184900 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2013-03-21 19:35
I was not disagreeing that there was an ambiguity, just trying to explain why some people would understand the text in a different way that what it meant.
msg213746 - (view) Author: Nitika Agarwal (nitika) * Date: 2014-03-16 18:26
Hi,
I would like to propose a patch for this issue.
msg213750 - (view) Author: Nitika Agarwal (nitika) * Date: 2014-03-16 20:04
Hello everyone,
I have tried creating a patch for the issue,
Please review the attached patch.
msg213767 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2014-03-16 22:27
Thanks for the patch.

+Enhancing the More on Modules documentation
+--------------------------------------------------------------------

This should not be in the patch.

-Modules can import other modules. It is customary but not required
-to place all import statements at the beginning of a module (or script, 
-for that matter). The imported module names are placed in the importing
-module’s global symbol table.
+Modules can import other modules. It is customary but not required
+to place all import statements at the beginning of a module (or script, 
+for that matter). The imported module names are placed in the importing
+module’s global symbol table.

These lines are not changed, I suspect the characters used for the end of lines have been changed by your text editor.  Please fix that (search for “EOL” or “hgeol” in the devguide).

+For more on namespace, follow the link :
+http://docs.python.org/2/tutorial/classes.html#python-scopes-and-namespaces

I don’t think adding this link solves the ambiguous phrasing.
History
Date User Action Args
2016-06-01 03:35:09berker.peksagsetnosy: + berker.peksag
stage: patch review -> needs patch
type: behavior

versions: + Python 3.5, Python 3.6
2014-06-19 22:55:50ezio.melottisetstage: needs patch -> patch review
2014-03-16 22:27:03eric.araujosetmessages: + msg213767
2014-03-16 20:04:18nitikasetfiles: + issue17383.patch
keywords: + patch
messages: + msg213750
2014-03-16 18:26:01nitikasetnosy: + nitika
messages: + msg213746
2013-03-21 19:35:07eric.araujosetmessages: + msg184900
stage: needs patch
2013-03-08 16:56:33Piotr.Kuchtasetmessages: + msg183751
2013-03-08 16:45:51jeffknuppsetmessages: + msg183748
2013-03-08 16:32:49eric.araujosetmessages: + msg183747
title: Error in documentation /2/tutorial/modules.html#more-on-modules -> Possibly ambiguous phrasing in tutorial/modules#more-on-modules
2013-03-08 16:29:20eric.araujosetmessages: + msg183746
2013-03-08 16:26:50Piotr.Kuchtasetmessages: + msg183745
2013-03-08 16:02:29jeffknuppsetnosy: + jeffknupp
messages: + msg183744
2013-03-08 15:12:30eric.araujosetnosy: + eric.araujo
messages: + msg183742
2013-03-08 00:20:24ashwchsetnosy: + ashwch
2013-03-07 23:58:54ezio.melottisetnosy: + ezio.melotti
messages: + msg183716
2013-03-07 23:55:00Piotr.Kuchtacreate