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 .. versionchanged:: 3.7 99 A format string argument is now :ref:`positional-only 100 <positional-only_parameter>`. 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 .. index:: 196 single: {} (curly brackets); in string formatting 197 single: . (dot); in string formatting 198 single: [] (square brackets); in string formatting 199 single: ! (exclamation); in string formatting 200 single: : (colon); in string formatting 201 202 Format strings contain "replacement fields" surrounded by curly braces ``{}``. 203 Anything that is not contained in braces is considered literal text, which is 204 copied unchanged to the output. If you need to include a brace character in the 205 literal text, it can be escaped by doubling: ``{{`` and ``}}``. 206 207 The grammar for a replacement field is as follows: 208 209 .. productionlist:: sf 210 replacement_field: "{" [`field_name`] ["!" `conversion`] [":" `format_spec`] "}" 211 field_name: arg_name ("." `attribute_name` | "[" `element_index` "]")* 212 arg_name: [`identifier` | `digit`+] 213 attribute_name: `identifier` 214 element_index: `digit`+ | `index_string` 215 index_string: <any source character except "]"> + 216 conversion: "r" | "s" | "a" 217 format_spec: <described in the next section> 218 219 In less formal terms, the replacement field can start with a *field_name* that specifies 220 the object whose value is to be formatted and inserted 221 into the output instead of the replacement field. 222 The *field_name* is optionally followed by a *conversion* field, which is 223 preceded by an exclamation point ``'!'``, and a *format_spec*, which is preceded 224 by a colon ``':'``. These specify a non-default format for the replacement value. 225 226 See also the :ref:`formatspec` section. 227 228 The *field_name* itself begins with an *arg_name* that is either a number or a 229 keyword. If it's a number, it refers to a positional argument, and if it's a keyword, 230 it refers to a named keyword argument. If the numerical arg_names in a format string 231 are 0, 1, 2, ... in sequence, they can all be omitted (not just some) 232 and the numbers 0, 1, 2, ... will be automatically inserted in that order. 233 Because *arg_name* is not quote-delimited, it is not possible to specify arbitrary 234 dictionary keys (e.g., the strings ``'10'`` or ``':-]'``) within a format string. 235 The *arg_name* can be followed by any number of index or 236 attribute expressions. An expression of the form ``'.name'`` selects the named 237 attribute using :func:`getattr`, while an expression of the form ``'[index]'`` 238 does an index lookup using :func:`__getitem__`. 239 240 .. versionchanged:: 3.1 241 The positional argument specifiers can be omitted for :meth:`str.format`, 242 so ``'{} {}'.format(a, b)`` is equivalent to ``'{0} {1}'.format(a, b)``. 243 244 .. versionchanged:: 3.4 245 The positional argument specifiers can be omitted for :class:`Formatter`. 246 247 Some simple format string examples:: 248 249 "First, thou shalt count to {0}" # References first positional argument 250 "Bring me a {}" # Implicitly references the first positional argument 251 "From {} to {}" # Same as "From {0} to {1}" 252 "My quest is {name}" # References keyword argument 'name' 253 "Weight in tons {0.weight}" # 'weight' attribute of first positional arg 254 "Units destroyed: {players[0]}" # First element of keyword argument 'players'. 255 256 The *conversion* field causes a type coercion before formatting. Normally, the 257 job of formatting a value is done by the :meth:`__format__` method of the value 258 itself. However, in some cases it is desirable to force a type to be formatted 259 as a string, overriding its own definition of formatting. By converting the 260 value to a string before calling :meth:`__format__`, the normal formatting logic 261 is bypassed. 262 263 Three conversion flags are currently supported: ``'!s'`` which calls :func:`str` 264 on the value, ``'!r'`` which calls :func:`repr` and ``'!a'`` which calls 265 :func:`ascii`. 266 267 Some examples:: 268 269 "Harold's a clever {0!s}" # Calls str() on the argument first 270 "Bring out the holy {name!r}" # Calls repr() on the argument first 271 "More {!a}" # Calls ascii() on the argument first 272 273 The *format_spec* field contains a specification of how the value should be 274 presented, including such details as field width, alignment, padding, decimal 275 precision and so on. Each value type can define its own "formatting 276 mini-language" or interpretation of the *format_spec*. 277 278 Most built-in types support a common formatting mini-language, which is 279 described in the next section. 280 281 A *format_spec* field can also include nested replacement fields within it. 282 These nested replacement fields may contain a field name, conversion flag 283 and format specification, but deeper nesting is 284 not allowed. The replacement fields within the 285 format_spec are substituted before the *format_spec* string is interpreted. 286 This allows the formatting of a value to be dynamically specified. 287 288 See the :ref:`formatexamples` section for some examples. 289 290 291 .. _formatspec: 292 293 Format Specification Mini-Language 294 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 295 296 "Format specifications" are used within replacement fields contained within a 297 format string to define how individual values are presented (see 298 :ref:`formatstrings` and :ref:`f-strings`). 299 They can also be passed directly to the built-in 300 :func:`format` function. Each formattable type may define how the format 301 specification is to be interpreted. 302 303 Most built-in types implement the following options for format specifications, 304 although some of the formatting options are only supported by the numeric types. 305 306 A general convention is that an empty format string (``""``) produces 307 the same result as if you had called :func:`str` on the value. A 308 non-empty format string typically modifies the result. 309 310 The general form of a *standard format specifier* is: 311 312 .. productionlist:: sf 313 format_spec: [[`fill`]`align`][`sign`][#][0][`width`][`grouping_option`][.`precision`][`type`] 314 fill: <any character> 315 align: "<" | ">" | "=" | "^" 316 sign: "+" | "-" | " " 317 width: `digit`+ 318 grouping_option: "_" | "," 319 precision: `digit`+ 320 type: "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%" 321 322 If a valid *align* value is specified, it can be preceded by a *fill* 323 character that can be any character and defaults to a space if omitted. 324 It is not possible to use a literal curly brace ("``{``" or "``}``") as 325 the *fill* character in a :ref:`formatted string literal 326 <f-strings>` or when using the :meth:`str.format` 327 method. However, it is possible to insert a curly brace 328 with a nested replacement field. This limitation doesn't 329 affect the :func:`format` function. 330 331 The meaning of the various alignment options is as follows: 332 333 .. index:: 334 single: < (less); in string formatting 335 single: > (greater); in string formatting 336 single: = (equals); in string formatting 337 single: ^ (caret); in string formatting 338 339 +---------+----------------------------------------------------------+ 340 | Option | Meaning | 341 +=========+==========================================================+ 342 | ``'<'`` | Forces the field to be left-aligned within the available | 343 | | space (this is the default for most objects). | 344 +---------+----------------------------------------------------------+ 345 | ``'>'`` | Forces the field to be right-aligned within the | 346 | | available space (this is the default for numbers). | 347 +---------+----------------------------------------------------------+ 348 | ``'='`` | Forces the padding to be placed after the sign (if any) | 349 | | but before the digits. This is used for printing fields | 350 | | in the form '+000000120'. This alignment option is only | 351 | | valid for numeric types. It becomes the default when '0'| 352 | | immediately precedes the field width. | 353 +---------+----------------------------------------------------------+ 354 | ``'^'`` | Forces the field to be centered within the available | 355 | | space. | 356 +---------+----------------------------------------------------------+ 357 358 Note that unless a minimum field width is defined, the field width will always 359 be the same size as the data to fill it, so that the alignment option has no 360 meaning in this case. 361 362 The *sign* option is only valid for number types, and can be one of the 363 following: 364 365 .. index:: 366 single: + (plus); in string formatting 367 single: - (minus); in string formatting 368 single: space; in string formatting 369 370 +---------+----------------------------------------------------------+ 371 | Option | Meaning | 372 +=========+==========================================================+ 373 | ``'+'`` | indicates that a sign should be used for both | 374 | | positive as well as negative numbers. | 375 +---------+----------------------------------------------------------+ 376 | ``'-'`` | indicates that a sign should be used only for negative | 377 | | numbers (this is the default behavior). | 378 +---------+----------------------------------------------------------+ 379 | space | indicates that a leading space should be used on | 380 | | positive numbers, and a minus sign on negative numbers. | 381 +---------+----------------------------------------------------------+ 382 383 384 .. index:: single: # (hash); in string formatting 385 386 The ``'#'`` option causes the "alternate form" to be used for the 387 conversion. The alternate form is defined differently for different 388 types. This option is only valid for integer, float, complex and 389 Decimal types. For integers, when binary, octal, or hexadecimal output 390 is used, this option adds the prefix respective ``'0b'``, ``'0o'``, or 391 ``'0x'`` to the output value. For floats, complex and Decimal the 392 alternate form causes the result of the conversion to always contain a 393 decimal-point character, even if no digits follow it. Normally, a 394 decimal-point character appears in the result of these conversions 395 only if a digit follows it. In addition, for ``'g'`` and ``'G'`` 396 conversions, trailing zeros are not removed from the result. 397 398 .. index:: single: , (comma); in string formatting 399 400 The ``','`` option signals the use of a comma for a thousands separator. 401 For a locale aware separator, use the ``'n'`` integer presentation type 402 instead. 403 404 .. versionchanged:: 3.1 405 Added the ``','`` option (see also :pep:`378`). 406 407 .. index:: single: _ (underscore); in string formatting 408 409 The ``'_'`` option signals the use of an underscore for a thousands 410 separator for floating point presentation types and for integer 411 presentation type ``'d'``. For integer presentation types ``'b'``, 412 ``'o'``, ``'x'``, and ``'X'``, underscores will be inserted every 4 413 digits. For other presentation types, specifying this option is an 414 error. 415 416 .. versionchanged:: 3.6 417 Added the ``'_'`` option (see also :pep:`515`). 418 419 *width* is a decimal integer defining the minimum field width. If not 420 specified, then the field width will be determined by the content. 421 422 When no explicit alignment is given, preceding the *width* field by a zero 423 (``'0'``) character enables 424 sign-aware zero-padding for numeric types. This is equivalent to a *fill* 425 character of ``'0'`` with an *alignment* type of ``'='``. 426 427 The *precision* is a decimal number indicating how many digits should be 428 displayed after the decimal point for a floating point value formatted with 429 ``'f'`` and ``'F'``, or before and after the decimal point for a floating point 430 value formatted with ``'g'`` or ``'G'``. For non-number types the field 431 indicates the maximum field size - in other words, how many characters will be 432 used from the field content. The *precision* is not allowed for integer values. 433 434 Finally, the *type* determines how the data should be presented. 435 436 The available string presentation types are: 437 438 +---------+----------------------------------------------------------+ 439 | Type | Meaning | 440 +=========+==========================================================+ 441 | ``'s'`` | String format. This is the default type for strings and | 442 | | may be omitted. | 443 +---------+----------------------------------------------------------+ 444 | None | The same as ``'s'``. | 445 +---------+----------------------------------------------------------+ 446 447 The available integer presentation types are: 448 449 +---------+----------------------------------------------------------+ 450 | Type | Meaning | 451 +=========+==========================================================+ 452 | ``'b'`` | Binary format. Outputs the number in base 2. | 453 +---------+----------------------------------------------------------+ 454 | ``'c'`` | Character. Converts the integer to the corresponding | 455 | | unicode character before printing. | 456 +---------+----------------------------------------------------------+ 457 | ``'d'`` | Decimal Integer. Outputs the number in base 10. | 458 +---------+----------------------------------------------------------+ 459 | ``'o'`` | Octal format. Outputs the number in base 8. | 460 +---------+----------------------------------------------------------+ 461 | ``'x'`` | Hex format. Outputs the number in base 16, using | 462 | | lower-case letters for the digits above 9. | 463 +---------+----------------------------------------------------------+ 464 | ``'X'`` | Hex format. Outputs the number in base 16, using | 465 | | upper-case letters for the digits above 9. | 466 +---------+----------------------------------------------------------+ 467 | ``'n'`` | Number. This is the same as ``'d'``, except that it uses | 468 | | the current locale setting to insert the appropriate | 469 | | number separator characters. | 470 +---------+----------------------------------------------------------+ 471 | None | The same as ``'d'``. | 472 +---------+----------------------------------------------------------+ 473 474 In addition to the above presentation types, integers can be formatted 475 with the floating point presentation types listed below (except 476 ``'n'`` and ``None``). When doing so, :func:`float` is used to convert the 477 integer to a floating point number before formatting. 478 479 The available presentation types for floating point and decimal values are: 480 481 +---------+----------------------------------------------------------+ 482 | Type | Meaning | 483 +=========+==========================================================+ 484 | ``'e'`` | Exponent notation. Prints the number in scientific | 485 | | notation using the letter 'e' to indicate the exponent. | 486 | | The default precision is ``6``. | 487 +---------+----------------------------------------------------------+ 488 | ``'E'`` | Exponent notation. Same as ``'e'`` except it uses an | 489 | | upper case 'E' as the separator character. | 490 +---------+----------------------------------------------------------+ 491 | ``'f'`` | Fixed-point notation. Displays the number as a | 492 | | fixed-point number. The default precision is ``6``. | 493 +---------+----------------------------------------------------------+ 494 | ``'F'`` | Fixed-point notation. Same as ``'f'``, but converts | 495 | | ``nan`` to ``NAN`` and ``inf`` to ``INF``. | 496 +---------+----------------------------------------------------------+ 497 | ``'g'`` | General format. For a given precision ``p >= 1``, | 498 | | this rounds the number to ``p`` significant digits and | 499 | | then formats the result in either fixed-point format | 500 | | or in scientific notation, depending on its magnitude. | 501 | | | 502 | | The precise rules are as follows: suppose that the | 503 | | result formatted with presentation type ``'e'`` and | 504 | | precision ``p-1`` would have exponent ``exp``. Then | 505 | | if ``-4 <= exp < p``, the number is formatted | 506 | | with presentation type ``'f'`` and precision | 507 | | ``p-1-exp``. Otherwise, the number is formatted | 508 | | with presentation type ``'e'`` and precision ``p-1``. | 509 | | In both cases insignificant trailing zeros are removed | 510 | | from the significand, and the decimal point is also | 511 | | removed if there are no remaining digits following it. | 512 | | | 513 | | Positive and negative infinity, positive and negative | 514 | | zero, and nans, are formatted as ``inf``, ``-inf``, | 515 | | ``0``, ``-0`` and ``nan`` respectively, regardless of | 516 | | the precision. | 517 | | | 518 | | A precision of ``0`` is treated as equivalent to a | 519 | | precision of ``1``. The default precision is ``6``. | 520 +---------+----------------------------------------------------------+ 521 | ``'G'`` | General format. Same as ``'g'`` except switches to | 522 | | ``'E'`` if the number gets too large. The | 523 | | representations of infinity and NaN are uppercased, too. | 524 +---------+----------------------------------------------------------+ 525 | ``'n'`` | Number. This is the same as ``'g'``, except that it uses | 526 | | the current locale setting to insert the appropriate | 527 | | number separator characters. | 528 +---------+----------------------------------------------------------+ 529 | ``'%'`` | Percentage. Multiplies the number by 100 and displays | 530 | | in fixed (``'f'``) format, followed by a percent sign. | 531 +---------+----------------------------------------------------------+ 532 | None | Similar to ``'g'``, except that fixed-point notation, | 533 | | when used, has at least one digit past the decimal point.| 534 | | The default precision is as high as needed to represent | 535 | | the particular value. The overall effect is to match the | 536 | | output of :func:`str` as altered by the other format | 537 | | modifiers. | 538 +---------+----------------------------------------------------------+ 539 540 541 .. _formatexamples: 542 543 Format examples 544 ^^^^^^^^^^^^^^^ 545 546 This section contains examples of the :meth:`str.format` syntax and 547 comparison with the old ``%``-formatting. 548 549 In most of the cases the syntax is similar to the old ``%``-formatting, with the 550 addition of the ``{}`` and with ``:`` used instead of ``%``. 551 For example, ``'%03.2f'`` can be translated to ``'{:03.2f}'``. 552 553 The new format syntax also supports new and different options, shown in the 554 following examples. 555 556 Accessing arguments by position:: 557 558 >>> '{0}, {1}, {2}'.format('a', 'b', 'c') 559 'a, b, c' 560 >>> '{}, {}, {}'.format('a', 'b', 'c') # 3.1+ only 561 'a, b, c' 562 >>> '{2}, {1}, {0}'.format('a', 'b', 'c') 563 'c, b, a' 564 >>> '{2}, {1}, {0}'.format(*'abc') # unpacking argument sequence 565 'c, b, a' 566 >>> '{0}{1}{0}'.format('abra', 'cad') # arguments' indices can be repeated 567 'abracadabra' 568 569 Accessing arguments by name:: 570 571 >>> 'Coordinates: {latitude}, {longitude}'.format(latitude='37.24N', longitude='-115.81W') 572 'Coordinates: 37.24N, -115.81W' 573 >>> coord = {'latitude': '37.24N', 'longitude': '-115.81W'} 574 >>> 'Coordinates: {latitude}, {longitude}'.format(**coord) 575 'Coordinates: 37.24N, -115.81W' 576 577 Accessing arguments' attributes:: 578 579 >>> c = 3-5j 580 >>> ('The complex number {0} is formed from the real part {0.real} ' 581 ... 'and the imaginary part {0.imag}.').format(c) 582 'The complex number (3-5j) is formed from the real part 3.0 and the imaginary part -5.0.' 583 >>> class Point: 584 ... def __init__(self, x, y): 585 ... self.x, self.y = x, y 586 ... def __str__(self): 587 ... return 'Point({self.x}, {self.y})'.format(self=self) 588 ... 589 >>> str(Point(4, 2)) 590 'Point(4, 2)' 591 592 Accessing arguments' items:: 593 594 >>> coord = (3, 5) 595 >>> 'X: {0[0]}; Y: {0[1]}'.format(coord) 596 'X: 3; Y: 5' 597 598 Replacing ``%s`` and ``%r``:: 599 600 >>> "repr() shows quotes: {!r}; str() doesn't: {!s}".format('test1', 'test2') 601 "repr() shows quotes: 'test1'; str() doesn't: test2" 602 603 Aligning the text and specifying a width:: 604 605 >>> '{:<30}'.format('left aligned') 606 'left aligned ' 607 >>> '{:>30}'.format('right aligned') 608 ' right aligned' 609 >>> '{:^30}'.format('centered') 610 ' centered ' 611 >>> '{:*^30}'.format('centered') # use '*' as a fill char 612 '***********centered***********' 613 614 Replacing ``%+f``, ``%-f``, and ``% f`` and specifying a sign:: 615 616 >>> '{:+f}; {:+f}'.format(3.14, -3.14) # show it always 617 '+3.140000; -3.140000' 618 >>> '{: f}; {: f}'.format(3.14, -3.14) # show a space for positive numbers 619 ' 3.140000; -3.140000' 620 >>> '{:-f}; {:-f}'.format(3.14, -3.14) # show only the minus -- same as '{:f}; {:f}' 621 '3.140000; -3.140000' 622 623 Replacing ``%x`` and ``%o`` and converting the value to different bases:: 624 625 >>> # format also supports binary numbers 626 >>> "int: {0:d}; hex: {0:x}; oct: {0:o}; bin: {0:b}".format(42) 627 'int: 42; hex: 2a; oct: 52; bin: 101010' 628 >>> # with 0x, 0o, or 0b as prefix: 629 >>> "int: {0:d}; hex: {0:#x}; oct: {0:#o}; bin: {0:#b}".format(42) 630 'int: 42; hex: 0x2a; oct: 0o52; bin: 0b101010' 631 632 Using the comma as a thousands separator:: 633 634 >>> '{:,}'.format(1234567890) 635 '1,234,567,890' 636 637 Expressing a percentage:: 638 639 >>> points = 19 640 >>> total = 22 641 >>> 'Correct answers: {:.2%}'.format(points/total) 642 'Correct answers: 86.36%' 643 644 Using type-specific formatting:: 645 646 >>> import datetime 647 >>> d = datetime.datetime(2010, 7, 4, 12, 15, 58) 648 >>> '{:%Y-%m-%d %H:%M:%S}'.format(d) 649 '2010-07-04 12:15:58' 650 651 Nesting arguments and more complex examples:: 652 653 >>> for align, text in zip('<^>', ['left', 'center', 'right']): 654 ... '{0:{fill}{align}16}'.format(text, fill=align, align=align) 655 ... 656 'left<<<<<<<<<<<<' 657 '^^^^^center^^^^^' 658 '>>>>>>>>>>>right' 659 >>> 660 >>> octets = [192, 168, 0, 1] 661 >>> '{:02X}{:02X}{:02X}{:02X}'.format(*octets) 662 'C0A80001' 663 >>> int(_, 16) 664 3232235521 665 >>> 666 >>> width = 5 667 >>> for num in range(5,12): #doctest: +NORMALIZE_WHITESPACE 668 ... for base in 'dXob': 669 ... print('{0:{width}{base}}'.format(num, base=base, width=width), end=' ') 670 ... print() 671 ... 672 5 5 5 101 673 6 6 6 110 674 7 7 7 111 675 8 8 10 1000 676 9 9 11 1001 677 10 A 12 1010 678 11 B 13 1011 679 680 681 682 .. _template-strings: 683 684 Template strings 685 ---------------- 686 687 Template strings provide simpler string substitutions as described in 688 :pep:`292`. A primary use case for template strings is for 689 internationalization (i18n) since in that context, the simpler syntax and 690 functionality makes it easier to translate than other built-in string 691 formatting facilities in Python. As an example of a library built on template 692 strings for i18n, see the 693 `flufl.i18n <http://flufli18n.readthedocs.io/en/latest/>`_ package. 694 695 .. index:: single: $ (dollar); in template strings 696 697 Template strings support ``$``-based substitutions, using the following rules: 698 699 * ``$$`` is an escape; it is replaced with a single ``$``. 700 701 * ``$identifier`` names a substitution placeholder matching a mapping key of 702 ``"identifier"``. By default, ``"identifier"`` is restricted to any 703 case-insensitive ASCII alphanumeric string (including underscores) that 704 starts with an underscore or ASCII letter. The first non-identifier 705 character after the ``$`` character terminates this placeholder 706 specification. 707 708 * ``${identifier}`` is equivalent to ``$identifier``. It is required when 709 valid identifier characters follow the placeholder but are not part of the 710 placeholder, such as ``"${noun}ification"``. 711 712 Any other appearance of ``$`` in the string will result in a :exc:`ValueError` 713 being raised. 714 715 The :mod:`string` module provides a :class:`Template` class that implements 716 these rules. The methods of :class:`Template` are: 717 718 719 .. class:: Template(template) 720 721 The constructor takes a single argument which is the template string. 722 723 724 .. method:: substitute(mapping, **kwds) 725 726 Performs the template substitution, returning a new string. *mapping* is 727 any dictionary-like object with keys that match the placeholders in the 728 template. Alternatively, you can provide keyword arguments, where the 729 keywords are the placeholders. When both *mapping* and *kwds* are given 730 and there are duplicates, the placeholders from *kwds* take precedence. 731 732 733 .. method:: safe_substitute(mapping, **kwds) 734 735 Like :meth:`substitute`, except that if placeholders are missing from 736 *mapping* and *kwds*, instead of raising a :exc:`KeyError` exception, the 737 original placeholder will appear in the resulting string intact. Also, 738 unlike with :meth:`substitute`, any other appearances of the ``$`` will 739 simply return ``$`` instead of raising :exc:`ValueError`. 740 741 While other exceptions may still occur, this method is called "safe" 742 because it always tries to return a usable string instead of 743 raising an exception. In another sense, :meth:`safe_substitute` may be 744 anything other than safe, since it will silently ignore malformed 745 templates containing dangling delimiters, unmatched braces, or 746 placeholders that are not valid Python identifiers. 747 748 :class:`Template` instances also provide one public data attribute: 749 750 .. attribute:: template 751 752 This is the object passed to the constructor's *template* argument. In 753 general, you shouldn't change it, but read-only access is not enforced. 754 755 Here is an example of how to use a Template:: 756 757 >>> from string import Template 758 >>> s = Template('$who likes $what') 759 >>> s.substitute(who='tim', what='kung pao') 760 'tim likes kung pao' 761 >>> d = dict(who='tim') 762 >>> Template('Give $who $100').substitute(d) 763 Traceback (most recent call last): 764 ... 765 ValueError: Invalid placeholder in string: line 1, col 11 766 >>> Template('$who likes $what').substitute(d) 767 Traceback (most recent call last): 768 ... 769 KeyError: 'what' 770 >>> Template('$who likes $what').safe_substitute(d) 771 'tim likes $what' 772 773 Advanced usage: you can derive subclasses of :class:`Template` to customize 774 the placeholder syntax, delimiter character, or the entire regular expression 775 used to parse template strings. To do this, you can override these class 776 attributes: 777 778 * *delimiter* -- This is the literal string describing a placeholder 779 introducing delimiter. The default value is ``$``. Note that this should 780 *not* be a regular expression, as the implementation will call 781 :meth:`re.escape` on this string as needed. Note further that you cannot 782 change the delimiter after class creation (i.e. a different delimiter must 783 be set in the subclass's class namespace). 784 785 * *idpattern* -- This is the regular expression describing the pattern for 786 non-braced placeholders. The default value is the regular expression 787 ``(?a:[_a-z][_a-z0-9]*)``. If this is given and *braceidpattern* is 788 ``None`` this pattern will also apply to braced placeholders. 789 790 .. note:: 791 792 Since default *flags* is ``re.IGNORECASE``, pattern ``[a-z]`` can match 793 with some non-ASCII characters. That's why we use the local ``a`` flag 794 here. 795 796 .. versionchanged:: 3.7 797 *braceidpattern* can be used to define separate patterns used inside and 798 outside the braces. 799 800 * *braceidpattern* -- This is like *idpattern* but describes the pattern for 801 braced placeholders. Defaults to ``None`` which means to fall back to 802 *idpattern* (i.e. the same pattern is used both inside and outside braces). 803 If given, this allows you to define different patterns for braced and 804 unbraced placeholders. 805 806 .. versionadded:: 3.7 807 808 * *flags* -- The regular expression flags that will be applied when compiling 809 the regular expression used for recognizing substitutions. The default value 810 is ``re.IGNORECASE``. Note that ``re.VERBOSE`` will always be added to the 811 flags, so custom *idpattern*\ s must follow conventions for verbose regular 812 expressions. 813 814 .. versionadded:: 3.2 815 816 Alternatively, you can provide the entire regular expression pattern by 817 overriding the class attribute *pattern*. If you do this, the value must be a 818 regular expression object with four named capturing groups. The capturing 819 groups correspond to the rules given above, along with the invalid placeholder 820 rule: 821 822 * *escaped* -- This group matches the escape sequence, e.g. ``$$``, in the 823 default pattern. 824 825 * *named* -- This group matches the unbraced placeholder name; it should not 826 include the delimiter in capturing group. 827 828 * *braced* -- This group matches the brace enclosed placeholder name; it should 829 not include either the delimiter or braces in the capturing group. 830 831 * *invalid* -- This group matches any other delimiter pattern (usually a single 832 delimiter), and it should appear last in the regular expression. 833 834 835 Helper functions 836 ---------------- 837 838 .. function:: capwords(s, sep=None) 839 840 Split the argument into words using :meth:`str.split`, capitalize each word 841 using :meth:`str.capitalize`, and join the capitalized words using 842 :meth:`str.join`. If the optional second argument *sep* is absent 843 or ``None``, runs of whitespace characters are replaced by a single space 844 and leading and trailing whitespace are removed, otherwise *sep* is used to 845 split and join the words. 846
