Ezio Melotti added the comment: 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'. ---------- nosy: +ezio.melotti _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17383> _______________________________________

Éric Araujo added the comment: 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. ---------- nosy: +eric.araujo _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17383> _______________________________________

Piotr Kuchta added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17383> _______________________________________

Éric Araujo added the comment: 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. ---------- title: Error in documentation /2/tutorial/modules.html#more-on-modules -> Possibly ambiguous phrasing in tutorial/modules#more-on-modules _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17383> _______________________________________

Piotr Kuchta added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17383> _______________________________________

Nitika Agarwal added the comment: Hi, I would like to propose a patch for this issue. ---------- nosy: +nitika _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17383> _______________________________________

Éric Araujo added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17383> _______________________________________

Changes by Berker Peksag <berker.peksag@gmail.com>: ---------- nosy: +berker.peksag stage: patch review -> needs patch type: -> behavior versions: +Python 3.5, Python 3.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17383> _______________________________________