Changeset 391 for python/trunk/Doc/library/string.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/library/string.rst (modified) (30 diffs)

python/trunk/Doc/library/string.rst

@@ -7 +7 @@
 
 .. index:: module: re
+
+**Source code:** :source:`Lib/string.py`
+
+--------------
 
 The :mod:`string` module contains a number of useful constants and
@@ -18 +22 @@
 string functions based on regular expressions.
 
-
 String constants
 ----------------
@@ -106 +109 @@
 -----------------
 
-Starting in Python 2.6, the built-in str and unicode classes provide the ability
+.. versionadded:: 2.6
+
+The built-in str and unicode classes provide the ability
 to do complex variable substitutions and value formatting via the
 :meth:`str.format` method described in :pep:`3101`.  The :class:`Formatter`
@@ -117 +122 @@
    The :class:`Formatter` class has the following public methods:
 
-   .. method:: format(format_string, *args, *kwargs)
-
-      :meth:`format` is the primary API method.  It takes a format template
-      string, and an arbitrary set of positional and keyword argument.
+   .. method:: format(format_string, *args, **kwargs)
+
+      :meth:`format` is the primary API method.  It takes a format string and
+      an arbitrary set of positional and keyword arguments.
       :meth:`format` is just a wrapper that calls :meth:`vformat`.
 
@@ -128 +133 @@
       separate function for cases where you want to pass in a predefined
       dictionary of arguments, rather than unpacking and repacking the
-      dictionary as individual arguments using the ``*args`` and ``**kwds``
-      syntax.  :meth:`vformat` does the work of breaking up the format template
-      string into character data and replacement fields.  It calls the various
+      dictionary as individual arguments using the ``*args`` and ``**kwargs``
+      syntax.  :meth:`vformat` does the work of breaking up the format string
+      into character data and replacement fields.  It calls the various
       methods described below.
 
@@ -140 +145 @@
       Loop over the format_string and return an iterable of tuples
       (*literal_text*, *field_name*, *format_spec*, *conversion*).  This is used
-      by :meth:`vformat` to break the string in to either literal text, or
+      by :meth:`vformat` to break the string into either literal text, or
       replacement fields.
 
@@ -189 +194 @@
       named arguments), and a reference to the *args* and *kwargs* that was
       passed to vformat.  The set of unused args can be calculated from these
-      parameters.  :meth:`check_unused_args` is assumed to throw an exception if
+      parameters.  :meth:`check_unused_args` is assumed to raise an exception if
       the check fails.
 
@@ -200 +205 @@
 
       Converts the value (returned by :meth:`get_field`) given a conversion type
-      (as in the tuple returned by the :meth:`parse` method.)  The default
-      version understands 'r' (repr) and 's' (str) conversion types.
+      (as in the tuple returned by the :meth:`parse` method).  The default
+      version understands 's' (str), 'r' (repr) and 'a' (ascii) conversion
+      types.
 
 
@@ -211 +217 @@
 The :meth:`str.format` method and the :class:`Formatter` class share the same
 syntax for format strings (although in the case of :class:`Formatter`,
-subclasses can define their own format string syntax.)
+subclasses can define their own format string syntax).
 
 Format strings contain "replacement fields" surrounded by curly braces ``{}``.
@@ -221 +227 @@
 
    .. productionlist:: sf
-      replacement_field: "{" `field_name` ["!" `conversion`] [":" `format_spec`] "}"
-      field_name: (`identifier` | `integer`) ("." `attribute_name` | "[" `element_index` "]")*
+      replacement_field: "{" [`field_name`] ["!" `conversion`] [":" `format_spec`] "}"
+      field_name: arg_name ("." `attribute_name` | "[" `element_index` "]")*
+      arg_name: [`identifier` | `integer`]
       attribute_name: `identifier`
       element_index: `integer` | `index_string`
@@ -229 +236 @@
       format_spec: <described in the next section>
 
-In less formal terms, the replacement field starts with a *field_name*, which
-can either be a number (for a positional argument), or an identifier (for
-keyword arguments).  Following this is an optional *conversion* field, which is
+In less formal terms, the replacement field can start with a *field_name* that specifies
+the object whose value is to be formatted and inserted
+into the output instead of the replacement field.
+The *field_name* is optionally followed by a  *conversion* field, which is
 preceded by an exclamation point ``'!'``, and a *format_spec*, which is preceded
