Repository navigation
[doc] Possibly ambiguous phrasing in tutorial/modules#more-on-modules #61585
Description
Activity
PiotrKuchta commented
on Mar 7, 2013 PiotrKuchtamannequinMannequinAuthorIn 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
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'.
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.
jeffknupp commented
on Mar 8, 2013 jeffknuppmannequinMannequinI 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).
PiotrKuchta commented
on Mar 8, 2013 PiotrKuchtamannequinMannequinAuthorJeff, 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.
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 tableYes. Not following the usage means placing imports in the middle of the module for example, but it does not imply imports in functions.
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.
- changed the title
[-]Error in documentation /2/tutorial/modules.html#more-on-modules[/-][+]Possibly ambiguous phrasing in tutorial/modules#more-on-modules[/+]on Mar 8, 2013 jeffknupp commented
on Mar 8, 2013 jeffknuppmannequinMannequinOf 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.
PiotrKuchta commented
on Mar 8, 2013 PiotrKuchtamannequinMannequinAuthorEric, 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.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.
nitika commented
on Mar 16, 2014 nitikamannequinMannequinHi,
I would like to propose a patch for this issue.nitika commented
on Mar 16, 2014 nitikamannequinMannequinHello everyone,
I have tried creating a patch for the issue,
Please review the attached patch.3 remaining items
- changed the title
[-]Possibly ambiguous phrasing in tutorial/modules#more-on-modules[/-][+][doc] Possibly ambiguous phrasing in tutorial/modules#more-on-modules[/+]on Nov 28, 2021 - added a commit that references this issue
on Jun 28, 2022 Didn’t get any notification about that PR, but it’s a good change! 👍🏽
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
bugs.python.org fields: