Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

gh-61585: Clarify import scope in modules tutorial #93455

Merged
merged 4 commits into from
Jun 28, 2022
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 11 additions & 10 deletions Doc/tutorial/modules.rst
Original file line number Diff line number Diff line change
@@ -47,8 +47,9 @@ command::

>>> import fibo

This does not enter the names of the functions defined in ``fibo`` directly in
the current symbol table; it only enters the module name ``fibo`` there. Using
This does not add the names of the functions defined in ``fibo`` directly to
the current :term:`namespace` (see :ref:`tut-scopes` for more details);
it only adds the module name ``fibo`` there. Using
the module name you can access the functions::

>>> fibo.fib(1000)
@@ -75,27 +76,27 @@ These statements are intended to initialize the module. They are executed only
the *first* time the module name is encountered in an import statement. [#]_
(They are also run if the file is executed as a script.)

Each module has its own private symbol table, which is used as the global symbol
table by all functions defined in the module. Thus, the author of a module can
Each module has its own private namespace, which is used as the global namespace
by all functions defined in the module. Thus, the author of a module can
use global variables in the module without worrying about accidental clashes
with a user's global variables. On the other hand, if you know what you are
doing you can touch a module's global variables with the same notation used to
refer to its functions, ``modname.itemname``.

Modules can import other modules. It is customary but not required to place all
:keyword:`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.
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 namespace.

There is a variant of the :keyword:`import` statement that imports names from a
module directly into the importing module's symbol table. For example::
module directly into the importing module's namespace. For example::

>>> from fibo import fib, fib2
>>> fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

This does not introduce the module name from which the imports are taken in the
local symbol table (so in the example, ``fibo`` is not defined).
local namespace (so in the example, ``fibo`` is not defined).

There is even a variant to import all names that a module defines::

@@ -580,5 +581,5 @@ modules found in a package.
.. rubric:: Footnotes

.. [#] In fact function definitions are also 'statements' that are 'executed'; the
execution of a module-level function definition enters the function name in
the module's global symbol table.
execution of a module-level function definition adds the function name to
the module's global namespace.