mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-11-02 03:01:58 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 15

Issue #19193: Improved cross-references in the tutorial.

Browse source
This commit is contained in:
Serhiy Storchaka 2013-10-09 09:54:46 +03:00
parent 7634e1cf90
commit 91aaeac050
2 changed files with 37 additions and 33 deletions
Download patch file Download diff file Expand all files Collapse all files

6
Doc/tutorial/classes.rst
View file

@ -652,7 +652,7 @@ will do nicely::
A piece of Python code that expects a particular abstract data type can often be A piece of Python code that expects a particular abstract data type can often be
passed a class that emulates the methods of that data type instead. For passed a class that emulates the methods of that data type instead. For
instance, if you have a function that formats some data from a file object, you instance, if you have a function that formats some data from a file object, you
can define a class with methods :meth:`read` and :meth:`readline` that get the can define a class with methods :meth:`read` and :meth:`!readline` that get the
data from a string buffer instead, and pass it as an argument. data from a string buffer instead, and pass it as an argument.
.. (Unfortunately, this technique has its limitations: a class can't define .. (Unfortunately, this technique has its limitations: a class can't define
@ -738,8 +738,8 @@ pervades and unifies Python. Behind the scenes, the :keyword:`for` statement
calls :func:`iter` on the container object. The function returns an iterator calls :func:`iter` on the container object. The function returns an iterator
object that defines the method :meth:`~iterator.__next__` which accesses object that defines the method :meth:`~iterator.__next__` which accesses
elements in the container one at a time. When there are no more elements, elements in the container one at a time. When there are no more elements,
:meth:`__next__` raises a :exc:`StopIteration` exception which tells the :meth:`~iterator.__next__` raises a :exc:`StopIteration` exception which tells the
:keyword:`for` loop to terminate. You can call the :meth:`__next__` method :keyword:`for` loop to terminate. You can call the :meth:`~iterator.__next__` method
using the :func:`next` built-in function; this example shows how it all works:: using the :func:`next` built-in function; this example shows how it all works::
>>> s = 'abc' >>> s = 'abc'

64
Doc/tutorial/stdlib2.rst
View file

@ -71,9 +71,9 @@ formatting numbers with group separators::
Templating Templating
========== ==========
The :mod:`string` module includes a versatile :class:`Template` class with a The :mod:`string` module includes a versatile :class:`~string.Template` class
simplified syntax suitable for editing by end-users. This allows users to with a simplified syntax suitable for editing by end-users. This allows users
customize their applications without having to alter the application. to customize their applications without having to alter the application.
The format uses placeholder names formed by ``$`` with valid Python identifiers The format uses placeholder names formed by ``$`` with valid Python identifiers
(alphanumeric characters and underscores). Surrounding the placeholder with (alphanumeric characters and underscores). Surrounding the placeholder with
@ -85,11 +85,11 @@ spaces. Writing ``$$`` creates a single escaped ``$``::
>>> t.substitute(village='Nottingham', cause='the ditch fund') >>> t.substitute(village='Nottingham', cause='the ditch fund')
'Nottinghamfolk send $10 to the ditch fund.' 'Nottinghamfolk send $10 to the ditch fund.'
The :meth:`substitute` method raises a :exc:`KeyError` when a placeholder is not The :meth:`~string.Template.substitute` method raises a :exc:`KeyError` when a
supplied in a dictionary or a keyword argument. For mail-merge style placeholder is not supplied in a dictionary or a keyword argument. For
applications, user supplied data may be incomplete and the mail-merge style applications, user supplied data may be incomplete and the
:meth:`safe_substitute` method may be more appropriate --- it will leave :meth:`~string.Template.safe_substitute` method may be more appropriate ---
placeholders unchanged if data is missing:: it will leave placeholders unchanged if data is missing::
>>> t = Template('Return the $item to $owner.') >>> t = Template('Return the $item to $owner.')
>>> d = dict(item='unladen swallow') >>> d = dict(item='unladen swallow')
@ -132,8 +132,9 @@ templates for XML files, plain text reports, and HTML web reports.
Working with Binary Data Record Layouts Working with Binary Data Record Layouts
======================================= =======================================
The :mod:`struct` module provides :func:`pack` and :func:`unpack` functions for The :mod:`struct` module provides :func:`~struct.pack` and
working with variable length binary record formats. The following example shows :func:`~struct.unpack` functions for working with variable length binary
record formats. The following example shows
how to loop through header information in a ZIP file without using the how to loop through header information in a ZIP file without using the
:mod:`zipfile` module. Pack codes ``"H"`` and ``"I"`` represent two and four :mod:`zipfile` module. Pack codes ``"H"`` and ``"I"`` represent two and four
byte unsigned numbers respectively. The ``"<"`` indicates that they are byte unsigned numbers respectively. The ``"<"`` indicates that they are
@ -201,7 +202,7 @@ While those tools are powerful, minor design errors can result in problems that
are difficult to reproduce. So, the preferred approach to task coordination is are difficult to reproduce. So, the preferred approach to task coordination is
to concentrate all access to a resource in a single thread and then use the to concentrate all access to a resource in a single thread and then use the
:mod:`queue` module to feed that thread with requests from other threads. :mod:`queue` module to feed that thread with requests from other threads.
Applications using :class:`Queue` objects for inter-thread communication and Applications using :class:`~queue.Queue` objects for inter-thread communication and
coordination are easier to design, more readable, and more reliable. coordination are easier to design, more readable, and more reliable.
@ -231,8 +232,9 @@ This produces the following output:
By default, informational and debugging messages are suppressed and the output By default, informational and debugging messages are suppressed and the output
is sent to standard error. Other output options include routing messages is sent to standard error. Other output options include routing messages
through email, datagrams, sockets, or to an HTTP Server. New filters can select through email, datagrams, sockets, or to an HTTP Server. New filters can select
different routing based on message priority: :const:`DEBUG`, :const:`INFO`, different routing based on message priority: :const:`~logging.DEBUG`,
:const:`WARNING`, :const:`ERROR`, and :const:`CRITICAL`. :const:`~logging.INFO`, :const:`~logging.WARNING`, :const:`~logging.ERROR`,
and :const:`~logging.CRITICAL`.
The logging system can be configured directly from Python or can be loaded from The logging system can be configured directly from Python or can be loaded from
a user editable configuration file for customized logging without altering the a user editable configuration file for customized logging without altering the
@ -289,11 +291,11 @@ Many data structure needs can be met with the built-in list type. However,
sometimes there is a need for alternative implementations with different sometimes there is a need for alternative implementations with different
performance trade-offs. performance trade-offs.
The :mod:`array` module provides an :class:`array()` object that is like a list The :mod:`array` module provides an :class:`~array.array()` object that is like
that stores only homogeneous data and stores it more compactly. The following a list that stores only homogeneous data and stores it more compactly. The
example shows an array of numbers stored as two byte unsigned binary numbers following example shows an array of numbers stored as two byte unsigned binary
(typecode ``"H"``) rather than the usual 16 bytes per entry for regular lists of numbers (typecode ``"H"``) rather than the usual 16 bytes per entry for regular
Python int objects:: lists of Python int objects::
>>> from array import array >>> from array import array
>>> a = array('H', [4000, 10, 700, 22222]) >>> a = array('H', [4000, 10, 700, 22222])
@ -302,10 +304,10 @@ Python int objects::
>>> a[1:3] >>> a[1:3]
array('H', [10, 700]) array('H', [10, 700])
The :mod:`collections` module provides a :class:`deque()` object that is like a The :mod:`collections` module provides a :class:`~collections.deque()` object
list with faster appends and pops from the left side but slower lookups in the that is like a list with faster appends and pops from the left side but slower
middle. These objects are well suited for implementing queues and breadth first lookups in the middle. These objects are well suited for implementing queues
tree searches:: and breadth first tree searches::
>>> from collections import deque >>> from collections import deque
>>> d = deque(["task1", "task2", "task3"]) >>> d = deque(["task1", "task2", "task3"])
@ -351,8 +353,8 @@ not want to run a full list sort::
Decimal Floating Point Arithmetic Decimal Floating Point Arithmetic
================================= =================================
The :mod:`decimal` module offers a :class:`Decimal` datatype for decimal The :mod:`decimal` module offers a :class:`~decimal.Decimal` datatype for
floating point arithmetic. Compared to the built-in :class:`float` decimal floating point arithmetic. Compared to the built-in :class:`float`
implementation of binary floating point, the class is especially helpful for implementation of binary floating point, the class is especially helpful for
* financial applications and other uses which require exact decimal * financial applications and other uses which require exact decimal
@ -373,13 +375,15 @@ becomes significant if the results are rounded to the nearest cent::
>>> round(.70 * 1.05, 2) >>> round(.70 * 1.05, 2)
0.73 0.73
The :class:`Decimal` result keeps a trailing zero, automatically inferring four The :class:`~decimal.Decimal` result keeps a trailing zero, automatically
place significance from multiplicands with two place significance. Decimal inferring four place significance from multiplicands with two place
reproduces mathematics as done by hand and avoids issues that can arise when significance. Decimal reproduces mathematics as done by hand and avoids
binary floating point cannot exactly represent decimal quantities. issues that can arise when binary floating point cannot exactly represent
decimal quantities.
Exact representation enables the :class:`Decimal` class to perform modulo Exact representation enables the :class:`~decimal.Decimal` class to perform
calculations and equality tests that are unsuitable for binary floating point:: modulo calculations and equality tests that are unsuitable for binary floating
point::
>>> Decimal('1.00') % Decimal('.10') >>> Decimal('1.00') % Decimal('.10')
Decimal('0.00') Decimal('0.00')