mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-03 08:34:29 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 6

Improve references in the tutorial (GH-108069)

Browse source 
* Use full qualified names for references (even if they do not work now,
  they will work in future).
* Silence references to examples.
This commit is contained in:
Serhiy Storchaka 2023-08-21 13:41:01 +03:00 • committed by GitHub
parent 20cc90c0df
commit 622ddc4167
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
6 changed files with 48 additions and 49 deletions
Download patch file Download diff file Expand all files Collapse all files

30
Doc/tutorial/modules.rst
View file

@ -183,7 +183,7 @@ The Module Search Path
.. index:: triple: module; search; path
When a module named :mod:`spam` is imported, the interpreter first searches for
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
@ -389,7 +389,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
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
variable names, the use of dotted module names saves the authors of multi-module
@ -448,7 +448,7 @@ example::
import sound.effects.echo
This loads the submodule :mod:`sound.effects.echo`. It must be referenced with
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 @@ An alternative way of importing the submodule is::
from sound.effects import echo
This also loads the submodule :mod:`echo`, and makes it available without its
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,8 +466,8 @@ Yet another variation is to import the desired function or variable directly::
from sound.effects.echo import echofilter
Again, this loads the submodule :mod:`echo`, but this makes its function
:func:`echofilter` directly available::
Again, this loads the submodule :mod:`!echo`, but this makes its function
:func:`!echofilter` directly available::
echofilter(input, output, delay=0.7, atten=4)
@ -510,7 +510,7 @@ code::
__all__ = ["echo", "surround", "reverse"]
This would mean that ``from sound.effects import *`` would import the three
named submodules of the :mod:`sound.effects` package.
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
@ -529,8 +529,8 @@ would only import the two submodules ``echo`` and ``surround``, but *not* the
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
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`)
and then imports whatever names are defined in the package. This includes any
names defined (and submodules explicitly loaded) by :file:`__init__.py`. It
@ -541,8 +541,8 @@ previous :keyword:`import` statements. Consider this code::
import sound.effects.surround
from sound.effects import *
In this example, the :mod:`echo` and :mod:`surround` modules are imported in the
current namespace because they are defined in the :mod:`sound.effects` package
In this example, the :mod:`!echo` and :mod:`!surround` modules are imported in the
current namespace because they are defined in the :mod:`!sound.effects` package
when the ``from...import`` statement is executed. (This also works when
``__all__`` is defined.)
@ -561,15 +561,15 @@ packages.
Intra-package References
------------------------
When packages are structured into subpackages (as with the :mod:`sound` package
When packages are structured into subpackages (as with the :mod:`!sound` package
in the example), you can use absolute imports to refer to submodules of siblings
packages. For example, if the module :mod:`sound.filters.vocoder` needs to use
the :mod:`echo` module in the :mod:`sound.effects` package, it can use ``from
packages. For example, if the module :mod:`!sound.filters.vocoder` needs to use
the :mod:`!echo` module in the :mod:`!sound.effects` package, it can use ``from
sound.effects import echo``.
You can also write relative imports, with the ``from module import name`` form
of import statement. These imports use leading dots to indicate the current and
parent packages involved in the relative import. From the :mod:`surround`
parent packages involved in the relative import. From the :mod:`!surround`
module for example, you might use::
from . import echo