cpython: fe692ee6d19a (original) (raw)

Mercurial > cpython

changeset 100174:fe692ee6d19a 2.7

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 [#25179]

Martin Panter vadmium+py@gmail.com
date	Mon, 08 Feb 2016 01:34:09 +0000
parents	a2a9ff290cb2
children	04424651f76c
files	Doc/library/datetime.rst Doc/library/pprint.rst Doc/library/string.rst Doc/tools/susp-ignored.csv Doc/tutorial/introduction.rst
diffstat	5 files changed, 21 insertions(+), 19 deletions(-)[+] [-] 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

line wrap: on

line diff

--- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -558,7 +558,7 @@ Instance methods: .. 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 @@ Instance methods: .. 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 @@ Instance methods: .. 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.

--- a/Doc/library/pprint.rst +++ b/Doc/library/pprint.rst @@ -190,7 +190,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

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

--- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -105,8 +105,8 @@ The constants defined in this module are .. _new-string-formatting: -String Formatting ------------------ +Custom String Formatting +------------------------ .. versionadded:: 2.6 @@ -115,7 +115,7 @@ to do complex variable substitutions and :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 @@ string formatting behaviors using the sa .. method:: format(format_string, *args, **kwargs)

 :meth:`format` is the primary API method.  It takes a format string and[](#l3.27)

 The primary API method.  It takes a format string and[](#l3.28)
 an arbitrary set of positional and keyword arguments.[](#l3.29)

 :meth:`format` is just a wrapper that calls :meth:`vformat`.[](#l3.30)

 It is just a wrapper that calls :meth:`vformat`.[](#l3.31)

.. method:: vformat(format_string, args, kwargs) @@ -293,8 +293,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. @@ -332,8 +333,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: @@ -508,8 +511,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/tools/susp-ignored.csv +++ b/Doc/tools/susp-ignored.csv @@ -46,7 +46,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,,:hi,all(val >= x for val in a[i:hi]) library/bisect,,:hi,all(val > x for val in a[i:hi])

--- a/Doc/tutorial/introduction.rst +++ b/Doc/tutorial/introduction.rst @@ -357,9 +357,8 @@ The built-in function :func:len return 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[](#l5.8)

```
 here.[](#l5.9)
```

:ref:formatstrings

 Information about string formatting with :meth:`str.format`.[](#l5.11)

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