Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

Commit be99653

Browse filesBrowse files
[3.11] Improve references in the tutorial (GH-108069) (GH-108204)
* Use full qualified names for references (even if they do not work now, they will work in future). * Silence references to examples. (cherry picked from commit 622ddc4)
1 parent a372274 commit be99653
Copy full SHA for be99653

File tree

Expand file treeCollapse file tree

6 files changed

+48
-49
lines changed
Filter options
Expand file treeCollapse file tree

6 files changed

+48
-49
lines changed

‎Doc/tools/.nitignore

Copy file name to clipboardExpand all lines: Doc/tools/.nitignore
-2Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -166,9 +166,7 @@ Doc/tutorial/appendix.rst
166166
Doc/tutorial/classes.rst
167167
Doc/tutorial/controlflow.rst
168168
Doc/tutorial/datastructures.rst
169-
Doc/tutorial/inputoutput.rst
170169
Doc/tutorial/introduction.rst
171-
Doc/tutorial/modules.rst
172170
Doc/using/cmdline.rst
173171
Doc/using/configure.rst
174172
Doc/using/windows.rst

‎Doc/tutorial/classes.rst

Copy file name to clipboardExpand all lines: Doc/tutorial/classes.rst
+22-21Lines changed: 22 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,7 @@ Attributes may be read-only or writable. In the latter case, assignment to
9191
attributes is possible. Module attributes are writable: you can write
9292
``modname.the_answer = 42``. Writable attributes may also be deleted with the
9393
:keyword:`del` statement. For example, ``del modname.the_answer`` will remove
94-
the attribute :attr:`the_answer` from the object named by ``modname``.
94+
the attribute :attr:`!the_answer` from the object named by ``modname``.
9595

