[3.12] gh-71261: Add paragraph on shadowing submodules with star imports (GH-107004)

Doc/tutorial/modules.rst

@@ -183,7 +183,7 @@
 
 .. index:: triple: module; search; path
 
 When a module named :mod:`spam` is imported, the interpreter first searches for
 a built-in module with that name. These module names are listed in
 :data:`sys.builtin_module_names`. If not found, it then searches for a file
 named :file:`spam.py` in a list of directories given by the variable
@@ -191,7 +191,7 @@
 
 * The directory containing the input script (or the current directory when no
  file is specified).
 * :envvar:`PYTHONPATH` (a list of directory names, with the same syntax as the
  shell variable :envvar:`PATH`).
 * The installation-dependent default (by convention including a
  ``site-packages`` directory, handled by the :mod:`site` module).
@@ -388,7 +388,7 @@
 Packages
 ========
 
 Packages are a way of structuring Python's module namespace by using "dotted
 module names". For example, the module name :mod:`A.B` designates a submodule
 named ``B`` in a package named ``A``. Just like the use of modules saves the
 authors of different modules from having to worry about each other's global
@@ -448,7 +448,7 @@
 
  import sound.effects.echo
 
 This loads the submodule :mod:`sound.effects.echo`. It must be referenced with
 its full name. ::
 
  sound.effects.echo.echofilter(input, output, delay=0.7, atten=4)
@@ -457,7 +457,7 @@
 
  from sound.effects import echo
 
 This also loads the submodule :mod:`echo`, and makes it available without its
 package prefix, so it can be used as follows::
 
  echo.echofilter(input, output, delay=0.7, atten=4)
@@ -466,7 +466,7 @@
 
  from sound.effects.echo import echofilter
 
 Again, this loads the submodule :mod:`echo`, but this makes its function
 :func:`echofilter` directly available::
 
  echofilter(input, output, delay=0.7, atten=4)
@@ -509,10 +509,26 @@
 
  __all__ = ["echo", "surround", "reverse"]
 
 This would mean that ``from sound.effects import *`` would import the three
 named submodules of the :mod:`sound.effects` package.
 
+Be aware that submodules might become shadowed by locally defined names. For
+example, if you added a ``reverse`` function to the
+:file:`sound/effects/__init__.py` file, the ``from sound.effects import *``
+would only import the two submodules ``echo`` and ``surround``, but *not* the
+``reverse`` submodule, because it is shadowed by the locally defined
+``reverse`` function::
+
+ __all__ = [
+ "echo", # refers to the 'echo.py' file
+ "surround", # refers to the 'surround.py' file
+ "reverse", # !!! refers to the 'reverse' function now !!!
+ ]
+
+ def reverse(msg: str): # <-- this name shadows the 'reverse.py' submodule
+ return msg[::-1] # in the case of a 'from sound.effects import *'
+
 If ``__all__`` is not defined, the statement ``from sound.effects import *``
 does *not* import all submodules from the package :mod:`sound.effects` into the
 current namespace; it only ensures that the package :mod:`sound.effects` has
 been imported (possibly running any initialization code in :file:`__init__.py`)