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

annotate Doc/library/string.rst @ 58925:eecf1bef052d 2.6

Merged revisions 78207 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r78207 | ezio.melotti | 2010-02-17 01:26:09 +0200 (Wed, 17 Feb 2010) | 1 line #7930: fix stripid ........

author	Ezio Melotti <ezio.melotti@gmail.com>
date	Tue, 16 Feb 2010 23:29:44 +0000
parents	465c047ef311
children	bd8357a91d3e

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.
52909 f3b26a729e82 Merged revisions 69578-69580,69901,69907,69994,70022-70023,70025-70026,70166,70273,70275,70342,70386-70387,70389-70390,70392-70393,70395,70397,70400,70418 via svnmerge Georg Brandl <georg@python.org> parents: 50522 diff changeset	65 On most systems this is the string ``'abcdefghijklmnopqrstuvwxyz'``. The
f3b26a729e82 Merged revisions 69578-69580,69901,69907,69994,70022-70023,70025-70026,70166,70273,70275,70342,70386-70387,70389-70390,70392-70393,70395,70397,70400,70418 via svnmerge Georg Brandl <georg@python.org> parents: 50522 diff changeset	66 specific value is locale-dependent, and will be updated when
f3b26a729e82 Merged revisions 69578-69580,69901,69907,69994,70022-70023,70025-70026,70166,70273,70275,70342,70386-70387,70389-70390,70392-70393,70395,70397,70400,70418 via svnmerge 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.
52909 f3b26a729e82 Merged revisions 69578-69580,69901,69907,69994,70022-70023,70025-70026,70166,70273,70275,70342,70386-70387,70389-70390,70392-70393,70395,70397,70400,70418 via svnmerge Georg Brandl <georg@python.org> parents: 50522 diff changeset	91 On most systems this is the string ``'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``. The
f3b26a729e82 Merged revisions 69578-69580,69901,69907,69994,70022-70023,70025-70026,70166,70273,70275,70342,70386-70387,70389-70390,70392-70393,70395,70397,70400,70418 via svnmerge Georg Brandl <georg@python.org> parents: 50522 diff changeset	92 specific value is locale-dependent, and will be updated when
f3b26a729e82 Merged revisions 69578-69580,69901,69907,69994,70022-70023,70025-70026,70166,70273,70275,70342,70386-70387,70389-70390,70392-70393,70395,70397,70400,70418 via svnmerge 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
52909 f3b26a729e82 Merged revisions 69578-69580,69901,69907,69994,70022-70023,70025-70026,70166,70273,70275,70342,70386-70387,70389-70390,70392-70393,70395,70397,70400,70418 via svnmerge 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`] "}"
52909 f3b26a729e82 Merged revisions 69578-69580,69901,69907,69994,70022-70023,70025-70026,70166,70273,70275,70342,70386-70387,70389-70390,70392-70393,70395,70397,70400,70418 via svnmerge Georg Brandl <georg@python.org> parents: 50522 diff changeset	224 field_name: (`identifier` \| `integer`) ("." `attribute_name` \| "[" `element_index` "]")*
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	225 attribute_name: `identifier`
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	226 element_index: `integer`
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	227 conversion: "r" \| "s"
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	228 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	229
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	230 In less formal terms, the replacement field starts with a field_name, which
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	231 can either be a number (for a positional argument), or an identifier (for
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	232 keyword arguments). Following this is an optional conversion field, which is
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	233 preceded by an exclamation point ``'!'``, and a format_spec, which is preceded
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	234 by a colon ``':'``.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	235
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	236 The field_name itself begins with either a number or a keyword. If it's a
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	237 number, it refers to a positional argument, and if it's a keyword it refers to a
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	238 named keyword argument. This can be followed by any number of index or
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	239 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	240 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	241 does an index lookup using :func:`__getitem__`.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	242
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	243 Some simple format string examples::
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	244
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	245 "First, thou shalt count to {0}" # References first positional argument
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	246 "My quest is {name}" # References keyword argument 'name'
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	247 "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	248 "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	249
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	250 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	251 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	252 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	253 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	254 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	255 is bypassed.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	256
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	257 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	258 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	259
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	260 Some examples::
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	261
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	262 "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	263 "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	264
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	265 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	266 presented, including such details as field width, alignment, padding, decimal
58916 465c047ef311 Merged revisions 78198 via svnmerge from Eric Smith <eric@trueblade.com> parents: 56822 diff changeset	267 precision and so on. Each value type can define its own "formatting
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	268 mini-language" or interpretation of the format_spec.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	269
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	270 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	271 described in the next section.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	272
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	273 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	274 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	275 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	276 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	277 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	278
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	279 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	280 determined by another variable::
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	281
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	282 "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	283
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	284 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	285 effectively::
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	286
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	287 "A man with two {0:10}"
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 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	290
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	291 "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	292
47937 38d3a50defec fix various doc typos #3320 Benjamin Peterson <benjamin@python.org> parents: 47280 diff changeset	293 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	294
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	295 "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	296
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	297 (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	298 alignment is the default for strings.)
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	299
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	300
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	301 .. _formatspec:
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	302
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	303 Format Specification Mini-Language
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	304 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	305
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	306 "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	307 format string to define how individual values are presented (see
56818 3e15a07a32fa Merged revisions 74209 via svnmerge from Georg Brandl <georg@python.org> parents: 56814 diff changeset	308 :ref:`formatstrings`.) They can also be passed directly to the built-in
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	309 :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	310 specification is to be interpreted.
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 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	313 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	314
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	315 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	316 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	317
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	318 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	319
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	320 .. 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	321 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	322 fill: <a character other than '}'>
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	323 align: "<" \| ">" \| "=" \| "^"
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	324 sign: "+" \| "-" \| " "
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	325 width: `integer`
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	326 precision: `integer`
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	327 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	328
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	329 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	330 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	331 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	332 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	333 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	334
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	335 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	336
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	337 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	338 \| Option \| Meaning \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	339 +=========+==========================================================+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	340 \| ``'<'`` \| 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	341 \| \| space (This is the default.) \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	342 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	343 \| ``'>'`` \| 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	344 \| \| available space. \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	345 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	346 \| ``'='`` \| 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	347 \| \| 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	348 \| \| 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	349 \| \| valid for numeric types. \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	350 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	351 \| ``'^'`` \| 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	352 \| \| space. \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	353 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	354
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	355 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	356 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	357 meaning in this case.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	358
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	359 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	360 following:
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 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	363 \| Option \| Meaning \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	364 +=========+==========================================================+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	365 \| ``'+'`` \| 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	366 \| \| positive as well as negative numbers. \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	367 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	368 \| ``'-'`` \| 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	369 \| \| numbers (this is the default behavior). \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	370 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	371 \| 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	372 \| \| 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	373 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	374
49152 0fcd4db23dff fix typo Benjamin Peterson <benjamin@python.org> parents: 48015 diff changeset	375 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	376 hexadecimal output. If present, it specifies that the output will be prefixed
0fcd4db23dff fix typo Benjamin Peterson <benjamin@python.org> parents: 48015 diff changeset	377 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	378
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	379 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	380 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	381
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	382 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	383 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	384 character of ``'0'``.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	385
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	386 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	387 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	388 ``'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	389 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	390 indicates the maximum field size - in other words, how many characters will be
53883 5502ff2fbdd6 Merged revisions 72439 via svnmerge from Eric Smith <eric@trueblade.com> parents: 53573 diff changeset	391 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	392
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	393 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	394
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	395 The available integer presentation types are:
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	396
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	397 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	398 \| Type \| Meaning \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	399 +=========+==========================================================+
47973 3fa44e5e4e2b Complete issue 3083: add alternate (#) formatting to bin, oct, hex in str.format(). Eric Smith <eric@trueblade.com> parents: 47937 diff changeset	400 \| ``'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	401 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	402 \| ``'c'`` \| Character. Converts the integer to the corresponding \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	403 \| \| unicode character before printing. \|
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 \| ``'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	406 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	407 \| ``'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	408 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	409 \| ``'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	410 \| \| case letters for the digits above 9. \|
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 \| ``'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	413 \| \| case letters for the digits above 9. \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	414 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	415 \| ``'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	416 \| \| the current locale setting to insert the appropriate \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	417 \| \| number separator characters. \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	418 +---------+----------------------------------------------------------+
48015 ac1cd46bf7d5 Document the different meaning of precision for {:f} and {:g}. Georg Brandl <georg@python.org> parents: 48003 diff changeset	419 \| None \| The same as ``'d'``. \|
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	420 +---------+----------------------------------------------------------+
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	421
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	422 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	423
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	424 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	425 \| Type \| Meaning \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	426 +=========+==========================================================+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	427 \| ``'e'`` \| Exponent notation. Prints the number in scientific \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	428 \| \| 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	429 +---------+----------------------------------------------------------+
48003 5c33009994b4 Backed out r65069, pending fixing it in Windows. Eric Smith <eric@trueblade.com> parents: 48001 diff changeset	430 \| ``'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	431 \| \| upper case 'E' as the separator character. \|
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	432 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	433 \| ``'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	434 \| \| number. \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	435 +---------+----------------------------------------------------------+
48003 5c33009994b4 Backed out r65069, pending fixing it in Windows. Eric Smith <eric@trueblade.com> parents: 48001 diff changeset	436 \| ``'F'`` \| Fixed point. Same as ``'f'``. \|
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	437 +---------+----------------------------------------------------------+
56822 c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	438 \| ``'g'`` \| General format. For a given precision ``p >= 1``, \|
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	439 \| \| this rounds the number to ``p`` significant digits and \|
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	440 \| \| then formats the result in either fixed-point format \|
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	441 \| \| or in scientific notation, depending on its magnitude. \|
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	442 \| \| \|
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	443 \| \| The precise rules are as follows: suppose that the \|
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	444 \| \| result formatted with presentation type ``'e'`` and \|
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	445 \| \| precision ``p-1`` would have exponent ``exp``. Then \|
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	446 \| \| if ``-4 <= exp < p``, the number is formatted \|
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	447 \| \| with presentation type ``'f'`` and precision \|
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	448 \| \| ``p-1-exp``. Otherwise, the number is formatted \|
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	449 \| \| with presentation type ``'e'`` and precision ``p-1``. \|
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	450 \| \| In both cases insignificant trailing zeros are removed \|
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	451 \| \| from the significand, and the decimal point is also \|
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	452 \| \| removed if there are no remaining digits following it. \|
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	453 \| \| \|
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	454 \| \| Postive and negative infinity, positive and negative \|
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	455 \| \| zero, and nans, are formatted as ``inf``, ``-inf``, \|
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	456 \| \| ``0``, ``-0`` and ``nan`` respectively, regardless of \|
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	457 \| \| the precision. \|
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	458 \| \| \|
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	459 \| \| A precision of ``0`` is treated as equivalent to a \|
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	460 \| \| precision of ``1``. \|
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	461 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	462 \| ``'G'`` \| General format. Same as ``'g'`` except switches to \|
56822 c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	463 \| \| ``'E'`` if the number gets too large. The \|
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	464 \| \| representations of infinity and NaN are uppercased, too. \|
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	465 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	466 \| ``'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	467 \| \| the current locale setting to insert the appropriate \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	468 \| \| number separator characters. \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	469 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	470 \| ``'%'`` \| Percentage. Multiplies the number by 100 and displays \|
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	471 \| \| 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	472 +---------+----------------------------------------------------------+
48015 ac1cd46bf7d5 Document the different meaning of precision for {:f} and {:g}. Georg Brandl <georg@python.org> parents: 48003 diff changeset	473 \| None \| The same as ``'g'``. \|
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	474 +---------+----------------------------------------------------------+
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	475
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46555 diff changeset	476
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	477 Template strings
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	478 ----------------
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 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	481 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	482 -based substitutions, using the following rules:
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 * ``$$`` 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	485
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	486 * ``$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	487 ``"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	488 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	489 terminates this placeholder specification.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	490
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	491 * ``${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	492 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	493 placeholder, such as ``"${noun}ification"``.
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 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	496 being raised.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	497
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	498 .. versionadded:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	499
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	500 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	501 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	502
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	503
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	504 .. class:: Template(template)
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 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	507
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 .. method:: substitute(mapping[, **kws])
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	510
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	511 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	512 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	513 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	514 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	515 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	516
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	517
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	518 .. method:: safe_substitute(mapping[, **kws])
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	519
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	520 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	521 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	522 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	523 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	524 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	525
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	526 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	527 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	528 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	529 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	530 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	531 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	532
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	533 :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	534
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	535
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	536 .. attribute:: string.template
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	537
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	538 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	539 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	540
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 42603 diff changeset	541 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	542
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	543 >>> from string import Template
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	544 >>> s = Template('$who likes $what')
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	545 >>> 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	546 'tim likes kung pao'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	547 >>> d = dict(who='tim')
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	548 >>> Template('Give $who $100').substitute(d)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	549 Traceback (most recent call last):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	550 [...]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	551 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	552 >>> Template('$who likes $what').substitute(d)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	553 Traceback (most recent call last):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	554 [...]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	555 KeyError: 'what'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	556 >>> 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	557 'tim likes $what'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	558
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	559 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	560 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	561 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	562
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	563 * 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	564 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	565 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	566 needed.
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 * 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	569 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	570 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	571 ``[_a-z][_a-z0-9]*``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	572
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	573 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	574 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	575 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	576 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	577 rule:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	578
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	579 * 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	580 default pattern.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	581
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	582 * 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	583 include the delimiter in capturing group.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	584
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	585 * 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	586 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	587
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	588 * 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	589 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	590
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	591
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	592 String functions
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	593 ----------------
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 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	596 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	597
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	598
56229 acbfc69b55f3 Merged revisions 75070 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 53883 diff changeset	599 .. function:: capwords(s[, sep])
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	600
56229 acbfc69b55f3 Merged revisions 75070 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 53883 diff changeset	601 Split the argument into words using :meth:`str.split`, capitalize each word
acbfc69b55f3 Merged revisions 75070 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 53883 diff changeset	602 using :meth:`str.capitalize`, and join the capitalized words using
acbfc69b55f3 Merged revisions 75070 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 53883 diff changeset	603 :meth:`str.join`. If the optional second argument sep is absent
acbfc69b55f3 Merged revisions 75070 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 53883 diff changeset	604 or ``None``, runs of whitespace characters are replaced by a single space
acbfc69b55f3 Merged revisions 75070 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 53883 diff changeset	605 and leading and trailing whitespace are removed, otherwise sep is used to
acbfc69b55f3 Merged revisions 75070 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 53883 diff changeset	606 split and join the words.
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 .. function:: maketrans(from, to)
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 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	612 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	613 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	614
53573 503f0f41f35f Merged revisions 72007-72010,72036-72037 via svnmerge from Georg Brandl <georg@python.org> parents: 52909 diff changeset	615 .. note::
42603 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 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	618 arguments; in some locales, these don't have the same length. For case
52909 f3b26a729e82 Merged revisions 69578-69580,69901,69907,69994,70022-70023,70025-70026,70166,70273,70275,70342,70386-70387,70389-70390,70392-70393,70395,70397,70400,70418 via svnmerge Georg Brandl <georg@python.org> parents: 50522 diff changeset	619 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	620
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	621
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	622 Deprecated string functions
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	623 ---------------------------
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 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	626 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	627 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	628 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	629
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	630
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	631 .. function:: atof(s)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	632
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	633 .. deprecated:: 2.0
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	634 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	635
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	636 .. index:: builtin: float
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	637
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	638 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	639 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	640 (``+`` 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	641 :func:`float` when passed a string.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	642
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	643 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	644
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	645 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	646 single: NaN
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	647 single: Infinity
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 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	650 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	651 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	652 vary.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	653
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	654
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	655 .. function:: atoi(s[, base])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	656
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	657 .. deprecated:: 2.0
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	658 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	659
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	660 .. index:: builtin: eval
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 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	663 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	664 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	665 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	666 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	667 ``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	668 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	669 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	670 function :func:`eval`.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	671
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	672
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	673 .. function:: atol(s[, base])
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 .. deprecated:: 2.0
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	676 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	677
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	678 .. index:: builtin: long
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 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	681 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	682 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	683 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	684 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	685 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	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:: capitalize(word)
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 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	691
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	692
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	693 .. function:: expandtabs(s[, tabsize])
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 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	696 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	697 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	698 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	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:: find(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 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	704 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	705 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	706 as for slices.
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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	709 .. function:: rfind(s, sub[, start[, end]])
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 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	712
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	713
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	714 .. function:: index(s, sub[, start[, end]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	715
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	716 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	717
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	718
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	719 .. function:: rindex(s, sub[, start[, end]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	720
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	721 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	722
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	723
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	724 .. function:: count(s, sub[, start[, end]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	725
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	726 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	727 ``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	728 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	729
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	730
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	731 .. function:: lower(s)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	732
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	733 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	734
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 .. function:: split(s[, sep[, maxsplit]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	737
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	738 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	739 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	740 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	741 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	742 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	743 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	744 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	745 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	746 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	747 ``maxsplit+1`` elements).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	748
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	749 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	750 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	751 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	752 element which is an empty string.
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:: rsplit(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 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	758 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	759 :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	760 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	761 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	762 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	763 ``maxsplit+1`` elements).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	764
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	765 .. versionadded:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	766
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 .. function:: splitfields(s[, sep[, maxsplit]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	769
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	770 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	771 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	772 two arguments.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	773
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	774
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	775 .. function:: join(words[, sep])
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 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	778 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	779 ``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	780
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	781
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	782 .. function:: joinfields(words[, sep])
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 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	785 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	786 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	787 use the :meth:`join` method instead.
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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	790 .. function:: lstrip(s[, chars])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	791
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	792 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	793 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	794 ``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	795 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	796
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	797 .. versionchanged:: 2.2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	798 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	799 earlier 2.2 versions.
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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	802 .. function:: rstrip(s[, chars])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	803
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	804 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	805 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	806 ``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	807 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	808
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	809 .. versionchanged:: 2.2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	810 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	811 earlier 2.2 versions.
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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	814 .. function:: strip(s[, chars])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	815
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	816 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	817 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	818 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	819 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	820
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	821 .. versionchanged:: 2.2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	822 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	823 earlier 2.2 versions.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	824
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 .. function:: swapcase(s)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	827
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	828 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	829 vice versa.
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:: translate(s, table[, deletechars])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	833
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	834 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	835 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	836 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	837 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	838
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	839
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	840 .. function:: upper(s)
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 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	843
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	844
56814 127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from Georg Brandl <georg@python.org> parents: 56807 diff changeset	845 .. function:: ljust(s, width[, fillchar])
127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from Georg Brandl <georg@python.org> parents: 56807 diff changeset	846 rjust(s, width[, fillchar])
127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from Georg Brandl <georg@python.org> parents: 56807 diff changeset	847 center(s, width[, fillchar])
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	848
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	849 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	850 a field of given width. They return a string that is at least width
56814 127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from Georg Brandl <georg@python.org> parents: 56807 diff changeset	851 characters wide, created by padding the string s with the character fillchar
127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from Georg Brandl <georg@python.org> parents: 56807 diff changeset	852 (default is a space) until the given width on the right, left or both sides.
127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from Georg Brandl <georg@python.org> parents: 56807 diff changeset	853 The string is never truncated.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	854
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	855
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	856 .. function:: zfill(s, width)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	857
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	858 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	859 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	860
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	861
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	862 .. function:: replace(str, old, new[, maxreplace])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	863
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	864 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	865 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	866 maxreplace occurrences are replaced.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	867

Mercurial > cpython-lru_cache-weakref

annotate Doc/library/string.rst @ 58925:eecf1bef052d 2.6