[doc] Possibly ambiguous phrasing in tutorial/modules#more-on-modules

[PiotrKuchta]

BPO	17383
Nosy	@ezio-melotti, @merwok, @berkerpeksag, @ashwch
Files	issue17383.patch

^{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:

assignee = None
closed_at = None
created_at = <Date 2013-03-07.23:55:00.898>
labels = ['3.11', 'type-bug', 'docs']
title = '[doc] Possibly ambiguous phrasing in tutorial/modules#more-on-modules'
updated_at = <Date 2021-11-28.13:21:44.318>
user = 'https://bugs.python.org/PiotrKuchta'

bugs.python.org fields:

activity = <Date 2021-11-28.13:21:44.318>
actor = 'iritkatriel'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2013-03-07.23:55:00.898>
creator = 'Piotr.Kuchta'
dependencies = []
files = ['34446']
hgrepos = []
issue_num = 17383
keywords = ['patch']
message_count = 13.0
messages = ['183715', '183716', '183742', '183744', '183745', '183746', '183747', '183748', '183751', '184900', '213746', '213750', '213767']
nosy_count = 8.0
nosy_names = ['ezio.melotti', 'eric.araujo', 'docs@python', 'berker.peksag', 'jeffknupp', 'ashwch', 'Piotr.Kuchta', 'nitika']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'needs patch'
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue17383'
versions = ['Python 3.11']

[PiotrKuchta]

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

[ezio-melotti]

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'.

[merwok]

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]

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).

[PiotrKuchta]

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.

[merwok]

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.

[merwok]

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.

[jeffknupp]

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.

[PiotrKuchta]

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.

[merwok]

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]

Hi,
I would like to propose a patch for this issue.

[nitika]

Hello everyone,
I have tried creating a patch for the issue,
Please review the attached patch.

[merwok]

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.

[ambv]

Fixed by @slateny in GH-93455 and backported to 3.11 and 3.10. Thanks! ✨ 🍰 ✨

[merwok]

Didn’t get any notification about that PR, but it’s a good change! 👍🏽