[Python-checkins] cpython (2.7): Issue #25179: Preparatory cleanup of existing docs on string formatting

Sat Feb 6 21:40:38 EST 2016

https://hg.python.org/cpython/rev/fe692ee6d19a
changeset:   100174:fe692ee6d19a
branch:      2.7
parent:      100168:a2a9ff290cb2
user:        Martin Panter <vadmium+py at gmail.com>
date:        Mon Feb 08 01:34:09 2016 +0000
summary:
  Issue #25179: Preparatory cleanup of existing docs on string formatting

* There was a link pointing to the section on the string.Formatter class (and
  multiple links in Python 3), when the section on the common format string
  syntax is probably more appropriate
* Fix references to various format() functions and methods
* Nested replacement fields may contain conversions and format specifiers,
  and this is tested in Python 3; see Issue #19729 for instance

files:
  Doc/library/datetime.rst      |   6 ++--
  Doc/library/pprint.rst        |   2 +-
  Doc/library/string.rst        |  25 ++++++++++++----------
  Doc/tools/susp-ignored.csv    |   2 +-
  Doc/tutorial/introduction.rst |   5 +--
  5 files changed, 21 insertions(+), 19 deletions(-)

diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
--- a/Doc/library/datetime.rst
+++ b/Doc/library/datetime.rst
@@ -558,7 +558,7 @@
 
 .. method:: date.__format__(format)
 
-   Same as :meth:`.date.strftime`. This makes it possible to specify format
+   Same as :meth:`.date.strftime`. This makes it possible to specify a format
    string for a :class:`.date` object when using :meth:`str.format`.
    See section :ref:`strftime-strptime-behavior`.
 
@@ -1058,7 +1058,7 @@
 
 .. method:: datetime.__format__(format)
 
-   Same as :meth:`.datetime.strftime`.  This makes it possible to specify format
+   Same as :meth:`.datetime.strftime`.  This makes it possible to specify a format
    string for a :class:`.datetime` object when using :meth:`str.format`.
    See section :ref:`strftime-strptime-behavior`.
 
@@ -1292,7 +1292,7 @@
 
 .. method:: time.__format__(format)
 
-   Same as :meth:`.time.strftime`. This makes it possible to specify format string
+   Same as :meth:`.time.strftime`. This makes it possible to specify a format string
    for a :class:`.time` object when using :meth:`str.format`.
    See section :ref:`strftime-strptime-behavior`.
 
diff --git a/Doc/library/pprint.rst b/Doc/library/pprint.rst
--- a/Doc/library/pprint.rst
+++ b/Doc/library/pprint.rst
@@ -190,7 +190,7 @@
    the current presentation context (direct and indirect containers for *object*
    that are affecting the presentation) as the keys; if an object needs to be
    presented which is already represented in *context*, the third return value
-   should be ``True``.  Recursive calls to the :meth:`format` method should add
+   should be ``True``.  Recursive calls to the :meth:`.format` method should add
    additional entries for containers to this dictionary.  The third argument,
    *maxlevels*, gives the requested limit to recursion; this will be ``0`` if there
    is no requested limit.  This argument should be passed unmodified to recursive
diff --git a/Doc/library/string.rst b/Doc/library/string.rst
--- a/Doc/library/string.rst
+++ b/Doc/library/string.rst
@@ -105,8 +105,8 @@
 
 .. _new-string-formatting:
 
-String Formatting
------------------
+Custom String Formatting
+------------------------
 
 .. versionadded:: 2.6
 
@@ -115,7 +115,7 @@
 :meth:`str.format` method described in :pep:`3101`.  The :class:`Formatter`
 class in the :mod:`string` module allows you to create and customize your own
 string formatting behaviors using the same implementation as the built-in
-:meth:`format` method.
+:meth:`~str.format` method.
 
 .. class:: Formatter
 
@@ -123,9 +123,9 @@
 
    .. method:: format(format_string, *args, **kwargs)
 
-      :meth:`format` is the primary API method.  It takes a format string and
+      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`.
+      It is just a wrapper that calls :meth:`vformat`.
 
    .. method:: vformat(format_string, args, kwargs)
 
@@ -293,8 +293,9 @@
 described in the next section.
 
 A *format_spec* field can also include nested replacement fields within it.
-These nested replacement fields can contain only a field name; conversion flags
-and format specifications are not allowed.  The replacement fields within the
+These nested replacement fields may contain a field name, conversion flag
+and format specification, but deeper nesting is
+not allowed.  The replacement fields within the
 format_spec are substituted before the *format_spec* string is interpreted.
 This allows the formatting of a value to be dynamically specified.
 
@@ -332,8 +333,10 @@
 
 If a valid *align* value is specified, it can be preceded 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
+It is not possible to use a literal curly brace ("``{``" or "``}``") as
+the *fill* character when using the :meth:`str.format`
+method.  However, it is possible to insert a curly brace
+with a nested replacement field.  This limitation doesn't
 affect the :func:`format` function.
 
 The meaning of the various alignment options is as follows:
@@ -508,8 +511,8 @@
 Format examples
 ^^^^^^^^^^^^^^^
 
-This section contains examples of the new format syntax and comparison with
-the old ``%``-formatting.
+This section contains examples of the :meth:`str.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 ``%``.
diff --git a/Doc/tools/susp-ignored.csv b/Doc/tools/susp-ignored.csv
--- a/Doc/tools/susp-ignored.csv
+++ b/Doc/tools/susp-ignored.csv
@@ -46,7 +46,7 @@
 howto/pyporting,,::,Programming Language :: Python :: 3
 howto/regex,,::,
 howto/regex,,:foo,(?:foo)
-howto/urllib2,,:example,"for example ""joe at password:example.com"""
+howto/urllib2,,:password,"for example ""joe:password at example.com"""
 library/audioop,,:ipos,"# factor = audioop.findfactor(in_test[ipos*2:ipos*2+len(out_test)],"
 library/bisect,,:hi,all(val >= x for val in a[i:hi])
 library/bisect,,:hi,all(val > x for val in a[i:hi])
diff --git a/Doc/tutorial/introduction.rst b/Doc/tutorial/introduction.rst
--- a/Doc/tutorial/introduction.rst
+++ b/Doc/tutorial/introduction.rst
@@ -357,9 +357,8 @@
       Both strings and Unicode strings support a large number of methods for
       basic transformations and searching.
 
-   :ref:`new-string-formatting`
-      Information about string formatting with :meth:`str.format` is described
-      here.
+   :ref:`formatstrings`
+      Information about string formatting with :meth:`str.format`.
 
    :ref:`string-formatting`
       The old formatting operations invoked when strings and Unicode strings are

-- 
Repository URL: https://hg.python.org/cpython
