Changeset 391 for python/trunk/Doc/tutorial/stdlib2.rst

Timestamp:

Mar 19, 2014, 11:31:01 PM (11 years ago)

Author:

dmik

Message:

python: Merge vendor 2.7.6 to trunk.

Location:

python/trunk

Files:

• . (modified) (1 prop)
• Doc/tutorial/stdlib2.rst (modified) (12 diffs)

python/trunk/Doc/tutorial/stdlib2.rst

@@ -72 +72 @@
 ==========
 
-The :mod:`string` module includes a versatile :class:`Template` class with a
-simplified syntax suitable for editing by end-users.  This allows users to
-customize their applications without having to alter the application.
+The :mod:`string` module includes a versatile :class:`~string.Template` class
+with a simplified syntax suitable for editing by end-users.  This allows users
+to customize their applications without having to alter the application.
 
 The format uses placeholder names formed by ``$`` with valid Python identifiers
@@ -86 +86 @@
    'Nottinghamfolk send $10 to the ditch fund.'
 
-The :meth:`substitute` method raises a :exc:`KeyError` when a placeholder is not
-supplied in a dictionary or a keyword argument. For mail-merge style
-applications, user supplied data may be incomplete and the
-:meth:`safe_substitute` method may be more appropriate --- it will leave
-placeholders unchanged if data is missing::
+The :meth:`~string.Template.substitute` method raises a :exc:`KeyError` when a
+placeholder is not supplied in a dictionary or a keyword argument.  For
+mail-merge style applications, user supplied data may be incomplete and the
+:meth:`~string.Template.safe_substitute` method may be more appropriate ---
+it will leave placeholders unchanged if data is missing::
 
    >>> t = Template('Return the $item to $owner.')
@@ -96 +96 @@
    >>> t.substitute(d)
    Traceback (most recent call last):
-     . . .
+     ...
    KeyError: 'owner'
    >>> t.safe_substitute(d)
@@ -133 +133 @@
 =======================================
 
-The :mod:`struct` module provides :func:`pack` and :func:`unpack` functions for
-working with variable length binary record formats.  The following example shows
+The :mod:`struct` module provides :func:`~struct.pack` and
+: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
 :mod:`zipfile` module.  Pack codes ``"H"`` and ``"I"`` represent two and four
@@ -219 +220 @@
    logging.critical('Critical error -- shutting down')
 
-This produces the following output::
+This produces the following output:
+
+.. code-block:: none
 
    WARNING:root:Warning:config file server.conf not found
@@ -228 +231 @@
 is sent to standard error.  Other output options include routing messages
 through email, datagrams, sockets, or to an HTTP Server.  New filters can select
-different routing based on message priority: :const:`DEBUG`, :const:`INFO`,
-:const:`WARNING`, :const:`ERROR`, and :const:`CRITICAL`.
+different routing based on message priority: :const:`~logging.DEBUG`,
+: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
@@ -256 +260 @@
    >>> class A:
    ...     def __init__(self, value):
-   ...             self.value = value
+   ...         self.value = value
    ...     def __repr__(self):
-   ...             return str(self.value)
+   ...         return str(self.value)
    ...
    >>> a = A(10)                   # create a reference
@@ -286 +290 @@
 performance trade-offs.
 
-The :mod:`array` module provides an :class:`array()` object that is like a list
-that stores only homogeneous data and stores it more compactly.  The following
-example shows an array of numbers stored as two byte unsigned binary numbers
-(typecode ``"H"``) rather than the usual 16 bytes per entry for regular lists of
-Python int objects::
+The :mod:`array` module provides an :class:`~array.array()` object that is like
+a list that stores only homogeneous data and stores it more compactly.  The
+following example shows an array of numbers stored as two byte unsigned binary
+numbers (typecode ``"H"``) rather than the usual 16 bytes per entry for regular
+lists of Python int objects::
 
    >>> from array import array
@@ -299 +303 @@
    array('H', [10, 700])
 
-The :mod:`collections` module provides a :class:`deque()` object that is like a
-list with faster appends and pops from the left side but slower lookups in the
-middle. These objects are well suited for implementing queues and breadth first
-tree searches::
+The :mod:`collections` module provides a :class:`~collections.deque()` object
+that is like a list with faster appends and pops from the left side but slower
+lookups in the middle. These objects are well suited for implementing queues
+and breadth first tree searches::
 
    >>> from collections import deque
@@ -309 +313 @@
    >>> print "Handling", d.popleft()
    Handling task1
+
+::
 
    unsearched = deque([starting_node])
@@ -346 +352 @@
 =================================
 
-The :mod:`decimal` module offers a :class:`Decimal` datatype for decimal
-floating point arithmetic.  Compared to the built-in :class:`float`
+The :mod:`decimal` module offers a :class:`~decimal.Decimal` datatype for
+decimal floating point arithmetic.  Compared to the built-in :class:`float`
 implementation of binary floating point, the class is especially helpful for
 
@@ -363 +369 @@
 
    >>> from decimal import *
-   >>> Decimal('0.70') * Decimal('1.05')
+   >>> x = Decimal('0.70') * Decimal('1.05')
+   >>> x
    Decimal('0.7350')
-   >>> .70 * 1.05
-   0.73499999999999999
-
-The :class:`Decimal` result keeps a trailing zero, automatically inferring four
-place significance from multiplicands with two place significance.  Decimal
-reproduces mathematics as done by hand and avoids issues that can arise when
-binary floating point cannot exactly represent decimal quantities.
-
-Exact representation enables the :class:`Decimal` class to perform modulo
-calculations and equality tests that are unsuitable for binary floating point::
+   >>> x.quantize(Decimal('0.01'))  # round to nearest cent
+   Decimal('0.74')
+   >>> round(.70 * 1.05, 2)         # same calculation with floats
+   0.73
+
+The :class:`~decimal.Decimal` result keeps a trailing zero, automatically
+inferring four place significance from multiplicands with two place
+significance.  Decimal reproduces mathematics as done by hand and avoids
+issues that can arise when binary floating point cannot exactly represent
+decimal quantities.
+
+Exact representation enables the :class:`~decimal.Decimal` class to perform
+modulo calculations and equality tests that are unsuitable for binary floating
+point::
 
    >>> Decimal('1.00') % Decimal('.10')