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'``.
.. 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`.
.. 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`.
.. 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`.
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
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
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.
.. _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
.. 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
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.
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:
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 ``%``.
*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::
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])
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
projects / python / commitdiff