cpython: f25d8cbd074a (original) (raw)

Mercurial > cpython

changeset 100172:f25d8cbd074a 3.5

Issue #25179: Preparatory cleanup of existing docs on string formatting * Various sections were pointing to the section on the string.Formatter class, 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; see Issue #19729 for instance [#25179]

Martin Panter vadmium+py@gmail.com
date Mon, 08 Feb 2016 01:34:09 +0000
parents aca6b47a260c
children 4cf08147a52e 9f998e24d8d8
files Doc/faq/programming.rst Doc/library/datetime.rst Doc/library/enum.rst Doc/library/pprint.rst Doc/library/stdtypes.rst Doc/library/string.rst Doc/library/tracemalloc.rst Doc/tools/susp-ignored.csv Doc/tutorial/introduction.rst
diffstat 9 files changed, 31 insertions(+), 29 deletions(-)[+] [-] Doc/faq/programming.rst 2 Doc/library/datetime.rst 6 Doc/library/enum.rst 12 Doc/library/pprint.rst 2 Doc/library/stdtypes.rst 2 Doc/library/string.rst 27 Doc/library/tracemalloc.rst 2 Doc/tools/susp-ignored.csv 2 Doc/tutorial/introduction.rst 5

line wrap: on

line diff

--- a/Doc/faq/programming.rst +++ b/Doc/faq/programming.rst @@ -839,7 +839,7 @@ How do I convert a number to a string? To convert, e.g., the number 144 to the string '144', use the built-in type constructor :func:str. If you want a hexadecimal or octal representation, use the built-in functions :func:hex or :func:oct. For fancy formatting, see -the :ref:string-formatting section, e.g. "{:04d}".format(144) yields +the :ref:formatstrings section, e.g. "{:04d}".format(144) yields '0144' and "{:.3f}".format(1.0/3.0) yields '0.333'.

--- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -604,7 +604,7 @@ Instance methods: .. method:: date.format(format)

.. method:: datetime.format(format)

.. method:: time.format(format)

--- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -555,12 +555,12 @@ 2. While :class:Enum can have members 3. When another data type is mixed in, the :attr:value attribute is not the same as the enum member itself, although it is equivalent and will compare equal. -4. %-style formatting: %s and %r call :class:Enum's :meth:__str__ and

Interesting examples

--- a/Doc/library/pprint.rst +++ b/Doc/library/pprint.rst @@ -197,7 +197,7 @@ are converted to strings. The default i 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

--- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -1450,7 +1450,7 @@ multiple fragments. For more information on the str class and its methods, see :ref:textseq and the :ref:string-methods section below. To output

--- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -75,14 +75,14 @@ The constants defined in this module are .. _string-formatting: -String Formatting ------------------ +Custom String Formatting +------------------------ The built-in string class provides the ability to do complex variable -substitutions and value formatting via the :func:format method described in +substitutions and value formatting via the :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. +implementation as the built-in :meth:~str.format method. .. class:: Formatter @@ -91,9 +91,9 @@ implementation as the built-in :meth:`fo .. method:: format(format_string, *args, **kwargs)

.. deprecated:: 3.5 Passing a format string as keyword argument format_string has been @@ -267,8 +267,9 @@ Most built-in types support a common for 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. @@ -306,8 +307,10 @@ The general form of a *standard format s 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: @@ -496,8 +499,8 @@ The available presentation types for flo 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 %.

--- a/Doc/library/tracemalloc.rst +++ b/Doc/library/tracemalloc.rst @@ -620,7 +620,7 @@ Traceback limit is set, only format the limit most recent frames. Similar to the :func:traceback.format_tb function, except that

Example::

--- a/Doc/tools/susp-ignored.csv +++ b/Doc/tools/susp-ignored.csv @@ -82,7 +82,7 @@ howto/pyporting,,::,Programming Language 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[ipos2:ipos2+len(out_test)]," library/bisect,32,:hi,all(val >= x for val in a[i:hi]) library/bisect,42,:hi,all(val > x for val in a[i:hi])

--- a/Doc/tutorial/introduction.rst +++ b/Doc/tutorial/introduction.rst @@ -352,9 +352,8 @@ The built-in function :func:len return Strings support a large number of methods for basic transformations and searching.

:ref:old-string-formatting The old formatting operations invoked when strings and Unicode strings are