Skip to content

Commit 9727880

Browse files
Issue python#19193: Improved cross-references in the tutorial.
1 parent b563d4b commit 9727880

2 files changed

Lines changed: 38 additions & 33 deletions

File tree

‎Doc/tutorial/classes.rst‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -609,7 +609,7 @@ will do nicely::
609609
A piece of Python code that expects a particular abstract data type can often be
610610
passed a class that emulates the methods of that data type instead. For
611611
instance, if you have a function that formats some data from a file object, you
612-
can define a class with methods :meth:`read` and :meth:`readline` that get the
612+
can define a class with methods :meth:`read` and :meth:`!readline` that get the
613613
data from a string buffer instead, and pass it as an argument.
614614

615615
.. (Unfortunately, this technique has its limitations: a class can't define
@@ -693,9 +693,10 @@ using a :keyword:`for` statement::
693693
This style of access is clear, concise, and convenient. The use of iterators
694694
pervades and unifies Python. Behind the scenes, the :keyword:`for` statement
695695
calls :func:`iter` on the container object. The function returns an iterator
696-
object that defines the method :meth:`next` which accesses elements in the
697-
container one at a time. When there are no more elements, :meth:`next` raises a
698-
:exc:`StopIteration` exception which tells the :keyword:`for` loop to terminate.
696+
object that defines the method :meth:`~iterator.next` which accesses elements
697+
in the container one at a time. When there are no more elements,
698+
:meth:`~iterator.next` raises a :exc:`StopIteration` exception which tells the
699+
:keyword:`for` loop to terminate.
699700
This example shows how it all works::
700701

701702
>>> s = 'abc'

‎Doc/tutorial/stdlib2.rst‎

Lines changed: 33 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -71,9 +71,9 @@ formatting numbers with group separators::
7171
Templating
7272
==========
7373

74-
The :mod:`string` module includes a versatile :class:`Template` class with a
75-
simplified syntax suitable for editing by end-users. This allows users to
76-
customize their applications without having to alter the application.
74+
The :mod:`string` module includes a versatile :class:`~string.Template` class
75+
with a simplified syntax suitable for editing by end-users. This allows users
76+
to customize their applications without having to alter the application.
7777

7878
The format uses placeholder names formed by ``$`` with valid Python identifiers
7979
(alphanumeric characters and underscores). Surrounding the placeholder with
@@ -85,11 +85,11 @@ spaces. Writing ``$$`` creates a single escaped ``$``::
8585
>>> t.substitute(village='Nottingham', cause='the ditch fund')
8686
'Nottinghamfolk send $10 to the ditch fund.'
8787

88-
The :meth:`substitute` method raises a :exc:`KeyError` when a placeholder is not
89-
supplied in a dictionary or a keyword argument. For mail-merge style
90-
applications, user supplied data may be incomplete and the
91-
:meth:`safe_substitute` method may be more appropriate --- it will leave
92-
placeholders unchanged if data is missing::
88+
The :meth:`~string.Template.substitute` method raises a :exc:`KeyError` when a
89+
placeholder is not supplied in a dictionary or a keyword argument. For
90+
mail-merge style applications, user supplied data may be incomplete and the
91+
:meth:`~string.Template.safe_substitute` method may be more appropriate ---
92+
it will leave placeholders unchanged if data is missing::
9393

9494
>>> t = Template('Return the $item to $owner.')
9595
>>> d = dict(item='unladen swallow')
@@ -132,8 +132,9 @@ templates for XML files, plain text reports, and HTML web reports.
132132
Working with Binary Data Record Layouts
133133
=======================================
134134

135-
The :mod:`struct` module provides :func:`pack` and :func:`unpack` functions for
136-
working with variable length binary record formats. The following example shows
135+
The :mod:`struct` module provides :func:`~struct.pack` and
136+
:func:`~struct.unpack` functions for working with variable length binary
137+
record formats. The following example shows
137138
how to loop through header information in a ZIP file without using the
138139
:mod:`zipfile` module. Pack codes ``"H"`` and ``"I"`` represent two and four
139140
byte unsigned numbers respectively. The ``"<"`` indicates that they are
@@ -229,8 +230,9 @@ This produces the following output:
229230
By default, informational and debugging messages are suppressed and the output
230231
is sent to standard error. Other output options include routing messages
231232
through email, datagrams, sockets, or to an HTTP Server. New filters can select
232-
different routing based on message priority: :const:`DEBUG`, :const:`INFO`,
233-
:const:`WARNING`, :const:`ERROR`, and :const:`CRITICAL`.
233+
different routing based on message priority: :const:`~logging.DEBUG`,
234+
:const:`~logging.INFO`, :const:`~logging.WARNING`, :const:`~logging.ERROR`,
235+
and :const:`~logging.CRITICAL`.
234236

235237
The logging system can be configured directly from Python or can be loaded from
236238
a user editable configuration file for customized logging without altering the
@@ -287,11 +289,11 @@ Many data structure needs can be met with the built-in list type. However,
287289
sometimes there is a need for alternative implementations with different
288290
performance trade-offs.
289291

290-
The :mod:`array` module provides an :class:`array()` object that is like a list
291-
that stores only homogeneous data and stores it more compactly. The following
292-
example shows an array of numbers stored as two byte unsigned binary numbers
293-
(typecode ``"H"``) rather than the usual 16 bytes per entry for regular lists of
294-
Python int objects::
292+
The :mod:`array` module provides an :class:`~array.array()` object that is like
293+
a list that stores only homogeneous data and stores it more compactly. The
294+
following example shows an array of numbers stored as two byte unsigned binary
295+
numbers (typecode ``"H"``) rather than the usual 16 bytes per entry for regular
296+
lists of Python int objects::
295297

296298
>>> from array import array
297299
>>> a = array('H', [4000, 10, 700, 22222])
@@ -300,10 +302,10 @@ Python int objects::
300302
>>> a[1:3]
301303
array('H', [10, 700])
302304

303-
The :mod:`collections` module provides a :class:`deque()` object that is like a
304-
list with faster appends and pops from the left side but slower lookups in the
305-
middle. These objects are well suited for implementing queues and breadth first
306-
tree searches::
305+
The :mod:`collections` module provides a :class:`~collections.deque()` object
306+
that is like a list with faster appends and pops from the left side but slower
307+
lookups in the middle. These objects are well suited for implementing queues
308+
and breadth first tree searches::
307309

308310
>>> from collections import deque
309311
>>> d = deque(["task1", "task2", "task3"])
@@ -349,8 +351,8 @@ not want to run a full list sort::
349351
Decimal Floating Point Arithmetic
350352
=================================
351353

352-
The :mod:`decimal` module offers a :class:`Decimal` datatype for decimal
353-
floating point arithmetic. Compared to the built-in :class:`float`
354+
The :mod:`decimal` module offers a :class:`~decimal.Decimal` datatype for
355+
decimal floating point arithmetic. Compared to the built-in :class:`float`
354356
implementation of binary floating point, the class is especially helpful for
355357

356358
* financial applications and other uses which require exact decimal
@@ -374,13 +376,15 @@ becomes significant if the results are rounded to the nearest cent::
374376
>>> round(.70 * 1.05, 2) # same calculation with floats
375377
0.73
376378

377-
The :class:`Decimal` result keeps a trailing zero, automatically inferring four
378-
place significance from multiplicands with two place significance. Decimal
379-
reproduces mathematics as done by hand and avoids issues that can arise when
380-
binary floating point cannot exactly represent decimal quantities.
379+
The :class:`~decimal.Decimal` result keeps a trailing zero, automatically
380+
inferring four place significance from multiplicands with two place
381+
significance. Decimal reproduces mathematics as done by hand and avoids
382+
issues that can arise when binary floating point cannot exactly represent
383+
decimal quantities.
381384

382-
Exact representation enables the :class:`Decimal` class to perform modulo
383-
calculations and equality tests that are unsuitable for binary floating point::
385+
Exact representation enables the :class:`~decimal.Decimal` class to perform
386+
modulo calculations and equality tests that are unsuitable for binary floating
387+
point::
384388

385389
>>> Decimal('1.00') % Decimal('.10')
386390
Decimal('0.00')

0 commit comments

Comments
 (0)