-by a colon ``':'``.
-
-The *field_name* itself begins with either a number or a keyword.  If it's a
-number, it refers to a positional argument, and if it's a keyword it refers to a
-named keyword argument.  This can be followed by any number of index or
+by a colon ``':'``.  These specify a non-default format for the replacement value.
+
+See also the :ref:`formatspec` section.
+
+The *field_name* itself begins with an *arg_name* that is either a number or a
+keyword.  If it's a number, it refers to a positional argument, and if it's a keyword,
+it refers to a named keyword argument.  If the numerical arg_names in a format string
+are 0, 1, 2, ... in sequence, they can all be omitted (not just some)
+and the numbers 0, 1, 2, ... will be automatically inserted in that order.
+Because *arg_name* is not quote-delimited, it is not possible to specify arbitrary
+dictionary keys (e.g., the strings ``'10'`` or ``':-]'``) within a format string.
+The *arg_name* can be followed by any number of index or
 attribute expressions. An expression of the form ``'.name'`` selects the named
 attribute using :func:`getattr`, while an expression of the form ``'[index]'``
 does an index lookup using :func:`__getitem__`.
 
+.. versionchanged:: 2.7
+   The positional argument specifiers can be omitted, so ``'{} {}'`` is
+   equivalent to ``'{0} {1}'``.
+
 Some simple format string examples::
 
    "First, thou shalt count to {0}" # References first positional argument
+   "Bring me a {}"                  # Implicitly references the first positional argument
+   "From {} to {}"                  # Same as "From {0} to {1}"
    "My quest is {name}"             # References keyword argument 'name'
    "Weight in tons {0.weight}"      # 'weight' attribute of first positional arg
@@ -278 +299 @@
 This allows the formatting of a value to be dynamically specified.
 
-For example, suppose you wanted to have a replacement field whose field width is
-determined by another variable::
-
-   "A man with two {0:{1}}".format("noses", 10)
-
-This would first evaluate the inner replacement field, making the format string
-effectively::
-
-   "A man with two {0:10}"
-
-Then the outer replacement field would be evaluated, producing::
-
-   "noses     "
-
-Which is substituted into the string, yielding::
-
-   "A man with two noses     "
-
-(The extra space is because we specified a field width of 10, and because left
-alignment is the default for strings.)
+See the :ref:`formatexamples` section for some examples.
 
 
@@ -307 +309 @@
 "Format specifications" are used within replacement fields contained within a
 format string to define how individual values are presented (see
-:ref:`formatstrings`.)  They can also be passed directly to the built-in
+:ref:`formatstrings`).  They can also be passed directly to the built-in
 :func:`format` function.  Each formattable type may define how the format
 specification is to be interpreted.
@@ -321 +323 @@
 
 .. productionlist:: sf
