cpython-lru_cache-weakref: Doc/library/string.rst annotate

annotate Doc/library/string.rst @ 54294:dba767bc3155 legacy-trunk

remove mention of old ctypes version

author	Benjamin Peterson <benjamin@python.org>
date	Sat, 23 May 2009 20:59:09 +0000
parents	d78037c16225
children	698557cc5dc5

rev	line source
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1 :mod:`string` --- Common string operations
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2 ==========================================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	4 .. module:: string
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	5 :synopsis: Common string operations.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	6
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	7
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	8 .. index:: module: re
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	9
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	10 The :mod:`string` module contains a number of useful constants and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	11 classes, as well as some deprecated legacy functions that are also
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	12 available as methods on strings. In addition, Python's built-in string
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	13 classes support the sequence type methods described in the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	14 :ref:`typesseq` section, and also the string-specific methods described
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	15 in the :ref:`string-methods` section. To output formatted strings use
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	16 template strings or the ``%`` operator described in the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	17 :ref:`string-formatting` section. Also, see the :mod:`re` module for
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	18 string functions based on regular expressions.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	19
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	20
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	21 String constants
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	22 ----------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	23
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24 The constants defined in this module are:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	25
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	26
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	27 .. data:: ascii_letters
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	28
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	29 The concatenation of the :const:`ascii_lowercase` and :const:`ascii_uppercase`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	30 constants described below. This value is not locale-dependent.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	31
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	32
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	33 .. data:: ascii_lowercase
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	34
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	35 The lowercase letters ``'abcdefghijklmnopqrstuvwxyz'``. This value is not
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	36 locale-dependent and will not change.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	37
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	38
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	39 .. data:: ascii_uppercase
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	40
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	41 The uppercase letters ``'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``. This value is not
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	42 locale-dependent and will not change.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	43
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	44
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	45 .. data:: digits
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	46
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	47 The string ``'0123456789'``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	48
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	49
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	50 .. data:: hexdigits
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	51
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	52 The string ``'0123456789abcdefABCDEF'``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	53
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	54
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	55 .. data:: letters
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	56
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	57 The concatenation of the strings :const:`lowercase` and :const:`uppercase`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	58 described below. The specific value is locale-dependent, and will be updated
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	59 when :func:`locale.setlocale` is called.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	60
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	61
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	62 .. data:: lowercase
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	63
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	64 A string containing all the characters that are considered lowercase letters.
52003 0c028685b44c Remove obsolete stuff from string module docs. Georg Brandl <georg@python.org> parents: 50522 diff changeset	65 On most systems this is the string ``'abcdefghijklmnopqrstuvwxyz'``. The
0c028685b44c Remove obsolete stuff from string module docs. Georg Brandl <georg@python.org> parents: 50522 diff changeset	66 specific value is locale-dependent, and will be updated when
0c028685b44c Remove obsolete stuff from string module docs. Georg Brandl <georg@python.org> parents: 50522 diff changeset	67 :func:`locale.setlocale` is called.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	68
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	69
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	70 .. data:: octdigits
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	71
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	72 The string ``'01234567'``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	73
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	74
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	75 .. data:: punctuation
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	76
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	77 String of ASCII characters which are considered punctuation characters in the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	78 ``C`` locale.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	79
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	80
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	81 .. data:: printable
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	82
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	83 String of characters which are considered printable. This is a combination of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	84 :const:`digits`, :const:`letters`, :const:`punctuation`, and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	85 :const:`whitespace`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	86
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	87
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	88 .. data:: uppercase
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	89
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	90 A string containing all the characters that are considered uppercase letters.
52003 0c028685b44c Remove obsolete stuff from string module docs. Georg Brandl <georg@python.org> parents: 50522 diff changeset	91 On most systems this is the string ``'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``. The
0c028685b44c Remove obsolete stuff from string module docs. Georg Brandl <georg@python.org> parents: 50522 diff changeset	92 specific value is locale-dependent, and will be updated when
0c028685b44c Remove obsolete stuff from string module docs. Georg Brandl <georg@python.org> parents: 50522 diff changeset	93 :func:`locale.setlocale` is called.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	94
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	95
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	96 .. data:: whitespace
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	97
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	98 A string containing all characters that are considered whitespace. On most
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	99 systems this includes the characters space, tab, linefeed, return, formfeed, and
52003 0c028685b44c Remove obsolete stuff from string module docs. Georg Brandl <georg@python.org> parents: 50522 diff changeset	100 vertical tab.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	101
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	102
47280 65953ae98122 rename the section about new formatting 'new-string-formatting' Benjamin Peterson <benjamin@python.org> parents: 46949 diff changeset	103 .. _new-string-formatting:
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	104
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	105 String Formatting
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	106 -----------------
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	107
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	108 Starting in Python 2.6, the built-in str and unicode classes provide the ability
47280 65953ae98122 rename the section about new formatting 'new-string-formatting' Benjamin Peterson <benjamin@python.org> parents: 46949 diff changeset	109 to do complex variable substitutions and value formatting via the
65953ae98122 rename the section about new formatting 'new-string-formatting' Benjamin Peterson <benjamin@python.org> parents: 46949 diff changeset	110 :meth:`str.format` method described in :pep:`3101`. The :class:`Formatter`
65953ae98122 rename the section about new formatting 'new-string-formatting' Benjamin Peterson <benjamin@python.org> parents: 46949 diff changeset	111 class in the :mod:`string` module allows you to create and customize your own
65953ae98122 rename the section about new formatting 'new-string-formatting' Benjamin Peterson <benjamin@python.org> parents: 46949 diff changeset	112 string formatting behaviors using the same implementation as the built-in
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	113 :meth:`format` method.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	114
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	115 .. class:: Formatter
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	116
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	117 The :class:`Formatter` class has the following public methods:
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	118
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	119 .. method:: format(format_string, args, kwargs)
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	120
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	121 :meth:`format` is the primary API method. It takes a format template
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	122 string, and an arbitrary set of positional and keyword argument.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	123 :meth:`format` is just a wrapper that calls :meth:`vformat`.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	124
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	125 .. method:: vformat(format_string, args, kwargs)
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49152 diff changeset	126
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	127 This function does the actual work of formatting. It is exposed as a
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	128 separate function for cases where you want to pass in a predefined
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	129 dictionary of arguments, rather than unpacking and repacking the
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	130 dictionary as individual arguments using the ``args`` and ``*kwds``
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	131 syntax. :meth:`vformat` does the work of breaking up the format template
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	132 string into character data and replacement fields. It calls the various
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	133 methods described below.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	134
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	135 In addition, the :class:`Formatter` defines a number of methods that are
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	136 intended to be replaced by subclasses:
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	137
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	138 .. method:: parse(format_string)
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49152 diff changeset	139
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	140 Loop over the format_string and return an iterable of tuples
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	141 (literal_text, field_name, format_spec, conversion). This is used
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	142 by :meth:`vformat` to break the string in to either literal text, or
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	143 replacement fields.
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49152 diff changeset	144
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	145 The values in the tuple conceptually represent a span of literal text
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	146 followed by a single replacement field. If there is no literal text
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	147 (which can happen if two replacement fields occur consecutively), then
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	148 literal_text will be a zero-length string. If there is no replacement
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	149 field, then the values of field_name, format_spec and conversion
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	150 will be ``None``.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	151
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	152 .. method:: get_field(field_name, args, kwargs)
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	153
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	154 Given field_name as returned by :meth:`parse` (see above), convert it to
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	155 an object to be formatted. Returns a tuple (obj, used_key). The default
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	156 version takes strings of the form defined in :pep:`3101`, such as
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	157 "0[name]" or "label.title". args and kwargs are as passed in to
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	158 :meth:`vformat`. The return value used_key has the same meaning as the
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	159 key parameter to :meth:`get_value`.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	160
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	161 .. method:: get_value(key, args, kwargs)
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49152 diff changeset	162
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	163 Retrieve a given field value. The key argument will be either an
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	164 integer or a string. If it is an integer, it represents the index of the
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	165 positional argument in args; if it is a string, then it represents a
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	166 named argument in kwargs.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	167
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	168 The args parameter is set to the list of positional arguments to
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	169 :meth:`vformat`, and the kwargs parameter is set to the dictionary of
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	170 keyword arguments.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	171
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	172 For compound field names, these functions are only called for the first
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	173 component of the field name; Subsequent components are handled through
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	174 normal attribute and indexing operations.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	175
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	176 So for example, the field expression '0.name' would cause
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	177 :meth:`get_value` to be called with a key argument of 0. The ``name``
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	178 attribute will be looked up after :meth:`get_value` returns by calling the
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	179 built-in :func:`getattr` function.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	180
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	181 If the index or keyword refers to an item that does not exist, then an
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	182 :exc:`IndexError` or :exc:`KeyError` should be raised.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	183
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	184 .. method:: check_unused_args(used_args, args, kwargs)
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	185
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	186 Implement checking for unused arguments if desired. The arguments to this
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	187 function is the set of all argument keys that were actually referred to in
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	188 the format string (integers for positional arguments, and strings for
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	189 named arguments), and a reference to the args and kwargs that was
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	190 passed to vformat. The set of unused args can be calculated from these
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	191 parameters. :meth:`check_unused_args` is assumed to throw an exception if
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	192 the check fails.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	193
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	194 .. method:: format_field(value, format_spec)
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	195
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	196 :meth:`format_field` simply calls the global :func:`format` built-in. The
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	197 method is provided so that subclasses can override it.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	198
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	199 .. method:: convert_field(value, conversion)
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49152 diff changeset	200
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	201 Converts the value (returned by :meth:`get_field`) given a conversion type
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	202 (as in the tuple returned by the :meth:`parse` method.) The default
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	203 version understands 'r' (repr) and 's' (str) conversion types.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	204
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	205
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	206 .. _formatstrings:
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	207
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	208 Format String Syntax
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	209 --------------------
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	210
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	211 The :meth:`str.format` method and the :class:`Formatter` class share the same
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	212 syntax for format strings (although in the case of :class:`Formatter`,
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	213 subclasses can define their own format string syntax.)
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	214
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	215 Format strings contain "replacement fields" surrounded by curly braces ``{}``.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	216 Anything that is not contained in braces is considered literal text, which is
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	217 copied unchanged to the output. If you need to include a brace character in the
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	218 literal text, it can be escaped by doubling: ``{{`` and ``}}``.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	219
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	220 The grammar for a replacement field is as follows:
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	221
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	222 .. productionlist:: sf
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	223 replacement_field: "{" `field_name` ["!" `conversion`] [":" `format_spec`] "}"
53305 c30681c66b3f Documentation for issue 5237, auto-numbered format fields. Contributed by Terry J. Reedy. Eric Smith <eric@trueblade.com> parents: 52379 diff changeset	224 field_name: arg_name ("." `attribute_name` \| "[" `element_index` "]")*
c30681c66b3f Documentation for issue 5237, auto-numbered format fields. Contributed by Terry J. Reedy. Eric Smith <eric@trueblade.com> parents: 52379 diff changeset	225 arg_name: (`identifier` \| `integer`)?
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	226 attribute_name: `identifier`
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	227 element_index: `integer`
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	228 conversion: "r" \| "s"
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	229 format_spec: <described in the next section>
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49152 diff changeset	230
53305 c30681c66b3f Documentation for issue 5237, auto-numbered format fields. Contributed by Terry J. Reedy. Eric Smith <eric@trueblade.com> parents: 52379 diff changeset	231 In less formal terms, the replacement field starts with a field_name that specifies
c30681c66b3f Documentation for issue 5237, auto-numbered format fields. Contributed by Terry J. Reedy. Eric Smith <eric@trueblade.com> parents: 52379 diff changeset	232 the object whose value is to be formatted and inserted
c30681c66b3f Documentation for issue 5237, auto-numbered format fields. Contributed by Terry J. Reedy. Eric Smith <eric@trueblade.com> parents: 52379 diff changeset	233 into the output instead of the replacement field.
c30681c66b3f Documentation for issue 5237, auto-numbered format fields. Contributed by Terry J. Reedy. Eric Smith <eric@trueblade.com> parents: 52379 diff changeset	234 The field_name is optionally followed by a conversion field, which is
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	235 preceded by an exclamation point ``'!'``, and a format_spec, which is preceded
53305 c30681c66b3f Documentation for issue 5237, auto-numbered format fields. Contributed by Terry J. Reedy. Eric Smith <eric@trueblade.com> parents: 52379 diff changeset	236 by a colon ``':'``. These specify a non-default format for the replacement value.
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	237
53305 c30681c66b3f Documentation for issue 5237, auto-numbered format fields. Contributed by Terry J. Reedy. Eric Smith <eric@trueblade.com> parents: 52379 diff changeset	238 The field_name itself begins with an arg_name that is either either a number or a
c30681c66b3f Documentation for issue 5237, auto-numbered format fields. Contributed by Terry J. Reedy. Eric Smith <eric@trueblade.com> parents: 52379 diff changeset	239 keyword. If it's a number, it refers to a positional argument, and if it's a keyword,
c30681c66b3f Documentation for issue 5237, auto-numbered format fields. Contributed by Terry J. Reedy. Eric Smith <eric@trueblade.com> parents: 52379 diff changeset	240 it refers to a named keyword argument. If the numerical arg_names in a format string
c30681c66b3f Documentation for issue 5237, auto-numbered format fields. Contributed by Terry J. Reedy. Eric Smith <eric@trueblade.com> parents: 52379 diff changeset	241 are 0, 1, 2, ... in sequence, they can all be omitted (not just some)
c30681c66b3f Documentation for issue 5237, auto-numbered format fields. Contributed by Terry J. Reedy. Eric Smith <eric@trueblade.com> parents: 52379 diff changeset	242 and the numbers 0, 1, 2, ... will be automatically inserted in that order.
c30681c66b3f Documentation for issue 5237, auto-numbered format fields. Contributed by Terry J. Reedy. Eric Smith <eric@trueblade.com> parents: 52379 diff changeset	243 The arg_name can be followed by any number of index or
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	244 attribute expressions. An expression of the form ``'.name'`` selects the named
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	245 attribute using :func:`getattr`, while an expression of the form ``'[index]'``
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	246 does an index lookup using :func:`__getitem__`.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	247
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	248 Some simple format string examples::
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	249
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	250 "First, thou shalt count to {0}" # References first positional argument
52379 da456f42ebe7 give os.symlink and os.link() better parameter names #5564 Benjamin Peterson <benjamin@python.org> parents: 52186 diff changeset	251 "Bring me a {}" # Implicitly references the first positional argument
53305 c30681c66b3f Documentation for issue 5237, auto-numbered format fields. Contributed by Terry J. Reedy. Eric Smith <eric@trueblade.com> parents: 52379 diff changeset	252 "From {} to {}" # Same as "From {0] to {1}"
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	253 "My quest is {name}" # References keyword argument 'name'
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	254 "Weight in tons {0.weight}" # 'weight' attribute of first positional arg
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	255 "Units destroyed: {players[0]}" # First element of keyword argument 'players'.
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49152 diff changeset	256
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	257 The conversion field causes a type coercion before formatting. Normally, the
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	258 job of formatting a value is done by the :meth:`__format__` method of the value
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	259 itself. However, in some cases it is desirable to force a type to be formatted
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	260 as a string, overriding its own definition of formatting. By converting the
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	261 value to a string before calling :meth:`__format__`, the normal formatting logic
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	262 is bypassed.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	263
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	264 Two conversion flags are currently supported: ``'!s'`` which calls :func:`str`
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	265 on the value, and ``'!r'`` which calls :func:`repr`.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	266
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	267 Some examples::
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	268
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	269 "Harold's a clever {0!s}" # Calls str() on the argument first
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	270 "Bring out the holy {name!r}" # Calls repr() on the argument first
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	271
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	272 The format_spec field contains a specification of how the value should be
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	273 presented, including such details as field width, alignment, padding, decimal
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	274 precision and so on. Each value type can define it's own "formatting
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	275 mini-language" or interpretation of the format_spec.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	276
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	277 Most built-in types support a common formatting mini-language, which is
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	278 described in the next section.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	279
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	280 A format_spec field can also include nested replacement fields within it.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	281 These nested replacement fields can contain only a field name; conversion flags
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	282 and format specifications are not allowed. The replacement fields within the
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	283 format_spec are substituted before the format_spec string is interpreted.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	284 This allows the formatting of a value to be dynamically specified.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	285
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	286 For example, suppose you wanted to have a replacement field whose field width is
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	287 determined by another variable::
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	288
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	289 "A man with two {0:{1}}".format("noses", 10)
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	290
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	291 This would first evaluate the inner replacement field, making the format string
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	292 effectively::
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	293
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	294 "A man with two {0:10}"
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	295
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	296 Then the outer replacement field would be evaluated, producing::
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	297
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	298 "noses "
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49152 diff changeset	299
47937 38d3a50defec fix various doc typos #3320 Benjamin Peterson <benjamin@python.org> parents: 47280 diff changeset	300 Which is substituted into the string, yielding::
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49152 diff changeset	301
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	302 "A man with two noses "
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49152 diff changeset	303
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	304 (The extra space is because we specified a field width of 10, and because left
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	305 alignment is the default for strings.)
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	306
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	307
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	308 .. _formatspec:
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	309
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	310 Format Specification Mini-Language
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	311 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	312
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	313 "Format specifications" are used within replacement fields contained within a
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	314 format string to define how individual values are presented (see
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	315 :ref:`formatstrings`.) They can also be passed directly to the builtin
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	316 :func:`format` function. Each formattable type may define how the format
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	317 specification is to be interpreted.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	318
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	319 Most built-in types implement the following options for format specifications,
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	320 although some of the formatting options are only supported by the numeric types.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	321
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	322 A general convention is that an empty format string (``""``) produces the same
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	323 result as if you had called :func:`str` on the value.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	324
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	325 The general form of a standard format specifier is:
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	326
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	327 .. productionlist:: sf
47973 3fa44e5e4e2b Complete issue 3083: add alternate (#) formatting to bin, oct, hex in str.format(). Eric Smith <eric@trueblade.com> parents: 47937 diff changeset	328 format_spec: [[`fill`]`align`][`sign`][#][0][`width`][.`precision`][`type`]
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	329 fill: <a character other than '}'>
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	330 align: "<" \| ">" \| "=" \| "^"
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	331 sign: "+" \| "-" \| " "
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	332 width: `integer`
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	333 precision: `integer`
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	334 type: "b" \| "c" \| "d" \| "e" \| "E" \| "f" \| "F" \| "g" \| "G" \| "n" \| "o" \| "x" \| "X" \| "%"
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49152 diff changeset	335
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	336 The fill character can be any character other than '}' (which signifies the
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	337 end of the field). The presence of a fill character is signaled by the next
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	338 character, which must be one of the alignment options. If the second character
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	339 of format_spec is not a valid alignment option, then it is assumed that both
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	340 the fill character and the alignment option are absent.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	341
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	342 The meaning of the various alignment options is as follows:
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	343
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	344 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	345 \| Option \| Meaning \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	346 +=========+==========================================================+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	347 \| ``'<'`` \| Forces the field to be left-aligned within the available \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	348 \| \| space (This is the default.) \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	349 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	350 \| ``'>'`` \| Forces the field to be right-aligned within the \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	351 \| \| available space. \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	352 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	353 \| ``'='`` \| Forces the padding to be placed after the sign (if any) \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	354 \| \| but before the digits. This is used for printing fields \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	355 \| \| in the form '+000000120'. This alignment option is only \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	356 \| \| valid for numeric types. \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	357 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	358 \| ``'^'`` \| Forces the field to be centered within the available \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	359 \| \| space. \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	360 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	361
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	362 Note that unless a minimum field width is defined, the field width will always
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	363 be the same size as the data to fill it, so that the alignment option has no
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	364 meaning in this case.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	365
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	366 The sign option is only valid for number types, and can be one of the
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	367 following:
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	368
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	369 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	370 \| Option \| Meaning \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	371 +=========+==========================================================+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	372 \| ``'+'`` \| indicates that a sign should be used for both \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	373 \| \| positive as well as negative numbers. \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	374 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	375 \| ``'-'`` \| indicates that a sign should be used only for negative \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	376 \| \| numbers (this is the default behavior). \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	377 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	378 \| space \| indicates that a leading space should be used on \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	379 \| \| positive numbers, and a minus sign on negative numbers. \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	380 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	381
49152 0fcd4db23dff fix typo Benjamin Peterson <benjamin@python.org> parents: 48015 diff changeset	382 The ``'#'`` option is only valid for integers, and only for binary, octal, or
0fcd4db23dff fix typo Benjamin Peterson <benjamin@python.org> parents: 48015 diff changeset	383 hexadecimal output. If present, it specifies that the output will be prefixed
0fcd4db23dff fix typo Benjamin Peterson <benjamin@python.org> parents: 48015 diff changeset	384 by ``'0b'``, ``'0o'``, or ``'0x'``, respectively.
47973 3fa44e5e4e2b Complete issue 3083: add alternate (#) formatting to bin, oct, hex in str.format(). Eric Smith <eric@trueblade.com> parents: 47937 diff changeset	385
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	386 width is a decimal integer defining the minimum field width. If not
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	387 specified, then the field width will be determined by the content.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	388
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	389 If the width field is preceded by a zero (``'0'``) character, this enables
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	390 zero-padding. This is equivalent to an alignment type of ``'='`` and a fill
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	391 character of ``'0'``.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	392
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	393 The precision is a decimal number indicating how many digits should be
48015 ac1cd46bf7d5 Document the different meaning of precision for {:f} and {:g}. Georg Brandl <georg@python.org> parents: 48003 diff changeset	394 displayed after the decimal point for a floating point value formatted with
ac1cd46bf7d5 Document the different meaning of precision for {:f} and {:g}. Georg Brandl <georg@python.org> parents: 48003 diff changeset	395 ``'f'`` and ``'F'``, or before and after the decimal point for a floating point
ac1cd46bf7d5 Document the different meaning of precision for {:f} and {:g}. Georg Brandl <georg@python.org> parents: 48003 diff changeset	396 value formatted with ``'g'`` or ``'G'``. For non-number types the field
ac1cd46bf7d5 Document the different meaning of precision for {:f} and {:g}. Georg Brandl <georg@python.org> parents: 48003 diff changeset	397 indicates the maximum field size - in other words, how many characters will be
53882 d78037c16225 Fixed wording for formatting integers: precision is not allowed. Eric Smith <eric@trueblade.com> parents: 53508 diff changeset	398 used from the field content. The precision is not allowed for integer values.
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	399
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	400 Finally, the type determines how the data should be presented.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	401
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	402 The available integer presentation types are:
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	403
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	404 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	405 \| Type \| Meaning \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	406 +=========+==========================================================+
47973 3fa44e5e4e2b Complete issue 3083: add alternate (#) formatting to bin, oct, hex in str.format(). Eric Smith <eric@trueblade.com> parents: 47937 diff changeset	407 \| ``'b'`` \| Binary format. Outputs the number in base 2. \|
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	408 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	409 \| ``'c'`` \| Character. Converts the integer to the corresponding \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	410 \| \| unicode character before printing. \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	411 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	412 \| ``'d'`` \| Decimal Integer. Outputs the number in base 10. \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	413 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	414 \| ``'o'`` \| Octal format. Outputs the number in base 8. \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	415 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	416 \| ``'x'`` \| Hex format. Outputs the number in base 16, using lower- \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	417 \| \| case letters for the digits above 9. \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	418 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	419 \| ``'X'`` \| Hex format. Outputs the number in base 16, using upper- \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	420 \| \| case letters for the digits above 9. \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	421 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	422 \| ``'n'`` \| Number. This is the same as ``'d'``, except that it uses \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	423 \| \| the current locale setting to insert the appropriate \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	424 \| \| number separator characters. \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	425 +---------+----------------------------------------------------------+
48015 ac1cd46bf7d5 Document the different meaning of precision for {:f} and {:g}. Georg Brandl <georg@python.org> parents: 48003 diff changeset	426 \| None \| The same as ``'d'``. \|
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	427 +---------+----------------------------------------------------------+
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49152 diff changeset	428
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	429 The available presentation types for floating point and decimal values are:
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 49152 diff changeset	430
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	431 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	432 \| Type \| Meaning \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	433 +=========+==========================================================+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	434 \| ``'e'`` \| Exponent notation. Prints the number in scientific \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	435 \| \| notation using the letter 'e' to indicate the exponent. \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	436 +---------+----------------------------------------------------------+
48003 5c33009994b4 Backed out r65069, pending fixing it in Windows. Eric Smith <eric@trueblade.com> parents: 48001 diff changeset	437 \| ``'E'`` \| Exponent notation. Same as ``'e'`` except it uses an \|
5c33009994b4 Backed out r65069, pending fixing it in Windows. Eric Smith <eric@trueblade.com> parents: 48001 diff changeset	438 \| \| upper case 'E' as the separator character. \|
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	439 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	440 \| ``'f'`` \| Fixed point. Displays the number as a fixed-point \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	441 \| \| number. \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	442 +---------+----------------------------------------------------------+
48003 5c33009994b4 Backed out r65069, pending fixing it in Windows. Eric Smith <eric@trueblade.com> parents: 48001 diff changeset	443 \| ``'F'`` \| Fixed point. Same as ``'f'``. \|
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	444 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	445 \| ``'g'`` \| General format. This prints the number as a fixed-point \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	446 \| \| number, unless the number is too large, in which case \|
48015 ac1cd46bf7d5 Document the different meaning of precision for {:f} and {:g}. Georg Brandl <georg@python.org> parents: 48003 diff changeset	447 \| \| it switches to ``'e'`` exponent notation. Infinity and \|
ac1cd46bf7d5 Document the different meaning of precision for {:f} and {:g}. Georg Brandl <georg@python.org> parents: 48003 diff changeset	448 \| \| NaN values are formatted as ``inf``, ``-inf`` and \|
ac1cd46bf7d5 Document the different meaning of precision for {:f} and {:g}. Georg Brandl <georg@python.org> parents: 48003 diff changeset	449 \| \| ``nan``, respectively. \|
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	450 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	451 \| ``'G'`` \| General format. Same as ``'g'`` except switches to \|
48015 ac1cd46bf7d5 Document the different meaning of precision for {:f} and {:g}. Georg Brandl <georg@python.org> parents: 48003 diff changeset	452 \| \| ``'E'`` if the number gets to large. The representations \|
ac1cd46bf7d5 Document the different meaning of precision for {:f} and {:g}. Georg Brandl <georg@python.org> parents: 48003 diff changeset	453 \| \| of infinity and NaN are uppercased, too. \|
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	454 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	455 \| ``'n'`` \| Number. This is the same as ``'g'``, except that it uses \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	456 \| \| the current locale setting to insert the appropriate \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	457 \| \| number separator characters. \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	458 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	459 \| ``'%'`` \| Percentage. Multiplies the number by 100 and displays \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	460 \| \| in fixed (``'f'``) format, followed by a percent sign. \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	461 +---------+----------------------------------------------------------+
48015 ac1cd46bf7d5 Document the different meaning of precision for {:f} and {:g}. Georg Brandl <georg@python.org> parents: 48003 diff changeset	462 \| None \| The same as ``'g'``. \|
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	463 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	464
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	465
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	466 Template strings
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	467 ----------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	468
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	469 Templates provide simpler string substitutions as described in :pep:`292`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	470 Instead of the normal ``%``\ -based substitutions, Templates support ``$``\
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	471 -based substitutions, using the following rules:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	472
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	473 * ``$$`` is an escape; it is replaced with a single ``$``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	474
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	475 * ``$identifier`` names a substitution placeholder matching a mapping key of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	476 ``"identifier"``. By default, ``"identifier"`` must spell a Python
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	477 identifier. The first non-identifier character after the ``$`` character
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	478 terminates this placeholder specification.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	479
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	480 * ``${identifier}`` is equivalent to ``$identifier``. It is required when valid
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	481 identifier characters follow the placeholder but are not part of the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	482 placeholder, such as ``"${noun}ification"``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	483
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	484 Any other appearance of ``$`` in the string will result in a :exc:`ValueError`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	485 being raised.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	486
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	487 .. versionadded:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	488
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	489 The :mod:`string` module provides a :class:`Template` class that implements
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	490 these rules. The methods of :class:`Template` are:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	491
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	492
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	493 .. class:: Template(template)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	494
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	495 The constructor takes a single argument which is the template string.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	496
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	497
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	498 .. method:: substitute(mapping[, **kws])
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	499
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	500 Performs the template substitution, returning a new string. mapping is
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	501 any dictionary-like object with keys that match the placeholders in the
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	502 template. Alternatively, you can provide keyword arguments, where the
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	503 keywords are the placeholders. When both mapping and kws are given
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	504 and there are duplicates, the placeholders from kws take precedence.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	505
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	506
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	507 .. method:: safe_substitute(mapping[, **kws])
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	508
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	509 Like :meth:`substitute`, except that if placeholders are missing from
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	510 mapping and kws, instead of raising a :exc:`KeyError` exception, the
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	511 original placeholder will appear in the resulting string intact. Also,
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	512 unlike with :meth:`substitute`, any other appearances of the ``$`` will
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	513 simply return ``$`` instead of raising :exc:`ValueError`.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	514
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	515 While other exceptions may still occur, this method is called "safe"
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	516 because substitutions always tries to return a usable string instead of
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	517 raising an exception. In another sense, :meth:`safe_substitute` may be
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	518 anything other than safe, since it will silently ignore malformed
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	519 templates containing dangling delimiters, unmatched braces, or
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	520 placeholders that are not valid Python identifiers.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	521
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	522 :class:`Template` instances also provide one public data attribute:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	523
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	524
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	525 .. attribute:: string.template
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	526
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	527 This is the object passed to the constructor's template argument. In general,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	528 you shouldn't change it, but read-only access is not enforced.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	529
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 42603 diff changeset	530 Here is an example of how to use a Template:
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	531
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	532 >>> from string import Template
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	533 >>> s = Template('$who likes $what')
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	534 >>> s.substitute(who='tim', what='kung pao')
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	535 'tim likes kung pao'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	536 >>> d = dict(who='tim')
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	537 >>> Template('Give $who $100').substitute(d)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	538 Traceback (most recent call last):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	539 [...]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	540 ValueError: Invalid placeholder in string: line 1, col 10
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	541 >>> Template('$who likes $what').substitute(d)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	542 Traceback (most recent call last):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	543 [...]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	544 KeyError: 'what'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	545 >>> Template('$who likes $what').safe_substitute(d)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	546 'tim likes $what'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	547
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	548 Advanced usage: you can derive subclasses of :class:`Template` to customize the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	549 placeholder syntax, delimiter character, or the entire regular expression used
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	550 to parse template strings. To do this, you can override these class attributes:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	551
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	552 * delimiter -- This is the literal string describing a placeholder introducing
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	553 delimiter. The default value ``$``. Note that this should not be a regular
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	554 expression, as the implementation will call :meth:`re.escape` on this string as
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	555 needed.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	556
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	557 * idpattern -- This is the regular expression describing the pattern for
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	558 non-braced placeholders (the braces will be added automatically as
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	559 appropriate). The default value is the regular expression
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	560 ``[_a-z][_a-z0-9]*``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	561
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	562 Alternatively, you can provide the entire regular expression pattern by
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	563 overriding the class attribute pattern. If you do this, the value must be a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	564 regular expression object with four named capturing groups. The capturing
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	565 groups correspond to the rules given above, along with the invalid placeholder
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	566 rule:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	567
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	568 * escaped -- This group matches the escape sequence, e.g. ``$$``, in the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	569 default pattern.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	570
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	571 * named -- This group matches the unbraced placeholder name; it should not
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	572 include the delimiter in capturing group.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	573
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	574 * braced -- This group matches the brace enclosed placeholder name; it should
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	575 not include either the delimiter or braces in the capturing group.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	576
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	577 * invalid -- This group matches any other delimiter pattern (usually a single
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	578 delimiter), and it should appear last in the regular expression.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	579
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	580
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	581 String functions
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	582 ----------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	583
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	584 The following functions are available to operate on string and Unicode objects.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	585 They are not available as string methods.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	586
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	587
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	588 .. function:: capwords(s)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	589
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	590 Split the argument into words using :func:`split`, capitalize each word using
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	591 :func:`capitalize`, and join the capitalized words using :func:`join`. Note
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	592 that this replaces runs of whitespace characters by a single space, and removes
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	593 leading and trailing whitespace.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	594
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	595
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	596 .. function:: maketrans(from, to)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	597
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	598 Return a translation table suitable for passing to :func:`translate`, that will
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	599 map each character in from into the character at the same position in to;
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	600 from and to must have the same length.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	601
53508 57812944c961 Demote warnings to notices where appropriate, following the goal that as few "red box" warnings Georg Brandl <georg@python.org> parents: 53305 diff changeset	602 .. note::
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	603
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	604 Don't use strings derived from :const:`lowercase` and :const:`uppercase` as
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	605 arguments; in some locales, these don't have the same length. For case
52003 0c028685b44c Remove obsolete stuff from string module docs. Georg Brandl <georg@python.org> parents: 50522 diff changeset	606 conversions, always use :meth:`str.lower` and :meth:`str.upper`.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	607
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	608
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	609 Deprecated string functions
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	610 ---------------------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	611
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	612 The following list of functions are also defined as methods of string and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	613 Unicode objects; see section :ref:`string-methods` for more information on
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	614 those. You should consider these functions as deprecated, although they will
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	615 not be removed until Python 3.0. The functions defined in this module are:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	616
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	617
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	618 .. function:: atof(s)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	619
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	620 .. deprecated:: 2.0
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	621 Use the :func:`float` built-in function.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	622
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	623 .. index:: builtin: float
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	624
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	625 Convert a string to a floating point number. The string must have the standard
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	626 syntax for a floating point literal in Python, optionally preceded by a sign
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	627 (``+`` or ``-``). Note that this behaves identical to the built-in function
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	628 :func:`float` when passed a string.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	629
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	630 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	631
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	632 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	633 single: NaN
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	634 single: Infinity
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	635
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	636 When passing in a string, values for NaN and Infinity may be returned, depending
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	637 on the underlying C library. The specific set of strings accepted which cause
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	638 these values to be returned depends entirely on the C library and is known to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	639 vary.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	640
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	641
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	642 .. function:: atoi(s[, base])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	643
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	644 .. deprecated:: 2.0
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	645 Use the :func:`int` built-in function.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	646
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	647 .. index:: builtin: eval
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	648
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	649 Convert string s to an integer in the given base. The string must consist
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	650 of one or more digits, optionally preceded by a sign (``+`` or ``-``). The
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	651 base defaults to 10. If it is 0, a default base is chosen depending on the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	652 leading characters of the string (after stripping the sign): ``0x`` or ``0X``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	653 means 16, ``0`` means 8, anything else means 10. If base is 16, a leading
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	654 ``0x`` or ``0X`` is always accepted, though not required. This behaves
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	655 identically to the built-in function :func:`int` when passed a string. (Also
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	656 note: for a more flexible interpretation of numeric literals, use the built-in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	657 function :func:`eval`.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	658
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	659
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	660 .. function:: atol(s[, base])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	661
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	662 .. deprecated:: 2.0
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	663 Use the :func:`long` built-in function.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	664
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	665 .. index:: builtin: long
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	666
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	667 Convert string s to a long integer in the given base. The string must
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	668 consist of one or more digits, optionally preceded by a sign (``+`` or ``-``).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	669 The base argument has the same meaning as for :func:`atoi`. A trailing ``l``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	670 or ``L`` is not allowed, except if the base is 0. Note that when invoked
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	671 without base or with base set to 10, this behaves identical to the built-in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	672 function :func:`long` when passed a string.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	673
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	674
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	675 .. function:: capitalize(word)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	676
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	677 Return a copy of word with only its first character capitalized.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	678
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	679
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	680 .. function:: expandtabs(s[, tabsize])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	681
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	682 Expand tabs in a string replacing them by one or more spaces, depending on the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	683 current column and the given tab size. The column number is reset to zero after
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	684 each newline occurring in the string. This doesn't understand other non-printing
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	685 characters or escape sequences. The tab size defaults to 8.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	686
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	687
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	688 .. function:: find(s, sub[, start[,end]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	689
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	690 Return the lowest index in s where the substring sub is found such that
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	691 sub is wholly contained in ``s[start:end]``. Return ``-1`` on failure.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	692 Defaults for start and end and interpretation of negative values is the same
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	693 as for slices.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	694
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	695
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	696 .. function:: rfind(s, sub[, start[, end]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	697
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	698 Like :func:`find` but find the highest index.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	699
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	700
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	701 .. function:: index(s, sub[, start[, end]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	702
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	703 Like :func:`find` but raise :exc:`ValueError` when the substring is not found.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	704
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	705
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	706 .. function:: rindex(s, sub[, start[, end]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	707
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	708 Like :func:`rfind` but raise :exc:`ValueError` when the substring is not found.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	709
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	710
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	711 .. function:: count(s, sub[, start[, end]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	712
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	713 Return the number of (non-overlapping) occurrences of substring sub in string
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	714 ``s[start:end]``. Defaults for start and end and interpretation of negative
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	715 values are the same as for slices.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	716
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	717
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	718 .. function:: lower(s)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	719
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	720 Return a copy of s, but with upper case letters converted to lower case.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	721
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	722
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	723 .. function:: split(s[, sep[, maxsplit]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	724
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	725 Return a list of the words of the string s. If the optional second argument
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	726 sep is absent or ``None``, the words are separated by arbitrary strings of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	727 whitespace characters (space, tab, newline, return, formfeed). If the second
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	728 argument sep is present and not ``None``, it specifies a string to be used as
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	729 the word separator. The returned list will then have one more item than the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	730 number of non-overlapping occurrences of the separator in the string. The
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	731 optional third argument maxsplit defaults to 0. If it is nonzero, at most
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	732 maxsplit number of splits occur, and the remainder of the string is returned
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	733 as the final element of the list (thus, the list will have at most
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	734 ``maxsplit+1`` elements).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	735
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	736 The behavior of split on an empty string depends on the value of sep. If sep
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	737 is not specified, or specified as ``None``, the result will be an empty list.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	738 If sep is specified as any string, the result will be a list containing one
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	739 element which is an empty string.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	740
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	741
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	742 .. function:: rsplit(s[, sep[, maxsplit]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	743
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	744 Return a list of the words of the string s, scanning s from the end. To all
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	745 intents and purposes, the resulting list of words is the same as returned by
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	746 :func:`split`, except when the optional third argument maxsplit is explicitly
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	747 specified and nonzero. When maxsplit is nonzero, at most maxsplit number of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	748 splits -- the rightmost ones -- occur, and the remainder of the string is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	749 returned as the first element of the list (thus, the list will have at most
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	750 ``maxsplit+1`` elements).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	751
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	752 .. versionadded:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	753
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	754
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	755 .. function:: splitfields(s[, sep[, maxsplit]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	756
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	757 This function behaves identically to :func:`split`. (In the past, :func:`split`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	758 was only used with one argument, while :func:`splitfields` was only used with
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	759 two arguments.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	760
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	761
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	762 .. function:: join(words[, sep])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	763
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	764 Concatenate a list or tuple of words with intervening occurrences of sep.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	765 The default value for sep is a single space character. It is always true that
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	766 ``string.join(string.split(s, sep), sep)`` equals s.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	767
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	768
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	769 .. function:: joinfields(words[, sep])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	770
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	771 This function behaves identically to :func:`join`. (In the past, :func:`join`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	772 was only used with one argument, while :func:`joinfields` was only used with two
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	773 arguments.) Note that there is no :meth:`joinfields` method on string objects;
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	774 use the :meth:`join` method instead.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	775
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	776
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	777 .. function:: lstrip(s[, chars])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	778
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	779 Return a copy of the string with leading characters removed. If chars is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	780 omitted or ``None``, whitespace characters are removed. If given and not
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	781 ``None``, chars must be a string; the characters in the string will be
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	782 stripped from the beginning of the string this method is called on.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	783
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	784 .. versionchanged:: 2.2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	785 The chars parameter was added. The chars parameter cannot be passed in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	786 earlier 2.2 versions.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	787
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	788
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	789 .. function:: rstrip(s[, chars])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	790
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	791 Return a copy of the string with trailing characters removed. If chars is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	792 omitted or ``None``, whitespace characters are removed. If given and not
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	793 ``None``, chars must be a string; the characters in the string will be
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	794 stripped from the end of the string this method is called on.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	795
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	796 .. versionchanged:: 2.2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	797 The chars parameter was added. The chars parameter cannot be passed in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	798 earlier 2.2 versions.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	799
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	800
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	801 .. function:: strip(s[, chars])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	802
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	803 Return a copy of the string with leading and trailing characters removed. If
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	804 chars is omitted or ``None``, whitespace characters are removed. If given and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	805 not ``None``, chars must be a string; the characters in the string will be
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	806 stripped from the both ends of the string this method is called on.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	807
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	808 .. versionchanged:: 2.2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	809 The chars parameter was added. The chars parameter cannot be passed in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	810 earlier 2.2 versions.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	811
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	812
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	813 .. function:: swapcase(s)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	814
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	815 Return a copy of s, but with lower case letters converted to upper case and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	816 vice versa.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	817
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	818
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	819 .. function:: translate(s, table[, deletechars])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	820
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	821 Delete all characters from s that are in deletechars (if present), and then
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	822 translate the characters using table, which must be a 256-character string
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	823 giving the translation for each character value, indexed by its ordinal. If
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	824 table is ``None``, then only the character deletion step is performed.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	825
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	826
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	827 .. function:: upper(s)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	828
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	829 Return a copy of s, but with lower case letters converted to upper case.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	830
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	831
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	832 .. function:: ljust(s, width)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	833 rjust(s, width)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	834 center(s, width)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	835
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	836 These functions respectively left-justify, right-justify and center a string in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	837 a field of given width. They return a string that is at least width
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	838 characters wide, created by padding the string s with spaces until the given
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	839 width on the right, left or both sides. The string is never truncated.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	840
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	841
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	842 .. function:: zfill(s, width)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	843
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	844 Pad a numeric string on the left with zero digits until the given width is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	845 reached. Strings starting with a sign are handled correctly.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	846
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	847
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	848 .. function:: replace(str, old, new[, maxreplace])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	849
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	850 Return a copy of string str with all occurrences of substring old replaced
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	851 by new. If the optional argument maxreplace is given, the first
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	852 maxreplace occurrences are replaced.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	853

Mercurial > cpython-lru_cache-weakref

annotate Doc/library/string.rst @ 54294:dba767bc3155 legacy-trunk