From d0ae0a8afb2113cdbb6e6ce9a435d8c726a6f00a Mon Sep 17 00:00:00 2001 From: Wolfgang Ulmer Date: Sat, 22 Jul 2023 10:56:52 +0000 Subject: [PATCH 1/2] Add paragraph on shadowing submodules with star imports --- Doc/tutorial/modules.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/Doc/tutorial/modules.rst b/Doc/tutorial/modules.rst index 3bd034bcc9703f8..f93fbf734c31733 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 case of an '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 From d1690601ae835725222f497ac2275964235e5684 Mon Sep 17 00:00:00 2001 From: Wolfgang Ulmer Date: Sat, 22 Jul 2023 13:21:16 +0000 Subject: [PATCH 2/2] Fix grammar on last sentence --- Doc/tutorial/modules.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/tutorial/modules.rst b/Doc/tutorial/modules.rst index f93fbf734c31733..734dd1cfe6871ac 100644 --- a/Doc/tutorial/modules.rst +++ b/Doc/tutorial/modules.rst @@ -526,7 +526,7 @@ would only import the two submodules ``echo`` and ``surround``, but *not* the ] def reverse(msg: str): # <-- this name shadows the 'reverse.py' submodule - return msg[::-1] # in case of an 'from sound.effects import *' + 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