-   format_spec: [[`fill`]`align`][`sign`][#][0][`width`][.`precision`][`type`]
-   fill: <a character other than '}'>
+   format_spec: [[`fill`]`align`][`sign`][#][0][`width`][,][.`precision`][`type`]
+   fill: <any character>
    align: "<" | ">" | "=" | "^"
    sign: "+" | "-" | " "
@@ -329 +331 @@
    type: "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%"
 
-The *fill* character can be any character other than '}' (which signifies the
-end of the field).  The presence of a fill character is signaled by the *next*
-character, which must be one of the alignment options. If the second character
-of *format_spec* is not a valid alignment option, then it is assumed that both
-the fill character and the alignment option are absent.
+If a valid *align* value is specified, it can be preceeded by a *fill*
+character that can be any character and defaults to a space if omitted.
+Note that it is not possible to use ``{`` and ``}`` as *fill* char while
+using the :meth:`str.format` method; this limitation however doesn't
+affect the :func:`format` function.
 
 The meaning of the various alignment options is as follows:
@@ -341 +343 @@
    +=========+==========================================================+
    | ``'<'`` | Forces the field to be left-aligned within the available |
-   |         | space (This is the default.)                             |
+   |         | space (this is the default for most objects).            |
    +---------+----------------------------------------------------------+
    | ``'>'`` | Forces the field to be right-aligned within the          |
-   |         | available space.                                         |
+   |         | available space (this is the default for numbers).       |
    +---------+----------------------------------------------------------+
    | ``'='`` | Forces the padding to be placed after the sign (if any)  |
@@ -379 +381 @@
 by ``'0b'``, ``'0o'``, or ``'0x'``, respectively.
 
+The ``','`` option signals the use of a comma for a thousands separator.
+For a locale aware separator, use the ``'n'`` integer presentation type
+instead.
+
+.. versionchanged:: 2.7
+   Added the ``','`` option (see also :pep:`378`).
+
 *width* is a decimal integer defining the minimum field width.  If not
 specified, then the field width will be determined by the content.
 
-If the *width* field is preceded by a zero (``'0'``) character, this enables
-zero-padding.  This is equivalent to an *alignment* type of ``'='`` and a *fill*
-character of ``'0'``.
+Preceding the *width* field by a zero (``'0'``) character enables
+sign-aware zero-padding for numeric types.  This is equivalent to a *fill*
+character of ``'0'`` with an *alignment* type of ``'='``.
 
 The *precision* is a decimal number indicating how many digits should be
@@ -445 +454 @@
    | ``'e'`` | Exponent notation. Prints the number in scientific       |
    |         | notation using the letter 'e' to indicate the exponent.  |
+   |         | The default precision is ``6``.                          |
    +---------+----------------------------------------------------------+
    | ``'E'`` | Exponent notation. Same as ``'e'`` except it uses an     |
@@ -450 +460 @@
    +---------+----------------------------------------------------------+
    | ``'f'`` | Fixed point. Displays the number as a fixed-point        |
-   |         | number.                                                  |
+   |         | number.  The default precision is ``6``.                 |
    +---------+----------------------------------------------------------+
    | ``'F'`` | Fixed point. Same as ``'f'``.                            |
@@ -470 +480 @@
    |         | removed if there are no remaining digits following it.   |
    |         |                                                          |
-   |         | Postive and negative infinity, positive and negative     |
+   |         | Positive and negative infinity, positive and negative    |
    |         | zero, and nans, are formatted as ``inf``, ``-inf``,      |
    |         | ``0``, ``-0`` and ``nan`` respectively, regardless of    |
@@ -476 +486 @@
    |         |                                                          |
    |         | A precision of ``0`` is treated as equivalent to a       |
-   |         | precision of ``1``.                                      |
+   |         | precision of ``1``.  The default precision is ``6``.     |
    +---------+----------------------------------------------------------+
    | ``'G'`` | General format. Same as ``'g'`` except switches to       |
@@ -493 +503 @@
 
 
+
+.. _formatexamples:
+
+Format examples
+^^^^^^^^^^^^^^^
+
+This section contains examples of the new format syntax and comparison with
+the old ``%``-formatting.
+
+In most of the cases the syntax is similar to the old ``%``-formatting, with the
+addition of the ``{}`` and with ``:`` used instead of ``%``.
+For example, ``'%03.2f'`` can be translated to ``'{:03.2f}'``.
+
+The new format syntax also supports new and different options, shown in the
+follow examples.
+
+Accessing arguments by position::
+
+   >>> '{0}, {1}, {2}'.format('a', 'b', 'c')
+   'a, b, c'
+   >>> '{}, {}, {}'.format('a', 'b', 'c')  # 2.7+ only
+   'a, b, c'
+   >>> '{2}, {1}, {0}'.format('a', 'b', 'c')
+   'c, b, a'
+   >>> '{2}, {1}, {0}'.format(*'abc')      # unpacking argument sequence
+   'c, b, a'
+   >>> '{0}{1}{0}'.format('abra', 'cad')   # arguments' indices can be repeated
+   'abracadabra'
+
+Accessing arguments by name::
+
+   >>> 'Coordinates: {latitude}, {longitude}'.format(latitude='37.24N', longitude='-115.81W')
+   'Coordinates: 37.24N, -115.81W'
+   >>> coord = {'latitude': '37.24N', 'longitude': '-115.81W'}
+   >>> 'Coordinates: {latitude}, {longitude}'.format(**coord)
+   'Coordinates: 37.24N, -115.81W'
+
+Accessing arguments' attributes::
+
+   >>> c = 3-5j
+   >>> ('The complex number {0} is formed from the real part {0.real} '
+   ...  'and the imaginary part {0.imag}.').format(c)
+   'The complex number (3-5j) is formed from the real part 3.0 and the imaginary part -5.0.'
+   >>> class Point(object):
+   ...     def __init__(self, x, y):
+   ...         self.x, self.y = x, y
+   ...     def __str__(self):
+   ...         return 'Point({self.x}, {self.y})'.format(self=self)
+   ...
+   >>> str(Point(4, 2))
+   'Point(4, 2)'
+
+
+Accessing arguments' items::
+
+   >>> coord = (3, 5)
+   >>> 'X: {0[0]};  Y: {0[1]}'.format(coord)
+   'X: 3;  Y: 5'
+
+Replacing ``%s`` and ``%r``::
+
+   >>> "repr() shows quotes: {!r}; str() doesn't: {!s}".format('test1', 'test2')
+   "repr() shows quotes: 'test1'; str() doesn't: test2"
+
+Aligning the text and specifying a width::
+
+   >>> '{:<30}'.format('left aligned')
+   'left aligned                  '
+   >>> '{:>30}'.format('right aligned')
+   '                 right aligned'
+   >>> '{:^30}'.format('centered')
+   '           centered           '
+   >>> '{:*^30}'.format('centered')  # use '*' as a fill char
+   '***********centered***********'
+
+Replacing ``%+f``, ``%-f``, and ``% f`` and specifying a sign::
+
+   >>> '{:+f}; {:+f}'.format(3.14, -3.14)  # show it always
+   '+3.140000; -3.140000'
+   >>> '{: f}; {: f}'.format(3.14, -3.14)  # show a space for positive numbers
+   ' 3.140000; -3.140000'
+   >>> '{:-f}; {:-f}'.format(3.14, -3.14)  # show only the minus -- same as '{:f}; {:f}'
+   '3.140000; -3.140000'
+
+Replacing ``%x`` and ``%o`` and converting the value to different bases::
+
+   >>> # format also supports binary numbers
+   >>> "int: {0:d};  hex: {0:x};  oct: {0:o};  bin: {0:b}".format(42)
+   'int: 42;  hex: 2a;  oct: 52;  bin: 101010'
+   >>> # with 0x, 0o, or 0b as prefix:
+   >>> "int: {0:d};  hex: {0:#x};  oct: {0:#o};  bin: {0:#b}".format(42)
+   'int: 42;  hex: 0x2a;  oct: 0o52;  bin: 0b101010'
+
+Using the comma as a thousands separator::
+
+   >>> '{:,}'.format(1234567890)
+   '1,234,567,890'
+
+Expressing a percentage::
+
+   >>> points = 19.5
+   >>> total = 22
+   >>> 'Correct answers: {:.2%}'.format(points/total)
+   'Correct answers: 88.64%'
+
+Using type-specific formatting::
+
+   >>> import datetime
+   >>> d = datetime.datetime(2010, 7, 4, 12, 15, 58)
+   >>> '{:%Y-%m-%d %H:%M:%S}'.format(d)
+   '2010-07-04 12:15:58'
+
+Nesting arguments and more complex examples::
+
+   >>> for align, text in zip('<^>', ['left', 'center', 'right']):
+   ...     '{0:{fill}{align}16}'.format(text, fill=align, align=align)
+   ...
+   'left<<<<<<<<<<<<'
+   '^^^^^center^^^^^'
+   '>>>>>>>>>>>right'
+   >>>
+   >>> octets = [192, 168, 0, 1]
+   >>> '{:02X}{:02X}{:02X}{:02X}'.format(*octets)
+   'C0A80001'
+   >>> int(_, 16)
+   3232235521
+   >>>
+   >>> width = 5
+   >>> for num in range(5,12):
+   ...     for base in 'dXob':
+   ...         print '{0:{width}{base}}'.format(num, base=base, width=width),
+   ...     print
+   ...
+       5     5     5   101
+       6     6     6   110
+       7     7     7   111
+       8     8    10  1000
+       9     9    11  1001
+      10     A    12  1010
+      11     B    13  1011
+
+
+
 Template strings
 ----------------
+
+.. versionadded:: 2.4
 
 Templates provide simpler string substitutions as described in :pep:`292`.
@@ -513 +668 @@
 Any other appearance of ``$`` in the string will result in a :exc:`ValueError`
 being raised.
-
-.. versionadded:: 2.4
 
 The :mod:`string` module provides a :class:`Template` class that implements
@@ -549 +702 @@
       placeholders that are not valid Python identifiers.
 
-:class:`Template` instances also provide one public data attribute:
-
-
-.. attribute:: string.template
-
-   This is the object passed to the constructor's *template* argument.  In general,
-   you shouldn't change it, but read-only access is not enforced.
-
-Here is an example of how to use a Template:
+   :class:`Template` instances also provide one public data attribute:
+
+   .. attribute:: template
+
+      This is the object passed to the constructor's *template* argument.  In
+      general, you shouldn't change it, but read-only access is not enforced.
+
+Here is an example of how to use a Template::
 
    >>> from string import Template
@@ -566 +718 @@
    >>> Template('Give $who $100').substitute(d)
    Traceback (most recent call last):
-   [...]
-   ValueError: Invalid placeholder in string: line 1, col 10
+   ...
+   ValueError: Invalid placeholder in string: line 1, col 11
    >>> Template('$who likes $what').substitute(d)
    Traceback (most recent call last):
-   [...]
+   ...
    KeyError: 'what'
    >>> Template('$who likes $what').safe_substitute(d)
@@ -580 +732 @@
 
 * *delimiter* -- This is the literal string describing a placeholder introducing
-  delimiter.  The default value ``$``.  Note that this should *not* be a regular
-  expression, as the implementation will call :meth:`re.escape` on this string as
-  needed.
+  delimiter.  The default value is ``$``.  Note that this should *not* be a
+  regular expression, as the implementation will call :meth:`re.escape` on this
+  string as needed.
 
 * *idpattern* -- This is the regular expression describing the pattern for
@@ -644 +796 @@
 Unicode objects; see section :ref:`string-methods` for more information on
 those.  You should consider these functions as deprecated, although they will
-not be removed until Python 3.0.  The functions defined in this module are:
+not be removed until Python 3.  The functions defined in this module are:
 
 
@@ -756 +908 @@
    Return a list of the words of the string *s*.  If the optional second argument
    *sep* is absent or ``None``, the words are separated by arbitrary strings of
-   whitespace characters (space, tab,  newline, return, formfeed).  If the second
+   whitespace characters (space, tab, newline, return, formfeed).  If the second
    argument *sep* is present and not ``None``, it specifies a string to be used as
    the  word separator.  The returned list will then have one more item than the
-   number of non-overlapping occurrences of the separator in the string.  The
-   optional third argument *maxsplit* defaults to 0.  If it is nonzero, at most
-   *maxsplit* number of splits occur, and the remainder of the string is returned
-   as the final element of the list (thus, the list will have at most
-   ``maxsplit+1`` elements).
+   number of non-overlapping occurrences of the separator in the string.
+   If *maxsplit* is given, at most *maxsplit* number of splits occur, and the
+   remainder of the string is returned as the final element of the list (thus,
+   the list will have at most ``maxsplit+1`` elements).  If *maxsplit* is not
+   specified or ``-1``, then there is no limit on the number of splits (all
+   possible splits are made).
 
    The behavior of split on an empty string depends on the value of *sep*. If *sep*
@@ -776 +929 @@
    intents and purposes, the resulting list of words is the same as returned by
    :func:`split`, except when the optional third argument *maxsplit* is explicitly
-   specified and nonzero.  When *maxsplit* is nonzero, at most *maxsplit* number of
+   specified and nonzero.  If *maxsplit* is given, at most *maxsplit* number of
    splits -- the *rightmost* ones -- occur, and the remainder of the string is
    returned as the first element of the list (thus, the list will have at most
@@ -874 +1027 @@
 .. function:: zfill(s, width)
 
-   Pad a numeric string on the left with zero digits until the given width is
-   reached.  Strings starting with a sign are handled correctly.
-
-
-.. function:: replace(str, old, new[, maxreplace])
-
-   Return a copy of string *str* with all occurrences of substring *old* replaced
+   Pad a numeric string *s* on the left with zero digits until the
+   given *width* is reached.  Strings starting with a sign are handled
+   correctly.
+
+
+.. function:: replace(s, old, new[, maxreplace])
+
+   Return a copy of string *s* with all occurrences of substring *old* replaced
    by *new*.  If the optional argument *maxreplace* is given, the first
    *maxreplace* occurrences are replaced.