gh-61585: Clarify import scope in modules tutorial

[slateny]

#61585

https://docs.python.org/3/tutorial/modules.html#more-on-modules

[AA-Turner]

This still isn't quite true, e.g.

import string

def f():
    import sys

import json

class A:
    import hashlib

class B:
    def c(self):
        import abc

B().c()

import re

for name in "string", "sys", "json", "hashlib", "abc", "re":
    print(f"Globals contains {name + '?': <8} {name in globals()}")

Yields (Python 3.10):

(sphinx) S:\Development\sphinx>python globals_test.py
Globals contains string?  True
Globals contains sys?     False
Globals contains json?    True
Globals contains hashlib? False
Globals contains abc?     False
Globals contains re?      True

Perhaps we could say:

Suggested change

	matter). The imported module names, if placed at the beginning of a module,
	are placed in the importing module's global symbol table.
	matter). The imported module names, if placed at the top level of a module,
	(no indentation) are placed in the importing module's global symbol table.

I would argue that "global symbol table" is an unfriendly term to beginners though, perhaps "dictionary of global names" or "global names table"?

A

[slateny]

I do like the changed wording, just don't know the assumed level of knowledge for the reader and whether they'd understand what 'top level' was in a tutorial.

Also agreed that 'global symbol table' doesn't quite belong in a tutorial (I think some comments in the issue also mentioned it), but I wonder if there's an even less technical way to put it than 'global names'. Or maybe better would be to expand on the definition immediately, like '... global symbol table, which is xyz. For more info see link'.

[AA-Turner]

Namespaces are introduced in Chapter 9 of the tutorial. No chapter before that makes any reference to namespaces, except 6 -- with three references. I think we should try to reword to avoid using the term until it is properly introduced.

Perhaps for this section:

Modules can import other modules, again using the :keyword:`import` statement.
Grouping :keyword:`import` statements together keeps your code more organised
and makes it easier to find where a given name comes from when you are
re-reading your code later.  Using an :keyword:`import` statements at the top
level of the module (with no indentation) means that you can access the 
imported name from anywhere within the module that contains the 
:keyword:`import` statement.  For example:

.. code-block:: python

   import cafe 

   for _ in range(3):
       print(cafe.menu)

@python/proofreaders -- "symbol table" is used 8 times in Ch4, 7 times in Ch6, and once in Ch14 but nowhere else in the tutorial -- does anyone have good ideas on an alternative terminology that is both friendly to beginners and conveys the idea sufficiently well? I'm drawing a blank.

A

[CAM-Gerlach]

To refresh my own RAM on the exact distinction between a "namespace" and a "symbol table", I googled it and the top hit was a Software Engineering SE question where a user was asking about this exact passage in the Python tutorial. To quote the answers:

A symbol table is an implementation detail. Namespaces are implemented using symbol tables, but symbol tables are used for more than just namespaces.

Hence, namespace and symbol table, in Python, relate to the same thing. The former is the symbol table as exposed to the developer, and the latter is the symbol table itself.

Especially given this is the beginner tutorial, not the language reference, IMO it makes much more sense to refer to the user-facing construct rather than an implementation detail internal to the guts of the interpreter.

Thus, I recommend we just use "namespace", linked to its glossary entry :term:`namespace` and/or the tutorial section :ref:`tut-scopes` linked above. It can be further clarified by mentioning, in a parenthetical, "outside any functions or classes", since in fact "no indentation" is not correct either as many/most constructs that result in an indented block (with, for, if, etc) don't create a new scope.

Therefore, my suggestion:

Suggested change

	matter). The imported module names, if placed at the beginning of a module,
	are placed in the importing module's global symbol table.
	matter). The imported module names, if placed at the top level of a module
	(outside any functions or classes), are added to the module's global
	:term:`namespace` (see :ref:`tut-scopes` for more details).