9696
Namespaces are created at different moments and have different lifetimes. The
9797
namespace containing the built-in names is created when the Python interpreter
@@ -249,7 +249,7 @@ created. This is basically a wrapper around the contents of the namespace
249249
created by the class definition; we'll learn more about class objects in the
250250
next section. The original local scope (the one in effect just before the class
251251
definition was entered) is reinstated, and the class object is bound here to the
252-
class name given in the class definition header (:class:`ClassName` in the
252+
class name given in the class definition header (:class:`!ClassName` in the
253253
example).
254254

255255

@@ -291,20 +291,20 @@ variable ``x``.
291291
The instantiation operation ("calling" a class object) creates an empty object.
292292
Many classes like to create objects with instances customized to a specific
293293
initial state. Therefore a class may define a special method named
294-
:meth:`__init__`, like this::
294+
:meth:`~object.__init__`, like this::
295295

296296
def __init__(self):
297297
self.data = []
298298

299-
When a class defines an :meth:`__init__` method, class instantiation
300-
automatically invokes :meth:`__init__` for the newly created class instance. So
299+
When a class defines an :meth:`~object.__init__` method, class instantiation
300+
automatically invokes :meth:`!__init__` for the newly created class instance. So
301301
in this example, a new, initialized instance can be obtained by::
302302

303303
x = MyClass()
304304

305-
Of course, the :meth:`__init__` method may have arguments for greater
305+
Of course, the :meth:`~object.__init__` method may have arguments for greater
306306
flexibility. In that case, arguments given to the class instantiation operator
307-
are passed on to :meth:`__init__`. For example, ::
307+
are passed on to :meth:`!__init__`. For example, ::
308308

309309
>>> class Complex:
310310
... def __init__(self, realpart, imagpart):
@@ -328,7 +328,7 @@ attribute names: data attributes and methods.
328328
*data attributes* correspond to "instance variables" in Smalltalk, and to "data
329329
members" in C++. Data attributes need not be declared; like local variables,
330330
they spring into existence when they are first assigned to. For example, if
331-
``x`` is the instance of :class:`MyClass` created above, the following piece of
331+
``x`` is the instance of :class:`!MyClass` created above, the following piece of
332332
code will print the value ``16``, without leaving a trace::
333333

334334
x.counter = 1
@@ -363,7 +363,7 @@ Usually, a method is called right after it is bound::
363363

364364
x.f()
365365

366-
In the :class:`MyClass` example, this will return the string ``'hello world'``.
366+
In the :class:`!MyClass` example, this will return the string ``'hello world'``.
367367
However, it is not necessary to call a method right away: ``x.f`` is a method
368368
object, and can be stored away and called at a later time. For example::
369369

@@ -375,7 +375,7 @@ will continue to print ``hello world`` until the end of time.
375375

376376
What exactly happens when a method is called? You may have noticed that
377377
``x.f()`` was called without an argument above, even though the function
378-
definition for :meth:`f` specified an argument. What happened to the argument?
378+
definition for :meth:`!f` specified an argument. What happened to the argument?
379379
Surely Python raises an exception when a function that requires an argument is
380380
called without any --- even if the argument isn't actually used...
381381

@@ -532,9 +532,9 @@ variable in the class is also ok. For example::
532532

533533
h = g
534534

535-
Now ``f``, ``g`` and ``h`` are all attributes of class :class:`C` that refer to
535+
Now ``f``, ``g`` and ``h`` are all attributes of class :class:`!C` that refer to
536536
function objects, and consequently they are all methods of instances of
537-
:class:`C` --- ``h`` being exactly equivalent to ``g``. Note that this practice
537+
:class:`!C` --- ``h`` being exactly equivalent to ``g``. Note that this practice
538538
usually only serves to confuse the reader of a program.
539539

540540
Methods may call other methods by using method attributes of the ``self``
@@ -581,7 +581,7 @@ this::
581581
.
582582
<statement-N>
583583

584-
The name :class:`BaseClassName` must be defined in a scope containing the
584+
The name :class:`!BaseClassName` must be defined in a scope containing the
585585
derived class definition. In place of a base class name, other arbitrary
586586
expressions are also allowed. This can be useful, for example, when the base
587587
class is defined in another module::
@@ -644,9 +644,9 @@ multiple base classes looks like this::
644644
For most purposes, in the simplest cases, you can think of the search for
645645
attributes inherited from a parent class as depth-first, left-to-right, not
646646
searching twice in the same class where there is an overlap in the hierarchy.
647-
Thus, if an attribute is not found in :class:`DerivedClassName`, it is searched
648-
for in :class:`Base1`, then (recursively) in the base classes of :class:`Base1`,
649-
and if it was not found there, it was searched for in :class:`Base2`, and so on.
647+
Thus, if an attribute is not found in :class:`!DerivedClassName`, it is searched
648+
for in :class:`!Base1`, then (recursively) in the base classes of :class:`!Base1`,
649+
and if it was not found there, it was searched for in :class:`!Base2`, and so on.
650650

651651
In fact, it is slightly more complex than that; the method resolution order
652652
changes dynamically to support cooperative calls to :func:`super`. This
@@ -759,7 +759,8 @@ is to use :mod:`dataclasses` for this purpose::
759759
A piece of Python code that expects a particular abstract data type can often be
760760
passed a class that emulates the methods of that data type instead. For
761761
instance, if you have a function that formats some data from a file object, you
762-
can define a class with methods :meth:`read` and :meth:`!readline` that get the
762+
can define a class with methods :meth:`~io.TextIOBase.read` and
763+
:meth:`~io.TextIOBase.readline` that get the
763764
data from a string buffer instead, and pass it as an argument.
764765

765766
.. (Unfortunately, this technique has its limitations: a class can't define
@@ -768,7 +769,7 @@ data from a string buffer instead, and pass it as an argument.
768769
not cause the interpreter to read further input from it.)
769770
770771
Instance method objects have attributes, too: ``m.__self__`` is the instance
771-
object with the method :meth:`m`, and ``m.__func__`` is the function object
772+
object with the method :meth:`!m`, and ``m.__func__`` is the function object
772773
corresponding to the method.
773774

774775

@@ -817,9 +818,9 @@ using the :func:`next` built-in function; this example shows how it all works::
817818
StopIteration
818819

819820
Having seen the mechanics behind the iterator protocol, it is easy to add
820-
iterator behavior to your classes. Define an :meth:`__iter__` method which
821+
iterator behavior to your classes. Define an :meth:`~container.__iter__` method which
821822
returns an object with a :meth:`~iterator.__next__` method. If the class
822-
defines :meth:`__next__`, then :meth:`__iter__` can just return ``self``::
823+
defines :meth:`!__next__`, then :meth:`!__iter__` can just return ``self``::
823824

824825
class Reverse:
825826
"""Iterator for looping over a sequence backwards."""
@@ -878,7 +879,7 @@ easy to create::
878879

879880
Anything that can be done with generators can also be done with class-based
880881
iterators as described in the previous section. What makes generators so
881-
compact is that the :meth:`__iter__` and :meth:`~generator.__next__` methods
882+
compact is that the :meth:`~iterator.__iter__` and :meth:`~generator.__next__` methods
882883
are created automatically.
883884

884885
Another key feature is that the local variables and execution state are

‎Doc/tutorial/controlflow.rst

Copy file name to clipboardExpand all lines: Doc/tutorial/controlflow.rst
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -534,7 +534,7 @@ This example, as usual, demonstrates some new Python features:
534534
Different types define different methods. Methods of different types may have
535535
the same name without causing ambiguity. (It is possible to define your own
536536
object types and methods, using *classes*, see :ref:`tut-classes`)
537-
The method :meth:`append` shown in the example is defined for list objects; it
537+
The method :meth:`~list.append` shown in the example is defined for list objects; it
538538
adds a new element at the end of the list. In this example it is equivalent to
539539
``result = result + [a]``, but more efficient.
540540

‎Doc/tutorial/datastructures.rst

Copy file name to clipboardExpand all lines: Doc/tutorial/datastructures.rst
+6-6Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -143,8 +143,8 @@ Using Lists as Stacks
143143

144144
The list methods make it very easy to use a list as a stack, where the last
145145
element added is the first element retrieved ("last-in, first-out"). To add an
146-
item to the top of the stack, use :meth:`append`. To retrieve an item from the
147-
top of the stack, use :meth:`pop` without an explicit index. For example::
146+
item to the top of the stack, use :meth:`~list.append`. To retrieve an item from the
147+
top of the stack, use :meth:`~list.pop` without an explicit index. For example::
148148

149149
>>> stack = [3, 4, 5]
150150
>>> stack.append(6)
@@ -341,7 +341,7 @@ The :keyword:`!del` statement
341341
=============================
342342

343343
There is a way to remove an item from a list given its index instead of its
344-
value: the :keyword:`del` statement. This differs from the :meth:`pop` method
344+
value: the :keyword:`del` statement. This differs from the :meth:`~list.pop` method
345345
which returns a value. The :keyword:`!del` statement can also be used to remove
346346
slices from a list or clear the entire list (which we did earlier by assignment
347347
of an empty list to the slice). For example::
@@ -501,8 +501,8 @@ any immutable type; strings and numbers can always be keys. Tuples can be used
501501
as keys if they contain only strings, numbers, or tuples; if a tuple contains
502502
any mutable object either directly or indirectly, it cannot be used as a key.
503503
You can't use lists as keys, since lists can be modified in place using index
504-
assignments, slice assignments, or methods like :meth:`append` and
505-
:meth:`extend`.
504+
assignments, slice assignments, or methods like :meth:`~list.append` and
505+
:meth:`~list.extend`.
506506

507507
It is best to think of a dictionary as a set of *key: value* pairs,
508508
with the requirement that the keys are unique (within one dictionary). A pair of
@@ -567,7 +567,7 @@ Looping Techniques
567567
==================
568568

569569
When looping through dictionaries, the key and corresponding value can be
570-
retrieved at the same time using the :meth:`items` method. ::
570+
retrieved at the same time using the :meth:`~dict.items` method. ::
571571

572572
>>> knights = {'gallahad': 'the pure', 'robin': 'the brave'}
573573
>>> for k, v in knights.items():

‎Doc/tutorial/inputoutput.rst

Copy file name to clipboardExpand all lines: Doc/tutorial/inputoutput.rst
+4-4Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Fancier Output Formatting
1515
=========================
1616

1717
So far we've encountered two ways of writing values: *expression statements* and
18-
the :func:`print` function. (A third way is using the :meth:`write` method
18+
the :func:`print` function. (A third way is using the :meth:`~io.TextIOBase.write` method
1919
of file objects; the standard output file can be referenced as ``sys.stdout``.
2020
See the Library Reference for more information on this.)
2121

@@ -456,8 +456,8 @@ to the very file end with ``seek(0, 2)``) and the only valid *offset* values are
456456
those returned from the ``f.tell()``, or zero. Any other *offset* value produces
457457
undefined behaviour.
458458

459-
File objects have some additional methods, such as :meth:`~file.isatty` and
460-
:meth:`~file.truncate` which are less frequently used; consult the Library
459+
File objects have some additional methods, such as :meth:`~io.IOBase.isatty` and
460+
:meth:`~io.IOBase.truncate` which are less frequently used; consult the Library
461461
Reference for a complete guide to file objects.
462462

463463

@@ -469,7 +469,7 @@ Saving structured data with :mod:`json`
469469
.. index:: pair: module; json
470470

471471
Strings can easily be written to and read from a file. Numbers take a bit more
472-
effort, since the :meth:`read` method only returns strings, which will have to
472+
effort, since the :meth:`~io.TextIOBase.read` method only returns strings, which will have to
473473
be passed to a function like :func:`int`, which takes a string like ``'123'``
474474
and returns its numeric value 123. When you want to save more complex data
475475
types like nested lists and dictionaries, parsing and serializing by hand

‎Doc/tutorial/modules.rst

Copy file name to clipboardExpand all lines: Doc/tutorial/modules.rst
+15-15Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -183,7 +183,7 @@ The Module Search Path
183183

184184
.. index:: triple: module; search; path
185185

186-
When a module named :mod:`spam` is imported, the interpreter first searches for
186+
When a module named :mod:`!spam` is imported, the interpreter first searches for
187187
a built-in module with that name. These module names are listed in
188188
:data:`sys.builtin_module_names`. If not found, it then searches for a file
189189
named :file:`spam.py` in a list of directories given by the variable
@@ -389,7 +389,7 @@ Packages
389389
========
390390

391391
Packages are a way of structuring Python's module namespace by using "dotted
392-
module names". For example, the module name :mod:`A.B` designates a submodule
392+
module names". For example, the module name :mod:`!A.B` designates a submodule
393393
named ``B`` in a package named ``A``. Just like the use of modules saves the
394394
authors of different modules from having to worry about each other's global
395395
variable names, the use of dotted module names saves the authors of multi-module
@@ -448,7 +448,7 @@ example::
448448

449449
import sound.effects.echo
450450

451-
This loads the submodule :mod:`sound.effects.echo`. It must be referenced with
451+
This loads the submodule :mod:`!sound.effects.echo`. It must be referenced with
452452
its full name. ::
453453

454454
sound.effects.echo.echofilter(input, output, delay=0.7, atten=4)
@@ -457,7 +457,7 @@ An alternative way of importing the submodule is::
457457

458458
from sound.effects import echo
459459

460-
This also loads the submodule :mod:`echo`, and makes it available without its
460+
This also loads the submodule :mod:`!echo`, and makes it available without its
461461
package prefix, so it can be used as follows::
462462

463463
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::
466466

467467
from sound.effects.echo import echofilter
468468

469-
Again, this loads the submodule :mod:`echo`, but this makes its function
470-
:func:`echofilter` directly available::
469+
Again, this loads the submodule :mod:`!echo`, but this makes its function
470+
:func:`!echofilter` directly available::
471471

472472
echofilter(input, output, delay=0.7, atten=4)
473473

@@ -510,7 +510,7 @@ code::
510510
__all__ = ["echo", "surround", "reverse"]
511511

512512
This would mean that ``from sound.effects import *`` would import the three
513-
named submodules of the :mod:`sound.effects` package.
513+
named submodules of the :mod:`!sound.effects` package.
514514

515515
Be aware that submodules might become shadowed by locally defined names. For
516516
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
529529
return msg[::-1] # in the case of a 'from sound.effects import *'
530530

531531
If ``__all__`` is not defined, the statement ``from sound.effects import *``
532-
does *not* import all submodules from the package :mod:`sound.effects` into the
533-
current namespace; it only ensures that the package :mod:`sound.effects` has
532+
does *not* import all submodules from the package :mod:`!sound.effects` into the
533+
current namespace; it only ensures that the package :mod:`!sound.effects` has
534534
been imported (possibly running any initialization code in :file:`__init__.py`)
535535
and then imports whatever names are defined in the package. This includes any
536536
names defined (and submodules explicitly loaded) by :file:`__init__.py`. It
@@ -541,8 +541,8 @@ previous :keyword:`import` statements. Consider this code::
541541
import sound.effects.surround
542542
from sound.effects import *
543543

544-
In this example, the :mod:`echo` and :mod:`surround` modules are imported in the
545-
current namespace because they are defined in the :mod:`sound.effects` package
544+
In this example, the :mod:`!echo` and :mod:`!surround` modules are imported in the
545+
current namespace because they are defined in the :mod:`!sound.effects` package
546546
when the ``from...import`` statement is executed. (This also works when
547547
``__all__`` is defined.)
548548

@@ -561,15 +561,15 @@ packages.
561561
Intra-package References
562562
------------------------
563563

564-
When packages are structured into subpackages (as with the :mod:`sound` package
564+
When packages are structured into subpackages (as with the :mod:`!sound` package
565565
in the example), you can use absolute imports to refer to submodules of siblings
566-
packages. For example, if the module :mod:`sound.filters.vocoder` needs to use
567-
the :mod:`echo` module in the :mod:`sound.effects` package, it can use ``from
566+
packages. For example, if the module :mod:`!sound.filters.vocoder` needs to use
567+
the :mod:`!echo` module in the :mod:`!sound.effects` package, it can use ``from
568568
sound.effects import echo``.
569569

570570
You can also write relative imports, with the ``from module import name`` form
571571
of import statement. These imports use leading dots to indicate the current and
572-
parent packages involved in the relative import. From the :mod:`surround`
572+
parent packages involved in the relative import. From the :mod:`!surround`
573573
module for example, you might use::
574574

575575
from . import echo

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.