From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Sun, 23 Jul 2023 09:12:52 +0000 (-0700)
Subject: [3.11] gh-71261: Add paragraph on shadowing submodules with star imports (GH-107004... 
X-Git-Tag: v3.11.5~166
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=5575b1204b9870301f2e5797a8535576487b5800;p=thirdparty%2FPython%2Fcpython.git

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

Co-authored-by: wulmer <wulmer@users.noreply.github.com>
---

diff --git a/Doc/tutorial/modules.rst b/Doc/tutorial/modules.rst
index 3bd034bcc970..734dd1cfe687 100644
--- a/Doc/tutorial/modules.rst
+++ b/Doc/tutorial/modules.rst
@@ -512,6 +512,22 @@ code::
 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