1 :mod:`string` --- Common string operations 2 ========================================== 3 4 .. module:: string 5 :synopsis: Common string operations. 6 7 **Source code:** :source:`Lib/string.py` 8 9 -------------- 10 11 .. seealso:: 12 13 :ref:`textseq` 14 15 :ref:`string-methods` 16 17 String constants 18 ---------------- 19 20 The constants defined in this module are: 21 22 23 .. data:: ascii_letters 24 25 The concatenation of the :const:`ascii_lowercase` and :const:`ascii_uppercase` 26 constants described below. This value is not locale-dependent. 27 28 29 .. data:: ascii_lowercase 30 31 The lowercase letters ``'abcdefghijklmnopqrstuvwxyz'``. This value is not 32 locale-dependent and will not change. 33 34 35 .. data:: ascii_uppercase 36 37 The uppercase letters ``'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``. This value is not 38 locale-dependent and will not change. 39 40 41 .. data:: digits 42 43 The string ``'0123456789'``. 44 45 46 .. data:: hexdigits 47 48 The string ``'0123456789abcdefABCDEF'``. 49 50 51 .. data:: octdigits 52 53 The string ``'01234567'``. 54 55 56 .. data:: punctuation 57 58 String of ASCII characters which are considered punctuation characters 59 in the ``C`` locale. 60 61 62 .. data:: printable 63 64 String of ASCII characters which are considered printable. This is a 65 combination of :const:`digits`, :const:`ascii_letters`, :const:`punctuation`, 66 and :const:`whitespace`. 67 68 69 .. data:: whitespace 70 71 A string containing all ASCII characters that are considered whitespace. 72 This includes the characters space, tab, linefeed, return, formfeed, and 73 vertical tab. 74 75 76 .. _string-formatting: 77 78 Custom String Formatting 79 ------------------------ 80 81 The built-in string class provides the ability to do complex variable 82 substitutions and value formatting via the :meth:`~str.format` method described in 83 :pep:`3101`. The :class:`Formatter` class in the :mod:`string` module allows 84 you to create and customize your own string formatting behaviors using the same 85 implementation as the built-in :meth:`~str.format` method. 86 87 88 .. class:: Formatter 89 90 The :class:`Formatter` class has the following public methods: 91 92 .. method:: format(format_string, *args, **kwargs) 93 94 The primary API method. It takes a format string and 95 an arbitrary set of positional and keyword arguments. 96 It is just a wrapper that calls :meth:`vformat`. 97 98 .. deprecated:: 3.5 99 Passing a format string as keyword argument *format_string* has been 100 deprecated. 101 102 .. method:: vformat(format_string, args, kwargs) 103 104 This function does the actual work of formatting. It is exposed as a 105 separate function for cases where you want to pass in a predefined 106 dictionary of arguments, rather than unpacking and repacking the 107 dictionary as individual arguments using the ``*args`` and ``**kwargs`` 108 syntax. :meth:`vformat` does the work of breaking up the format string 109 into character data and replacement fields. It calls the various 110 methods described below. 111 112 In addition, the :class:`Formatter` defines a number of methods that are 113 intended to be replaced by subclasses: 114 115 .. method:: parse(format_string) 116 117 Loop over the format_string and return an iterable of tuples 118 (*literal_text*, *field_name*, *format_spec*, *conversion*). This is used 119 by :meth:`vformat` to break the string into either literal text, or 120 replacement fields. 121 122 The values in the tuple conceptually represent a span of literal text 123 followed by a single replacement field. If there is no literal text 124 (which can happen if two replacement fields occur consecutively), then 125 *literal_text* will be a zero-length string. If there is no replacement 126 field, then the values of *field_name*, *format_spec* and *conversion* 127 will be ``None``. 128 129 .. method:: get_field(field_name, args, kwargs) 130 131 Given *field_name* as returned by :meth:`parse` (see above), convert it to 132 an object to be formatted. Returns a tuple (obj, used_key). The default 133 version takes strings of the form defined in :pep:`3101`, such as 134 "0[name]" or "label.title". *args* and *kwargs* are as passed in to 135 :meth:`vformat`. The return value *used_key* has the same meaning as the 136 *key* parameter to :meth:`get_value`. 137 138 .. method:: get_value(key, args, kwargs) 139 140 Retrieve a given field value. The *key* argument will be either an 141 integer or a string. If it is an integer, it represents the index of the 142 positional argument in *args*; if it is a string, then it represents a 143 named argument in *kwargs*. 144 145 The *args* parameter is set to the list of positional arguments to 146 :meth:`vformat`, and the *kwargs* parameter is set to the dictionary of 147 keyword arguments. 148 149 For compound field names, these functions are only called for the first 150 component of the field name; Subsequent components are handled through 151 normal attribute and indexing operations. 152 153 So for example, the field expression '0.name' would cause 154 :meth:`get_value` to be called with a *key* argument of 0. The ``name`` 155 attribute will be looked up after :meth:`get_value` returns by calling the 156 built-in :func:`getattr` function. 157 158 If the index or keyword refers to an item that does not exist, then an 159 :exc:`IndexError` or :exc:`KeyError` should be raised. 160 161 .. method:: check_unused_args(used_args, args, kwargs) 162 163 Implement checking for unused arguments if desired. The arguments to this 164 function is the set of all argument keys that were actually referred to in 165 the format string (integers for positional arguments, and strings for 166 named arguments), and a reference to the *args* and *kwargs* that was 167 passed to vformat. The set of unused args can be calculated from these 168 parameters. :meth:`check_unused_args` is assumed to raise an exception if 169 the check fails. 170 171 .. method:: format_field(value, format_spec) 172 173 :meth:`format_field` simply calls the global :func:`format` built-in. The 174 method is provided so that subclasses can override it. 175 176 .. method:: convert_field(value, conversion) 177 178 Converts the value (returned by :meth:`get_field`) given a conversion type 179 (as in the tuple returned by the :meth:`parse` method). The default 180 version understands 's' (str), 'r' (repr) and 'a' (ascii) conversion 181 types. 182 183 184 .. _formatstrings: 185 186 Format String Syntax 187 -------------------- 188 189 The :meth:`str.format` method and the :class:`Formatter` class share the same 190 syntax for format strings (although in the case of :class:`Formatter`, 191 subclasses can define their own format string syntax). The syntax is 192 related to that of :ref:`formatted string literals <f-strings>`, but 193 there are differences. 194 195 Format strings contain "replacement fields" surrounded by curly braces ``{}``. 196 Anything that is not contained in braces is considered literal text, which is 197 copied unchanged to the output. If you need to include a brace character in the 198 literal text, it can be escaped by doubling: ``{{`` and ``}}``. 199 200 The grammar for a replacement field is as follows: 201 202 .. productionlist:: sf 203 replacement_field: "{" [`field_name`] ["!" `conversion`] [":" `format_spec`] "}" 204 field_name: arg_name ("." `attribute_name` | "[" `element_index` "]")* 205 arg_name: [`identifier` | `integer`] 206 attribute_name: `identifier` 207 element_index: `integer` | `index_string` 208 index_string: <any source character except "]"> + 209 conversion: "r" | "s" | "a" 210 format_spec: <described in the next section> 211 212 In less formal terms, the replacement field can start with a *field_name* that specifies 213 the object whose value is to be formatted and inserted 214 into the output instead of the replacement field. 215 The *field_name* is optionally followed by a *conversion* field, which is 216 preceded by an exclamation point ``'!'``, and a *format_spec*, which is preceded 217 by a colon ``':'``. These specify a non-default format for the replacement value. 218 219 See also the :ref:`formatspec` section. 220 221 The *field_name* itself begins with an *arg_name* that is either a number or a 222 keyword. If it's a number, it refers to a positional argument, and if it's a keyword, 223 it refers to a named keyword argument. If the numerical arg_names in a format string 224 are 0, 1, 2, ... in sequence, they can all be omitted (not just some) 225 and the numbers 0, 1, 2, ... will be automatically inserted in that order. 226 Because *arg_name* is not quote-delimited, it is not possible to specify arbitrary 227 dictionary keys (e.g., the strings ``'10'`` or ``':-]'``) within a format string. 228 The *arg_name* can be followed by any number of index or 229 attribute expressions. An expression of the form ``'.name'`` selects the named 230 attribute using :func:`getattr`, while an expression of the form ``'[index]'`` 231 does an index lookup using :func:`__getitem__`. 232 233 .. versionchanged:: 3.1 234 The positional argument specifiers can be omitted, so ``'{} {}'`` is 235 equivalent to ``'{0} {1}'``. 236 237 Some simple format string examples:: 238 239 "First, thou shalt count to {0}" # References first positional argument 240 "Bring me a {}" # Implicitly references the first positional argument 241 "From {} to {}" # Same as "From {0} to {1}" 242 "My quest is {name}" # References keyword argument 'name' 243 "Weight in tons {0.weight}" # 'weight' attribute of first positional arg 244 "Units destroyed: {players[0]}" # First element of keyword argument 'players'. 245 246 The *conversion* field causes a type coercion before formatting. Normally, the 247 job of formatting a value is done by the :meth:`__format__` method of the value 248 itself. However, in some cases it is desirable to force a type to be formatted 249 as a string, overriding its own definition of formatting. By converting the 250 value to a string before calling :meth:`__format__`, the normal formatting logic 251 is bypassed. 252 253 Three conversion flags are currently supported: ``'!s'`` which calls :func:`str` 254 on the value, ``'!r'`` which calls :func:`repr` and ``'!a'`` which calls 255 :func:`ascii`. 256 257 Some examples:: 258 259 "Harold's a clever {0!s}" # Calls str() on the argument first 260 "Bring out the holy {name!r}" # Calls repr() on the argument first 261 "More {!a}" # Calls ascii() on the argument first 262 263 The *format_spec* field contains a specification of how the value should be 264 presented, including such details as field width, alignment, padding, decimal 265 precision and so on. Each value type can define its own "formatting 266 mini-language" or interpretation of the *format_spec*. 267 268 Most built-in types support a common formatting mini-language, which is 269 described in the next section. 270 271 A *format_spec* field can also include nested replacement fields within it. 272 These nested replacement fields may contain a field name, conversion flag 273 and format specification, but deeper nesting is 274 not allowed. The replacement fields within the 275 format_spec are substituted before the *format_spec* string is interpreted. 276 This allows the formatting of a value to be dynamically specified. 277 278 See the :ref:`formatexamples` section for some examples. 279 280 281 .. _formatspec: 282 283 Format Specification Mini-Language 284 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 285 286 "Format specifications" are used within replacement fields contained within a 287 format string to define how individual values are presented (see 288 :ref:`formatstrings` and :ref:`f-strings`). 289 They can also be passed directly to the built-in 290 :func:`format` function. Each formattable type may define how the format 291 specification is to be interpreted. 292 293 Most built-in types implement the following options for format specifications, 294 although some of the formatting options are only supported by the numeric types. 295 296 A general convention is that an empty format string (``""``) produces 297 the same result as if you had called :func:`str` on the value. A 298 non-empty format string typically modifies the result. 299 300 The general form of a *standard format specifier* is: 301 302 .. productionlist:: sf 303 format_spec: [[`fill`]`align`][`sign`][#][0][`width`][`grouping_option`][.`precision`][`type`] 304 fill: <any character> 305 align: "<" | ">" | "=" | "^" 306 sign: "+" | "-" | " " 307 width: `integer` 308 grouping_option: "_" | "," 309 precision: `integer` 310 type: "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%" 311 312 If a valid *align* value is specified, it can be preceded by a *fill* 313 character that can be any character and defaults to a space if omitted. 314 It is not possible to use a literal curly brace ("``{``" or "``}``") as 315 the *fill* character in a :ref:`formatted string literal 316 <f-strings>` or when using the :meth:`str.format` 317 method. However, it is possible to insert a curly brace 318 with a nested replacement field. This limitation doesn't 319 affect the :func:`format` function. 320 321 The meaning of the various alignment options is as follows: 322 323 +---------+----------------------------------------------------------+ 324 | Option | Meaning | 325 +=========+==========================================================+ 326 | ``'<'`` | Forces the field to be left-aligned within the available | 327 | | space (this is the default for most objects). | 328 +---------+----------------------------------------------------------+ 329 | ``'>'`` | Forces the field to be right-aligned within the | 330 | | available space (this is the default for numbers). | 331 +---------+----------------------------------------------------------+ 332 | ``'='`` | Forces the padding to be placed after the sign (if any) | 333 | | but before the digits. This is used for printing fields | 334 | | in the form '+000000120'. This alignment option is only | 335 | | valid for numeric types. It becomes the default when '0'| 336 | | immediately precedes the field width. | 337 +---------+----------------------------------------------------------+ 338 | ``'^'`` | Forces the field to be centered within the available | 339 | | space. | 340 +---------+----------------------------------------------------------+ 341 342 Note that unless a minimum field width is defined, the field width will always 343 be the same size as the data to fill it, so that the alignment option has no 344 meaning in this case. 345 346 The *sign* option is only valid for number types, and can be one of the 347 following: 348 349 +---------+----------------------------------------------------------+ 350 | Option | Meaning | 351 +=========+==========================================================+ 352 | ``'+'`` | indicates that a sign should be used for both | 353 | | positive as well as negative numbers. | 354 +---------+----------------------------------------------------------+ 355 | ``'-'`` | indicates that a sign should be used only for negative | 356 | | numbers (this is the default behavior). | 357 +---------+----------------------------------------------------------+ 358 | space | indicates that a leading space should be used on | 359 | | positive numbers, and a minus sign on negative numbers. | 360 +---------+----------------------------------------------------------+ 361 362 363 The ``'#'`` option causes the "alternate form" to be used for the 364 conversion. The alternate form is defined differently for different 365 types. This option is only valid for integer, float, complex and 366 Decimal types. For integers, when binary, octal, or hexadecimal output 367 is used, this option adds the prefix respective ``'0b'``, ``'0o'``, or 368 ``'0x'`` to the output value. For floats, complex and Decimal the 369 alternate form causes the result of the conversion to always contain a 370 decimal-point character, even if no digits follow it. Normally, a 371 decimal-point character appears in the result of these conversions 372 only if a digit follows it. In addition, for ``'g'`` and ``'G'`` 373 conversions, trailing zeros are not removed from the result. 374 375 The ``','`` option signals the use of a comma for a thousands separator. 376 For a locale aware separator, use the ``'n'`` integer presentation type 377 instead. 378 379 .. versionchanged:: 3.1 380 Added the ``','`` option (see also :pep:`378`). 381 382 The ``'_'`` option signals the use of an underscore for a thousands 383 separator for floating point presentation types and for integer 384 presentation type ``'d'``. For integer presentation types ``'b'``, 385 ``'o'``, ``'x'``, and ``'X'``, underscores will be inserted every 4 386 digits. For other presentation types, specifying this option is an 387 error. 388 389 .. versionchanged:: 3.6 390 Added the ``'_'`` option (see also :pep:`515`). 391 392 *width* is a decimal integer defining the minimum field width. If not 393 specified, then the field width will be determined by the content. 394 395 When no explicit alignment is given, preceding the *width* field by a zero 396 (``'0'``) character enables 397 sign-aware zero-padding for numeric types. This is equivalent to a *fill* 398 character of ``'0'`` with an *alignment* type of ``'='``. 399 400 The *precision* is a decimal number indicating how many digits should be 401 displayed after the decimal point for a floating point value formatted with 402 ``'f'`` and ``'F'``, or before and after the decimal point for a floating point 403 value formatted with ``'g'`` or ``'G'``. For non-number types the field 404 indicates the maximum field size - in other words, how many characters will be 405 used from the field content. The *precision* is not allowed for integer values. 406 407 Finally, the *type* determines how the data should be presented. 408 409 The available string presentation types are: 410 411 +---------+----------------------------------------------------------+ 412 | Type | Meaning | 413 +=========+==========================================================+ 414 | ``'s'`` | String format. This is the default type for strings and | 415 | | may be omitted. | 416 +---------+----------------------------------------------------------+ 417 | None | The same as ``'s'``. | 418 +---------+----------------------------------------------------------+ 419 420 The available integer presentation types are: 421 422 +---------+----------------------------------------------------------+ 423 | Type | Meaning | 424 +=========+==========================================================+ 425 | ``'b'`` | Binary format. Outputs the number in base 2. | 426 +---------+----------------------------------------------------------+ 427 | ``'c'`` | Character. Converts the integer to the corresponding | 428 | | unicode character before printing. | 429 +---------+----------------------------------------------------------+ 430 | ``'d'`` | Decimal Integer. Outputs the number in base 10. | 431 +---------+----------------------------------------------------------+ 432 | ``'o'`` | Octal format. Outputs the number in base 8. | 433 +---------+----------------------------------------------------------+ 434 | ``'x'`` | Hex format. Outputs the number in base 16, using lower- | 435 | | case letters for the digits above 9. | 436 +---------+----------------------------------------------------------+ 437 | ``'X'`` | Hex format. Outputs the number in base 16, using upper- | 438 | | case letters for the digits above 9. | 439 +---------+----------------------------------------------------------+ 440 | ``'n'`` | Number. This is the same as ``'d'``, except that it uses | 441 | | the current locale setting to insert the appropriate | 442 | | number separator characters. | 443 +---------+----------------------------------------------------------+ 444 | None | The same as ``'d'``. | 445 +---------+----------------------------------------------------------+ 446 447 In addition to the above presentation types, integers can be formatted 448 with the floating point presentation types listed below (except 449 ``'n'`` and ``None``). When doing so, :func:`float` is used to convert the 450 integer to a floating point number before formatting. 451 452 The available presentation types for floating point and decimal values are: 453 454 +---------+----------------------------------------------------------+ 455 | Type | Meaning | 456 +=========+==========================================================+ 457 | ``'e'`` | Exponent notation. Prints the number in scientific | 458 | | notation using the letter 'e' to indicate the exponent. | 459 | | The default precision is ``6``. | 460 +---------+----------------------------------------------------------+ 461 | ``'E'`` | Exponent notation. Same as ``'e'`` except it uses an | 462 | | upper case 'E' as the separator character. | 463 +---------+----------------------------------------------------------+ 464 | ``'f'`` | Fixed point. Displays the number as a fixed-point | 465 | | number. The default precision is ``6``. | 466 +---------+----------------------------------------------------------+ 467 | ``'F'`` | Fixed point. Same as ``'f'``, but converts ``nan`` to | 468 | | ``NAN`` and ``inf`` to ``INF``. | 469 +---------+----------------------------------------------------------+ 470 | ``'g'`` | General format. For a given precision ``p >= 1``, | 471 | | this rounds the number to ``p`` significant digits and | 472 | | then formats the result in either fixed-point format | 473 | | or in scientific notation, depending on its magnitude. | 474 | | | 475 | | The precise rules are as follows: suppose that the | 476 | | result formatted with presentation type ``'e'`` and | 477 | | precision ``p-1`` would have exponent ``exp``. Then | 478 | | if ``-4 <= exp < p``, the number is formatted | 479 | | with presentation type ``'f'`` and precision | 480 | | ``p-1-exp``. Otherwise, the number is formatted | 481 | | with presentation type ``'e'`` and precision ``p-1``. | 482 | | In both cases insignificant trailing zeros are removed | 483 | | from the significand, and the decimal point is also | 484 | | removed if there are no remaining digits following it. | 485 | | | 486 | | Positive and negative infinity, positive and negative | 487 | | zero, and nans, are formatted as ``inf``, ``-inf``, | 488 | | ``0``, ``-0`` and ``nan`` respectively, regardless of | 489 | | the precision. | 490 | | | 491 | | A precision of ``0`` is treated as equivalent to a | 492 | | precision of ``1``. The default precision is ``6``. | 493 +---------+----------------------------------------------------------+ 494 | ``'G'`` | General format. Same as ``'g'`` except switches to | 495 | | ``'E'`` if the number gets too large. The | 496 | | representations of infinity and NaN are uppercased, too. | 497 +---------+----------------------------------------------------------+ 498 | ``'n'`` | Number. This is the same as ``'g'``, except that it uses | 499 | | the current locale setting to insert the appropriate | 500 | | number separator characters. | 501 +---------+----------------------------------------------------------+ 502 | ``'%'`` | Percentage. Multiplies the number by 100 and displays | 503 | | in fixed (``'f'``) format, followed by a percent sign. | 504 +---------+----------------------------------------------------------+ 505 | None | Similar to ``'g'``, except that fixed-point notation, | 506 | | when used, has at least one digit past the decimal point.| 507 | | The default precision is as high as needed to represent | 508 | | the particular value. The overall effect is to match the | 509 | | output of :func:`str` as altered by the other format | 510 | | modifiers. | 511 +---------+----------------------------------------------------------+ 512 513 514 .. _formatexamples: 515 516 Format examples 517 ^^^^^^^^^^^^^^^ 518 519 This section contains examples of the :meth:`str.format` syntax and 520 comparison with the old ``%``-formatting. 521 522 In most of the cases the syntax is similar to the old ``%``-formatting, with the 523 addition of the ``{}`` and with ``:`` used instead of ``%``. 524 For example, ``'%03.2f'`` can be translated to ``'{:03.2f}'``. 525 526 The new format syntax also supports new and different options, shown in the 527 follow examples. 528 529 Accessing arguments by position:: 530 531 >>> '{0}, {1}, {2}'.format('a', 'b', 'c') 532 'a, b, c' 533 >>> '{}, {}, {}'.format('a', 'b', 'c') # 3.1+ only 534 'a, b, c' 535 >>> '{2}, {1}, {0}'.format('a', 'b', 'c') 536 'c, b, a' 537 >>> '{2}, {1}, {0}'.format(*'abc') # unpacking argument sequence 538 'c, b, a' 539 >>> '{0}{1}{0}'.format('abra', 'cad') # arguments' indices can be repeated 540 'abracadabra' 541 542 Accessing arguments by name:: 543 544 >>> 'Coordinates: {latitude}, {longitude}'.format(latitude='37.24N', longitude='-115.81W') 545 'Coordinates: 37.24N, -115.81W' 546 >>> coord = {'latitude': '37.24N', 'longitude': '-115.81W'} 547 >>> 'Coordinates: {latitude}, {longitude}'.format(**coord) 548 'Coordinates: 37.24N, -115.81W' 549 550 Accessing arguments' attributes:: 551 552 >>> c = 3-5j 553 >>> ('The complex number {0} is formed from the real part {0.real} ' 554 ... 'and the imaginary part {0.imag}.').format(c) 555 'The complex number (3-5j) is formed from the real part 3.0 and the imaginary part -5.0.' 556 >>> class Point: 557 ... def __init__(self, x, y): 558 ... self.x, self.y = x, y 559 ... def __str__(self): 560 ... return 'Point({self.x}, {self.y})'.format(self=self) 561 ... 562 >>> str(Point(4, 2)) 563 'Point(4, 2)' 564 565 Accessing arguments' items:: 566 567 >>> coord = (3, 5) 568 >>> 'X: {0[0]}; Y: {0[1]}'.format(coord) 569 'X: 3; Y: 5' 570 571 Replacing ``%s`` and ``%r``:: 572 573 >>> "repr() shows quotes: {!r}; str() doesn't: {!s}".format('test1', 'test2') 574 "repr() shows quotes: 'test1'; str() doesn't: test2" 575 576 Aligning the text and specifying a width:: 577 578 >>> '{:<30}'.format('left aligned') 579 'left aligned ' 580 >>> '{:>30}'.format('right aligned') 581 ' right aligned' 582 >>> '{:^30}'.format('centered') 583 ' centered ' 584 >>> '{:*^30}'.format('centered') # use '*' as a fill char 585 '***********centered***********' 586 587 Replacing ``%+f``, ``%-f``, and ``% f`` and specifying a sign:: 588 589 >>> '{:+f}; {:+f}'.format(3.14, -3.14) # show it always 590 '+3.140000; -3.140000' 591 >>> '{: f}; {: f}'.format(3.14, -3.14) # show a space for positive numbers 592 ' 3.140000; -3.140000' 593 >>> '{:-f}; {:-f}'.format(3.14, -3.14) # show only the minus -- same as '{:f}; {:f}' 594 '3.140000; -3.140000' 595 596 Replacing ``%x`` and ``%o`` and converting the value to different bases:: 597 598 >>> # format also supports binary numbers 599 >>> "int: {0:d}; hex: {0:x}; oct: {0:o}; bin: {0:b}".format(42) 600 'int: 42; hex: 2a; oct: 52; bin: 101010' 601 >>> # with 0x, 0o, or 0b as prefix: 602 >>> "int: {0:d}; hex: {0:#x}; oct: {0:#o}; bin: {0:#b}".format(42) 603 'int: 42; hex: 0x2a; oct: 0o52; bin: 0b101010' 604 605 Using the comma as a thousands separator:: 606 607 >>> '{:,}'.format(1234567890) 608 '1,234,567,890' 609 610 Expressing a percentage:: 611 612 >>> points = 19 613 >>> total = 22 614 >>> 'Correct answers: {:.2%}'.format(points/total) 615 'Correct answers: 86.36%' 616 617 Using type-specific formatting:: 618 619 >>> import datetime 620 >>> d = datetime.datetime(2010, 7, 4, 12, 15, 58) 621 >>> '{:%Y-%m-%d %H:%M:%S}'.format(d) 622 '2010-07-04 12:15:58' 623 624 Nesting arguments and more complex examples:: 625 626 >>> for align, text in zip('<^>', ['left', 'center', 'right']): 627 ... '{0:{fill}{align}16}'.format(text, fill=align, align=align) 628 ... 629 'left<<<<<<<<<<<<' 630 '^^^^^center^^^^^' 631 '>>>>>>>>>>>right' 632 >>> 633 >>> octets = [192, 168, 0, 1] 634 >>> '{:02X}{:02X}{:02X}{:02X}'.format(*octets) 635 'C0A80001' 636 >>> int(_, 16) 637 3232235521 638 >>> 639 >>> width = 5 640 >>> for num in range(5,12): #doctest: +NORMALIZE_WHITESPACE 641 ... for base in 'dXob': 642 ... print('{0:{width}{base}}'.format(num, base=base, width=width), end=' ') 643 ... print() 644 ... 645 5 5 5 101 646 6 6 6 110 647 7 7 7 111 648 8 8 10 1000 649 9 9 11 1001 650 10 A 12 1010 651 11 B 13 1011 652 653 654 655 .. _template-strings: 656 657 Template strings 658 ---------------- 659 660 Templates provide simpler string substitutions as described in :pep:`292`. 661 Instead of the normal ``%``\ -based substitutions, Templates support ``$``\ 662 -based substitutions, using the following rules: 663 664 * ``$$`` is an escape; it is replaced with a single ``$``. 665 666 * ``$identifier`` names a substitution placeholder matching a mapping key of 667 ``"identifier"``. By default, ``"identifier"`` is restricted to any 668 case-insensitive ASCII alphanumeric string (including underscores) that 669 starts with an underscore or ASCII letter. The first non-identifier 670 character after the ``$`` character terminates this placeholder 671 specification. 672 673 * ``${identifier}`` is equivalent to ``$identifier``. It is required when 674 valid identifier characters follow the placeholder but are not part of the 675 placeholder, such as ``"${noun}ification"``. 676 677 Any other appearance of ``$`` in the string will result in a :exc:`ValueError` 678 being raised. 679 680 The :mod:`string` module provides a :class:`Template` class that implements 681 these rules. The methods of :class:`Template` are: 682 683 684 .. class:: Template(template) 685 686 The constructor takes a single argument which is the template string. 687 688 689 .. method:: substitute(mapping, **kwds) 690 691 Performs the template substitution, returning a new string. *mapping* is 692 any dictionary-like object with keys that match the placeholders in the 693 template. Alternatively, you can provide keyword arguments, where the 694 keywords are the placeholders. When both *mapping* and *kwds* are given 695 and there are duplicates, the placeholders from *kwds* take precedence. 696 697 698 .. method:: safe_substitute(mapping, **kwds) 699 700 Like :meth:`substitute`, except that if placeholders are missing from 701 *mapping* and *kwds*, instead of raising a :exc:`KeyError` exception, the 702 original placeholder will appear in the resulting string intact. Also, 703 unlike with :meth:`substitute`, any other appearances of the ``$`` will 704 simply return ``$`` instead of raising :exc:`ValueError`. 705 706 While other exceptions may still occur, this method is called "safe" 707 because substitutions always tries to return a usable string instead of 708 raising an exception. In another sense, :meth:`safe_substitute` may be 709 anything other than safe, since it will silently ignore malformed 710 templates containing dangling delimiters, unmatched braces, or 711 placeholders that are not valid Python identifiers. 712 713 :class:`Template` instances also provide one public data attribute: 714 715 .. attribute:: template 716 717 This is the object passed to the constructor's *template* argument. In 718 general, you shouldn't change it, but read-only access is not enforced. 719 720 Here is an example of how to use a Template:: 721 722 >>> from string import Template 723 >>> s = Template('$who likes $what') 724 >>> s.substitute(who='tim', what='kung pao') 725 'tim likes kung pao' 726 >>> d = dict(who='tim') 727 >>> Template('Give $who $100').substitute(d) 728 Traceback (most recent call last): 729 ... 730 ValueError: Invalid placeholder in string: line 1, col 11 731 >>> Template('$who likes $what').substitute(d) 732 Traceback (most recent call last): 733 ... 734 KeyError: 'what' 735 >>> Template('$who likes $what').safe_substitute(d) 736 'tim likes $what' 737 738 Advanced usage: you can derive subclasses of :class:`Template` to customize the 739 placeholder syntax, delimiter character, or the entire regular expression used 740 to parse template strings. To do this, you can override these class attributes: 741 742 * *delimiter* -- This is the literal string describing a placeholder introducing 743 delimiter. The default value is ``$``. Note that this should *not* be a 744 regular expression, as the implementation will call :meth:`re.escape` on this 745 string as needed. 746 747 * *idpattern* -- This is the regular expression describing the pattern for 748 non-braced placeholders (the braces will be added automatically as 749 appropriate). The default value is the regular expression 750 ``[_a-z][_a-z0-9]*``. 751 752 * *flags* -- The regular expression flags that will be applied when compiling 753 the regular expression used for recognizing substitutions. The default value 754 is ``re.IGNORECASE``. Note that ``re.VERBOSE`` will always be added to the 755 flags, so custom *idpattern*\ s must follow conventions for verbose regular 756 expressions. 757 758 .. versionadded:: 3.2 759 760 Alternatively, you can provide the entire regular expression pattern by 761 overriding the class attribute *pattern*. If you do this, the value must be a 762 regular expression object with four named capturing groups. The capturing 763 groups correspond to the rules given above, along with the invalid placeholder 764 rule: 765 766 * *escaped* -- This group matches the escape sequence, e.g. ``$$``, in the 767 default pattern. 768 769 * *named* -- This group matches the unbraced placeholder name; it should not 770 include the delimiter in capturing group. 771 772 * *braced* -- This group matches the brace enclosed placeholder name; it should 773 not include either the delimiter or braces in the capturing group. 774 775 * *invalid* -- This group matches any other delimiter pattern (usually a single 776 delimiter), and it should appear last in the regular expression. 777 778 779 Helper functions 780 ---------------- 781 782 .. function:: capwords(s, sep=None) 783 784 Split the argument into words using :meth:`str.split`, capitalize each word 785 using :meth:`str.capitalize`, and join the capitalized words using 786 :meth:`str.join`. If the optional second argument *sep* is absent 787 or ``None``, runs of whitespace characters are replaced by a single space 788 and leading and trailing whitespace are removed, otherwise *sep* is used to 789 split and join the words. 790 791
