(original) (raw)

changeset: 100174:fe692ee6d19a branch: 2.7 parent: 100168:a2a9ff290cb2 user: Martin Panter vadmium+py@gmail.com date: Mon Feb 08 01:34:09 2016 +0000 files: Doc/library/datetime.rst Doc/library/pprint.rst Doc/library/string.rst Doc/tools/susp-ignored.csv Doc/tutorial/introduction.rst description: 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 diff -r a2a9ff290cb2 -r fe692ee6d19a Doc/library/datetime.rst --- a/Doc/library/datetime.rst Fri Feb 05 19:35:57 2016 -0800 +++ b/Doc/library/datetime.rst Mon Feb 08 01:34:09 2016 +0000 @@ -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 -r a2a9ff290cb2 -r fe692ee6d19a Doc/library/pprint.rst --- a/Doc/library/pprint.rst Fri Feb 05 19:35:57 2016 -0800 +++ b/Doc/library/pprint.rst Mon Feb 08 01:34:09 2016 +0000 @@ -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 -r a2a9ff290cb2 -r fe692ee6d19a Doc/library/string.rst --- a/Doc/library/string.rst Fri Feb 05 19:35:57 2016 -0800 +++ b/Doc/library/string.rst Mon Feb 08 01:34:09 2016 +0000 @@ -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 -r a2a9ff290cb2 -r fe692ee6d19a Doc/tools/susp-ignored.csv --- a/Doc/tools/susp-ignored.csv Fri Feb 05 19:35:57 2016 -0800 +++ b/Doc/tools/susp-ignored.csv Mon Feb 08 01:34:09 2016 +0000 @@ -46,7 +46,7 @@ howto/pyporting,,::,Programming Language :: Python :: 3 howto/regex,,::, howto/regex,,:foo,(?:foo) -howto/urllib2,,:example,"for example ""joe@password:example.com""" +howto/urllib2,,:password,"for example ""joe:password@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 -r a2a9ff290cb2 -r fe692ee6d19a Doc/tutorial/introduction.rst --- a/Doc/tutorial/introduction.rst Fri Feb 05 19:35:57 2016 -0800 +++ b/Doc/tutorial/introduction.rst Mon Feb 08 01:34:09 2016 +0000 @@ -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 /vadmium+py@gmail.com