diff options
| -rw-r--r-- | Doc/faq/programming.rst | 2 | ||||
| -rw-r--r-- | Doc/library/datetime.rst | 6 | ||||
| -rw-r--r-- | Doc/library/enum.rst | 12 | ||||
| -rw-r--r-- | Doc/library/pprint.rst | 2 | ||||
| -rw-r--r-- | Doc/library/stdtypes.rst | 2 | ||||
| -rw-r--r-- | Doc/library/string.rst | 27 | ||||
| -rw-r--r-- | Doc/library/tracemalloc.rst | 2 | ||||
| -rw-r--r-- | Doc/tools/susp-ignored.csv | 2 | ||||
| -rw-r--r-- | Doc/tutorial/introduction.rst | 5 |
9 files changed, 31 insertions, 29 deletions
diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst index 94b428d..9fba9fe 100644 --- 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'``. diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index 976cd49..980dfcf 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -604,7 +604,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`. For a complete list of formatting directives, see :ref:`strftime-strptime-behavior`. @@ -1179,7 +1179,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`. For a complete list of formatting directives, see :ref:`strftime-strptime-behavior`. @@ -1424,7 +1424,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`. For a complete list of formatting directives, see :ref:`strftime-strptime-behavior`. diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst index 81f97b3..8a02a55 100644 --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -555,12 +555,12 @@ Some rules: 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 - :meth:`__repr__` respectively; other codes (such as `%i` or `%h` for - IntEnum) treat the enum member as its mixed-in type. -5. :meth:`str.__format__` (or :func:`format`) will use the mixed-in - type's :meth:`__format__`. If the :class:`Enum`'s :func:`str` or - :func:`repr` is desired use the `!s` or `!r` :class:`str` format codes. +4. %-style formatting: `%s` and `%r` call the :class:`Enum` class's + :meth:`__str__` and :meth:`__repr__` respectively; other codes (such as + `%i` or `%h` for IntEnum) treat the enum member as its mixed-in type. +5. :meth:`str.format` (or :func:`format`) will use the mixed-in + type's :meth:`__format__`. If the :class:`Enum` class's :func:`str` or + :func:`repr` is desired, use the `!s` or `!r` format codes. Interesting examples diff --git a/Doc/library/pprint.rst b/Doc/library/pprint.rst index 0b44dc8..b109efe 100644 --- a/Doc/library/pprint.rst +++ b/Doc/library/pprint.rst @@ -197,7 +197,7 @@ are converted to strings. The default implementation uses the internals of the 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/stdtypes.rst b/Doc/library/stdtypes.rst index 8bcc4a0..774b0c6 100644 --- 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 - formatted strings, see the :ref:`string-formatting` section. In addition, + formatted strings, see the :ref:`formatstrings` section. In addition, see the :ref:`stringservices` section. diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 2bd8dfd..5b917d9 100644 --- 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:`format` method. .. 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`. .. 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 formatting mini-language, which is 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 specifier* is: 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 floating point and decimal values are: 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/library/tracemalloc.rst b/Doc/library/tracemalloc.rst index 861be37..5feb2d9 100644 --- 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 - :meth:`format` does not include newlines. + :meth:`.format` does not include newlines. Example:: diff --git a/Doc/tools/susp-ignored.csv b/Doc/tools/susp-ignored.csv index 2a95fca..3ccf910 100644 --- a/Doc/tools/susp-ignored.csv +++ b/Doc/tools/susp-ignored.csv @@ -82,7 +82,7 @@ howto/pyporting,,::,Programming Language :: Python :: 2 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,32,:hi,all(val >= x for val in a[i:hi]) library/bisect,42,:hi,all(val > x for val in a[i:hi]) diff --git a/Doc/tutorial/introduction.rst b/Doc/tutorial/introduction.rst index c5c1343..8758f38 100644 --- a/Doc/tutorial/introduction.rst +++ b/Doc/tutorial/introduction.rst @@ -352,9 +352,8 @@ The built-in function :func:`len` returns the length of a string:: Strings support a large number of methods for basic transformations and searching. - :ref:`string-formatting` - Information about string formatting with :meth:`str.format` is described - here. + :ref:`formatstrings` + Information about string formatting with :meth:`str.format`. :ref:`old-string-formatting` The old formatting operations invoked when strings and Unicode strings are |