/Doc/library/stdtypes.rst
ReStructuredText | 2723 lines | 1927 code | 796 blank | 0 comment | 0 complexity | b712e452ec171c361e2db790d841e54a MD5 | raw file
Large files files are truncated, but you can click here to view the full file
1.. XXX: reference/datamodel and this have quite a few overlaps! 2 3 4.. _bltin-types: 5 6************** 7Built-in Types 8************** 9 10The following sections describe the standard types that are built into the 11interpreter. 12 13.. note:: 14 15 Historically (until release 2.2), Python's built-in types have differed from 16 user-defined types because it was not possible to use the built-in types as the 17 basis for object-oriented inheritance. This limitation no longer 18 exists. 19 20.. index:: pair: built-in; types 21 22The principal built-in types are numerics, sequences, mappings, files, classes, 23instances and exceptions. 24 25.. index:: statement: print 26 27Some operations are supported by several object types; in particular, 28practically all objects can be compared, tested for truth value, and converted 29to a string (with the :func:`repr` function or the slightly different 30:func:`str` function). The latter function is implicitly used when an object is 31written by the :func:`print` function. 32 33 34.. _truth: 35 36Truth Value Testing 37=================== 38 39.. index:: 40 statement: if 41 statement: while 42 pair: truth; value 43 pair: Boolean; operations 44 single: false 45 46Any object can be tested for truth value, for use in an :keyword:`if` or 47:keyword:`while` condition or as operand of the Boolean operations below. The 48following values are considered false: 49 50 .. index:: single: None (Built-in object) 51 52* ``None`` 53 54 .. index:: single: False (Built-in object) 55 56* ``False`` 57 58* zero of any numeric type, for example, ``0``, ``0L``, ``0.0``, ``0j``. 59 60* any empty sequence, for example, ``''``, ``()``, ``[]``. 61 62* any empty mapping, for example, ``{}``. 63 64* instances of user-defined classes, if the class defines a :meth:`__nonzero__` 65 or :meth:`__len__` method, when that method returns the integer zero or 66 :class:`bool` value ``False``. [#]_ 67 68.. index:: single: true 69 70All other values are considered true --- so objects of many types are always 71true. 72 73.. index:: 74 operator: or 75 operator: and 76 single: False 77 single: True 78 79Operations and built-in functions that have a Boolean result always return ``0`` 80or ``False`` for false and ``1`` or ``True`` for true, unless otherwise stated. 81(Important exception: the Boolean operations ``or`` and ``and`` always return 82one of their operands.) 83 84 85.. _boolean: 86 87Boolean Operations --- :keyword:`and`, :keyword:`or`, :keyword:`not` 88==================================================================== 89 90.. index:: pair: Boolean; operations 91 92These are the Boolean operations, ordered by ascending priority: 93 94+-------------+---------------------------------+-------+ 95| Operation | Result | Notes | 96+=============+=================================+=======+ 97| ``x or y`` | if *x* is false, then *y*, else | \(1) | 98| | *x* | | 99+-------------+---------------------------------+-------+ 100| ``x and y`` | if *x* is false, then *x*, else | \(2) | 101| | *y* | | 102+-------------+---------------------------------+-------+ 103| ``not x`` | if *x* is false, then ``True``, | \(3) | 104| | else ``False`` | | 105+-------------+---------------------------------+-------+ 106 107.. index:: 108 operator: and 109 operator: or 110 operator: not 111 112Notes: 113 114(1) 115 This is a short-circuit operator, so it only evaluates the second 116 argument if the first one is :const:`False`. 117 118(2) 119 This is a short-circuit operator, so it only evaluates the second 120 argument if the first one is :const:`True`. 121 122(3) 123 ``not`` has a lower priority than non-Boolean operators, so ``not a == b`` is 124 interpreted as ``not (a == b)``, and ``a == not b`` is a syntax error. 125 126 127.. _stdcomparisons: 128 129Comparisons 130=========== 131 132.. index:: pair: chaining; comparisons 133 134Comparison operations are supported by all objects. They all have the same 135priority (which is higher than that of the Boolean operations). Comparisons can 136be chained arbitrarily; for example, ``x < y <= z`` is equivalent to ``x < y and 137y <= z``, except that *y* is evaluated only once (but in both cases *z* is not 138evaluated at all when ``x < y`` is found to be false). 139 140This table summarizes the comparison operations: 141 142+------------+-------------------------+-------+ 143| Operation | Meaning | Notes | 144+============+=========================+=======+ 145| ``<`` | strictly less than | | 146+------------+-------------------------+-------+ 147| ``<=`` | less than or equal | | 148+------------+-------------------------+-------+ 149| ``>`` | strictly greater than | | 150+------------+-------------------------+-------+ 151| ``>=`` | greater than or equal | | 152+------------+-------------------------+-------+ 153| ``==`` | equal | | 154+------------+-------------------------+-------+ 155| ``!=`` | not equal | \(1) | 156+------------+-------------------------+-------+ 157| ``is`` | object identity | | 158+------------+-------------------------+-------+ 159| ``is not`` | negated object identity | | 160+------------+-------------------------+-------+ 161 162.. index:: 163 pair: operator; comparison 164 operator: == 165 operator: < 166 operator: <= 167 operator: > 168 operator: >= 169 operator: != 170 operator: is 171 operator: is not 172 173Notes: 174 175(1) 176 ``!=`` can also be written ``<>``, but this is an obsolete usage 177 kept for backwards compatibility only. New code should always use 178 ``!=``. 179 180.. index:: 181 pair: object; numeric 182 pair: objects; comparing 183 184Objects of different types, except different numeric types and different string 185types, never compare equal; such objects are ordered consistently but 186arbitrarily (so that sorting a heterogeneous array yields a consistent result). 187Furthermore, some types (for example, file objects) support only a degenerate 188notion of comparison where any two objects of that type are unequal. Again, 189such objects are ordered arbitrarily but consistently. The ``<``, ``<=``, ``>`` 190and ``>=`` operators will raise a :exc:`TypeError` exception when any operand is 191a complex number. 192 193.. index:: single: __cmp__() (instance method) 194 195Instances of a class normally compare as non-equal unless the class defines the 196:meth:`__cmp__` method. Refer to :ref:`customization`) for information on the 197use of this method to effect object comparisons. 198 199**Implementation note:** Objects of different types except numbers are ordered 200by their type names; objects of the same types that don't support proper 201comparison are ordered by their address. 202 203.. index:: 204 operator: in 205 operator: not in 206 207Two more operations with the same syntactic priority, ``in`` and ``not in``, are 208supported only by sequence types (below). 209 210 211.. _typesnumeric: 212 213Numeric Types --- :class:`int`, :class:`float`, :class:`long`, :class:`complex` 214=============================================================================== 215 216.. index:: 217 object: numeric 218 object: Boolean 219 object: integer 220 object: long integer 221 object: floating point 222 object: complex number 223 pair: C; language 224 225There are four distinct numeric types: :dfn:`plain integers`, :dfn:`long 226integers`, :dfn:`floating point numbers`, and :dfn:`complex numbers`. In 227addition, Booleans are a subtype of plain integers. Plain integers (also just 228called :dfn:`integers`) are implemented using :ctype:`long` in C, which gives 229them at least 32 bits of precision (``sys.maxint`` is always set to the maximum 230plain integer value for the current platform, the minimum value is 231``-sys.maxint - 1``). Long integers have unlimited precision. Floating point 232numbers are implemented using :ctype:`double` in C. All bets on their precision 233are off unless you happen to know the machine you are working with. 234 235Complex numbers have a real and imaginary part, which are each implemented using 236:ctype:`double` in C. To extract these parts from a complex number *z*, use 237``z.real`` and ``z.imag``. 238 239.. index:: 240 pair: numeric; literals 241 pair: integer; literals 242 triple: long; integer; literals 243 pair: floating point; literals 244 pair: complex number; literals 245 pair: hexadecimal; literals 246 pair: octal; literals 247 248Numbers are created by numeric literals or as the result of built-in functions 249and operators. Unadorned integer literals (including binary, hex, and octal 250numbers) yield plain integers unless the value they denote is too large to be 251represented as a plain integer, in which case they yield a long integer. 252Integer literals with an ``'L'`` or ``'l'`` suffix yield long integers (``'L'`` 253is preferred because ``1l`` looks too much like eleven!). Numeric literals 254containing a decimal point or an exponent sign yield floating point numbers. 255Appending ``'j'`` or ``'J'`` to a numeric literal yields a complex number with a 256zero real part. A complex numeric literal is the sum of a real and an imaginary 257part. 258 259.. index:: 260 single: arithmetic 261 builtin: int 262 builtin: long 263 builtin: float 264 builtin: complex 265 266Python fully supports mixed arithmetic: when a binary arithmetic operator has 267operands of different numeric types, the operand with the "narrower" type is 268widened to that of the other, where plain integer is narrower than long integer 269is narrower than floating point is narrower than complex. Comparisons between 270numbers of mixed type use the same rule. [#]_ The constructors :func:`int`, 271:func:`long`, :func:`float`, and :func:`complex` can be used to produce numbers 272of a specific type. 273 274All builtin numeric types support the following operations. See 275:ref:`power` and later sections for the operators' priorities. 276 277+--------------------+---------------------------------+--------+ 278| Operation | Result | Notes | 279+====================+=================================+========+ 280| ``x + y`` | sum of *x* and *y* | | 281+--------------------+---------------------------------+--------+ 282| ``x - y`` | difference of *x* and *y* | | 283+--------------------+---------------------------------+--------+ 284| ``x * y`` | product of *x* and *y* | | 285+--------------------+---------------------------------+--------+ 286| ``x / y`` | quotient of *x* and *y* | \(1) | 287+--------------------+---------------------------------+--------+ 288| ``x // y`` | (floored) quotient of *x* and | (4)(5) | 289| | *y* | | 290+--------------------+---------------------------------+--------+ 291| ``x % y`` | remainder of ``x / y`` | \(4) | 292+--------------------+---------------------------------+--------+ 293| ``-x`` | *x* negated | | 294+--------------------+---------------------------------+--------+ 295| ``+x`` | *x* unchanged | | 296+--------------------+---------------------------------+--------+ 297| ``abs(x)`` | absolute value or magnitude of | \(3) | 298| | *x* | | 299+--------------------+---------------------------------+--------+ 300| ``int(x)`` | *x* converted to integer | \(2) | 301+--------------------+---------------------------------+--------+ 302| ``long(x)`` | *x* converted to long integer | \(2) | 303+--------------------+---------------------------------+--------+ 304| ``float(x)`` | *x* converted to floating point | \(6) | 305+--------------------+---------------------------------+--------+ 306| ``complex(re,im)`` | a complex number with real part | | 307| | *re*, imaginary part *im*. | | 308| | *im* defaults to zero. | | 309+--------------------+---------------------------------+--------+ 310| ``c.conjugate()`` | conjugate of the complex number | | 311| | *c*. (Identity on real numbers) | | 312+--------------------+---------------------------------+--------+ 313| ``divmod(x, y)`` | the pair ``(x // y, x % y)`` | (3)(4) | 314+--------------------+---------------------------------+--------+ 315| ``pow(x, y)`` | *x* to the power *y* | (3)(7) | 316+--------------------+---------------------------------+--------+ 317| ``x ** y`` | *x* to the power *y* | \(7) | 318+--------------------+---------------------------------+--------+ 319 320.. index:: 321 triple: operations on; numeric; types 322 single: conjugate() (complex number method) 323 324Notes: 325 326(1) 327 .. index:: 328 pair: integer; division 329 triple: long; integer; division 330 331 For (plain or long) integer division, the result is an integer. The result is 332 always rounded towards minus infinity: 1/2 is 0, (-1)/2 is -1, 1/(-2) is -1, and 333 (-1)/(-2) is 0. Note that the result is a long integer if either operand is a 334 long integer, regardless of the numeric value. 335 336(2) 337 .. index:: 338 module: math 339 single: floor() (in module math) 340 single: ceil() (in module math) 341 single: trunc() (in module math) 342 pair: numeric; conversions 343 344 Conversion from floats using :func:`int` or :func:`long` truncates toward 345 zero like the related function, :func:`math.trunc`. Use the function 346 :func:`math.floor` to round downward and :func:`math.ceil` to round 347 upward. 348 349(3) 350 See :ref:`built-in-funcs` for a full description. 351 352(4) 353 Complex floor division operator, modulo operator, and :func:`divmod`. 354 355 .. deprecated:: 2.3 356 Instead convert to float using :func:`abs` if appropriate. 357 358(5) 359 Also referred to as integer division. The resultant value is a whole integer, 360 though the result's type is not necessarily int. 361 362(6) 363 float also accepts the strings "nan" and "inf" with an optional prefix "+" 364 or "-" for Not a Number (NaN) and positive or negative infinity. 365 366 .. versionadded:: 2.6 367 368(7) 369 Python defines ``pow(0, 0)`` and ``0 ** 0`` to be ``1``, as is common for 370 programming languages. 371 372All :class:`numbers.Real` types (:class:`int`, :class:`long`, and 373:class:`float`) also include the following operations: 374 375+--------------------+------------------------------------+--------+ 376| Operation | Result | Notes | 377+====================+====================================+========+ 378| ``math.trunc(x)`` | *x* truncated to Integral | | 379+--------------------+------------------------------------+--------+ 380| ``round(x[, n])`` | *x* rounded to n digits, | | 381| | rounding half to even. If n is | | 382| | omitted, it defaults to 0. | | 383+--------------------+------------------------------------+--------+ 384| ``math.floor(x)`` | the greatest integral float <= *x* | | 385+--------------------+------------------------------------+--------+ 386| ``math.ceil(x)`` | the least integral float >= *x* | | 387+--------------------+------------------------------------+--------+ 388 389.. XXXJH exceptions: overflow (when? what operations?) zerodivision 390 391 392.. _bitstring-ops: 393 394Bit-string Operations on Integer Types 395-------------------------------------- 396 397.. _bit-string-operations: 398 399Plain and long integer types support additional operations that make sense only 400for bit-strings. Negative numbers are treated as their 2's complement value 401(for long integers, this assumes a sufficiently large number of bits that no 402overflow occurs during the operation). 403 404The priorities of the binary bitwise operations are all lower than the numeric 405operations and higher than the comparisons; the unary operation ``~`` has the 406same priority as the other unary numeric operations (``+`` and ``-``). 407 408This table lists the bit-string operations sorted in ascending priority: 409 410+------------+--------------------------------+----------+ 411| Operation | Result | Notes | 412+============+================================+==========+ 413| ``x | y`` | bitwise :dfn:`or` of *x* and | | 414| | *y* | | 415+------------+--------------------------------+----------+ 416| ``x ^ y`` | bitwise :dfn:`exclusive or` of | | 417| | *x* and *y* | | 418+------------+--------------------------------+----------+ 419| ``x & y`` | bitwise :dfn:`and` of *x* and | | 420| | *y* | | 421+------------+--------------------------------+----------+ 422| ``x << n`` | *x* shifted left by *n* bits | (1)(2) | 423+------------+--------------------------------+----------+ 424| ``x >> n`` | *x* shifted right by *n* bits | (1)(3) | 425+------------+--------------------------------+----------+ 426| ``~x`` | the bits of *x* inverted | | 427+------------+--------------------------------+----------+ 428 429.. index:: 430 triple: operations on; integer; types 431 pair: bit-string; operations 432 pair: shifting; operations 433 pair: masking; operations 434 435Notes: 436 437(1) 438 Negative shift counts are illegal and cause a :exc:`ValueError` to be raised. 439 440(2) 441 A left shift by *n* bits is equivalent to multiplication by ``pow(2, n)``. A 442 long integer is returned if the result exceeds the range of plain integers. 443 444(3) 445 A right shift by *n* bits is equivalent to division by ``pow(2, n)``. 446 447 448Additional Methods on Float 449--------------------------- 450 451The float type has some additional methods. 452 453.. method:: float.as_integer_ratio() 454 455 Return a pair of integers whose ratio is exactly equal to the 456 original float and with a positive denominator. Raises 457 :exc:`OverflowError` on infinities and a :exc:`ValueError` on 458 NaNs. 459 460 .. versionadded:: 2.6 461 462Two methods support conversion to 463and from hexadecimal strings. Since Python's floats are stored 464internally as binary numbers, converting a float to or from a 465*decimal* string usually involves a small rounding error. In 466contrast, hexadecimal strings allow exact representation and 467specification of floating-point numbers. This can be useful when 468debugging, and in numerical work. 469 470 471.. method:: float.hex() 472 473 Return a representation of a floating-point number as a hexadecimal 474 string. For finite floating-point numbers, this representation 475 will always include a leading ``0x`` and a trailing ``p`` and 476 exponent. 477 478 .. versionadded:: 2.6 479 480 481.. method:: float.fromhex(s) 482 483 Class method to return the float represented by a hexadecimal 484 string *s*. The string *s* may have leading and trailing 485 whitespace. 486 487 .. versionadded:: 2.6 488 489 490Note that :meth:`float.hex` is an instance method, while 491:meth:`float.fromhex` is a class method. 492 493A hexadecimal string takes the form:: 494 495 [sign] ['0x'] integer ['.' fraction] ['p' exponent] 496 497where the optional ``sign`` may by either ``+`` or ``-``, ``integer`` 498and ``fraction`` are strings of hexadecimal digits, and ``exponent`` 499is a decimal integer with an optional leading sign. Case is not 500significant, and there must be at least one hexadecimal digit in 501either the integer or the fraction. This syntax is similar to the 502syntax specified in section 6.4.4.2 of the C99 standard, and also to 503the syntax used in Java 1.5 onwards. In particular, the output of 504:meth:`float.hex` is usable as a hexadecimal floating-point literal in 505C or Java code, and hexadecimal strings produced by C's ``%a`` format 506character or Java's ``Double.toHexString`` are accepted by 507:meth:`float.fromhex`. 508 509 510Note that the exponent is written in decimal rather than hexadecimal, 511and that it gives the power of 2 by which to multiply the coefficient. 512For example, the hexadecimal string ``0x3.a7p10`` represents the 513floating-point number ``(3 + 10./16 + 7./16**2) * 2.0**10``, or 514``3740.0``:: 515 516 >>> float.fromhex('0x3.a7p10') 517 3740.0 518 519 520Applying the reverse conversion to ``3740.0`` gives a different 521hexadecimal string representing the same number:: 522 523 >>> float.hex(3740.0) 524 '0x1.d380000000000p+11' 525 526 527.. _typeiter: 528 529Iterator Types 530============== 531 532.. versionadded:: 2.2 533 534.. index:: 535 single: iterator protocol 536 single: protocol; iterator 537 single: sequence; iteration 538 single: container; iteration over 539 540Python supports a concept of iteration over containers. This is implemented 541using two distinct methods; these are used to allow user-defined classes to 542support iteration. Sequences, described below in more detail, always support 543the iteration methods. 544 545One method needs to be defined for container objects to provide iteration 546support: 547 548.. XXX duplicated in reference/datamodel! 549 550.. method:: container.__iter__() 551 552 Return an iterator object. The object is required to support the iterator 553 protocol described below. If a container supports different types of 554 iteration, additional methods can be provided to specifically request 555 iterators for those iteration types. (An example of an object supporting 556 multiple forms of iteration would be a tree structure which supports both 557 breadth-first and depth-first traversal.) This method corresponds to the 558 :attr:`tp_iter` slot of the type structure for Python objects in the Python/C 559 API. 560 561The iterator objects themselves are required to support the following two 562methods, which together form the :dfn:`iterator protocol`: 563 564 565.. method:: iterator.__iter__() 566 567 Return the iterator object itself. This is required to allow both containers 568 and iterators to be used with the :keyword:`for` and :keyword:`in` statements. 569 This method corresponds to the :attr:`tp_iter` slot of the type structure for 570 Python objects in the Python/C API. 571 572 573.. method:: iterator.next() 574 575 Return the next item from the container. If there are no further items, raise 576 the :exc:`StopIteration` exception. This method corresponds to the 577 :attr:`tp_iternext` slot of the type structure for Python objects in the 578 Python/C API. 579 580Python defines several iterator objects to support iteration over general and 581specific sequence types, dictionaries, and other more specialized forms. The 582specific types are not important beyond their implementation of the iterator 583protocol. 584 585The intention of the protocol is that once an iterator's :meth:`next` method 586raises :exc:`StopIteration`, it will continue to do so on subsequent calls. 587Implementations that do not obey this property are deemed broken. (This 588constraint was added in Python 2.3; in Python 2.2, various iterators are broken 589according to this rule.) 590 591Python's :term:`generator`\s provide a convenient way to implement the iterator 592protocol. If a container object's :meth:`__iter__` method is implemented as a 593generator, it will automatically return an iterator object (technically, a 594generator object) supplying the :meth:`__iter__` and :meth:`next` methods. 595 596 597.. _typesseq: 598 599Sequence Types --- :class:`str`, :class:`unicode`, :class:`list`, :class:`tuple`, :class:`buffer`, :class:`xrange` 600================================================================================================================== 601 602There are six sequence types: strings, Unicode strings, lists, tuples, buffers, 603and xrange objects. 604 605For other containers see the built in :class:`dict` and :class:`set` classes, 606and the :mod:`collections` module. 607 608 609.. index:: 610 object: sequence 611 object: string 612 object: Unicode 613 object: tuple 614 object: list 615 object: buffer 616 object: xrange 617 618String literals are written in single or double quotes: ``'xyzzy'``, 619``"frobozz"``. See :ref:`strings` for more about string literals. 620Unicode strings are much like strings, but are specified in the syntax 621using a preceding ``'u'`` character: ``u'abc'``, ``u"def"``. In addition 622to the functionality described here, there are also string-specific 623methods described in the :ref:`string-methods` section. Lists are 624constructed with square brackets, separating items with commas: ``[a, b, c]``. 625Tuples are constructed by the comma operator (not within square 626brackets), with or without enclosing parentheses, but an empty tuple 627must have the enclosing parentheses, such as ``a, b, c`` or ``()``. A 628single item tuple must have a trailing comma, such as ``(d,)``. 629 630Buffer objects are not directly supported by Python syntax, but can be created 631by calling the builtin function :func:`buffer`. They don't support 632concatenation or repetition. 633 634Objects of type xrange are similar to buffers in that there is no specific syntax to 635create them, but they are created using the :func:`xrange` function. They don't 636support slicing, concatenation or repetition, and using ``in``, ``not in``, 637:func:`min` or :func:`max` on them is inefficient. 638 639Most sequence types support the following operations. The ``in`` and ``not in`` 640operations have the same priorities as the comparison operations. The ``+`` and 641``*`` operations have the same priority as the corresponding numeric operations. 642[#]_ Additional methods are provided for :ref:`typesseq-mutable`. 643 644This table lists the sequence operations sorted in ascending priority 645(operations in the same box have the same priority). In the table, *s* and *t* 646are sequences of the same type; *n*, *i* and *j* are integers: 647 648+------------------+--------------------------------+----------+ 649| Operation | Result | Notes | 650+==================+================================+==========+ 651| ``x in s`` | ``True`` if an item of *s* is | \(1) | 652| | equal to *x*, else ``False`` | | 653+------------------+--------------------------------+----------+ 654| ``x not in s`` | ``False`` if an item of *s* is | \(1) | 655| | equal to *x*, else ``True`` | | 656+------------------+--------------------------------+----------+ 657| ``s + t`` | the concatenation of *s* and | \(6) | 658| | *t* | | 659+------------------+--------------------------------+----------+ 660| ``s * n, n * s`` | *n* shallow copies of *s* | \(2) | 661| | concatenated | | 662+------------------+--------------------------------+----------+ 663| ``s[i]`` | *i*'th item of *s*, origin 0 | \(3) | 664+------------------+--------------------------------+----------+ 665| ``s[i:j]`` | slice of *s* from *i* to *j* | (3)(4) | 666+------------------+--------------------------------+----------+ 667| ``s[i:j:k]`` | slice of *s* from *i* to *j* | (3)(5) | 668| | with step *k* | | 669+------------------+--------------------------------+----------+ 670| ``len(s)`` | length of *s* | | 671+------------------+--------------------------------+----------+ 672| ``min(s)`` | smallest item of *s* | | 673+------------------+--------------------------------+----------+ 674| ``max(s)`` | largest item of *s* | | 675+------------------+--------------------------------+----------+ 676 677Sequence types also support comparisons. In particular, tuples and lists 678are compared lexicographically by comparing corresponding 679elements. This means that to compare equal, every element must compare 680equal and the two sequences must be of the same type and have the same 681length. (For full details see :ref:`comparisons` in the language 682reference.) 683 684.. index:: 685 triple: operations on; sequence; types 686 builtin: len 687 builtin: min 688 builtin: max 689 pair: concatenation; operation 690 pair: repetition; operation 691 pair: subscript; operation 692 pair: slice; operation 693 pair: extended slice; operation 694 operator: in 695 operator: not in 696 697Notes: 698 699(1) 700 When *s* is a string or Unicode string object the ``in`` and ``not in`` 701 operations act like a substring test. In Python versions before 2.3, *x* had to 702 be a string of length 1. In Python 2.3 and beyond, *x* may be a string of any 703 length. 704 705(2) 706 Values of *n* less than ``0`` are treated as ``0`` (which yields an empty 707 sequence of the same type as *s*). Note also that the copies are shallow; 708 nested structures are not copied. This often haunts new Python programmers; 709 consider: 710 711 >>> lists = [[]] * 3 712 >>> lists 713 [[], [], []] 714 >>> lists[0].append(3) 715 >>> lists 716 [[3], [3], [3]] 717 718 What has happened is that ``[[]]`` is a one-element list containing an empty 719 list, so all three elements of ``[[]] * 3`` are (pointers to) this single empty 720 list. Modifying any of the elements of ``lists`` modifies this single list. 721 You can create a list of different lists this way: 722 723 >>> lists = [[] for i in range(3)] 724 >>> lists[0].append(3) 725 >>> lists[1].append(5) 726 >>> lists[2].append(7) 727 >>> lists 728 [[3], [5], [7]] 729 730(3) 731 If *i* or *j* is negative, the index is relative to the end of the string: 732 ``len(s) + i`` or ``len(s) + j`` is substituted. But note that ``-0`` is still 733 ``0``. 734 735(4) 736 The slice of *s* from *i* to *j* is defined as the sequence of items with index 737 *k* such that ``i <= k < j``. If *i* or *j* is greater than ``len(s)``, use 738 ``len(s)``. If *i* is omitted or ``None``, use ``0``. If *j* is omitted or 739 ``None``, use ``len(s)``. If *i* is greater than or equal to *j*, the slice is 740 empty. 741 742(5) 743 The slice of *s* from *i* to *j* with step *k* is defined as the sequence of 744 items with index ``x = i + n*k`` such that ``0 <= n < (j-i)/k``. In other words, 745 the indices are ``i``, ``i+k``, ``i+2*k``, ``i+3*k`` and so on, stopping when 746 *j* is reached (but never including *j*). If *i* or *j* is greater than 747 ``len(s)``, use ``len(s)``. If *i* or *j* are omitted or ``None``, they become 748 "end" values (which end depends on the sign of *k*). Note, *k* cannot be zero. 749 If *k* is ``None``, it is treated like ``1``. 750 751(6) 752 If *s* and *t* are both strings, some Python implementations such as CPython can 753 usually perform an in-place optimization for assignments of the form ``s=s+t`` 754 or ``s+=t``. When applicable, this optimization makes quadratic run-time much 755 less likely. This optimization is both version and implementation dependent. 756 For performance sensitive code, it is preferable to use the :meth:`str.join` 757 method which assures consistent linear concatenation performance across versions 758 and implementations. 759 760 .. versionchanged:: 2.4 761 Formerly, string concatenation never occurred in-place. 762 763 764.. _string-methods: 765 766String Methods 767-------------- 768 769.. index:: pair: string; methods 770 771Below are listed the string methods which both 8-bit strings and Unicode objects 772support. Note that none of these methods take keyword arguments. 773 774In addition, Python's strings support the sequence type methods 775described in the :ref:`typesseq` section. To output formatted strings 776use template strings or the ``%`` operator described in the 777:ref:`string-formatting` section. Also, see the :mod:`re` module for 778string functions based on regular expressions. 779 780.. method:: str.capitalize() 781 782 Return a copy of the string with only its first character capitalized. 783 784 For 8-bit strings, this method is locale-dependent. 785 786 787.. method:: str.center(width[, fillchar]) 788 789 Return centered in a string of length *width*. Padding is done using the 790 specified *fillchar* (default is a space). 791 792 .. versionchanged:: 2.4 793 Support for the *fillchar* argument. 794 795 796.. method:: str.count(sub[, start[, end]]) 797 798 Return the number of non-overlapping occurrences of substring *sub* in the 799 range [*start*, *end*]. Optional arguments *start* and *end* are 800 interpreted as in slice notation. 801 802 803.. method:: str.decode([encoding[, errors]]) 804 805 Decodes the string using the codec registered for *encoding*. *encoding* 806 defaults to the default string encoding. *errors* may be given to set a 807 different error handling scheme. The default is ``'strict'``, meaning that 808 encoding errors raise :exc:`UnicodeError`. Other possible values are 809 ``'ignore'``, ``'replace'`` and any other name registered via 810 :func:`codecs.register_error`, see section :ref:`codec-base-classes`. 811 812 .. versionadded:: 2.2 813 814 .. versionchanged:: 2.3 815 Support for other error handling schemes added. 816 817 818.. method:: str.encode([encoding[,errors]]) 819 820 Return an encoded version of the string. Default encoding is the current 821 default string encoding. *errors* may be given to set a different error 822 handling scheme. The default for *errors* is ``'strict'``, meaning that 823 encoding errors raise a :exc:`UnicodeError`. Other possible values are 824 ``'ignore'``, ``'replace'``, ``'xmlcharrefreplace'``, ``'backslashreplace'`` and 825 any other name registered via :func:`codecs.register_error`, see section 826 :ref:`codec-base-classes`. For a list of possible encodings, see section 827 :ref:`standard-encodings`. 828 829 .. versionadded:: 2.0 830 831 .. versionchanged:: 2.3 832 Support for ``'xmlcharrefreplace'`` and ``'backslashreplace'`` and other error 833 handling schemes added. 834 835 836.. method:: str.endswith(suffix[, start[, end]]) 837 838 Return ``True`` if the string ends with the specified *suffix*, otherwise return 839 ``False``. *suffix* can also be a tuple of suffixes to look for. With optional 840 *start*, test beginning at that position. With optional *end*, stop comparing 841 at that position. 842 843 .. versionchanged:: 2.5 844 Accept tuples as *suffix*. 845 846 847.. method:: str.expandtabs([tabsize]) 848 849 Return a copy of the string where all tab characters are replaced by one or 850 more spaces, depending on the current column and the given tab size. The 851 column number is reset to zero after each newline occurring in the string. 852 If *tabsize* is not given, a tab size of ``8`` characters is assumed. This 853 doesn't understand other non-printing characters or escape sequences. 854 855 856.. method:: str.find(sub[, start[, end]]) 857 858 Return the lowest index in the string where substring *sub* is found, such that 859 *sub* is contained in the range [*start*, *end*]. Optional arguments *start* 860 and *end* are interpreted as in slice notation. Return ``-1`` if *sub* is not 861 found. 862 863 864.. method:: str.format(format_string, *args, **kwargs) 865 866 Perform a string formatting operation. The *format_string* argument can 867 contain literal text or replacement fields delimited by braces ``{}``. Each 868 replacement field contains either the numeric index of a positional argument, 869 or the name of a keyword argument. Returns a copy of *format_string* where 870 each replacement field is replaced with the string value of the corresponding 871 argument. 872 873 >>> "The sum of 1 + 2 is {0}".format(1+2) 874 'The sum of 1 + 2 is 3' 875 876 See :ref:`formatstrings` for a description of the various formatting options 877 that can be specified in format strings. 878 879 This method of string formatting is the new standard in Python 3.0, and 880 should be preferred to the ``%`` formatting described in 881 :ref:`string-formatting` in new code. 882 883 .. versionadded:: 2.6 884 885 886.. method:: str.index(sub[, start[, end]]) 887 888 Like :meth:`find`, but raise :exc:`ValueError` when the substring is not found. 889 890 891.. method:: str.isalnum() 892 893 Return true if all characters in the string are alphanumeric and there is at 894 least one character, false otherwise. 895 896 For 8-bit strings, this method is locale-dependent. 897 898 899.. method:: str.isalpha() 900 901 Return true if all characters in the string are alphabetic and there is at least 902 one character, false otherwise. 903 904 For 8-bit strings, this method is locale-dependent. 905 906 907.. method:: str.isdigit() 908 909 Return true if all characters in the string are digits and there is at least one 910 character, false otherwise. 911 912 For 8-bit strings, this method is locale-dependent. 913 914 915.. method:: str.islower() 916 917 Return true if all cased characters in the string are lowercase and there is at 918 least one cased character, false otherwise. 919 920 For 8-bit strings, this method is locale-dependent. 921 922 923.. method:: str.isspace() 924 925 Return true if there are only whitespace characters in the string and there is 926 at least one character, false otherwise. 927 928 For 8-bit strings, this method is locale-dependent. 929 930 931.. method:: str.istitle() 932 933 Return true if the string is a titlecased string and there is at least one 934 character, for example uppercase characters may only follow uncased characters 935 and lowercase characters only cased ones. Return false otherwise. 936 937 For 8-bit strings, this method is locale-dependent. 938 939 940.. method:: str.isupper() 941 942 Return true if all cased characters in the string are uppercase and there is at 943 least one cased character, false otherwise. 944 945 For 8-bit strings, this method is locale-dependent. 946 947 948.. method:: str.join(seq) 949 950 Return a string which is the concatenation of the strings in the sequence *seq*. 951 The separator between elements is the string providing this method. 952 953 954.. method:: str.ljust(width[, fillchar]) 955 956 Return the string left justified in a string of length *width*. Padding is done 957 using the specified *fillchar* (default is a space). The original string is 958 returned if *width* is less than ``len(s)``. 959 960 .. versionchanged:: 2.4 961 Support for the *fillchar* argument. 962 963 964.. method:: str.lower() 965 966 Return a copy of the string converted to lowercase. 967 968 For 8-bit strings, this method is locale-dependent. 969 970 971.. method:: str.lstrip([chars]) 972 973 Return a copy of the string with leading characters removed. The *chars* 974 argument is a string specifying the set of characters to be removed. If omitted 975 or ``None``, the *chars* argument defaults to removing whitespace. The *chars* 976 argument is not a prefix; rather, all combinations of its values are stripped: 977 978 >>> ' spacious '.lstrip() 979 'spacious ' 980 >>> 'www.example.com'.lstrip('cmowz.') 981 'example.com' 982 983 .. versionchanged:: 2.2.2 984 Support for the *chars* argument. 985 986 987.. method:: str.partition(sep) 988 989 Split the string at the first occurrence of *sep*, and return a 3-tuple 990 containing the part before the separator, the separator itself, and the part 991 after the separator. If the separator is not found, return a 3-tuple containing 992 the string itself, followed by two empty strings. 993 994 .. versionadded:: 2.5 995 996 997.. method:: str.replace(old, new[, count]) 998 999 Return a copy of the string with all occurrences of substring *old* replaced by 1000 *new*. If the optional argument *count* is given, only the first *count* 1001 occurrences are replaced. 1002 1003 1004.. method:: str.rfind(sub [,start [,end]]) 1005 1006 Return the highest index in the string where substring *sub* is found, such that 1007 *sub* is contained within s[start,end]. Optional arguments *start* and *end* 1008 are interpreted as in slice notation. Return ``-1`` on failure. 1009 1010 1011.. method:: str.rindex(sub[, start[, end]]) 1012 1013 Like :meth:`rfind` but raises :exc:`ValueError` when the substring *sub* is not 1014 found. 1015 1016 1017.. method:: str.rjust(width[, fillchar]) 1018 1019 Return the string right justified in a string of length *width*. Padding is done 1020 using the specified *fillchar* (default is a space). The original string is 1021 returned if *width* is less than ``len(s)``. 1022 1023 .. versionchanged:: 2.4 1024 Support for the *fillchar* argument. 1025 1026 1027.. method:: str.rpartition(sep) 1028 1029 Split the string at the last occurrence of *sep*, and return a 3-tuple 1030 containing the part before the separator, the separator itself, and the part 1031 after the separator. If the separator is not found, return a 3-tuple containing 1032 two empty strings, followed by the string itself. 1033 1034 .. versionadded:: 2.5 1035 1036 1037.. method:: str.rsplit([sep [,maxsplit]]) 1038 1039 Return a list of the words in the string, using *sep* as the delimiter string. 1040 If *maxsplit* is given, at most *maxsplit* splits are done, the *rightmost* 1041 ones. If *sep* is not specified or ``None``, any whitespace string is a 1042 separator. Except for splitting from the right, :meth:`rsplit` behaves like 1043 :meth:`split` which is described in detail below. 1044 1045 .. versionadded:: 2.4 1046 1047 1048.. method:: str.rstrip([chars]) 1049 1050 Return a copy of the string with trailing characters removed. The *chars* 1051 argument is a string specifying the set of characters to be removed. If omitted 1052 or ``None``, the *chars* argument defaults to removing whitespace. The *chars* 1053 argument is not a suffix; rather, all combinations of its values are stripped: 1054 1055 >>> ' spacious '.rstrip() 1056 ' spacious' 1057 >>> 'mississippi'.rstrip('ipz') 1058 'mississ' 1059 1060 .. versionchanged:: 2.2.2 1061 Support for the *chars* argument. 1062 1063 1064.. method:: str.split([sep[, maxsplit]]) 1065 1066 Return a list of the words in the string, using *sep* as the delimiter 1067 string. If *maxsplit* is given, at most *maxsplit* splits are done (thus, 1068 the list will have at most ``maxsplit+1`` elements). If *maxsplit* is not 1069 specified, then there is no limit on the number of splits (all possible 1070 splits are made). 1071 1072 If *sep* is given, consecutive delimiters are not grouped together and are 1073 deemed to delimit empty strings (for example, ``'1,,2'.split(',')`` returns 1074 ``['1', '', '2']``). The *sep* argument may consist of multiple characters 1075 (for example, ``'1<>2<>3'.split('<>')`` returns ``['1', '2', '3']``). 1076 Splitting an empty string with a specified separator returns ``['']``. 1077 1078 If *sep* is not specified or is ``None``, a different splitting algorithm is 1079 applied: runs of consecutive whitespace are regarded as a single separator, 1080 and the result will contain no empty strings at the start or end if the 1081 string has leading or trailing whitespace. Consequently, splitting an empty 1082 string or a string consisting of just whitespace with a ``None`` separator 1083 returns ``[]``. 1084 1085 For example, ``' 1 2 3 '.split()`` returns ``['1', '2', '3']``, and 1086 ``' 1 2 3 '.split(None, 1)`` returns ``['1', '2 3 ']``. 1087 1088 1089.. method:: str.splitlines([keepends]) 1090 1091 Return a list of the lines in the string, breaking at line boundaries. Line 1092 breaks are not included in the resulting list unless *keepends* is given and 1093 true. 1094 1095 1096.. method:: str.startswith(prefix[, start[, end]]) 1097 1098 Return ``True`` if string starts with the *prefix*, otherwise return ``False``. 1099 *prefix* can also be a tuple of prefixes to look for. With optional *start*, 1100 test string beginning at that position. With optional *end*, stop comparing 1101 string at that position. 1102 1103 .. versionchanged:: 2.5 1104 Accept tuples as *prefix*. 1105 1106 1107.. method:: str.strip([chars]) 1108 1109 Return a copy of the string with the leading and trailing characters removed. 1110 The *chars* argument is a string specifying the set of characters to be removed. 1111 If omitted or ``None``, the *chars* argument defaults to removing whitespace. 1112 The *chars* argument is not a prefix or suffix; rather, all combinations of its 1113 values are stripped: 1114 1115 >>> ' spacious '.strip() 1116 'spacious' 1117 >>> 'www.example.com'.strip('cmowz.') 1118 'example' 1119 1120 .. versionchanged:: 2.2.2 1121 Support for the *chars* argument. 1122 1123 1124.. method:: str.swapcase() 1125 1126 Return a copy of the string with uppercase characters converted to lowercase and 1127 vice versa. 1128 1129 For 8-bit strings, this method is locale-dependent. 1130 1131 1132.. method:: str.title() 1133 1134 Return a titlecased version of the string where words start with an uppercase 1135 character and the remaining characters are lowercase. 1136 1137 The algorithm uses a simple language-independent definition of a word as 1138 groups of consecutive letters. The definition works in many contexts but 1139 it means that apostrophes in contractions and possessives form word 1140 boundaries, which may not be the desired result:: 1141 1142 >>> "they're bill's friends from the UK".title() 1143 "They'Re Bill'S Friends From The Uk" 1144 1145 A workaround for apostrophes can be constructed using regular expressions:: 1146 1147 >>> import re 1148 >>> def titlecase(s): 1149 return re.sub(r"[A-Za-z]+('[A-Za-z]+)?", 1150 lambda mo: mo.group(0)[0].upper() + 1151 mo.group(0)[1:].lower(), 1152 s) 1153 1154 >>> titlecase("they're bill's friends.") 1155 "They're Bill's Friends." 1156 1157 For 8-bit strings, this method is locale-dependent. 1158 1159 1160.. method:: str.translate(table[, deletechars]) 1161 1162 Return a copy of the string where all characters occurring in the optional 1163 argument *deletechars* are removed, and the remaining characters have been 1164 mapped through the given translation table, which must be a string of length 1165 256. 1166 1167 You can use the :func:`maketrans` helper function in the :mod:`string` module to 1168 create a translation table. For string objects, set the *table* argument to 1169 ``None`` for translations that only delete characters: 1170 1171 >>> 'read this short text'.translate(None, 'aeiou') 1172 'rd ths shrt txt' 1173 1174 .. versionadded:: 2.6 1175 Support for a ``None`` *table* argument. 1176 1177 For Unicode objects, the :meth:`translate` method does not accept the optional 1178 *deletechars* argument. Instead, it returns a copy of the *s* where all 1179 characters have been mapped through the given translation table which must be a 1180 mapping of Unicode ordinals to Unicode ordinals, Unicode strings or ``None``. 1181 Unmapped characters are left untouched. Characters mapped to ``None`` are 1182 deleted. Note, a more flexible approach is to create a custom character mapping 1183 codec using the :mod:`codecs` module (see :mod:`encodings.cp1251` for an 1184 example). 1185 1186 1187.. method:: str.upper() 1188 1189 Return a copy of the string converted to uppercase. 1190 1191 For 8-bit strings, this method is locale-dependent. 1192 1193 1194.. method:: str.zfill(width) 1195 1196 Return the numeric string left filled with zeros in a string of length 1197 *width*. A sign prefix is handled correctly. The original string is 1198 returned if *width* is less than ``len(s)``. 1199 1200 1201 .. versionadded:: 2.2.2 1202 1203The following methods are present only on unicode objects: 1204 1205.. method:: unicode.isnumeric() 1206 1207 Return ``True`` if there are only numeric characters in S, ``False`` 1208 otherwise. Numeric characters include digit characters, and all characters 1209 that have the Unicode numeric value property, e.g. U+2155, 1210 VULGAR FRACTION ONE FIFTH. 1211 1212.. method:: unicode.isdecimal() 1213 1214 Return ``True`` if there are only decimal characters in S, ``False`` 1215 otherwise. Decimal characters include digit characters, and all characters 1216 that that can be used to form decimal-radix numbers, e.g. U+0660, 1217 ARABIC-INDIC DIGIT ZERO. 1218 1219 1220.. _string-formatting: 1221 1222String Formatting Operations 1223---------------------------- 1224 1225.. index:: 1226 single: formatting, string (%) 1227 single: interpolation, string (%) 1228 single: string; formatting 1229 single: string; interpolation 1230 single: printf-style formatting 1231 single: sprintf-style formatting 1232 single: % formatting 1233 single: % interpolation 1234 1235String and Unicode objects have one unique built-in operation: the ``%`` 1236operator (modulo). This is also known as the string *formatting* or 1237*interpolation* operator. Given ``format % values`` (where *format* is a string 1238or Unicode object), ``%`` conversion specifications in *format* are replaced 1239with zero or more elements of *values*. The effect is similar to the using 1240:cfunc:`sprintf` in the C language. If *format* is a Unicode object, or if any 1241of the objects being converted using the ``%s`` conversion are Unicode objects, 1242the result will also be a Unicode object. 1243 1244If *format* requires a single argument, *values* may be a single non-tuple 1245object. [#]_ Otherwise, *values* must be a tuple with exactly the number of 1246items specified by the format string, or a single mapping object (for example, a 1247dictionary). 1248 1249A conversion specifier contains two or more characters and has the following 1250components, which must occur in this order: 1251 1252#. The ``'%'`` character, which marks the start of the specifier. 1253 1254#. Mapping key (optional), consisting of a parenthesised sequence of characters 1255 (for example, ``(somename)``). 1256 1257#. Conversion flags (optional), which affect the result of some conversion 1258 types. 1259 1260#. Minimum field width (optional). If specified as an ``'*'`` (asterisk), the 1261 actual width is read from the next element of the tuple in *values*, and the 1262 object to convert comes after the minimum field width and optional precision. 1263 1264#. Precision (optional), given as a ``'.'`` (dot) followed by the precision. If 1265 specified as ``'*'`` (an asterisk), the actual width is read from the next 1266 element of the tuple in *values*, and the value to convert comes after the 1267 precision. 1268 1269#. Length modifier (optional). 1270 1271#. Conversion type. 1272 1273When the right argument is a dictionary (or other mapping type), then the 1274formats in the string *must* include a parenthesised mapping key into that 1275dictionary inserted immediately after the ``'%'`` character. The mapping key 1276selects the value to be formatted from the mapping. For example: 1277 1278 >>> print '%(language)s has %(#)03d quote types.' % \ 1279 ... {'language': "Python", "#": 2} 1280 Python has 002 quote types. 1281 1282In this case no ``*`` specifiers may occur in a format (since they require a 1283sequential parameter list). 1284 1285The conversion flag characters are: 1286 1287+---------+---------------------------------------------------------------------+ 1288| Flag | Meaning | 1289+=========+=====================================================================+ 1290| ``'#'`` | The value conversion will use the "alternate form" (where defined | 1291| | below). | 1292+---------+---------------------------------------------------------------------+ 1293| ``'0'`` | The conversion will be zero padded for numeric values. | 1294+---------+---------------------------------------------------------------------+ 1295| ``'-'`` | The converted value is left adjusted (overrides the ``'0'`` | 1296| | conversion if both are given). | 1297+---------+---------------------------------------------------------------------+ 1298| ``' '`` | (a space) A blank should be left before a positiv…
Large files files are truncated, but you can click here to view the full file