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.. index:: pair: built-in; types 14 15The principal built-in types are numerics, sequences, mappings, classes, 16instances and exceptions. 17 18Some collection classes are mutable. The methods that add, subtract, or 19rearrange their members in place, and don't return a specific item, never return 20the collection instance itself but ``None``. 21 22Some operations are supported by several object types; in particular, 23practically all objects can be compared for equality, tested for truth 24value, and converted to a string (with the :func:`repr` function or the 25slightly different :func:`str` function). The latter function is implicitly 26used when an object is written by the :func:`print` function. 27 28 29.. _truth: 30 31Truth Value Testing 32=================== 33 34.. index:: 35 statement: if 36 statement: while 37 pair: truth; value 38 pair: Boolean; operations 39 single: false 40 41Any object can be tested for truth value, for use in an :keyword:`if` or 42:keyword:`while` condition or as operand of the Boolean operations below. 43 44.. index:: single: true 45 46By default, an object is considered true unless its class defines either a 47:meth:`__bool__` method that returns ``False`` or a :meth:`__len__` method that 48returns zero, when called with the object. [1]_ Here are most of the built-in 49objects considered false: 50 51 .. index:: 52 single: None (Built-in object) 53 single: False (Built-in object) 54 55* constants defined to be false: ``None`` and ``False``. 56 57* zero of any numeric type: ``0``, ``0.0``, ``0j``, ``Decimal(0)``, 58 ``Fraction(0, 1)`` 59 60* empty sequences and collections: ``''``, ``()``, ``[]``, ``{}``, ``set()``, 61 ``range(0)`` 62 63.. index:: 64 operator: or 65 operator: and 66 single: False 67 single: True 68 69Operations and built-in functions that have a Boolean result always return ``0`` 70or ``False`` for false and ``1`` or ``True`` for true, unless otherwise stated. 71(Important exception: the Boolean operations ``or`` and ``and`` always return 72one of their operands.) 73 74 75.. _boolean: 76 77Boolean Operations --- :keyword:`!and`, :keyword:`!or`, :keyword:`!not` 78======================================================================= 79 80.. index:: pair: Boolean; operations 81 82These are the Boolean operations, ordered by ascending priority: 83 84+-------------+---------------------------------+-------+ 85| Operation | Result | Notes | 86+=============+=================================+=======+ 87| ``x or y`` | if *x* is false, then *y*, else | \(1) | 88| | *x* | | 89+-------------+---------------------------------+-------+ 90| ``x and y`` | if *x* is false, then *x*, else | \(2) | 91| | *y* | | 92+-------------+---------------------------------+-------+ 93| ``not x`` | if *x* is false, then ``True``, | \(3) | 94| | else ``False`` | | 95+-------------+---------------------------------+-------+ 96 97.. index:: 98 operator: and 99 operator: or 100 operator: not 101 102Notes: 103 104(1) 105 This is a short-circuit operator, so it only evaluates the second 106 argument if the first one is false. 107 108(2) 109 This is a short-circuit operator, so it only evaluates the second 110 argument if the first one is true. 111 112(3) 113 ``not`` has a lower priority than non-Boolean operators, so ``not a == b`` is 114 interpreted as ``not (a == b)``, and ``a == not b`` is a syntax error. 115 116 117.. _stdcomparisons: 118 119Comparisons 120=========== 121 122.. index:: 123 pair: chaining; comparisons 124 pair: operator; comparison 125 operator: == 126 operator: < (less) 127 operator: <= 128 operator: > (greater) 129 operator: >= 130 operator: != 131 operator: is 132 operator: is not 133 134There are eight comparison operations in Python. 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 | 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 | 156+------------+-------------------------+ 157| ``is`` | object identity | 158+------------+-------------------------+ 159| ``is not`` | negated object identity | 160+------------+-------------------------+ 161 162.. index:: 163 pair: object; numeric 164 pair: objects; comparing 165 166Objects of different types, except different numeric types, never compare equal. 167The ``==`` operator is always defined but for some object types (for example, 168class objects) is equivalent to :keyword:`is`. The ``<``, ``<=``, ``>`` and ``>=`` 169operators are only defined where they make sense; for example, they raise a 170:exc:`TypeError` exception when one of the arguments is a complex number. 171 172.. index:: 173 single: __eq__() (instance method) 174 single: __ne__() (instance method) 175 single: __lt__() (instance method) 176 single: __le__() (instance method) 177 single: __gt__() (instance method) 178 single: __ge__() (instance method) 179 180Non-identical instances of a class normally compare as non-equal unless the 181class defines the :meth:`__eq__` method. 182 183Instances of a class cannot be ordered with respect to other instances of the 184same class, or other types of object, unless the class defines enough of the 185methods :meth:`__lt__`, :meth:`__le__`, :meth:`__gt__`, and :meth:`__ge__` (in 186general, :meth:`__lt__` and :meth:`__eq__` are sufficient, if you want the 187conventional meanings of the comparison operators). 188 189The behavior of the :keyword:`is` and :keyword:`is not` operators cannot be 190customized; also they can be applied to any two objects and never raise an 191exception. 192 193.. index:: 194 operator: in 195 operator: not in 196 197Two more operations with the same syntactic priority, :keyword:`in` and 198:keyword:`not in`, are supported by types that are :term:`iterable` or 199implement the :meth:`__contains__` method. 200 201.. _typesnumeric: 202 203Numeric Types --- :class:`int`, :class:`float`, :class:`complex` 204================================================================ 205 206.. index:: 207 object: numeric 208 object: Boolean 209 object: integer 210 object: floating point 211 object: complex number 212 pair: C; language 213 214There are three distinct numeric types: :dfn:`integers`, :dfn:`floating 215point numbers`, and :dfn:`complex numbers`. In addition, Booleans are a 216subtype of integers. Integers have unlimited precision. Floating point 217numbers are usually implemented using :c:type:`double` in C; information 218about the precision and internal representation of floating point 219numbers for the machine on which your program is running is available 220in :data:`sys.float_info`. Complex numbers have a real and imaginary 221part, which are each a floating point number. To extract these parts 222from a complex number *z*, use ``z.real`` and ``z.imag``. (The standard 223library includes the additional numeric types :mod:`fractions.Fraction`, for 224rationals, and :mod:`decimal.Decimal`, for floating-point numbers with 225user-definable precision.) 226 227.. index:: 228 pair: numeric; literals 229 pair: integer; literals 230 pair: floating point; literals 231 pair: complex number; literals 232 pair: hexadecimal; literals 233 pair: octal; literals 234 pair: binary; literals 235 236Numbers are created by numeric literals or as the result of built-in functions 237and operators. Unadorned integer literals (including hex, octal and binary 238numbers) yield integers. Numeric literals containing a decimal point or an 239exponent sign yield floating point numbers. Appending ``'j'`` or ``'J'`` to a 240numeric literal yields an imaginary number (a complex number with a zero real 241part) which you can add to an integer or float to get a complex number with real 242and imaginary parts. 243 244.. index:: 245 single: arithmetic 246 builtin: int 247 builtin: float 248 builtin: complex 249 single: operator; + (plus) 250 single: + (plus); unary operator 251 single: + (plus); binary operator 252 single: operator; - (minus) 253 single: - (minus); unary operator 254 single: - (minus); binary operator 255 operator: * (asterisk) 256 operator: / (slash) 257 operator: // 258 operator: % (percent) 259 operator: ** 260 261Python fully supports mixed arithmetic: when a binary arithmetic operator has 262operands of different numeric types, the operand with the "narrower" type is 263widened to that of the other, where integer is narrower than floating point, 264which is narrower than complex. A comparison between numbers of different types 265behaves as though the exact values of those numbers were being compared. [2]_ 266 267The constructors :func:`int`, :func:`float`, and 268:func:`complex` can be used to produce numbers of a specific type. 269 270All numeric types (except complex) support the following operations (for priorities of 271the operations, see :ref:`operator-summary`): 272 273+---------------------+---------------------------------+---------+--------------------+ 274| Operation | Result | Notes | Full documentation | 275+=====================+=================================+=========+====================+ 276| ``x + y`` | sum of *x* and *y* | | | 277+---------------------+---------------------------------+---------+--------------------+ 278| ``x - y`` | difference of *x* and *y* | | | 279+---------------------+---------------------------------+---------+--------------------+ 280| ``x * y`` | product of *x* and *y* | | | 281+---------------------+---------------------------------+---------+--------------------+ 282| ``x / y`` | quotient of *x* and *y* | | | 283+---------------------+---------------------------------+---------+--------------------+ 284| ``x // y`` | floored quotient of *x* and | \(1) | | 285| | *y* | | | 286+---------------------+---------------------------------+---------+--------------------+ 287| ``x % y`` | remainder of ``x / y`` | \(2) | | 288+---------------------+---------------------------------+---------+--------------------+ 289| ``-x`` | *x* negated | | | 290+---------------------+---------------------------------+---------+--------------------+ 291| ``+x`` | *x* unchanged | | | 292+---------------------+---------------------------------+---------+--------------------+ 293| ``abs(x)`` | absolute value or magnitude of | | :func:`abs` | 294| | *x* | | | 295+---------------------+---------------------------------+---------+--------------------+ 296| ``int(x)`` | *x* converted to integer | \(3)\(6)| :func:`int` | 297+---------------------+---------------------------------+---------+--------------------+ 298| ``float(x)`` | *x* converted to floating point | \(4)\(6)| :func:`float` | 299+---------------------+---------------------------------+---------+--------------------+ 300| ``complex(re, im)`` | a complex number with real part | \(6) | :func:`complex` | 301| | *re*, imaginary part *im*. | | | 302| | *im* defaults to zero. | | | 303+---------------------+---------------------------------+---------+--------------------+ 304| ``c.conjugate()`` | conjugate of the complex number | | | 305| | *c* | | | 306+---------------------+---------------------------------+---------+--------------------+ 307| ``divmod(x, y)`` | the pair ``(x // y, x % y)`` | \(2) | :func:`divmod` | 308+---------------------+---------------------------------+---------+--------------------+ 309| ``pow(x, y)`` | *x* to the power *y* | \(5) | :func:`pow` | 310+---------------------+---------------------------------+---------+--------------------+ 311| ``x ** y`` | *x* to the power *y* | \(5) | | 312+---------------------+---------------------------------+---------+--------------------+ 313 314.. index:: 315 triple: operations on; numeric; types 316 single: conjugate() (complex number method) 317 318Notes: 319 320(1) 321 Also referred to as integer division. The resultant value is a whole 322 integer, though the result's type is not necessarily int. The result is 323 always rounded towards minus infinity: ``1//2`` is ``0``, ``(-1)//2`` is 324 ``-1``, ``1//(-2)`` is ``-1``, and ``(-1)//(-2)`` is ``0``. 325 326(2) 327 Not for complex numbers. Instead convert to floats using :func:`abs` if 328 appropriate. 329 330(3) 331 .. index:: 332 module: math 333 single: floor() (in module math) 334 single: ceil() (in module math) 335 single: trunc() (in module math) 336 pair: numeric; conversions 337 pair: C; language 338 339 Conversion from floating point to integer may round or truncate 340 as in C; see functions :func:`math.floor` and :func:`math.ceil` for 341 well-defined conversions. 342 343(4) 344 float also accepts the strings "nan" and "inf" with an optional prefix "+" 345 or "-" for Not a Number (NaN) and positive or negative infinity. 346 347(5) 348 Python defines ``pow(0, 0)`` and ``0 ** 0`` to be ``1``, as is common for 349 programming languages. 350 351(6) 352 The numeric literals accepted include the digits ``0`` to ``9`` or any 353 Unicode equivalent (code points with the ``Nd`` property). 354 355 See http://www.unicode.org/Public/12.1.0/ucd/extracted/DerivedNumericType.txt 356 for a complete list of code points with the ``Nd`` property. 357 358 359All :class:`numbers.Real` types (:class:`int` and :class:`float`) also include 360the following operations: 361 362+--------------------+---------------------------------------------+ 363| Operation | Result | 364+====================+=============================================+ 365| :func:`math.trunc(\| *x* truncated to :class:`~numbers.Integral` | 366| x) <math.trunc>` | | 367+--------------------+---------------------------------------------+ 368| :func:`round(x[, | *x* rounded to *n* digits, | 369| n]) <round>` | rounding half to even. If *n* is | 370| | omitted, it defaults to 0. | 371+--------------------+---------------------------------------------+ 372| :func:`math.floor(\| the greatest :class:`~numbers.Integral` | 373| x) <math.floor>` | <= *x* | 374+--------------------+---------------------------------------------+ 375| :func:`math.ceil(x)| the least :class:`~numbers.Integral` >= *x* | 376| <math.ceil>` | | 377+--------------------+---------------------------------------------+ 378 379For additional numeric operations see the :mod:`math` and :mod:`cmath` 380modules. 381 382.. XXXJH exceptions: overflow (when? what operations?) zerodivision 383 384 385.. _bitstring-ops: 386 387Bitwise Operations on Integer Types 388----------------------------------- 389 390.. index:: 391 triple: operations on; integer; types 392 pair: bitwise; operations 393 pair: shifting; operations 394 pair: masking; operations 395 operator: | (vertical bar) 396 operator: ^ (caret) 397 operator: & (ampersand) 398 operator: << 399 operator: >> 400 operator: ~ (tilde) 401 402Bitwise operations only make sense for integers. The result of bitwise 403operations is calculated as though carried out in two's complement with an 404infinite number of sign bits. 405 406The priorities of the binary bitwise operations are all lower than the numeric 407operations and higher than the comparisons; the unary operation ``~`` has the 408same priority as the other unary numeric operations (``+`` and ``-``). 409 410This table lists the bitwise operations sorted in ascending priority: 411 412+------------+--------------------------------+----------+ 413| Operation | Result | Notes | 414+============+================================+==========+ 415| ``x | y`` | bitwise :dfn:`or` of *x* and | \(4) | 416| | *y* | | 417+------------+--------------------------------+----------+ 418| ``x ^ y`` | bitwise :dfn:`exclusive or` of | \(4) | 419| | *x* and *y* | | 420+------------+--------------------------------+----------+ 421| ``x & y`` | bitwise :dfn:`and` of *x* and | \(4) | 422| | *y* | | 423+------------+--------------------------------+----------+ 424| ``x << n`` | *x* shifted left by *n* bits | (1)(2) | 425+------------+--------------------------------+----------+ 426| ``x >> n`` | *x* shifted right by *n* bits | (1)(3) | 427+------------+--------------------------------+----------+ 428| ``~x`` | the bits of *x* inverted | | 429+------------+--------------------------------+----------+ 430 431Notes: 432 433(1) 434 Negative shift counts are illegal and cause a :exc:`ValueError` to be raised. 435 436(2) 437 A left shift by *n* bits is equivalent to multiplication by ``pow(2, n)``. 438 439(3) 440 A right shift by *n* bits is equivalent to floor division by ``pow(2, n)``. 441 442(4) 443 Performing these calculations with at least one extra sign extension bit in 444 a finite two's complement representation (a working bit-width of 445 ``1 + max(x.bit_length(), y.bit_length())`` or more) is sufficient to get the 446 same result as if there were an infinite number of sign bits. 447 448 449Additional Methods on Integer Types 450----------------------------------- 451 452The int type implements the :class:`numbers.Integral` :term:`abstract base 453class`. In addition, it provides a few more methods: 454 455.. method:: int.bit_length() 456 457 Return the number of bits necessary to represent an integer in binary, 458 excluding the sign and leading zeros:: 459 460 >>> n = -37 461 >>> bin(n) 462 '-0b100101' 463 >>> n.bit_length() 464 6 465 466 More precisely, if ``x`` is nonzero, then ``x.bit_length()`` is the 467 unique positive integer ``k`` such that ``2**(k-1) <= abs(x) < 2**k``. 468 Equivalently, when ``abs(x)`` is small enough to have a correctly 469 rounded logarithm, then ``k = 1 + int(log(abs(x), 2))``. 470 If ``x`` is zero, then ``x.bit_length()`` returns ``0``. 471 472 Equivalent to:: 473 474 def bit_length(self): 475 s = bin(self) # binary representation: bin(-37) --> '-0b100101' 476 s = s.lstrip('-0b') # remove leading zeros and minus sign 477 return len(s) # len('100101') --> 6 478 479 .. versionadded:: 3.1 480 481.. method:: int.to_bytes(length, byteorder, *, signed=False) 482 483 Return an array of bytes representing an integer. 484 485 >>> (1024).to_bytes(2, byteorder='big') 486 b'\x04\x00' 487 >>> (1024).to_bytes(10, byteorder='big') 488 b'\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00' 489 >>> (-1024).to_bytes(10, byteorder='big', signed=True) 490 b'\xff\xff\xff\xff\xff\xff\xff\xff\xfc\x00' 491 >>> x = 1000 492 >>> x.to_bytes((x.bit_length() + 7) // 8, byteorder='little') 493 b'\xe8\x03' 494 495 The integer is represented using *length* bytes. An :exc:`OverflowError` 496 is raised if the integer is not representable with the given number of 497 bytes. 498 499 The *byteorder* argument determines the byte order used to represent the 500 integer. If *byteorder* is ``"big"``, the most significant byte is at the 501 beginning of the byte array. If *byteorder* is ``"little"``, the most 502 significant byte is at the end of the byte array. To request the native 503 byte order of the host system, use :data:`sys.byteorder` as the byte order 504 value. 505 506 The *signed* argument determines whether two's complement is used to 507 represent the integer. If *signed* is ``False`` and a negative integer is 508 given, an :exc:`OverflowError` is raised. The default value for *signed* 509 is ``False``. 510 511 .. versionadded:: 3.2 512 513.. classmethod:: int.from_bytes(bytes, byteorder, *, signed=False) 514 515 Return the integer represented by the given array of bytes. 516 517 >>> int.from_bytes(b'\x00\x10', byteorder='big') 518 16 519 >>> int.from_bytes(b'\x00\x10', byteorder='little') 520 4096 521 >>> int.from_bytes(b'\xfc\x00', byteorder='big', signed=True) 522 -1024 523 >>> int.from_bytes(b'\xfc\x00', byteorder='big', signed=False) 524 64512 525 >>> int.from_bytes([255, 0, 0], byteorder='big') 526 16711680 527 528 The argument *bytes* must either be a :term:`bytes-like object` or an 529 iterable producing bytes. 530 531 The *byteorder* argument determines the byte order used to represent the 532 integer. If *byteorder* is ``"big"``, the most significant byte is at the 533 beginning of the byte array. If *byteorder* is ``"little"``, the most 534 significant byte is at the end of the byte array. To request the native 535 byte order of the host system, use :data:`sys.byteorder` as the byte order 536 value. 537 538 The *signed* argument indicates whether two's complement is used to 539 represent the integer. 540 541 .. versionadded:: 3.2 542 543.. method:: int.as_integer_ratio() 544 545 Return a pair of integers whose ratio is exactly equal to the original 546 integer and with a positive denominator. The integer ratio of integers 547 (whole numbers) is always the integer as the numerator and ``1`` as the 548 denominator. 549 550 .. versionadded:: 3.8 551 552Additional Methods on Float 553--------------------------- 554 555The float type implements the :class:`numbers.Real` :term:`abstract base 556class`. float also has the following additional methods. 557 558.. method:: float.as_integer_ratio() 559 560 Return a pair of integers whose ratio is exactly equal to the 561 original float and with a positive denominator. Raises 562 :exc:`OverflowError` on infinities and a :exc:`ValueError` on 563 NaNs. 564 565.. method:: float.is_integer() 566 567 Return ``True`` if the float instance is finite with integral 568 value, and ``False`` otherwise:: 569 570 >>> (-2.0).is_integer() 571 True 572 >>> (3.2).is_integer() 573 False 574 575Two methods support conversion to 576and from hexadecimal strings. Since Python's floats are stored 577internally as binary numbers, converting a float to or from a 578*decimal* string usually involves a small rounding error. In 579contrast, hexadecimal strings allow exact representation and 580specification of floating-point numbers. This can be useful when 581debugging, and in numerical work. 582 583 584.. method:: float.hex() 585 586 Return a representation of a floating-point number as a hexadecimal 587 string. For finite floating-point numbers, this representation 588 will always include a leading ``0x`` and a trailing ``p`` and 589 exponent. 590 591 592.. classmethod:: float.fromhex(s) 593 594 Class method to return the float represented by a hexadecimal 595 string *s*. The string *s* may have leading and trailing 596 whitespace. 597 598 599Note that :meth:`float.hex` is an instance method, while 600:meth:`float.fromhex` is a class method. 601 602A hexadecimal string takes the form:: 603 604 [sign] ['0x'] integer ['.' fraction] ['p' exponent] 605 606where the optional ``sign`` may by either ``+`` or ``-``, ``integer`` 607and ``fraction`` are strings of hexadecimal digits, and ``exponent`` 608is a decimal integer with an optional leading sign. Case is not 609significant, and there must be at least one hexadecimal digit in 610either the integer or the fraction. This syntax is similar to the 611syntax specified in section 6.4.4.2 of the C99 standard, and also to 612the syntax used in Java 1.5 onwards. In particular, the output of 613:meth:`float.hex` is usable as a hexadecimal floating-point literal in 614C or Java code, and hexadecimal strings produced by C's ``%a`` format 615character or Java's ``Double.toHexString`` are accepted by 616:meth:`float.fromhex`. 617 618 619Note that the exponent is written in decimal rather than hexadecimal, 620and that it gives the power of 2 by which to multiply the coefficient. 621For example, the hexadecimal string ``0x3.a7p10`` represents the 622floating-point number ``(3 + 10./16 + 7./16**2) * 2.0**10``, or 623``3740.0``:: 624 625 >>> float.fromhex('0x3.a7p10') 626 3740.0 627 628 629Applying the reverse conversion to ``3740.0`` gives a different 630hexadecimal string representing the same number:: 631 632 >>> float.hex(3740.0) 633 '0x1.d380000000000p+11' 634 635 636.. _numeric-hash: 637 638Hashing of numeric types 639------------------------ 640 641For numbers ``x`` and ``y``, possibly of different types, it's a requirement 642that ``hash(x) == hash(y)`` whenever ``x == y`` (see the :meth:`__hash__` 643method documentation for more details). For ease of implementation and 644efficiency across a variety of numeric types (including :class:`int`, 645:class:`float`, :class:`decimal.Decimal` and :class:`fractions.Fraction`) 646Python's hash for numeric types is based on a single mathematical function 647that's defined for any rational number, and hence applies to all instances of 648:class:`int` and :class:`fractions.Fraction`, and all finite instances of 649:class:`float` and :class:`decimal.Decimal`. Essentially, this function is 650given by reduction modulo ``P`` for a fixed prime ``P``. The value of ``P`` is 651made available to Python as the :attr:`modulus` attribute of 652:data:`sys.hash_info`. 653 654.. impl-detail:: 655 656 Currently, the prime used is ``P = 2**31 - 1`` on machines with 32-bit C 657 longs and ``P = 2**61 - 1`` on machines with 64-bit C longs. 658 659Here are the rules in detail: 660 661- If ``x = m / n`` is a nonnegative rational number and ``n`` is not divisible 662 by ``P``, define ``hash(x)`` as ``m * invmod(n, P) % P``, where ``invmod(n, 663 P)`` gives the inverse of ``n`` modulo ``P``. 664 665- If ``x = m / n`` is a nonnegative rational number and ``n`` is 666 divisible by ``P`` (but ``m`` is not) then ``n`` has no inverse 667 modulo ``P`` and the rule above doesn't apply; in this case define 668 ``hash(x)`` to be the constant value ``sys.hash_info.inf``. 669 670- If ``x = m / n`` is a negative rational number define ``hash(x)`` 671 as ``-hash(-x)``. If the resulting hash is ``-1``, replace it with 672 ``-2``. 673 674- The particular values ``sys.hash_info.inf``, ``-sys.hash_info.inf`` 675 and ``sys.hash_info.nan`` are used as hash values for positive 676 infinity, negative infinity, or nans (respectively). (All hashable 677 nans have the same hash value.) 678 679- For a :class:`complex` number ``z``, the hash values of the real 680 and imaginary parts are combined by computing ``hash(z.real) + 681 sys.hash_info.imag * hash(z.imag)``, reduced modulo 682 ``2**sys.hash_info.width`` so that it lies in 683 ``range(-2**(sys.hash_info.width - 1), 2**(sys.hash_info.width - 684 1))``. Again, if the result is ``-1``, it's replaced with ``-2``. 685 686 687To clarify the above rules, here's some example Python code, 688equivalent to the built-in hash, for computing the hash of a rational 689number, :class:`float`, or :class:`complex`:: 690 691 692 import sys, math 693 694 def hash_fraction(m, n): 695 """Compute the hash of a rational number m / n. 696 697 Assumes m and n are integers, with n positive. 698 Equivalent to hash(fractions.Fraction(m, n)). 699 700 """ 701 P = sys.hash_info.modulus 702 # Remove common factors of P. (Unnecessary if m and n already coprime.) 703 while m % P == n % P == 0: 704 m, n = m // P, n // P 705 706 if n % P == 0: 707 hash_value = sys.hash_info.inf 708 else: 709 # Fermat's Little Theorem: pow(n, P-1, P) is 1, so 710 # pow(n, P-2, P) gives the inverse of n modulo P. 711 hash_value = (abs(m) % P) * pow(n, P - 2, P) % P 712 if m < 0: 713 hash_value = -hash_value 714 if hash_value == -1: 715 hash_value = -2 716 return hash_value 717 718 def hash_float(x): 719 """Compute the hash of a float x.""" 720 721 if math.isnan(x): 722 return sys.hash_info.nan 723 elif math.isinf(x): 724 return sys.hash_info.inf if x > 0 else -sys.hash_info.inf 725 else: 726 return hash_fraction(*x.as_integer_ratio()) 727 728 def hash_complex(z): 729 """Compute the hash of a complex number z.""" 730 731 hash_value = hash_float(z.real) + sys.hash_info.imag * hash_float(z.imag) 732 # do a signed reduction modulo 2**sys.hash_info.width 733 M = 2**(sys.hash_info.width - 1) 734 hash_value = (hash_value & (M - 1)) - (hash_value & M) 735 if hash_value == -1: 736 hash_value = -2 737 return hash_value 738 739.. _typeiter: 740 741Iterator Types 742============== 743 744.. index:: 745 single: iterator protocol 746 single: protocol; iterator 747 single: sequence; iteration 748 single: container; iteration over 749 750Python supports a concept of iteration over containers. This is implemented 751using two distinct methods; these are used to allow user-defined classes to 752support iteration. Sequences, described below in more detail, always support 753the iteration methods. 754 755One method needs to be defined for container objects to provide iteration 756support: 757 758.. XXX duplicated in reference/datamodel! 759 760.. method:: container.__iter__() 761 762 Return an iterator object. The object is required to support the iterator 763 protocol described below. If a container supports different types of 764 iteration, additional methods can be provided to specifically request 765 iterators for those iteration types. (An example of an object supporting 766 multiple forms of iteration would be a tree structure which supports both 767 breadth-first and depth-first traversal.) This method corresponds to the 768 :c:member:`~PyTypeObject.tp_iter` slot of the type structure for Python objects in the Python/C 769 API. 770 771The iterator objects themselves are required to support the following two 772methods, which together form the :dfn:`iterator protocol`: 773 774 775.. method:: iterator.__iter__() 776 777 Return the iterator object itself. This is required to allow both containers 778 and iterators to be used with the :keyword:`for` and :keyword:`in` statements. 779 This method corresponds to the :c:member:`~PyTypeObject.tp_iter` slot of the type structure for 780 Python objects in the Python/C API. 781 782 783.. method:: iterator.__next__() 784 785 Return the next item from the container. If there are no further items, raise 786 the :exc:`StopIteration` exception. This method corresponds to the 787 :c:member:`~PyTypeObject.tp_iternext` slot of the type structure for Python objects in the 788 Python/C API. 789 790Python defines several iterator objects to support iteration over general and 791specific sequence types, dictionaries, and other more specialized forms. The 792specific types are not important beyond their implementation of the iterator 793protocol. 794 795Once an iterator's :meth:`~iterator.__next__` method raises 796:exc:`StopIteration`, it must continue to do so on subsequent calls. 797Implementations that do not obey this property are deemed broken. 798 799 800.. _generator-types: 801 802Generator Types 803--------------- 804 805Python's :term:`generator`\s provide a convenient way to implement the iterator 806protocol. If a container object's :meth:`__iter__` method is implemented as a 807generator, it will automatically return an iterator object (technically, a 808generator object) supplying the :meth:`__iter__` and :meth:`~generator.__next__` 809methods. 810More information about generators can be found in :ref:`the documentation for 811the yield expression <yieldexpr>`. 812 813 814.. _typesseq: 815 816Sequence Types --- :class:`list`, :class:`tuple`, :class:`range` 817================================================================ 818 819There are three basic sequence types: lists, tuples, and range objects. 820Additional sequence types tailored for processing of 821:ref:`binary data <binaryseq>` and :ref:`text strings <textseq>` are 822described in dedicated sections. 823 824 825.. _typesseq-common: 826 827Common Sequence Operations 828-------------------------- 829 830.. index:: object: sequence 831 832The operations in the following table are supported by most sequence types, 833both mutable and immutable. The :class:`collections.abc.Sequence` ABC is 834provided to make it easier to correctly implement these operations on 835custom sequence types. 836 837This table lists the sequence operations sorted in ascending priority. In the 838table, *s* and *t* are sequences of the same type, *n*, *i*, *j* and *k* are 839integers and *x* is an arbitrary object that meets any type and value 840restrictions imposed by *s*. 841 842The ``in`` and ``not in`` operations have the same priorities as the 843comparison operations. The ``+`` (concatenation) and ``*`` (repetition) 844operations have the same priority as the corresponding numeric operations. [3]_ 845 846.. index:: 847 triple: operations on; sequence; types 848 builtin: len 849 builtin: min 850 builtin: max 851 pair: concatenation; operation 852 pair: repetition; operation 853 pair: subscript; operation 854 pair: slice; operation 855 operator: in 856 operator: not in 857 single: count() (sequence method) 858 single: index() (sequence method) 859 860+--------------------------+--------------------------------+----------+ 861| Operation | Result | Notes | 862+==========================+================================+==========+ 863| ``x in s`` | ``True`` if an item of *s* is | \(1) | 864| | equal to *x*, else ``False`` | | 865+--------------------------+--------------------------------+----------+ 866| ``x not in s`` | ``False`` if an item of *s* is | \(1) | 867| | equal to *x*, else ``True`` | | 868+--------------------------+--------------------------------+----------+ 869| ``s + t`` | the concatenation of *s* and | (6)(7) | 870| | *t* | | 871+--------------------------+--------------------------------+----------+ 872| ``s * n`` or | equivalent to adding *s* to | (2)(7) | 873| ``n * s`` | itself *n* times | | 874+--------------------------+--------------------------------+----------+ 875| ``s[i]`` | *i*\ th item of *s*, origin 0 | \(3) | 876+--------------------------+--------------------------------+----------+ 877| ``s[i:j]`` | slice of *s* from *i* to *j* | (3)(4) | 878+--------------------------+--------------------------------+----------+ 879| ``s[i:j:k]`` | slice of *s* from *i* to *j* | (3)(5) | 880| | with step *k* | | 881+--------------------------+--------------------------------+----------+ 882| ``len(s)`` | length of *s* | | 883+--------------------------+--------------------------------+----------+ 884| ``min(s)`` | smallest item of *s* | | 885+--------------------------+--------------------------------+----------+ 886| ``max(s)`` | largest item of *s* | | 887+--------------------------+--------------------------------+----------+ 888| ``s.index(x[, i[, j]])`` | index of the first occurrence | \(8) | 889| | of *x* in *s* (at or after | | 890| | index *i* and before index *j*)| | 891+--------------------------+--------------------------------+----------+ 892| ``s.count(x)`` | total number of occurrences of | | 893| | *x* in *s* | | 894+--------------------------+--------------------------------+----------+ 895 896Sequences of the same type also support comparisons. In particular, tuples 897and lists are compared lexicographically by comparing corresponding elements. 898This means that to compare equal, every element must compare equal and the 899two sequences must be of the same type and have the same length. (For full 900details see :ref:`comparisons` in the language reference.) 901 902Notes: 903 904(1) 905 While the ``in`` and ``not in`` operations are used only for simple 906 containment testing in the general case, some specialised sequences 907 (such as :class:`str`, :class:`bytes` and :class:`bytearray`) also use 908 them for subsequence testing:: 909 910 >>> "gg" in "eggs" 911 True 912 913(2) 914 Values of *n* less than ``0`` are treated as ``0`` (which yields an empty 915 sequence of the same type as *s*). Note that items in the sequence *s* 916 are not copied; they are referenced multiple times. This often haunts 917 new Python programmers; consider:: 918 919 >>> lists = [[]] * 3 920 >>> lists 921 [[], [], []] 922 >>> lists[0].append(3) 923 >>> lists 924 [[3], [3], [3]] 925 926 What has happened is that ``[[]]`` is a one-element list containing an empty 927 list, so all three elements of ``[[]] * 3`` are references to this single empty 928 list. Modifying any of the elements of ``lists`` modifies this single list. 929 You can create a list of different lists this way:: 930 931 >>> lists = [[] for i in range(3)] 932 >>> lists[0].append(3) 933 >>> lists[1].append(5) 934 >>> lists[2].append(7) 935 >>> lists 936 [[3], [5], [7]] 937 938 Further explanation is available in the FAQ entry 939 :ref:`faq-multidimensional-list`. 940 941(3) 942 If *i* or *j* is negative, the index is relative to the end of sequence *s*: 943 ``len(s) + i`` or ``len(s) + j`` is substituted. But note that ``-0`` is 944 still ``0``. 945 946(4) 947 The slice of *s* from *i* to *j* is defined as the sequence of items with index 948 *k* such that ``i <= k < j``. If *i* or *j* is greater than ``len(s)``, use 949 ``len(s)``. If *i* is omitted or ``None``, use ``0``. If *j* is omitted or 950 ``None``, use ``len(s)``. If *i* is greater than or equal to *j*, the slice is 951 empty. 952 953(5) 954 The slice of *s* from *i* to *j* with step *k* is defined as the sequence of 955 items with index ``x = i + n*k`` such that ``0 <= n < (j-i)/k``. In other words, 956 the indices are ``i``, ``i+k``, ``i+2*k``, ``i+3*k`` and so on, stopping when 957 *j* is reached (but never including *j*). When *k* is positive, 958 *i* and *j* are reduced to ``len(s)`` if they are greater. 959 When *k* is negative, *i* and *j* are reduced to ``len(s) - 1`` if 960 they are greater. If *i* or *j* are omitted or ``None``, they become 961 "end" values (which end depends on the sign of *k*). Note, *k* cannot be zero. 962 If *k* is ``None``, it is treated like ``1``. 963 964(6) 965 Concatenating immutable sequences always results in a new object. This 966 means that building up a sequence by repeated concatenation will have a 967 quadratic runtime cost in the total sequence length. To get a linear 968 runtime cost, you must switch to one of the alternatives below: 969 970 * if concatenating :class:`str` objects, you can build a list and use 971 :meth:`str.join` at the end or else write to an :class:`io.StringIO` 972 instance and retrieve its value when complete 973 974 * if concatenating :class:`bytes` objects, you can similarly use 975 :meth:`bytes.join` or :class:`io.BytesIO`, or you can do in-place 976 concatenation with a :class:`bytearray` object. :class:`bytearray` 977 objects are mutable and have an efficient overallocation mechanism 978 979 * if concatenating :class:`tuple` objects, extend a :class:`list` instead 980 981 * for other types, investigate the relevant class documentation 982 983 984(7) 985 Some sequence types (such as :class:`range`) only support item sequences 986 that follow specific patterns, and hence don't support sequence 987 concatenation or repetition. 988 989(8) 990 ``index`` raises :exc:`ValueError` when *x* is not found in *s*. 991 Not all implementations support passing the additional arguments *i* and *j*. 992 These arguments allow efficient searching of subsections of the sequence. Passing 993 the extra arguments is roughly equivalent to using ``s[i:j].index(x)``, only 994 without copying any data and with the returned index being relative to 995 the start of the sequence rather than the start of the slice. 996 997 998.. _typesseq-immutable: 999 1000Immutable Sequence Types 1001------------------------ 1002 1003.. index:: 1004 triple: immutable; sequence; types 1005 object: tuple 1006 builtin: hash 1007 1008The only operation that immutable sequence types generally implement that is 1009not also implemented by mutable sequence types is support for the :func:`hash` 1010built-in. 1011 1012This support allows immutable sequences, such as :class:`tuple` instances, to 1013be used as :class:`dict` keys and stored in :class:`set` and :class:`frozenset` 1014instances. 1015 1016Attempting to hash an immutable sequence that contains unhashable values will 1017result in :exc:`TypeError`. 1018 1019 1020.. _typesseq-mutable: 1021 1022Mutable Sequence Types 1023---------------------- 1024 1025.. index:: 1026 triple: mutable; sequence; types 1027 object: list 1028 object: bytearray 1029 1030The operations in the following table are defined on mutable sequence types. 1031The :class:`collections.abc.MutableSequence` ABC is provided to make it 1032easier to correctly implement these operations on custom sequence types. 1033 1034In the table *s* is an instance of a mutable sequence type, *t* is any 1035iterable object and *x* is an arbitrary object that meets any type 1036and value restrictions imposed by *s* (for example, :class:`bytearray` only 1037accepts integers that meet the value restriction ``0 <= x <= 255``). 1038 1039 1040.. index:: 1041 triple: operations on; sequence; types 1042 triple: operations on; list; type 1043 pair: subscript; assignment 1044 pair: slice; assignment 1045 statement: del 1046 single: append() (sequence method) 1047 single: clear() (sequence method) 1048 single: copy() (sequence method) 1049 single: extend() (sequence method) 1050 single: insert() (sequence method) 1051 single: pop() (sequence method) 1052 single: remove() (sequence method) 1053 single: reverse() (sequence method) 1054 1055+------------------------------+--------------------------------+---------------------+ 1056| Operation | Result | Notes | 1057+==============================+================================+=====================+ 1058| ``s[i] = x`` | item *i* of *s* is replaced by | | 1059| | *x* | | 1060+------------------------------+--------------------------------+---------------------+ 1061| ``s[i:j] = t`` | slice of *s* from *i* to *j* | | 1062| | is replaced by the contents of | | 1063| | the iterable *t* | | 1064+------------------------------+--------------------------------+---------------------+ 1065| ``del s[i:j]`` | same as ``s[i:j] = []`` | | 1066+------------------------------+--------------------------------+---------------------+ 1067| ``s[i:j:k] = t`` | the elements of ``s[i:j:k]`` | \(1) | 1068| | are replaced by those of *t* | | 1069+------------------------------+--------------------------------+---------------------+ 1070| ``del s[i:j:k]`` | removes the elements of | | 1071| | ``s[i:j:k]`` from the list | | 1072+------------------------------+--------------------------------+---------------------+ 1073| ``s.append(x)`` | appends *x* to the end of the | | 1074| | sequence (same as | | 1075| | ``s[len(s):len(s)] = [x]``) | | 1076+------------------------------+--------------------------------+---------------------+ 1077| ``s.clear()`` | removes all items from *s* | \(5) | 1078| | (same as ``del s[:]``) | | 1079+------------------------------+--------------------------------+---------------------+ 1080| ``s.copy()`` | creates a shallow copy of *s* | \(5) | 1081| | (same as ``s[:]``) | | 1082+------------------------------+--------------------------------+---------------------+ 1083| ``s.extend(t)`` or | extends *s* with the | | 1084| ``s += t`` | contents of *t* (for the | | 1085| | most part the same as | | 1086| | ``s[len(s):len(s)] = t``) | | 1087+------------------------------+--------------------------------+---------------------+ 1088| ``s *= n`` | updates *s* with its contents | \(6) | 1089| | repeated *n* times | | 1090+------------------------------+--------------------------------+---------------------+ 1091| ``s.insert(i, x)`` | inserts *x* into *s* at the | | 1092| | index given by *i* | | 1093| | (same as ``s[i:i] = [x]``) | | 1094+------------------------------+--------------------------------+---------------------+ 1095| ``s.pop()`` or ``s.pop(i)`` | retrieves the item at *i* and | \(2) | 1096| | also removes it from *s* | | 1097+------------------------------+--------------------------------+---------------------+ 1098| ``s.remove(x)`` | remove the first item from *s* | \(3) | 1099| | where ``s[i]`` is equal to *x* | | 1100+------------------------------+--------------------------------+---------------------+ 1101| ``s.reverse()`` | reverses the items of *s* in | \(4) | 1102| | place | | 1103+------------------------------+--------------------------------+---------------------+ 1104 1105 1106Notes: 1107 1108(1) 1109 *t* must have the same length as the slice it is replacing. 1110 1111(2) 1112 The optional argument *i* defaults to ``-1``, so that by default the last 1113 item is removed and returned. 1114 1115(3) 1116 :meth:`remove` raises :exc:`ValueError` when *x* is not found in *s*. 1117 1118(4) 1119 The :meth:`reverse` method modifies the sequence in place for economy of 1120 space when reversing a large sequence. To remind users that it operates by 1121 side effect, it does not return the reversed sequence. 1122 1123(5) 1124 :meth:`clear` and :meth:`!copy` are included for consistency with the 1125 interfaces of mutable containers that don't support slicing operations 1126 (such as :class:`dict` and :class:`set`). :meth:`!copy` is not part of the 1127 :class:`collections.abc.MutableSequence` ABC, but most concrete 1128 mutable sequence classes provide it. 1129 1130 .. versionadded:: 3.3 1131 :meth:`clear` and :meth:`!copy` methods. 1132 1133(6) 1134 The value *n* is an integer, or an object implementing 1135 :meth:`~object.__index__`. Zero and negative values of *n* clear 1136 the sequence. Items in the sequence are not copied; they are referenced 1137 multiple times, as explained for ``s * n`` under :ref:`typesseq-common`. 1138 1139 1140.. _typesseq-list: 1141 1142Lists 1143----- 1144 1145.. index:: object: list 1146 1147Lists are mutable sequences, typically used to store collections of 1148homogeneous items (where the precise degree of similarity will vary by 1149application). 1150 1151.. class:: list([iterable]) 1152 1153 Lists may be constructed in several ways: 1154 1155 * Using a pair of square brackets to denote the empty list: ``[]`` 1156 * Using square brackets, separating items with commas: ``[a]``, ``[a, b, c]`` 1157 * Using a list comprehension: ``[x for x in iterable]`` 1158 * Using the type constructor: ``list()`` or ``list(iterable)`` 1159 1160 The constructor builds a list whose items are the same and in the same 1161 order as *iterable*'s items. *iterable* may be either a sequence, a 1162 container that supports iteration, or an iterator object. If *iterable* 1163 is already a list, a copy is made and returned, similar to ``iterable[:]``. 1164 For example, ``list('abc')`` returns ``['a', 'b', 'c']`` and 1165 ``list( (1, 2, 3) )`` returns ``[1, 2, 3]``. 1166 If no argument is given, the constructor creates a new empty list, ``[]``. 1167 1168 1169 Many other operations also produce lists, including the :func:`sorted` 1170 built-in. 1171 1172 Lists implement all of the :ref:`common <typesseq-common>` and 1173 :ref:`mutable <typesseq-mutable>` sequence operations. Lists also provide the 1174 following additional method: 1175 1176 .. method:: list.sort(*, key=None, reverse=False) 1177 1178 This method sorts the list in place, using only ``<`` comparisons 1179 between items. Exceptions are not suppressed - if any comparison operations 1180 fail, the entire sort operation will fail (and the list will likely be left 1181 in a partially modified state). 1182 1183 :meth:`sort` accepts two arguments that can only be passed by keyword 1184 (:ref:`keyword-only arguments <keyword-only_parameter>`): 1185 1186 *key* specifies a function of one argument that is used to extract a 1187 comparison key from each list element (for example, ``key=str.lower``). 1188 The key corresponding to each item in the list is calculated once and 1189 then used for the entire sorting process. The default value of ``None`` 1190 means that list items are sorted directly without calculating a separate 1191 key value. 1192 1193 The :func:`functools.cmp_to_key` utility is available to convert a 2.x 1194 style *cmp* function to a *key* function. 1195 1196 *reverse* is a boolean value. If set to ``True``, then the list elements 1197 are sorted as if each comparison were reversed. 1198 1199 This method modifies the sequence in place for economy of space when 1200 sorting a large sequence. To remind users that it operates by side 1201 effect, it does not return the sorted sequence (use :func:`sorted` to 1202 explicitly request a new sorted list instance). 1203 1204 The :meth:`sort` method is guaranteed to be stable. A sort is stable if it 1205 guarantees not to change the relative order of elements that compare equal 1206 --- this is helpful for sorting in multiple passes (for example, sort by 1207 department, then by salary grade). 1208 1209 For sorting examples and a brief sorting tutorial, see :ref:`sortinghowto`. 1210 1211 .. impl-detail:: 1212 1213 While a list is being sorted, the effect of attempting to mutate, or even 1214 inspect, the list is undefined. The C implementation of Python makes the 1215 list appear empty for the duration, and raises :exc:`ValueError` if it can 1216 detect that the list has been mutated during a sort. 1217 1218 1219.. _typesseq-tuple: 1220 1221Tuples 1222------ 1223 1224.. index:: object: tuple 1225 1226Tuples are immutable sequences, typically used to store collections of 1227heterogeneous data (such as the 2-tuples produced by the :func:`enumerate` 1228built-in). Tuples are also used for cases where an immutable sequence of 1229homogeneous data is needed (such as allowing storage in a :class:`set` or 1230:class:`dict` instance). 1231 1232.. class:: tuple([iterable]) 1233 1234 Tuples may be constructed in a number of ways: 1235 1236 * Using a pair of parentheses to denote the empty tuple: ``()`` 1237 * Using a trailing comma for a singleton tuple: ``a,`` or ``(a,)`` 1238 * Separating items with commas: ``a, b, c`` or ``(a, b, c)`` 1239 * Using the :func:`tuple` built-in: ``tuple()`` or ``tuple(iterable)`` 1240 1241 The constructor builds a tuple whose items are the same and in the same 1242 order as *iterable*'s items. *iterable* may be either a sequence, a 1243 container that supports iteration, or an iterator object. If *iterable* 1244 is already a tuple, it is returned unchanged. For example, 1245 ``tuple('abc')`` returns ``('a', 'b', 'c')`` and 1246 ``tuple( [1, 2, 3] )`` returns ``(1, 2, 3)``. 1247 If no argument is given, the constructor creates a new empty tuple, ``()``. 1248 1249 Note that it is actually the comma which makes a tuple, not the parentheses. 1250 The parentheses are optional, except in the empty tuple case, or 1251 when they are needed to avoid syntactic ambiguity. For example, 1252 ``f(a, b, c)`` is a function call with three arguments, while 1253 ``f((a, b, c))`` is a function call with a 3-tuple as the sole argument. 1254 1255 Tuples implement all of the :ref:`common <typesseq-common>` sequence 1256 operations. 1257 1258For heterogeneous collections of data where access by name is clearer than 1259access by index, :func:`collections.namedtuple` may be a more appropriate 1260choice than a simple tuple object. 1261 1262 1263.. _typesseq-range: 1264 1265Ranges 1266------ 1267 1268.. index:: object: range 1269 1270The :class:`range` type represents an immutable sequence of numbers and is 1271commonly used for looping a specific number of times in :keyword:`for` 1272loops. 1273 1274.. class:: range(stop) 1275 range(start, stop[, step]) 1276 1277 The arguments to the range constructor must be integers (either built-in 1278 :class:`int` or any object that implements the ``__index__`` special 1279 method). If the *step* argument is omitted, it defaults to ``1``. 1280 If the *start* argument is omitted, it defaults to ``0``. 1281 If *step* is zero, :exc:`ValueError` is raised. 1282 1283 For a positive *step*, the contents of a range ``r`` are determined by the 1284 formula ``r[i] = start + step*i`` where ``i >= 0`` and 1285 ``r[i] < stop``. 1286 1287 For a negative *step*, the contents of the range are still determined by 1288 the formula ``r[i] = start + step*i``, but the constraints are ``i >= 0`` 1289 and ``r[i] > stop``. 1290 1291 A range object will be empty if ``r[0]`` does not meet the value 1292 constraint. Ranges do support negative indices, but these are interpreted 1293 as indexing from the end of the sequence determined by the positive 1294 indices. 1295 1296 Ranges containing absolute values larger than :data:`sys.maxsize` are 1297 permitted but some features (such as :func:`len`) may raise 1298 :exc:`OverflowError`. 1299 1300 Range examples:: 1301 1302 >>> list(range(10)) 1303 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] 1304 >>> list(range(1, 11)) 1305 [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] 1306 >>> list(range(0, 30, 5)) 1307 [0, 5, 10, 15, 20, 25] 1308 >>> list(range(0, 10, 3)) 1309 [0, 3, 6, 9] 1310 >>> list(range(0, -10, -1)) 1311 [0, -1, -2, -3, -4, -5, -6, -7, -8, -9] 1312 >>> list(range(0)) 1313 [] 1314 >>> list(range(1, 0)) 1315 [] 1316 1317 Ranges implement all of the :ref:`common <typesseq-common>` sequence operations 1318 except concatenation and repetition (due to the fact that range objects can 1319 only represent sequences that follow a strict pattern and repetition and 1320 concatenation will usually violate that pattern). 1321 1322 .. attribute:: start 1323 1324 The value of the *start* parameter (or ``0`` if the parameter was 1325 not supplied) 1326 1327 .. attribute:: stop 1328 1329 The value of the *stop* parameter 1330 1331 .. attribute:: step 1332 1333 The value of the *step* parameter (or ``1`` if the parameter was 1334 not supplied) 1335 1336The advantage of the :class:`range` type over a regular :class:`list` or 1337:class:`tuple` is that a :class:`range` object will always take the same 1338(small) amount of memory, no matter the size of the range it represents (as it 1339only stores the ``start``, ``stop`` and ``step`` values, calculating individual 1340items and subranges as needed). 1341 1342Range objects implement the :class:`collections.abc.Sequence` ABC, and provide 1343features such as containment tests, element index lookup, slicing and 1344support for negative indices (see :ref:`typesseq`): 1345 1346 >>> r = range(0, 20, 2) 1347 >>> r 1348 range(0, 20, 2) 1349 >>> 11 in r 1350 False 1351 >>> 10 in r 1352 True 1353 >>> r.index(10) 1354 5 1355 >>> r[5] 1356 10 1357 >>> r[:5] 1358 range(0, 10, 2) 1359 >>> r[-1] 1360 18 1361 1362Testing range objects for equality with ``==`` and ``!=`` compares 1363them as sequences. That is, two range objects are considered equal if 1364they represent the same sequence of values. (Note that two range 1365objects that compare equal might have different :attr:`~range.start`, 1366:attr:`~range.stop` and :attr:`~range.step` attributes, for example 1367``range(0) == range(2, 1, 3)`` or ``range(0, 3, 2) == range(0, 4, 2)``.) 1368 1369.. versionchanged:: 3.2 1370 Implement the Sequence ABC. 1371 Support slicing and negative indices. 1372 Test :class:`int` objects for membership in constant time instead of 1373 iterating through all items. 1374 1375.. versionchanged:: 3.3 1376 Define '==' and '!=' to compare range objects based on the 1377 sequence of values they define (instead of comparing based on 1378 object identity). 1379 1380.. versionadded:: 3.3 1381 The :attr:`~range.start`, :attr:`~range.stop` and :attr:`~range.step` 1382 attributes. 1383 1384.. seealso:: 1385 1386 * The `linspace recipe <http://code.activestate.com/recipes/579000/>`_ 1387 shows how to implement a lazy version of range suitable for floating 1388 point applications. 1389 1390.. index:: 1391 single: string; text sequence type 1392 single: str (built-in class); (see also string) 1393 object: string 1394 1395.. _textseq: 1396 1397Text Sequence Type --- :class:`str` 1398=================================== 1399 1400Textual data in Python is handled with :class:`str` objects, or :dfn:`strings`. 1401Strings are immutable 1402:ref:`sequences <typesseq>` of Unicode code points. String literals are 1403written in a variety of ways: 1404 1405* Single quotes: ``'allows embedded "double" quotes'`` 1406* Double quotes: ``"allows embedded 'single' quotes"``. 1407* Triple quoted: ``'''Three single quotes'''``, ``"""Three double quotes"""`` 1408 1409Triple quoted strings may span multiple lines - all associated whitespace will 1410be included in the string literal. 1411 1412String literals that are part of a single expression and have only whitespace 1413between them will be implicitly converted to a single string literal. That 1414is, ``("spam " "eggs") == "spam eggs"``. 1415 1416See :ref:`strings` for more about the various forms of string literal, 1417including supported escape sequences, and the ``r`` ("raw") prefix that 1418disables most escape sequence processing. 1419 1420Strings may also be created from other objects using the :class:`str` 1421constructor. 1422 1423Since there is no separate "character" type, indexing a string produces 1424strings of length 1. That is, for a non-empty string *s*, ``s[0] == s[0:1]``. 1425 1426.. index:: 1427 object: io.StringIO 1428 1429There is also no mutable string type, but :meth:`str.join` or 1430:class:`io.StringIO` can be used to efficiently construct strings from 1431multiple fragments. 1432 1433.. versionchanged:: 3.3 1434 For backwards compatibility with the Python 2 series, the ``u`` prefix is 1435 once again permitted on string literals. It has no effect on the meaning 1436 of string literals and cannot be combined with the ``r`` prefix. 1437 1438 1439.. index:: 1440 single: string; str (built-in class) 1441 1442.. class:: str(object='') 1443 str(object=b'', encoding='utf-8', errors='strict') 1444 1445 Return a :ref:`string <textseq>` version of *object*. If *object* is not 1446 provided, returns the empty string. Otherwise, the behavior of ``str()`` 1447 depends on whether *encoding* or *errors* is given, as follows. 1448 1449 If neither *encoding* nor *errors* is given, ``str(object)`` returns 1450 :meth:`object.__str__() <object.__str__>`, which is the "informal" or nicely 1451 printable string representation of *object*. For string objects, this is 1452 the string itself. If *object* does not have a :meth:`~object.__str__` 1453 method, then :func:`str` falls back to returning 1454 :meth:`repr(object) <repr>`. 1455 1456 .. index:: 1457 single: buffer protocol; str (built-in class) 1458 single: bytes; str (built-in class) 1459 1460 If at least one of *encoding* or *errors* is given, *object* should be a 1461 :term:`bytes-like object` (e.g. :class:`bytes` or :class:`bytearray`). In 1462 this case, if *object* is a :class:`bytes` (or :class:`bytearray`) object, 1463 then ``str(bytes, encoding, errors)`` is equivalent to 1464 :meth:`bytes.decode(encoding, errors) <bytes.decode>`. Otherwise, the bytes 1465 object underlying the buffer object is obtained before calling 1466 :meth:`bytes.decode`. See :ref:`binaryseq` and 1467 :ref:`bufferobjects` for information on buffer objects. 1468 1469 Passing a :class:`bytes` object to :func:`str` without the *encoding* 1470 or *errors* arguments falls under the first case of returning the informal 1471 string representation (see also the :option:`-b` command-line option to 1472 Python). For example:: 1473 1474 >>> str(b'Zoot!') 1475 "b'Zoot!'" 1476 1477 For more information on the ``str`` class and its methods, see 1478 :ref:`textseq` and the :ref:`string-methods` section below. To output 1479 formatted strings, see the :ref:`f-strings` and :ref:`formatstrings` 1480 sections. In addition, see the :ref:`stringservices` section. 1481 1482 1483.. index:: 1484 pair: string; methods 1485 1486.. _string-methods: 1487 1488String Methods 1489-------------- 1490 1491.. index:: 1492 module: re 1493 1494Strings implement all of the :ref:`common <typesseq-common>` sequence 1495operations, along with the additional methods described below. 1496 1497Strings also support two styles of string formatting, one providing a large 1498degree of flexibility and customization (see :meth:`str.format`, 1499:ref:`formatstrings` and :ref:`string-formatting`) and the other based on C 1500``printf`` style formatting that handles a narrower range of types and is 1501slightly harder to use correctly, but is often faster for the cases it can 1502handle (:ref:`old-string-formatting`). 1503 1504The :ref:`textservices` section of the standard library covers a number of 1505other modules that provide various text related utilities (including regular 1506expression support in the :mod:`re` module). 1507 1508.. method:: str.capitalize() 1509 1510 Return a copy of the string with its first character capitalized and the 1511 rest lowercased. 1512 1513 .. versionchanged:: 3.8 1514 The first character is now put into titlecase rather than uppercase. 1515 This means that characters like digraphs will only have their first 1516 letter capitalized, instead of the full character. 1517 1518.. method:: str.casefold() 1519 1520 Return a casefolded copy of the string. Casefolded strings may be used for 1521 caseless matching. 1522 1523 Casefolding is similar to lowercasing but more aggressive because it is 1524 intended to remove all case distinctions in a string. For example, the German 1525 lowercase letter ``'ß'`` is equivalent to ``"ss"``. Since it is already 1526 lowercase, :meth:`lower` would do nothing to ``'ß'``; :meth:`casefold` 1527 converts it to ``"ss"``. 1528 1529 The casefolding algorithm is described in section 3.13 of the Unicode 1530 Standard. 1531 1532 .. versionadded:: 3.3 1533 1534 1535.. method:: str.center(width[, fillchar]) 1536 1537 Return centered in a string of length *width*. Padding is done using the 1538 specified *fillchar* (default is an ASCII space). The original string is 1539 returned if *width* is less than or equal to ``len(s)``. 1540 1541 1542 1543.. method:: str.count(sub[, start[, end]]) 1544 1545 Return the number of non-overlapping occurrences of substring *sub* in the 1546 range [*start*, *end*]. Optional arguments *start* and *end* are 1547 interpreted as in slice notation. 1548 1549 1550.. method:: str.encode(encoding="utf-8", errors="strict") 1551 1552 Return an encoded version of the string as a bytes object. Default encoding 1553 is ``'utf-8'``. *errors* may be given to set a different error handling scheme. 1554 The default for *errors* is ``'strict'``, meaning that encoding errors raise 1555 a :exc:`UnicodeError`. Other possible 1556 values are ``'ignore'``, ``'replace'``, ``'xmlcharrefreplace'``, 1557 ``'backslashreplace'`` and any other name registered via 1558 :func:`codecs.register_error`, see section :ref:`error-handlers`. For a 1559 list of possible encodings, see section :ref:`standard-encodings`. 1560 1561 .. versionchanged:: 3.1 1562 Support for keyword arguments added. 1563 1564 1565.. method:: str.endswith(suffix[, start[, end]]) 1566 1567 Return ``True`` if the string ends with the specified *suffix*, otherwise return 1568 ``False``. *suffix* can also be a tuple of suffixes to look for. With optional 1569 *start*, test beginning at that position. With optional *end*, stop comparing 1570 at that position. 1571 1572 1573.. method:: str.expandtabs(tabsize=8) 1574 1575 Return a copy of the string where all tab characters are replaced by one or 1576 more spaces, depending on the current column and the given tab size. Tab 1577 positions occur every *tabsize* characters (default is 8, giving tab 1578 positions at columns 0, 8, 16 and so on). To expand the string, the current 1579 column is set to zero and the string is examined character by character. If 1580 the character is a tab (``\t``), one or more space characters are inserted 1581 in the result until the current column is equal to the next tab position. 1582 (The tab character itself is not copied.) If the character is a newline 1583 (``\n``) or return (``\r``), it is copied and the current column is reset to 1584 zero. Any other character is copied unchanged and the current column is 1585 incremented by one regardless of how the character is represented when 1586 printed. 1587 1588 >>> '01\t012\t0123\t01234'.expandtabs() 1589 '01 012 0123 01234' 1590 >>> '01\t012\t0123\t01234'.expandtabs(4) 1591 '01 012 0123 01234' 1592 1593 1594.. method:: str.find(sub[, start[, end]]) 1595 1596 Return the lowest index in the string where substring *sub* is found within 1597 the slice ``s[start:end]``. Optional arguments *start* and *end* are 1598 interpreted as in slice notation. Return ``-1`` if *sub* is not found. 1599 1600 .. note:: 1601 1602 The :meth:`~str.find` method should be used only if you need to know the 1603 position of *sub*. To check if *sub* is a substring or not, use the 1604 :keyword:`in` operator:: 1605 1606 >>> 'Py' in 'Python' 1607 True 1608 1609 1610.. method:: str.format(*args, **kwargs) 1611 1612 Perform a string formatting operation. The string on which this method is 1613 called can contain literal text or replacement fields delimited by braces 1614 ``{}``. Each replacement field contains either the numeric index of a 1615 positional argument, or the name of a keyword argument. Returns a copy of 1616 the string where each replacement field is replaced with the string value of 1617 the corresponding argument. 1618 1619 >>> "The sum of 1 + 2 is {0}".format(1+2) 1620 'The sum of 1 + 2 is 3' 1621 1622 See :ref:`formatstrings` for a description of the various formatting options 1623 that can be specified in format strings. 1624 1625 .. note:: 1626 When formatting a number (:class:`int`, :class:`float`, :class:`complex`, 1627 :class:`decimal.Decimal` and subclasses) with the ``n`` type 1628 (ex: ``'{:n}'.format(1234)``), the function temporarily sets the 1629 ``LC_CTYPE`` locale to the ``LC_NUMERIC`` locale to decode 1630 ``decimal_point`` and ``thousands_sep`` fields of :c:func:`localeconv` if 1631 they are non-ASCII or longer than 1 byte, and the ``LC_NUMERIC`` locale is 1632 different than the ``LC_CTYPE`` locale. This temporary change affects 1633 other threads. 1634 1635 .. versionchanged:: 3.7 1636 When formatting a number with the ``n`` type, the function sets 1637 temporarily the ``LC_CTYPE`` locale to the ``LC_NUMERIC`` locale in some 1638 cases. 1639 1640 1641.. method:: str.format_map(mapping) 1642 1643 Similar to ``str.format(**mapping)``, except that ``mapping`` is 1644 used directly and not copied to a :class:`dict`. This is useful 1645 if for example ``mapping`` is a dict subclass: 1646 1647 >>> class Default(dict): 1648 ... def __missing__(self, key): 1649 ... return key 1650 ... 1651 >>> '{name} was born in {country}'.format_map(Default(name='Guido')) 1652 'Guido was born in country' 1653 1654 .. versionadded:: 3.2 1655 1656 1657.. method:: str.index(sub[, start[, end]]) 1658 1659 Like :meth:`~str.find`, but raise :exc:`ValueError` when the substring is 1660 not found. 1661 1662 1663.. method:: str.isalnum() 1664 1665 Return ``True`` if all characters in the string are alphanumeric and there is at 1666 least one character, ``False`` otherwise. A character ``c`` is alphanumeric if one 1667 of the following returns ``True``: ``c.isalpha()``, ``c.isdecimal()``, 1668 ``c.isdigit()``, or ``c.isnumeric()``. 1669 1670 1671.. method:: str.isalpha() 1672 1673 Return ``True`` if all characters in the string are alphabetic and there is at least 1674 one character, ``False`` otherwise. Alphabetic characters are those characters defined 1675 in the Unicode character database as "Letter", i.e., those with general category 1676 property being one of "Lm", "Lt", "Lu", "Ll", or "Lo". Note that this is different 1677 from the "Alphabetic" property defined in the Unicode Standard. 1678 1679 1680.. method:: str.isascii() 1681 1682 Return ``True`` if the string is empty or all characters in the string are ASCII, 1683 ``False`` otherwise. 1684 ASCII characters have code points in the range U+0000-U+007F. 1685 1686 .. versionadded:: 3.7 1687 1688 1689.. method:: str.isdecimal() 1690 1691 Return ``True`` if all characters in the string are decimal 1692 characters and there is at least one character, ``False`` 1693 otherwise. Decimal characters are those that can be used to form 1694 numbers in base 10, e.g. U+0660, ARABIC-INDIC DIGIT 1695 ZERO. Formally a decimal character is a character in the Unicode 1696 General Category "Nd". 1697 1698 1699.. method:: str.isdigit() 1700 1701 Return ``True`` if all characters in the string are digits and there is at least one 1702 character, ``False`` otherwise. Digits include decimal characters and digits that need 1703 special handling, such as the compatibility superscript digits. 1704 This covers digits which cannot be used to form numbers in base 10, 1705 like the Kharosthi numbers. Formally, a digit is a character that has the 1706 property value Numeric_Type=Digit or Numeric_Type=Decimal. 1707 1708 1709.. method:: str.isidentifier() 1710 1711 Return ``True`` if the string is a valid identifier according to the language 1712 definition, section :ref:`identifiers`. 1713 1714 Call :func:`keyword.iskeyword` to test whether string ``s`` is a reserved 1715 identifier, such as :keyword:`def` and :keyword:`class`. 1716 1717 Example: 1718 :: 1719 1720 >>> from keyword import iskeyword 1721 1722 >>> 'hello'.isidentifier(), iskeyword('hello') 1723 True, False 1724 >>> 'def'.isidentifier(), iskeyword('def') 1725 True, True 1726 1727 1728.. method:: str.islower() 1729 1730 Return ``True`` if all cased characters [4]_ in the string are lowercase and 1731 there is at least one cased character, ``False`` otherwise. 1732 1733 1734.. method:: str.isnumeric() 1735 1736 Return ``True`` if all characters in the string are numeric 1737 characters, and there is at least one character, ``False`` 1738 otherwise. Numeric characters include digit characters, and all characters 1739 that have the Unicode numeric value property, e.g. U+2155, 1740 VULGAR FRACTION ONE FIFTH. Formally, numeric characters are those with the property 1741 value Numeric_Type=Digit, Numeric_Type=Decimal or Numeric_Type=Numeric. 1742 1743 1744.. method:: str.isprintable() 1745 1746 Return ``True`` if all characters in the string are printable or the string is 1747 empty, ``False`` otherwise. Nonprintable characters are those characters defined 1748 in the Unicode character database as "Other" or "Separator", excepting the 1749 ASCII space (0x20) which is considered printable. (Note that printable 1750 characters in this context are those which should not be escaped when 1751 :func:`repr` is invoked on a string. It has no bearing on the handling of 1752 strings written to :data:`sys.stdout` or :data:`sys.stderr`.) 1753 1754 1755.. method:: str.isspace() 1756 1757 Return ``True`` if there are only whitespace characters in the string and there is 1758 at least one character, ``False`` otherwise. 1759 1760 A character is *whitespace* if in the Unicode character database 1761 (see :mod:`unicodedata`), either its general category is ``Zs`` 1762 ("Separator, space"), or its bidirectional class is one of ``WS``, 1763 ``B``, or ``S``. 1764 1765 1766.. method:: str.istitle() 1767 1768 Return ``True`` if the string is a titlecased string and there is at least one 1769 character, for example uppercase characters may only follow uncased characters 1770 and lowercase characters only cased ones. Return ``False`` otherwise. 1771 1772 1773.. method:: str.isupper() 1774 1775 Return ``True`` if all cased characters [4]_ in the string are uppercase and 1776 there is at least one cased character, ``False`` otherwise. 1777 1778 1779.. method:: str.join(iterable) 1780 1781 Return a string which is the concatenation of the strings in *iterable*. 1782 A :exc:`TypeError` will be raised if there are any non-string values in 1783 *iterable*, including :class:`bytes` objects. The separator between 1784 elements is the string providing this method. 1785 1786 1787.. method:: str.ljust(width[, fillchar]) 1788 1789 Return the string left justified in a string of length *width*. Padding is 1790 done using the specified *fillchar* (default is an ASCII space). The 1791 original string is returned if *width* is less than or equal to ``len(s)``. 1792 1793 1794.. method:: str.lower() 1795 1796 Return a copy of the string with all the cased characters [4]_ converted to 1797 lowercase. 1798 1799 The lowercasing algorithm used is described in section 3.13 of the Unicode 1800 Standard. 1801 1802 1803.. method:: str.lstrip([chars]) 1804 1805 Return a copy of the string with leading characters removed. The *chars* 1806 argument is a string specifying the set of characters to be removed. If omitted 1807 or ``None``, the *chars* argument defaults to removing whitespace. The *chars* 1808 argument is not a prefix; rather, all combinations of its values are stripped:: 1809 1810 >>> ' spacious '.lstrip() 1811 'spacious ' 1812 >>> 'www.example.com'.lstrip('cmowz.') 1813 'example.com' 1814 1815 1816.. staticmethod:: str.maketrans(x[, y[, z]]) 1817 1818 This static method returns a translation table usable for :meth:`str.translate`. 1819 1820 If there is only one argument, it must be a dictionary mapping Unicode 1821 ordinals (integers) or characters (strings of length 1) to Unicode ordinals, 1822 strings (of arbitrary lengths) or ``None``. Character keys will then be 1823 converted to ordinals. 1824 1825 If there are two arguments, they must be strings of equal length, and in the 1826 resulting dictionary, each character in x will be mapped to the character at 1827 the same position in y. If there is a third argument, it must be a string, 1828 whose characters will be mapped to ``None`` in the result. 1829 1830 1831.. method:: str.partition(sep) 1832 1833 Split the string at the first occurrence of *sep*, and return a 3-tuple 1834 containing the part before the separator, the separator itself, and the part 1835 after the separator. If the separator is not found, return a 3-tuple containing 1836 the string itself, followed by two empty strings. 1837 1838 1839.. method:: str.replace(old, new[, count]) 1840 1841 Return a copy of the string with all occurrences of substring *old* replaced by 1842 *new*. If the optional argument *count* is given, only the first *count* 1843 occurrences are replaced. 1844 1845 1846.. method:: str.rfind(sub[, start[, end]]) 1847 1848 Return the highest index in the string where substring *sub* is found, such 1849 that *sub* is contained within ``s[start:end]``. Optional arguments *start* 1850 and *end* are interpreted as in slice notation. Return ``-1`` on failure. 1851 1852 1853.. method:: str.rindex(sub[, start[, end]]) 1854 1855 Like :meth:`rfind` but raises :exc:`ValueError` when the substring *sub* is not 1856 found. 1857 1858 1859.. method:: str.rjust(width[, fillchar]) 1860 1861 Return the string right justified in a string of length *width*. Padding is 1862 done using the specified *fillchar* (default is an ASCII space). The 1863 original string is returned if *width* is less than or equal to ``len(s)``. 1864 1865 1866.. method:: str.rpartition(sep) 1867 1868 Split the string at the last occurrence of *sep*, and return a 3-tuple 1869 containing the part before the separator, the separator itself, and the part 1870 after the separator. If the separator is not found, return a 3-tuple containing 1871 two empty strings, followed by the string itself. 1872 1873 1874.. method:: str.rsplit(sep=None, maxsplit=-1) 1875 1876 Return a list of the words in the string, using *sep* as the delimiter string. 1877 If *maxsplit* is given, at most *maxsplit* splits are done, the *rightmost* 1878 ones. If *sep* is not specified or ``None``, any whitespace string is a 1879 separator. Except for splitting from the right, :meth:`rsplit` behaves like 1880 :meth:`split` which is described in detail below. 1881 1882 1883.. method:: str.rstrip([chars]) 1884 1885 Return a copy of the string with trailing characters removed. The *chars* 1886 argument is a string specifying the set of characters to be removed. If omitted 1887 or ``None``, the *chars* argument defaults to removing whitespace. The *chars* 1888 argument is not a suffix; rather, all combinations of its values are stripped:: 1889 1890 >>> ' spacious '.rstrip() 1891 ' spacious' 1892 >>> 'mississippi'.rstrip('ipz') 1893 'mississ' 1894 1895 1896.. method:: str.split(sep=None, maxsplit=-1) 1897 1898 Return a list of the words in the string, using *sep* as the delimiter 1899 string. If *maxsplit* is given, at most *maxsplit* splits are done (thus, 1900 the list will have at most ``maxsplit+1`` elements). If *maxsplit* is not 1901 specified or ``-1``, then there is no limit on the number of splits 1902 (all possible splits are made). 1903 1904 If *sep* is given, consecutive delimiters are not grouped together and are 1905 deemed to delimit empty strings (for example, ``'1,,2'.split(',')`` returns 1906 ``['1', '', '2']``). The *sep* argument may consist of multiple characters 1907 (for example, ``'1<>2<>3'.split('<>')`` returns ``['1', '2', '3']``). 1908 Splitting an empty string with a specified separator returns ``['']``. 1909 1910 For example:: 1911 1912 >>> '1,2,3'.split(',') 1913 ['1', '2', '3'] 1914 >>> '1,2,3'.split(',', maxsplit=1) 1915 ['1', '2,3'] 1916 >>> '1,2,,3,'.split(',') 1917 ['1', '2', '', '3', ''] 1918 1919 If *sep* is not specified or is ``None``, a different splitting algorithm is 1920 applied: runs of consecutive whitespace are regarded as a single separator, 1921 and the result will contain no empty strings at the start or end if the 1922 string has leading or trailing whitespace. Consequently, splitting an empty 1923 string or a string consisting of just whitespace with a ``None`` separator 1924 returns ``[]``. 1925 1926 For example:: 1927 1928 >>> '1 2 3'.split() 1929 ['1', '2', '3'] 1930 >>> '1 2 3'.split(maxsplit=1) 1931 ['1', '2 3'] 1932 >>> ' 1 2 3 '.split() 1933 ['1', '2', '3'] 1934 1935 1936.. index:: 1937 single: universal newlines; str.splitlines method 1938 1939.. method:: str.splitlines([keepends]) 1940 1941 Return a list of the lines in the string, breaking at line boundaries. Line 1942 breaks are not included in the resulting list unless *keepends* is given and 1943 true. 1944 1945 This method splits on the following line boundaries. In particular, the 1946 boundaries are a superset of :term:`universal newlines`. 1947 1948 +-----------------------+-----------------------------+ 1949 | Representation | Description | 1950 +=======================+=============================+ 1951 | ``\n`` | Line Feed | 1952 +-----------------------+-----------------------------+ 1953 | ``\r`` | Carriage Return | 1954 +-----------------------+-----------------------------+ 1955 | ``\r\n`` | Carriage Return + Line Feed | 1956 +-----------------------+-----------------------------+ 1957 | ``\v`` or ``\x0b`` | Line Tabulation | 1958 +-----------------------+-----------------------------+ 1959 | ``\f`` or ``\x0c`` | Form Feed | 1960 +-----------------------+-----------------------------+ 1961 | ``\x1c`` | File Separator | 1962 +-----------------------+-----------------------------+ 1963 | ``\x1d`` | Group Separator | 1964 +-----------------------+-----------------------------+ 1965 | ``\x1e`` | Record Separator | 1966 +-----------------------+-----------------------------+ 1967 | ``\x85`` | Next Line (C1 Control Code) | 1968 +-----------------------+-----------------------------+ 1969 | ``\u2028`` | Line Separator | 1970 +-----------------------+-----------------------------+ 1971 | ``\u2029`` | Paragraph Separator | 1972 +-----------------------+-----------------------------+ 1973 1974 .. versionchanged:: 3.2 1975 1976 ``\v`` and ``\f`` added to list of line boundaries. 1977 1978 For example:: 1979 1980 >>> 'ab c\n\nde fg\rkl\r\n'.splitlines() 1981 ['ab c', '', 'de fg', 'kl'] 1982 >>> 'ab c\n\nde fg\rkl\r\n'.splitlines(keepends=True) 1983 ['ab c\n', '\n', 'de fg\r', 'kl\r\n'] 1984 1985 Unlike :meth:`~str.split` when a delimiter string *sep* is given, this 1986 method returns an empty list for the empty string, and a terminal line 1987 break does not result in an extra line:: 1988 1989 >>> "".splitlines() 1990 [] 1991 >>> "One line\n".splitlines() 1992 ['One line'] 1993 1994 For comparison, ``split('\n')`` gives:: 1995 1996 >>> ''.split('\n') 1997 [''] 1998 >>> 'Two lines\n'.split('\n') 1999 ['Two lines', ''] 2000 2001 2002.. method:: str.startswith(prefix[, start[, end]]) 2003 2004 Return ``True`` if string starts with the *prefix*, otherwise return ``False``. 2005 *prefix* can also be a tuple of prefixes to look for. With optional *start*, 2006 test string beginning at that position. With optional *end*, stop comparing 2007 string at that position. 2008 2009 2010.. method:: str.strip([chars]) 2011 2012 Return a copy of the string with the leading and trailing characters removed. 2013 The *chars* argument is a string specifying the set of characters to be removed. 2014 If omitted or ``None``, the *chars* argument defaults to removing whitespace. 2015 The *chars* argument is not a prefix or suffix; rather, all combinations of its 2016 values are stripped:: 2017 2018 >>> ' spacious '.strip() 2019 'spacious' 2020 >>> 'www.example.com'.strip('cmowz.') 2021 'example' 2022 2023 The outermost leading and trailing *chars* argument values are stripped 2024 from the string. Characters are removed from the leading end until 2025 reaching a string character that is not contained in the set of 2026 characters in *chars*. A similar action takes place on the trailing end. 2027 For example:: 2028 2029 >>> comment_string = '#....... Section 3.2.1 Issue #32 .......' 2030 >>> comment_string.strip('.#! ') 2031 'Section 3.2.1 Issue #32' 2032 2033 2034.. method:: str.swapcase() 2035 2036 Return a copy of the string with uppercase characters converted to lowercase and 2037 vice versa. Note that it is not necessarily true that 2038 ``s.swapcase().swapcase() == s``. 2039 2040 2041.. method:: str.title() 2042 2043 Return a titlecased version of the string where words start with an uppercase 2044 character and the remaining characters are lowercase. 2045 2046 For example:: 2047 2048 >>> 'Hello world'.title() 2049 'Hello World' 2050 2051 The algorithm uses a simple language-independent definition of a word as 2052 groups of consecutive letters. The definition works in many contexts but 2053 it means that apostrophes in contractions and possessives form word 2054 boundaries, which may not be the desired result:: 2055 2056 >>> "they're bill's friends from the UK".title() 2057 "They'Re Bill'S Friends From The Uk" 2058 2059 A workaround for apostrophes can be constructed using regular expressions:: 2060 2061 >>> import re 2062 >>> def titlecase(s): 2063 ... return re.sub(r"[A-Za-z]+('[A-Za-z]+)?", 2064 ... lambda mo: mo.group(0).capitalize(), 2065 ... s) 2066 ... 2067 >>> titlecase("they're bill's friends.") 2068 "They're Bill's Friends." 2069 2070 2071.. method:: str.translate(table) 2072 2073 Return a copy of the string in which each character has been mapped through 2074 the given translation table. The table must be an object that implements 2075 indexing via :meth:`__getitem__`, typically a :term:`mapping` or 2076 :term:`sequence`. When indexed by a Unicode ordinal (an integer), the 2077 table object can do any of the following: return a Unicode ordinal or a 2078 string, to map the character to one or more other characters; return 2079 ``None``, to delete the character from the return string; or raise a 2080 :exc:`LookupError` exception, to map the character to itself. 2081 2082 You can use :meth:`str.maketrans` to create a translation map from 2083 character-to-character mappings in different formats. 2084 2085 See also the :mod:`codecs` module for a more flexible approach to custom 2086 character mappings. 2087 2088 2089.. method:: str.upper() 2090 2091 Return a copy of the string with all the cased characters [4]_ converted to 2092 uppercase. Note that ``s.upper().isupper()`` might be ``False`` if ``s`` 2093 contains uncased characters or if the Unicode category of the resulting 2094 character(s) is not "Lu" (Letter, uppercase), but e.g. "Lt" (Letter, 2095 titlecase). 2096 2097 The uppercasing algorithm used is described in section 3.13 of the Unicode 2098 Standard. 2099 2100 2101.. method:: str.zfill(width) 2102 2103 Return a copy of the string left filled with ASCII ``'0'`` digits to 2104 make a string of length *width*. A leading sign prefix (``'+'``/``'-'``) 2105 is handled by inserting the padding *after* the sign character rather 2106 than before. The original string is returned if *width* is less than 2107 or equal to ``len(s)``. 2108 2109 For example:: 2110 2111 >>> "42".zfill(5) 2112 '00042' 2113 >>> "-42".zfill(5) 2114 '-0042' 2115 2116 2117 2118.. _old-string-formatting: 2119 2120``printf``-style String Formatting 2121---------------------------------- 2122 2123.. index:: 2124 single: formatting, string (%) 2125 single: interpolation, string (%) 2126 single: string; formatting, printf 2127 single: string; interpolation, printf 2128 single: printf-style formatting 2129 single: sprintf-style formatting 2130 single: % (percent); printf-style formatting 2131 2132.. note:: 2133 2134 The formatting operations described here exhibit a variety of quirks that 2135 lead to a number of common errors (such as failing to display tuples and 2136 dictionaries correctly). Using the newer :ref:`formatted string literals 2137 <f-strings>`, the :meth:`str.format` interface, or :ref:`template strings 2138 <template-strings>` may help avoid these errors. Each of these 2139 alternatives provides their own trade-offs and benefits of simplicity, 2140 flexibility, and/or extensibility. 2141 2142String objects have one unique built-in operation: the ``%`` operator (modulo). 2143This is also known as the string *formatting* or *interpolation* operator. 2144Given ``format % values`` (where *format* is a string), ``%`` conversion 2145specifications in *format* are replaced with zero or more elements of *values*. 2146The effect is similar to using the :c:func:`sprintf` in the C language. 2147 2148If *format* requires a single argument, *values* may be a single non-tuple 2149object. [5]_ Otherwise, *values* must be a tuple with exactly the number of 2150items specified by the format string, or a single mapping object (for example, a 2151dictionary). 2152 2153.. index:: 2154 single: () (parentheses); in printf-style formatting 2155 single: * (asterisk); in printf-style formatting 2156 single: . (dot); in printf-style formatting 2157 2158A conversion specifier contains two or more characters and has the following 2159components, which must occur in this order: 2160 2161#. The ``'%'`` character, which marks the start of the specifier. 2162 2163#. Mapping key (optional), consisting of a parenthesised sequence of characters 2164 (for example, ``(somename)``). 2165 2166#. Conversion flags (optional), which affect the result of some conversion 2167 types. 2168 2169#. Minimum field width (optional). If specified as an ``'*'`` (asterisk), the 2170 actual width is read from the next element of the tuple in *values*, and the 2171 object to convert comes after the minimum field width and optional precision. 2172 2173#. Precision (optional), given as a ``'.'`` (dot) followed by the precision. If 2174 specified as ``'*'`` (an asterisk), the actual precision is read from the next 2175 element of the tuple in *values*, and the value to convert comes after the 2176 precision. 2177 2178#. Length modifier (optional). 2179 2180#. Conversion type. 2181 2182When the right argument is a dictionary (or other mapping type), then the 2183formats in the string *must* include a parenthesised mapping key into that 2184dictionary inserted immediately after the ``'%'`` character. The mapping key 2185selects the value to be formatted from the mapping. For example: 2186 2187 >>> print('%(language)s has %(number)03d quote types.' % 2188 ... {'language': "Python", "number": 2}) 2189 Python has 002 quote types. 2190 2191In this case no ``*`` specifiers may occur in a format (since they require a 2192sequential parameter list). 2193 2194The conversion flag characters are: 2195 2196.. index:: 2197 single: # (hash); in printf-style formatting 2198 single: - (minus); in printf-style formatting 2199 single: + (plus); in printf-style formatting 2200 single: space; in printf-style formatting 2201 2202+---------+---------------------------------------------------------------------+ 2203| Flag | Meaning | 2204+=========+=====================================================================+ 2205| ``'#'`` | The value conversion will use the "alternate form" (where defined | 2206| | below). | 2207+---------+---------------------------------------------------------------------+ 2208| ``'0'`` | The conversion will be zero padded for numeric values. | 2209+---------+---------------------------------------------------------------------+ 2210| ``'-'`` | The converted value is left adjusted (overrides the ``'0'`` | 2211| | conversion if both are given). | 2212+---------+---------------------------------------------------------------------+ 2213| ``' '`` | (a space) A blank should be left before a positive number (or empty | 2214| | string) produced by a signed conversion. | 2215+---------+---------------------------------------------------------------------+ 2216| ``'+'`` | A sign character (``'+'`` or ``'-'``) will precede the conversion | 2217| | (overrides a "space" flag). | 2218+---------+---------------------------------------------------------------------+ 2219 2220A length modifier (``h``, ``l``, or ``L``) may be present, but is ignored as it 2221is not necessary for Python -- so e.g. ``%ld`` is identical to ``%d``. 2222 2223The conversion types are: 2224 2225+------------+-----------------------------------------------------+-------+ 2226| Conversion | Meaning | Notes | 2227+============+=====================================================+=======+ 2228| ``'d'`` | Signed integer decimal. | | 2229+------------+-----------------------------------------------------+-------+ 2230| ``'i'`` | Signed integer decimal. | | 2231+------------+-----------------------------------------------------+-------+ 2232| ``'o'`` | Signed octal value. | \(1) | 2233+------------+-----------------------------------------------------+-------+ 2234| ``'u'`` | Obsolete type -- it is identical to ``'d'``. | \(6) | 2235+------------+-----------------------------------------------------+-------+ 2236| ``'x'`` | Signed hexadecimal (lowercase). | \(2) | 2237+------------+-----------------------------------------------------+-------+ 2238| ``'X'`` | Signed hexadecimal (uppercase). | \(2) | 2239+------------+-----------------------------------------------------+-------+ 2240| ``'e'`` | Floating point exponential format (lowercase). | \(3) | 2241+------------+-----------------------------------------------------+-------+ 2242| ``'E'`` | Floating point exponential format (uppercase). | \(3) | 2243+------------+-----------------------------------------------------+-------+ 2244| ``'f'`` | Floating point decimal format. | \(3) | 2245+------------+-----------------------------------------------------+-------+ 2246| ``'F'`` | Floating point decimal format. | \(3) | 2247+------------+-----------------------------------------------------+-------+ 2248| ``'g'`` | Floating point format. Uses lowercase exponential | \(4) | 2249| | format if exponent is less than -4 or not less than | | 2250| | precision, decimal format otherwise. | | 2251+------------+-----------------------------------------------------+-------+ 2252| ``'G'`` | Floating point format. Uses uppercase exponential | \(4) | 2253| | format if exponent is less than -4 or not less than | | 2254| | precision, decimal format otherwise. | | 2255+------------+-----------------------------------------------------+-------+ 2256| ``'c'`` | Single character (accepts integer or single | | 2257| | character string). | | 2258+------------+-----------------------------------------------------+-------+ 2259| ``'r'`` | String (converts any Python object using | \(5) | 2260| | :func:`repr`). | | 2261+------------+-----------------------------------------------------+-------+ 2262| ``'s'`` | String (converts any Python object using | \(5) | 2263| | :func:`str`). | | 2264+------------+-----------------------------------------------------+-------+ 2265| ``'a'`` | String (converts any Python object using | \(5) | 2266| | :func:`ascii`). | | 2267+------------+-----------------------------------------------------+-------+ 2268| ``'%'`` | No argument is converted, results in a ``'%'`` | | 2269| | character in the result. | | 2270+------------+-----------------------------------------------------+-------+ 2271 2272Notes: 2273 2274(1) 2275 The alternate form causes a leading octal specifier (``'0o'``) to be 2276 inserted before the first digit. 2277 2278(2) 2279 The alternate form causes a leading ``'0x'`` or ``'0X'`` (depending on whether 2280 the ``'x'`` or ``'X'`` format was used) to be inserted before the first digit. 2281 2282(3) 2283 The alternate form causes the result to always contain a decimal point, even if 2284 no digits follow it. 2285 2286 The precision determines the number of digits after the decimal point and 2287 defaults to 6. 2288 2289(4) 2290 The alternate form causes the result to always contain a decimal point, and 2291 trailing zeroes are not removed as they would otherwise be. 2292 2293 The precision determines the number of significant digits before and after the 2294 decimal point and defaults to 6. 2295 2296(5) 2297 If precision is ``N``, the output is truncated to ``N`` characters. 2298 2299(6) 2300 See :pep:`237`. 2301 2302Since Python strings have an explicit length, ``%s`` conversions do not assume 2303that ``'\0'`` is the end of the string. 2304 2305.. XXX Examples? 2306 2307.. versionchanged:: 3.1 2308 ``%f`` conversions for numbers whose absolute value is over 1e50 are no 2309 longer replaced by ``%g`` conversions. 2310 2311 2312.. index:: 2313 single: buffer protocol; binary sequence types 2314 2315.. _binaryseq: 2316 2317Binary Sequence Types --- :class:`bytes`, :class:`bytearray`, :class:`memoryview` 2318================================================================================= 2319 2320.. index:: 2321 object: bytes 2322 object: bytearray 2323 object: memoryview 2324 module: array 2325 2326The core built-in types for manipulating binary data are :class:`bytes` and 2327:class:`bytearray`. They are supported by :class:`memoryview` which uses 2328the :ref:`buffer protocol <bufferobjects>` to access the memory of other 2329binary objects without needing to make a copy. 2330 2331The :mod:`array` module supports efficient storage of basic data types like 233232-bit integers and IEEE754 double-precision floating values. 2333 2334.. _typebytes: 2335 2336Bytes Objects 2337------------- 2338 2339.. index:: object: bytes 2340 2341Bytes objects are immutable sequences of single bytes. Since many major 2342binary protocols are based on the ASCII text encoding, bytes objects offer 2343several methods that are only valid when working with ASCII compatible 2344data and are closely related to string objects in a variety of other ways. 2345 2346.. class:: bytes([source[, encoding[, errors]]]) 2347 2348 Firstly, the syntax for bytes literals is largely the same as that for string 2349 literals, except that a ``b`` prefix is added: 2350 2351 * Single quotes: ``b'still allows embedded "double" quotes'`` 2352 * Double quotes: ``b"still allows embedded 'single' quotes"``. 2353 * Triple quoted: ``b'''3 single quotes'''``, ``b"""3 double quotes"""`` 2354 2355 Only ASCII characters are permitted in bytes literals (regardless of the 2356 declared source code encoding). Any binary values over 127 must be entered 2357 into bytes literals using the appropriate escape sequence. 2358 2359 As with string literals, bytes literals may also use a ``r`` prefix to disable 2360 processing of escape sequences. See :ref:`strings` for more about the various 2361 forms of bytes literal, including supported escape sequences. 2362 2363 While bytes literals and representations are based on ASCII text, bytes 2364 objects actually behave like immutable sequences of integers, with each 2365 value in the sequence restricted such that ``0 <= x < 256`` (attempts to 2366 violate this restriction will trigger :exc:`ValueError`). This is done 2367 deliberately to emphasise that while many binary formats include ASCII based 2368 elements and can be usefully manipulated with some text-oriented algorithms, 2369 this is not generally the case for arbitrary binary data (blindly applying 2370 text processing algorithms to binary data formats that are not ASCII 2371 compatible will usually lead to data corruption). 2372 2373 In addition to the literal forms, bytes objects can be created in a number of 2374 other ways: 2375 2376 * A zero-filled bytes object of a specified length: ``bytes(10)`` 2377 * From an iterable of integers: ``bytes(range(20))`` 2378 * Copying existing binary data via the buffer protocol: ``bytes(obj)`` 2379 2380 Also see the :ref:`bytes <func-bytes>` built-in. 2381 2382 Since 2 hexadecimal digits correspond precisely to a single byte, hexadecimal 2383 numbers are a commonly used format for describing binary data. Accordingly, 2384 the bytes type has an additional class method to read data in that format: 2385 2386 .. classmethod:: fromhex(string) 2387 2388 This :class:`bytes` class method returns a bytes object, decoding the 2389 given string object. The string must contain two hexadecimal digits per 2390 byte, with ASCII whitespace being ignored. 2391 2392 >>> bytes.fromhex('2Ef0 F1f2 ') 2393 b'.\xf0\xf1\xf2' 2394 2395 .. versionchanged:: 3.7 2396 :meth:`bytes.fromhex` now skips all ASCII whitespace in the string, 2397 not just spaces. 2398 2399 A reverse conversion function exists to transform a bytes object into its 2400 hexadecimal representation. 2401 2402 .. method:: hex([sep[, bytes_per_sep]]) 2403 2404 Return a string object containing two hexadecimal digits for each 2405 byte in the instance. 2406 2407 >>> b'\xf0\xf1\xf2'.hex() 2408 'f0f1f2' 2409 2410 If you want to make the hex string easier to read, you can specify a 2411 single character separator *sep* parameter to include in the output. 2412 By default between each byte. A second optional *bytes_per_sep* 2413 parameter controls the spacing. Positive values calculate the 2414 separator position from the right, negative values from the left. 2415 2416 >>> value = b'\xf0\xf1\xf2' 2417 >>> value.hex('-') 2418 'f0-f1-f2' 2419 >>> value.hex('_', 2) 2420 'f0_f1f2' 2421 >>> b'UUDDLRLRAB'.hex(' ', -4) 2422 '55554444 4c524c52 4142' 2423 2424 .. versionadded:: 3.5 2425 2426 .. versionchanged:: 3.8 2427 :meth:`bytes.hex` now supports optional *sep* and *bytes_per_sep* 2428 parameters to insert separators between bytes in the hex output. 2429 2430Since bytes objects are sequences of integers (akin to a tuple), for a bytes 2431object *b*, ``b[0]`` will be an integer, while ``b[0:1]`` will be a bytes 2432object of length 1. (This contrasts with text strings, where both indexing 2433and slicing will produce a string of length 1) 2434 2435The representation of bytes objects uses the literal format (``b'...'``) 2436since it is often more useful than e.g. ``bytes([46, 46, 46])``. You can 2437always convert a bytes object into a list of integers using ``list(b)``. 2438 2439.. note:: 2440 For Python 2.x users: In the Python 2.x series, a variety of implicit 2441 conversions between 8-bit strings (the closest thing 2.x offers to a 2442 built-in binary data type) and Unicode strings were permitted. This was a 2443 backwards compatibility workaround to account for the fact that Python 2444 originally only supported 8-bit text, and Unicode text was a later 2445 addition. In Python 3.x, those implicit conversions are gone - conversions 2446 between 8-bit binary data and Unicode text must be explicit, and bytes and 2447 string objects will always compare unequal. 2448 2449 2450.. _typebytearray: 2451 2452Bytearray Objects 2453----------------- 2454 2455.. index:: object: bytearray 2456 2457:class:`bytearray` objects are a mutable counterpart to :class:`bytes` 2458objects. 2459 2460.. class:: bytearray([source[, encoding[, errors]]]) 2461 2462 There is no dedicated literal syntax for bytearray objects, instead 2463 they are always created by calling the constructor: 2464 2465 * Creating an empty instance: ``bytearray()`` 2466 * Creating a zero-filled instance with a given length: ``bytearray(10)`` 2467 * From an iterable of integers: ``bytearray(range(20))`` 2468 * Copying existing binary data via the buffer protocol: ``bytearray(b'Hi!')`` 2469 2470 As bytearray objects are mutable, they support the 2471 :ref:`mutable <typesseq-mutable>` sequence operations in addition to the 2472 common bytes and bytearray operations described in :ref:`bytes-methods`. 2473 2474 Also see the :ref:`bytearray <func-bytearray>` built-in. 2475 2476 Since 2 hexadecimal digits correspond precisely to a single byte, hexadecimal 2477 numbers are a commonly used format for describing binary data. Accordingly, 2478 the bytearray type has an additional class method to read data in that format: 2479 2480 .. classmethod:: fromhex(string) 2481 2482 This :class:`bytearray` class method returns bytearray object, decoding 2483 the given string object. The string must contain two hexadecimal digits 2484 per byte, with ASCII whitespace being ignored. 2485 2486 >>> bytearray.fromhex('2Ef0 F1f2 ') 2487 bytearray(b'.\xf0\xf1\xf2') 2488 2489 .. versionchanged:: 3.7 2490 :meth:`bytearray.fromhex` now skips all ASCII whitespace in the string, 2491 not just spaces. 2492 2493 A reverse conversion function exists to transform a bytearray object into its 2494 hexadecimal representation. 2495 2496 .. method:: hex([sep[, bytes_per_sep]]) 2497 2498 Return a string object containing two hexadecimal digits for each 2499 byte in the instance. 2500 2501 >>> bytearray(b'\xf0\xf1\xf2').hex() 2502 'f0f1f2' 2503 2504 .. versionadded:: 3.5 2505 2506 .. versionchanged:: 3.8 2507 Similar to :meth:`bytes.hex`, :meth:`bytearray.hex` now supports 2508 optional *sep* and *bytes_per_sep* parameters to insert separators 2509 between bytes in the hex output. 2510 2511Since bytearray objects are sequences of integers (akin to a list), for a 2512bytearray object *b*, ``b[0]`` will be an integer, while ``b[0:1]`` will be 2513a bytearray object of length 1. (This contrasts with text strings, where 2514both indexing and slicing will produce a string of length 1) 2515 2516The representation of bytearray objects uses the bytes literal format 2517(``bytearray(b'...')``) since it is often more useful than e.g. 2518``bytearray([46, 46, 46])``. You can always convert a bytearray object into 2519a list of integers using ``list(b)``. 2520 2521 2522.. _bytes-methods: 2523 2524Bytes and Bytearray Operations 2525------------------------------ 2526 2527.. index:: pair: bytes; methods 2528 pair: bytearray; methods 2529 2530Both bytes and bytearray objects support the :ref:`common <typesseq-common>` 2531sequence operations. They interoperate not just with operands of the same 2532type, but with any :term:`bytes-like object`. Due to this flexibility, they can be 2533freely mixed in operations without causing errors. However, the return type 2534of the result may depend on the order of operands. 2535 2536.. note:: 2537 2538 The methods on bytes and bytearray objects don't accept strings as their 2539 arguments, just as the methods on strings don't accept bytes as their 2540 arguments. For example, you have to write:: 2541 2542 a = "abc" 2543 b = a.replace("a", "f") 2544 2545 and:: 2546 2547 a = b"abc" 2548 b = a.replace(b"a", b"f") 2549 2550Some bytes and bytearray operations assume the use of ASCII compatible 2551binary formats, and hence should be avoided when working with arbitrary 2552binary data. These restrictions are covered below. 2553 2554.. note:: 2555 Using these ASCII based operations to manipulate binary data that is not 2556 stored in an ASCII based format may lead to data corruption. 2557 2558The following methods on bytes and bytearray objects can be used with 2559arbitrary binary data. 2560 2561.. method:: bytes.count(sub[, start[, end]]) 2562 bytearray.count(sub[, start[, end]]) 2563 2564 Return the number of non-overlapping occurrences of subsequence *sub* in 2565 the range [*start*, *end*]. Optional arguments *start* and *end* are 2566 interpreted as in slice notation. 2567 2568 The subsequence to search for may be any :term:`bytes-like object` or an 2569 integer in the range 0 to 255. 2570 2571 .. versionchanged:: 3.3 2572 Also accept an integer in the range 0 to 255 as the subsequence. 2573 2574 2575.. method:: bytes.decode(encoding="utf-8", errors="strict") 2576 bytearray.decode(encoding="utf-8", errors="strict") 2577 2578 Return a string decoded from the given bytes. Default encoding is 2579 ``'utf-8'``. *errors* may be given to set a different 2580 error handling scheme. The default for *errors* is ``'strict'``, meaning 2581 that encoding errors raise a :exc:`UnicodeError`. Other possible values are 2582 ``'ignore'``, ``'replace'`` and any other name registered via 2583 :func:`codecs.register_error`, see section :ref:`error-handlers`. For a 2584 list of possible encodings, see section :ref:`standard-encodings`. 2585 2586 .. note:: 2587 2588 Passing the *encoding* argument to :class:`str` allows decoding any 2589 :term:`bytes-like object` directly, without needing to make a temporary 2590 bytes or bytearray object. 2591 2592 .. versionchanged:: 3.1 2593 Added support for keyword arguments. 2594 2595 2596.. method:: bytes.endswith(suffix[, start[, end]]) 2597 bytearray.endswith(suffix[, start[, end]]) 2598 2599 Return ``True`` if the binary data ends with the specified *suffix*, 2600 otherwise return ``False``. *suffix* can also be a tuple of suffixes to 2601 look for. With optional *start*, test beginning at that position. With 2602 optional *end*, stop comparing at that position. 2603 2604 The suffix(es) to search for may be any :term:`bytes-like object`. 2605 2606 2607.. method:: bytes.find(sub[, start[, end]]) 2608 bytearray.find(sub[, start[, end]]) 2609 2610 Return the lowest index in the data where the subsequence *sub* is found, 2611 such that *sub* is contained in the slice ``s[start:end]``. Optional 2612 arguments *start* and *end* are interpreted as in slice notation. Return 2613 ``-1`` if *sub* is not found. 2614 2615 The subsequence to search for may be any :term:`bytes-like object` or an 2616 integer in the range 0 to 255. 2617 2618 .. note:: 2619 2620 The :meth:`~bytes.find` method should be used only if you need to know the 2621 position of *sub*. To check if *sub* is a substring or not, use the 2622 :keyword:`in` operator:: 2623 2624 >>> b'Py' in b'Python' 2625 True 2626 2627 .. versionchanged:: 3.3 2628 Also accept an integer in the range 0 to 255 as the subsequence. 2629 2630 2631.. method:: bytes.index(sub[, start[, end]]) 2632 bytearray.index(sub[, start[, end]]) 2633 2634 Like :meth:`~bytes.find`, but raise :exc:`ValueError` when the 2635 subsequence is not found. 2636 2637 The subsequence to search for may be any :term:`bytes-like object` or an 2638 integer in the range 0 to 255. 2639 2640 .. versionchanged:: 3.3 2641 Also accept an integer in the range 0 to 255 as the subsequence. 2642 2643 2644.. method:: bytes.join(iterable) 2645 bytearray.join(iterable) 2646 2647 Return a bytes or bytearray object which is the concatenation of the 2648 binary data sequences in *iterable*. A :exc:`TypeError` will be raised 2649 if there are any values in *iterable* that are not :term:`bytes-like 2650 objects <bytes-like object>`, including :class:`str` objects. The 2651 separator between elements is the contents of the bytes or 2652 bytearray object providing this method. 2653 2654 2655.. staticmethod:: bytes.maketrans(from, to) 2656 bytearray.maketrans(from, to) 2657 2658 This static method returns a translation table usable for 2659 :meth:`bytes.translate` that will map each character in *from* into the 2660 character at the same position in *to*; *from* and *to* must both be 2661 :term:`bytes-like objects <bytes-like object>` and have the same length. 2662 2663 .. versionadded:: 3.1 2664 2665 2666.. method:: bytes.partition(sep) 2667 bytearray.partition(sep) 2668 2669 Split the sequence at the first occurrence of *sep*, and return a 3-tuple 2670 containing the part before the separator, the separator itself or its 2671 bytearray copy, and the part after the separator. 2672 If the separator is not found, return a 3-tuple 2673 containing a copy of the original sequence, followed by two empty bytes or 2674 bytearray objects. 2675 2676 The separator to search for may be any :term:`bytes-like object`. 2677 2678 2679.. method:: bytes.replace(old, new[, count]) 2680 bytearray.replace(old, new[, count]) 2681 2682 Return a copy of the sequence with all occurrences of subsequence *old* 2683 replaced by *new*. If the optional argument *count* is given, only the 2684 first *count* occurrences are replaced. 2685 2686 The subsequence to search for and its replacement may be any 2687 :term:`bytes-like object`. 2688 2689 .. note:: 2690 2691 The bytearray version of this method does *not* operate in place - it 2692 always produces a new object, even if no changes were made. 2693 2694 2695.. method:: bytes.rfind(sub[, start[, end]]) 2696 bytearray.rfind(sub[, start[, end]]) 2697 2698 Return the highest index in the sequence where the subsequence *sub* is 2699 found, such that *sub* is contained within ``s[start:end]``. Optional 2700 arguments *start* and *end* are interpreted as in slice notation. Return 2701 ``-1`` on failure. 2702 2703 The subsequence to search for may be any :term:`bytes-like object` or an 2704 integer in the range 0 to 255. 2705 2706 .. versionchanged:: 3.3 2707 Also accept an integer in the range 0 to 255 as the subsequence. 2708 2709 2710.. method:: bytes.rindex(sub[, start[, end]]) 2711 bytearray.rindex(sub[, start[, end]]) 2712 2713 Like :meth:`~bytes.rfind` but raises :exc:`ValueError` when the 2714 subsequence *sub* is not found. 2715 2716 The subsequence to search for may be any :term:`bytes-like object` or an 2717 integer in the range 0 to 255. 2718 2719 .. versionchanged:: 3.3 2720 Also accept an integer in the range 0 to 255 as the subsequence. 2721 2722 2723.. method:: bytes.rpartition(sep) 2724 bytearray.rpartition(sep) 2725 2726 Split the sequence at the last occurrence of *sep*, and return a 3-tuple 2727 containing the part before the separator, the separator itself or its 2728 bytearray copy, and the part after the separator. 2729 If the separator is not found, return a 3-tuple 2730 containing two empty bytes or bytearray objects, followed by a copy of the 2731 original sequence. 2732 2733 The separator to search for may be any :term:`bytes-like object`. 2734 2735 2736.. method:: bytes.startswith(prefix[, start[, end]]) 2737 bytearray.startswith(prefix[, start[, end]]) 2738 2739 Return ``True`` if the binary data starts with the specified *prefix*, 2740 otherwise return ``False``. *prefix* can also be a tuple of prefixes to 2741 look for. With optional *start*, test beginning at that position. With 2742 optional *end*, stop comparing at that position. 2743 2744 The prefix(es) to search for may be any :term:`bytes-like object`. 2745 2746 2747.. method:: bytes.translate(table, /, delete=b'') 2748 bytearray.translate(table, /, delete=b'') 2749 2750 Return a copy of the bytes or bytearray object where all bytes occurring in 2751 the optional argument *delete* are removed, and the remaining bytes have 2752 been mapped through the given translation table, which must be a bytes 2753 object of length 256. 2754 2755 You can use the :func:`bytes.maketrans` method to create a translation 2756 table. 2757 2758 Set the *table* argument to ``None`` for translations that only delete 2759 characters:: 2760 2761 >>> b'read this short text'.translate(None, b'aeiou') 2762 b'rd ths shrt txt' 2763 2764 .. versionchanged:: 3.6 2765 *delete* is now supported as a keyword argument. 2766 2767 2768The following methods on bytes and bytearray objects have default behaviours 2769that assume the use of ASCII compatible binary formats, but can still be used 2770with arbitrary binary data by passing appropriate arguments. Note that all of 2771the bytearray methods in this section do *not* operate in place, and instead 2772produce new objects. 2773 2774.. method:: bytes.center(width[, fillbyte]) 2775 bytearray.center(width[, fillbyte]) 2776 2777 Return a copy of the object centered in a sequence of length *width*. 2778 Padding is done using the specified *fillbyte* (default is an ASCII 2779 space). For :class:`bytes` objects, the original sequence is returned if 2780 *width* is less than or equal to ``len(s)``. 2781 2782 .. note:: 2783 2784 The bytearray version of this method does *not* operate in place - 2785 it always produces a new object, even if no changes were made. 2786 2787 2788.. method:: bytes.ljust(width[, fillbyte]) 2789 bytearray.ljust(width[, fillbyte]) 2790 2791 Return a copy of the object left justified in a sequence of length *width*. 2792 Padding is done using the specified *fillbyte* (default is an ASCII 2793 space). For :class:`bytes` objects, the original sequence is returned if 2794 *width* is less than or equal to ``len(s)``. 2795 2796 .. note:: 2797 2798 The bytearray version of this method does *not* operate in place - 2799 it always produces a new object, even if no changes were made. 2800 2801 2802.. method:: bytes.lstrip([chars]) 2803 bytearray.lstrip([chars]) 2804 2805 Return a copy of the sequence with specified leading bytes removed. The 2806 *chars* argument is a binary sequence specifying the set of byte values to 2807 be removed - the name refers to the fact this method is usually used with 2808 ASCII characters. If omitted or ``None``, the *chars* argument defaults 2809 to removing ASCII whitespace. The *chars* argument is not a prefix; 2810 rather, all combinations of its values are stripped:: 2811 2812 >>> b' spacious '.lstrip() 2813 b'spacious ' 2814 >>> b'www.example.com'.lstrip(b'cmowz.') 2815 b'example.com' 2816 2817 The binary sequence of byte values to remove may be any 2818 :term:`bytes-like object`. 2819 2820 .. note:: 2821 2822 The bytearray version of this method does *not* operate in place - 2823 it always produces a new object, even if no changes were made. 2824 2825 2826.. method:: bytes.rjust(width[, fillbyte]) 2827 bytearray.rjust(width[, fillbyte]) 2828 2829 Return a copy of the object right justified in a sequence of length *width*. 2830 Padding is done using the specified *fillbyte* (default is an ASCII 2831 space). For :class:`bytes` objects, the original sequence is returned if 2832 *width* is less than or equal to ``len(s)``. 2833 2834 .. note:: 2835 2836 The bytearray version of this method does *not* operate in place - 2837 it always produces a new object, even if no changes were made. 2838 2839 2840.. method:: bytes.rsplit(sep=None, maxsplit=-1) 2841 bytearray.rsplit(sep=None, maxsplit=-1) 2842 2843 Split the binary sequence into subsequences of the same type, using *sep* 2844 as the delimiter string. If *maxsplit* is given, at most *maxsplit* splits 2845 are done, the *rightmost* ones. If *sep* is not specified or ``None``, 2846 any subsequence consisting solely of ASCII whitespace is a separator. 2847 Except for splitting from the right, :meth:`rsplit` behaves like 2848 :meth:`split` which is described in detail below. 2849 2850 2851.. method:: bytes.rstrip([chars]) 2852 bytearray.rstrip([chars]) 2853 2854 Return a copy of the sequence with specified trailing bytes removed. The 2855 *chars* argument is a binary sequence specifying the set of byte values to 2856 be removed - the name refers to the fact this method is usually used with 2857 ASCII characters. If omitted or ``None``, the *chars* argument defaults to 2858 removing ASCII whitespace. The *chars* argument is not a suffix; rather, 2859 all combinations of its values are stripped:: 2860 2861 >>> b' spacious '.rstrip() 2862 b' spacious' 2863 >>> b'mississippi'.rstrip(b'ipz') 2864 b'mississ' 2865 2866 The binary sequence of byte values to remove may be any 2867 :term:`bytes-like object`. 2868 2869 .. note:: 2870 2871 The bytearray version of this method does *not* operate in place - 2872 it always produces a new object, even if no changes were made. 2873 2874 2875.. method:: bytes.split(sep=None, maxsplit=-1) 2876 bytearray.split(sep=None, maxsplit=-1) 2877 2878 Split the binary sequence into subsequences of the same type, using *sep* 2879 as the delimiter string. If *maxsplit* is given and non-negative, at most 2880 *maxsplit* splits are done (thus, the list will have at most ``maxsplit+1`` 2881 elements). If *maxsplit* is not specified or is ``-1``, then there is no 2882 limit on the number of splits (all possible splits are made). 2883 2884 If *sep* is given, consecutive delimiters are not grouped together and are 2885 deemed to delimit empty subsequences (for example, ``b'1,,2'.split(b',')`` 2886 returns ``[b'1', b'', b'2']``). The *sep* argument may consist of a 2887 multibyte sequence (for example, ``b'1<>2<>3'.split(b'<>')`` returns 2888 ``[b'1', b'2', b'3']``). Splitting an empty sequence with a specified 2889 separator returns ``[b'']`` or ``[bytearray(b'')]`` depending on the type 2890 of object being split. The *sep* argument may be any 2891 :term:`bytes-like object`. 2892 2893 For example:: 2894 2895 >>> b'1,2,3'.split(b',') 2896 [b'1', b'2', b'3'] 2897 >>> b'1,2,3'.split(b',', maxsplit=1) 2898 [b'1', b'2,3'] 2899 >>> b'1,2,,3,'.split(b',') 2900 [b'1', b'2', b'', b'3', b''] 2901 2902 If *sep* is not specified or is ``None``, a different splitting algorithm 2903 is applied: runs of consecutive ASCII whitespace are regarded as a single 2904 separator, and the result will contain no empty strings at the start or 2905 end if the sequence has leading or trailing whitespace. Consequently, 2906 splitting an empty sequence or a sequence consisting solely of ASCII 2907 whitespace without a specified separator returns ``[]``. 2908 2909 For example:: 2910 2911 2912 >>> b'1 2 3'.split() 2913 [b'1', b'2', b'3'] 2914 >>> b'1 2 3'.split(maxsplit=1) 2915 [b'1', b'2 3'] 2916 >>> b' 1 2 3 '.split() 2917 [b'1', b'2', b'3'] 2918 2919 2920.. method:: bytes.strip([chars]) 2921 bytearray.strip([chars]) 2922 2923 Return a copy of the sequence with specified leading and trailing bytes 2924 removed. The *chars* argument is a binary sequence specifying the set of 2925 byte values to be removed - the name refers to the fact this method is 2926 usually used with ASCII characters. If omitted or ``None``, the *chars* 2927 argument defaults to removing ASCII whitespace. The *chars* argument is 2928 not a prefix or suffix; rather, all combinations of its values are 2929 stripped:: 2930 2931 >>> b' spacious '.strip() 2932 b'spacious' 2933 >>> b'www.example.com'.strip(b'cmowz.') 2934 b'example' 2935 2936 The binary sequence of byte values to remove may be any 2937 :term:`bytes-like object`. 2938 2939 .. note:: 2940 2941 The bytearray version of this method does *not* operate in place - 2942 it always produces a new object, even if no changes were made. 2943 2944 2945The following methods on bytes and bytearray objects assume the use of ASCII 2946compatible binary formats and should not be applied to arbitrary binary data. 2947Note that all of the bytearray methods in this section do *not* operate in 2948place, and instead produce new objects. 2949 2950.. method:: bytes.capitalize() 2951 bytearray.capitalize() 2952 2953 Return a copy of the sequence with each byte interpreted as an ASCII 2954 character, and the first byte capitalized and the rest lowercased. 2955 Non-ASCII byte values are passed through unchanged. 2956 2957 .. note:: 2958 2959 The bytearray version of this method does *not* operate in place - it 2960 always produces a new object, even if no changes were made. 2961 2962 2963.. method:: bytes.expandtabs(tabsize=8) 2964 bytearray.expandtabs(tabsize=8) 2965 2966 Return a copy of the sequence where all ASCII tab characters are replaced 2967 by one or more ASCII spaces, depending on the current column and the given 2968 tab size. Tab positions occur every *tabsize* bytes (default is 8, 2969 giving tab positions at columns 0, 8, 16 and so on). To expand the 2970 sequence, the current column is set to zero and the sequence is examined 2971 byte by byte. If the byte is an ASCII tab character (``b'\t'``), one or 2972 more space characters are inserted in the result until the current column 2973 is equal to the next tab position. (The tab character itself is not 2974 copied.) If the current byte is an ASCII newline (``b'\n'``) or 2975 carriage return (``b'\r'``), it is copied and the current column is reset 2976 to zero. Any other byte value is copied unchanged and the current column 2977 is incremented by one regardless of how the byte value is represented when 2978 printed:: 2979 2980 >>> b'01\t012\t0123\t01234'.expandtabs() 2981 b'01 012 0123 01234' 2982 >>> b'01\t012\t0123\t01234'.expandtabs(4) 2983 b'01 012 0123 01234' 2984 2985 .. note:: 2986 2987 The bytearray version of this method does *not* operate in place - it 2988 always produces a new object, even if no changes were made. 2989 2990 2991.. method:: bytes.isalnum() 2992 bytearray.isalnum() 2993 2994 Return ``True`` if all bytes in the sequence are alphabetical ASCII characters 2995 or ASCII decimal digits and the sequence is not empty, ``False`` otherwise. 2996 Alphabetic ASCII characters are those byte values in the sequence 2997 ``b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'``. ASCII decimal 2998 digits are those byte values in the sequence ``b'0123456789'``. 2999 3000 For example:: 3001 3002 >>> b'ABCabc1'.isalnum() 3003 True 3004 >>> b'ABC abc1'.isalnum() 3005 False 3006 3007 3008.. method:: bytes.isalpha() 3009 bytearray.isalpha() 3010 3011 Return ``True`` if all bytes in the sequence are alphabetic ASCII characters 3012 and the sequence is not empty, ``False`` otherwise. Alphabetic ASCII 3013 characters are those byte values in the sequence 3014 ``b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'``. 3015 3016 For example:: 3017 3018 >>> b'ABCabc'.isalpha() 3019 True 3020 >>> b'ABCabc1'.isalpha() 3021 False 3022 3023 3024.. method:: bytes.isascii() 3025 bytearray.isascii() 3026 3027 Return ``True`` if the sequence is empty or all bytes in the sequence are ASCII, 3028 ``False`` otherwise. 3029 ASCII bytes are in the range 0-0x7F. 3030 3031 .. versionadded:: 3.7 3032 3033 3034.. method:: bytes.isdigit() 3035 bytearray.isdigit() 3036 3037 Return ``True`` if all bytes in the sequence are ASCII decimal digits 3038 and the sequence is not empty, ``False`` otherwise. ASCII decimal digits are 3039 those byte values in the sequence ``b'0123456789'``. 3040 3041 For example:: 3042 3043 >>> b'1234'.isdigit() 3044 True 3045 >>> b'1.23'.isdigit() 3046 False 3047 3048 3049.. method:: bytes.islower() 3050 bytearray.islower() 3051 3052 Return ``True`` if there is at least one lowercase ASCII character 3053 in the sequence and no uppercase ASCII characters, ``False`` otherwise. 3054 3055 For example:: 3056 3057 >>> b'hello world'.islower() 3058 True 3059 >>> b'Hello world'.islower() 3060 False 3061 3062 Lowercase ASCII characters are those byte values in the sequence 3063 ``b'abcdefghijklmnopqrstuvwxyz'``. Uppercase ASCII characters 3064 are those byte values in the sequence ``b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``. 3065 3066 3067.. method:: bytes.isspace() 3068 bytearray.isspace() 3069 3070 Return ``True`` if all bytes in the sequence are ASCII whitespace and the 3071 sequence is not empty, ``False`` otherwise. ASCII whitespace characters are 3072 those byte values in the sequence ``b' \t\n\r\x0b\f'`` (space, tab, newline, 3073 carriage return, vertical tab, form feed). 3074 3075 3076.. method:: bytes.istitle() 3077 bytearray.istitle() 3078 3079 Return ``True`` if the sequence is ASCII titlecase and the sequence is not 3080 empty, ``False`` otherwise. See :meth:`bytes.title` for more details on the 3081 definition of "titlecase". 3082 3083 For example:: 3084 3085 >>> b'Hello World'.istitle() 3086 True 3087 >>> b'Hello world'.istitle() 3088 False 3089 3090 3091.. method:: bytes.isupper() 3092 bytearray.isupper() 3093 3094 Return ``True`` if there is at least one uppercase alphabetic ASCII character 3095 in the sequence and no lowercase ASCII characters, ``False`` otherwise. 3096 3097 For example:: 3098 3099 >>> b'HELLO WORLD'.isupper() 3100 True 3101 >>> b'Hello world'.isupper() 3102 False 3103 3104 Lowercase ASCII characters are those byte values in the sequence 3105 ``b'abcdefghijklmnopqrstuvwxyz'``. Uppercase ASCII characters 3106 are those byte values in the sequence ``b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``. 3107 3108 3109.. method:: bytes.lower() 3110 bytearray.lower() 3111 3112 Return a copy of the sequence with all the uppercase ASCII characters 3113 converted to their corresponding lowercase counterpart. 3114 3115 For example:: 3116 3117 >>> b'Hello World'.lower() 3118 b'hello world' 3119 3120 Lowercase ASCII characters are those byte values in the sequence 3121 ``b'abcdefghijklmnopqrstuvwxyz'``. Uppercase ASCII characters 3122 are those byte values in the sequence ``b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``. 3123 3124 .. note:: 3125 3126 The bytearray version of this method does *not* operate in place - it 3127 always produces a new object, even if no changes were made. 3128 3129 3130.. index:: 3131 single: universal newlines; bytes.splitlines method 3132 single: universal newlines; bytearray.splitlines method 3133 3134.. method:: bytes.splitlines(keepends=False) 3135 bytearray.splitlines(keepends=False) 3136 3137 Return a list of the lines in the binary sequence, breaking at ASCII 3138 line boundaries. This method uses the :term:`universal newlines` approach 3139 to splitting lines. Line breaks are not included in the resulting list 3140 unless *keepends* is given and true. 3141 3142 For example:: 3143 3144 >>> b'ab c\n\nde fg\rkl\r\n'.splitlines() 3145 [b'ab c', b'', b'de fg', b'kl'] 3146 >>> b'ab c\n\nde fg\rkl\r\n'.splitlines(keepends=True) 3147 [b'ab c\n', b'\n', b'de fg\r', b'kl\r\n'] 3148 3149 Unlike :meth:`~bytes.split` when a delimiter string *sep* is given, this 3150 method returns an empty list for the empty string, and a terminal line 3151 break does not result in an extra line:: 3152 3153 >>> b"".split(b'\n'), b"Two lines\n".split(b'\n') 3154 ([b''], [b'Two lines', b'']) 3155 >>> b"".splitlines(), b"One line\n".splitlines() 3156 ([], [b'One line']) 3157 3158 3159.. method:: bytes.swapcase() 3160 bytearray.swapcase() 3161 3162 Return a copy of the sequence with all the lowercase ASCII characters 3163 converted to their corresponding uppercase counterpart and vice-versa. 3164 3165 For example:: 3166 3167 >>> b'Hello World'.swapcase() 3168 b'hELLO wORLD' 3169 3170 Lowercase ASCII characters are those byte values in the sequence 3171 ``b'abcdefghijklmnopqrstuvwxyz'``. Uppercase ASCII characters 3172 are those byte values in the sequence ``b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``. 3173 3174 Unlike :func:`str.swapcase()`, it is always the case that 3175 ``bin.swapcase().swapcase() == bin`` for the binary versions. Case 3176 conversions are symmetrical in ASCII, even though that is not generally 3177 true for arbitrary Unicode code points. 3178 3179 .. note:: 3180 3181 The bytearray version of this method does *not* operate in place - it 3182 always produces a new object, even if no changes were made. 3183 3184 3185.. method:: bytes.title() 3186 bytearray.title() 3187 3188 Return a titlecased version of the binary sequence where words start with 3189 an uppercase ASCII character and the remaining characters are lowercase. 3190 Uncased byte values are left unmodified. 3191 3192 For example:: 3193 3194 >>> b'Hello world'.title() 3195 b'Hello World' 3196 3197 Lowercase ASCII characters are those byte values in the sequence 3198 ``b'abcdefghijklmnopqrstuvwxyz'``. Uppercase ASCII characters 3199 are those byte values in the sequence ``b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``. 3200 All other byte values are uncased. 3201 3202 The algorithm uses a simple language-independent definition of a word as 3203 groups of consecutive letters. The definition works in many contexts but 3204 it means that apostrophes in contractions and possessives form word 3205 boundaries, which may not be the desired result:: 3206 3207 >>> b"they're bill's friends from the UK".title() 3208 b"They'Re Bill'S Friends From The Uk" 3209 3210 A workaround for apostrophes can be constructed using regular expressions:: 3211 3212 >>> import re 3213 >>> def titlecase(s): 3214 ... return re.sub(rb"[A-Za-z]+('[A-Za-z]+)?", 3215 ... lambda mo: mo.group(0)[0:1].upper() + 3216 ... mo.group(0)[1:].lower(), 3217 ... s) 3218 ... 3219 >>> titlecase(b"they're bill's friends.") 3220 b"They're Bill's Friends." 3221 3222 .. note:: 3223 3224 The bytearray version of this method does *not* operate in place - it 3225 always produces a new object, even if no changes were made. 3226 3227 3228.. method:: bytes.upper() 3229 bytearray.upper() 3230 3231 Return a copy of the sequence with all the lowercase ASCII characters 3232 converted to their corresponding uppercase counterpart. 3233 3234 For example:: 3235 3236 >>> b'Hello World'.upper() 3237 b'HELLO WORLD' 3238 3239 Lowercase ASCII characters are those byte values in the sequence 3240 ``b'abcdefghijklmnopqrstuvwxyz'``. Uppercase ASCII characters 3241 are those byte values in the sequence ``b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``. 3242 3243 .. note:: 3244 3245 The bytearray version of this method does *not* operate in place - it 3246 always produces a new object, even if no changes were made. 3247 3248 3249.. method:: bytes.zfill(width) 3250 bytearray.zfill(width) 3251 3252 Return a copy of the sequence left filled with ASCII ``b'0'`` digits to 3253 make a sequence of length *width*. A leading sign prefix (``b'+'``/ 3254 ``b'-'``) is handled by inserting the padding *after* the sign character 3255 rather than before. For :class:`bytes` objects, the original sequence is 3256 returned if *width* is less than or equal to ``len(seq)``. 3257 3258 For example:: 3259 3260 >>> b"42".zfill(5) 3261 b'00042' 3262 >>> b"-42".zfill(5) 3263 b'-0042' 3264 3265 .. note:: 3266 3267 The bytearray version of this method does *not* operate in place - it 3268 always produces a new object, even if no changes were made. 3269 3270 3271.. _bytes-formatting: 3272 3273``printf``-style Bytes Formatting 3274---------------------------------- 3275 3276.. index:: 3277 single: formatting; bytes (%) 3278 single: formatting; bytearray (%) 3279 single: interpolation; bytes (%) 3280 single: interpolation; bytearray (%) 3281 single: bytes; formatting 3282 single: bytearray; formatting 3283 single: bytes; interpolation 3284 single: bytearray; interpolation 3285 single: printf-style formatting 3286 single: sprintf-style formatting 3287 single: % (percent); printf-style formatting 3288 3289.. note:: 3290 3291 The formatting operations described here exhibit a variety of quirks that 3292 lead to a number of common errors (such as failing to display tuples and 3293 dictionaries correctly). If the value being printed may be a tuple or 3294 dictionary, wrap it in a tuple. 3295 3296Bytes objects (``bytes``/``bytearray``) have one unique built-in operation: 3297the ``%`` operator (modulo). 3298This is also known as the bytes *formatting* or *interpolation* operator. 3299Given ``format % values`` (where *format* is a bytes object), ``%`` conversion 3300specifications in *format* are replaced with zero or more elements of *values*. 3301The effect is similar to using the :c:func:`sprintf` in the C language. 3302 3303If *format* requires a single argument, *values* may be a single non-tuple 3304object. [5]_ Otherwise, *values* must be a tuple with exactly the number of 3305items specified by the format bytes object, or a single mapping object (for 3306example, a dictionary). 3307 3308.. index:: 3309 single: () (parentheses); in printf-style formatting 3310 single: * (asterisk); in printf-style formatting 3311 single: . (dot); in printf-style formatting 3312 3313A conversion specifier contains two or more characters and has the following 3314components, which must occur in this order: 3315 3316#. The ``'%'`` character, which marks the start of the specifier. 3317 3318#. Mapping key (optional), consisting of a parenthesised sequence of characters 3319 (for example, ``(somename)``). 3320 3321#. Conversion flags (optional), which affect the result of some conversion 3322 types. 3323 3324#. Minimum field width (optional). If specified as an ``'*'`` (asterisk), the 3325 actual width is read from the next element of the tuple in *values*, and the 3326 object to convert comes after the minimum field width and optional precision. 3327 3328#. Precision (optional), given as a ``'.'`` (dot) followed by the precision. If 3329 specified as ``'*'`` (an asterisk), the actual precision is read from the next 3330 element of the tuple in *values*, and the value to convert comes after the 3331 precision. 3332 3333#. Length modifier (optional). 3334 3335#. Conversion type. 3336 3337When the right argument is a dictionary (or other mapping type), then the 3338formats in the bytes object *must* include a parenthesised mapping key into that 3339dictionary inserted immediately after the ``'%'`` character. The mapping key 3340selects the value to be formatted from the mapping. For example: 3341 3342 >>> print(b'%(language)s has %(number)03d quote types.' % 3343 ... {b'language': b"Python", b"number": 2}) 3344 b'Python has 002 quote types.' 3345 3346In this case no ``*`` specifiers may occur in a format (since they require a 3347sequential parameter list). 3348 3349The conversion flag characters are: 3350 3351.. index:: 3352 single: # (hash); in printf-style formatting 3353 single: - (minus); in printf-style formatting 3354 single: + (plus); in printf-style formatting 3355 single: space; in printf-style formatting 3356 3357+---------+---------------------------------------------------------------------+ 3358| Flag | Meaning | 3359+=========+=====================================================================+ 3360| ``'#'`` | The value conversion will use the "alternate form" (where defined | 3361| | below). | 3362+---------+---------------------------------------------------------------------+ 3363| ``'0'`` | The conversion will be zero padded for numeric values. | 3364+---------+---------------------------------------------------------------------+ 3365| ``'-'`` | The converted value is left adjusted (overrides the ``'0'`` | 3366| | conversion if both are given). | 3367+---------+---------------------------------------------------------------------+ 3368| ``' '`` | (a space) A blank should be left before a positive number (or empty | 3369| | string) produced by a signed conversion. | 3370+---------+---------------------------------------------------------------------+ 3371| ``'+'`` | A sign character (``'+'`` or ``'-'``) will precede the conversion | 3372| | (overrides a "space" flag). | 3373+---------+---------------------------------------------------------------------+ 3374 3375A length modifier (``h``, ``l``, or ``L``) may be present, but is ignored as it 3376is not necessary for Python -- so e.g. ``%ld`` is identical to ``%d``. 3377 3378The conversion types are: 3379 3380+------------+-----------------------------------------------------+-------+ 3381| Conversion | Meaning | Notes | 3382+============+=====================================================+=======+ 3383| ``'d'`` | Signed integer decimal. | | 3384+------------+-----------------------------------------------------+-------+ 3385| ``'i'`` | Signed integer decimal. | | 3386+------------+-----------------------------------------------------+-------+ 3387| ``'o'`` | Signed octal value. | \(1) | 3388+------------+-----------------------------------------------------+-------+ 3389| ``'u'`` | Obsolete type -- it is identical to ``'d'``. | \(8) | 3390+------------+-----------------------------------------------------+-------+ 3391| ``'x'`` | Signed hexadecimal (lowercase). | \(2) | 3392+------------+-----------------------------------------------------+-------+ 3393| ``'X'`` | Signed hexadecimal (uppercase). | \(2) | 3394+------------+-----------------------------------------------------+-------+ 3395| ``'e'`` | Floating point exponential format (lowercase). | \(3) | 3396+------------+-----------------------------------------------------+-------+ 3397| ``'E'`` | Floating point exponential format (uppercase). | \(3) | 3398+------------+-----------------------------------------------------+-------+ 3399| ``'f'`` | Floating point decimal format. | \(3) | 3400+------------+-----------------------------------------------------+-------+ 3401| ``'F'`` | Floating point decimal format. | \(3) | 3402+------------+-----------------------------------------------------+-------+ 3403| ``'g'`` | Floating point format. Uses lowercase exponential | \(4) | 3404| | format if exponent is less than -4 or not less than | | 3405| | precision, decimal format otherwise. | | 3406+------------+-----------------------------------------------------+-------+ 3407| ``'G'`` | Floating point format. Uses uppercase exponential | \(4) | 3408| | format if exponent is less than -4 or not less than | | 3409| | precision, decimal format otherwise. | | 3410+------------+-----------------------------------------------------+-------+ 3411| ``'c'`` | Single byte (accepts integer or single | | 3412| | byte objects). | | 3413+------------+-----------------------------------------------------+-------+ 3414| ``'b'`` | Bytes (any object that follows the | \(5) | 3415| | :ref:`buffer protocol <bufferobjects>` or has | | 3416| | :meth:`__bytes__`). | | 3417+------------+-----------------------------------------------------+-------+ 3418| ``'s'`` | ``'s'`` is an alias for ``'b'`` and should only | \(6) | 3419| | be used for Python2/3 code bases. | | 3420+------------+-----------------------------------------------------+-------+ 3421| ``'a'`` | Bytes (converts any Python object using | \(5) | 3422| | ``repr(obj).encode('ascii','backslashreplace)``). | | 3423+------------+-----------------------------------------------------+-------+ 3424| ``'r'`` | ``'r'`` is an alias for ``'a'`` and should only | \(7) | 3425| | be used for Python2/3 code bases. | | 3426+------------+-----------------------------------------------------+-------+ 3427| ``'%'`` | No argument is converted, results in a ``'%'`` | | 3428| | character in the result. | | 3429+------------+-----------------------------------------------------+-------+ 3430 3431Notes: 3432 3433(1) 3434 The alternate form causes a leading octal specifier (``'0o'``) to be 3435 inserted before the first digit. 3436 3437(2) 3438 The alternate form causes a leading ``'0x'`` or ``'0X'`` (depending on whether 3439 the ``'x'`` or ``'X'`` format was used) to be inserted before the first digit. 3440 3441(3) 3442 The alternate form causes the result to always contain a decimal point, even if 3443 no digits follow it. 3444 3445 The precision determines the number of digits after the decimal point and 3446 defaults to 6. 3447 3448(4) 3449 The alternate form causes the result to always contain a decimal point, and 3450 trailing zeroes are not removed as they would otherwise be. 3451 3452 The precision determines the number of significant digits before and after the 3453 decimal point and defaults to 6. 3454 3455(5) 3456 If precision is ``N``, the output is truncated to ``N`` characters. 3457 3458(6) 3459 ``b'%s'`` is deprecated, but will not be removed during the 3.x series. 3460 3461(7) 3462 ``b'%r'`` is deprecated, but will not be removed during the 3.x series. 3463 3464(8) 3465 See :pep:`237`. 3466 3467.. note:: 3468 3469 The bytearray version of this method does *not* operate in place - it 3470 always produces a new object, even if no changes were made. 3471 3472.. seealso:: 3473 3474 :pep:`461` - Adding % formatting to bytes and bytearray 3475 3476.. versionadded:: 3.5 3477 3478.. _typememoryview: 3479 3480Memory Views 3481------------ 3482 3483:class:`memoryview` objects allow Python code to access the internal data 3484of an object that supports the :ref:`buffer protocol <bufferobjects>` without 3485copying. 3486 3487.. class:: memoryview(obj) 3488 3489 Create a :class:`memoryview` that references *obj*. *obj* must support the 3490 buffer protocol. Built-in objects that support the buffer protocol include 3491 :class:`bytes` and :class:`bytearray`. 3492 3493 A :class:`memoryview` has the notion of an *element*, which is the 3494 atomic memory unit handled by the originating object *obj*. For many 3495 simple types such as :class:`bytes` and :class:`bytearray`, an element 3496 is a single byte, but other types such as :class:`array.array` may have 3497 bigger elements. 3498 3499 ``len(view)`` is equal to the length of :class:`~memoryview.tolist`. 3500 If ``view.ndim = 0``, the length is 1. If ``view.ndim = 1``, the length 3501 is equal to the number of elements in the view. For higher dimensions, 3502 the length is equal to the length of the nested list representation of 3503 the view. The :class:`~memoryview.itemsize` attribute will give you the 3504 number of bytes in a single element. 3505 3506 A :class:`memoryview` supports slicing and indexing to expose its data. 3507 One-dimensional slicing will result in a subview:: 3508 3509 >>> v = memoryview(b'abcefg') 3510 >>> v[1] 3511 98 3512 >>> v[-1] 3513 103 3514 >>> v[1:4] 3515 <memory at 0x7f3ddc9f4350> 3516 >>> bytes(v[1:4]) 3517 b'bce' 3518 3519 If :class:`~memoryview.format` is one of the native format specifiers 3520 from the :mod:`struct` module, indexing with an integer or a tuple of 3521 integers is also supported and returns a single *element* with 3522 the correct type. One-dimensional memoryviews can be indexed 3523 with an integer or a one-integer tuple. Multi-dimensional memoryviews 3524 can be indexed with tuples of exactly *ndim* integers where *ndim* is 3525 the number of dimensions. Zero-dimensional memoryviews can be indexed 3526 with the empty tuple. 3527 3528 Here is an example with a non-byte format:: 3529 3530 >>> import array 3531 >>> a = array.array('l', [-11111111, 22222222, -33333333, 44444444]) 3532 >>> m = memoryview(a) 3533 >>> m[0] 3534 -11111111 3535 >>> m[-1] 3536 44444444 3537 >>> m[::2].tolist() 3538 [-11111111, -33333333] 3539 3540 If the underlying object is writable, the memoryview supports 3541 one-dimensional slice assignment. Resizing is not allowed:: 3542 3543 >>> data = bytearray(b'abcefg') 3544 >>> v = memoryview(data) 3545 >>> v.readonly 3546 False 3547 >>> v[0] = ord(b'z') 3548 >>> data 3549 bytearray(b'zbcefg') 3550 >>> v[1:4] = b'123' 3551 >>> data 3552 bytearray(b'z123fg') 3553 >>> v[2:3] = b'spam' 3554 Traceback (most recent call last): 3555 File "<stdin>", line 1, in <module> 3556 ValueError: memoryview assignment: lvalue and rvalue have different structures 3557 >>> v[2:6] = b'spam' 3558 >>> data 3559 bytearray(b'z1spam') 3560 3561 One-dimensional memoryviews of hashable (read-only) types with formats 3562 'B', 'b' or 'c' are also hashable. The hash is defined as 3563 ``hash(m) == hash(m.tobytes())``:: 3564 3565 >>> v = memoryview(b'abcefg') 3566 >>> hash(v) == hash(b'abcefg') 3567 True 3568 >>> hash(v[2:4]) == hash(b'ce') 3569 True 3570 >>> hash(v[::-2]) == hash(b'abcefg'[::-2]) 3571 True 3572 3573 .. versionchanged:: 3.3 3574 One-dimensional memoryviews can now be sliced. 3575 One-dimensional memoryviews with formats 'B', 'b' or 'c' are now hashable. 3576 3577 .. versionchanged:: 3.4 3578 memoryview is now registered automatically with 3579 :class:`collections.abc.Sequence` 3580 3581 .. versionchanged:: 3.5 3582 memoryviews can now be indexed with tuple of integers. 3583 3584 :class:`memoryview` has several methods: 3585 3586 .. method:: __eq__(exporter) 3587 3588 A memoryview and a :pep:`3118` exporter are equal if their shapes are 3589 equivalent and if all corresponding values are equal when the operands' 3590 respective format codes are interpreted using :mod:`struct` syntax. 3591 3592 For the subset of :mod:`struct` format strings currently supported by 3593 :meth:`tolist`, ``v`` and ``w`` are equal if ``v.tolist() == w.tolist()``:: 3594 3595 >>> import array 3596 >>> a = array.array('I', [1, 2, 3, 4, 5]) 3597 >>> b = array.array('d', [1.0, 2.0, 3.0, 4.0, 5.0]) 3598 >>> c = array.array('b', [5, 3, 1]) 3599 >>> x = memoryview(a) 3600 >>> y = memoryview(b) 3601 >>> x == a == y == b 3602 True 3603 >>> x.tolist() == a.tolist() == y.tolist() == b.tolist() 3604 True 3605 >>> z = y[::-2] 3606 >>> z == c 3607 True 3608 >>> z.tolist() == c.tolist() 3609 True 3610 3611 If either format string is not supported by the :mod:`struct` module, 3612 then the objects will always compare as unequal (even if the format 3613 strings and buffer contents are identical):: 3614 3615 >>> from ctypes import BigEndianStructure, c_long 3616 >>> class BEPoint(BigEndianStructure): 3617 ... _fields_ = [("x", c_long), ("y", c_long)] 3618 ... 3619 >>> point = BEPoint(100, 200) 3620 >>> a = memoryview(point) 3621 >>> b = memoryview(point) 3622 >>> a == point 3623 False 3624 >>> a == b 3625 False 3626 3627 Note that, as with floating point numbers, ``v is w`` does *not* imply 3628 ``v == w`` for memoryview objects. 3629 3630 .. versionchanged:: 3.3 3631 Previous versions compared the raw memory disregarding the item format 3632 and the logical array structure. 3633 3634 .. method:: tobytes(order=None) 3635 3636 Return the data in the buffer as a bytestring. This is equivalent to 3637 calling the :class:`bytes` constructor on the memoryview. :: 3638 3639 >>> m = memoryview(b"abc") 3640 >>> m.tobytes() 3641 b'abc' 3642 >>> bytes(m) 3643 b'abc' 3644 3645 For non-contiguous arrays the result is equal to the flattened list 3646 representation with all elements converted to bytes. :meth:`tobytes` 3647 supports all format strings, including those that are not in 3648 :mod:`struct` module syntax. 3649 3650 .. versionadded:: 3.8 3651 *order* can be {'C', 'F', 'A'}. When *order* is 'C' or 'F', the data 3652 of the original array is converted to C or Fortran order. For contiguous 3653 views, 'A' returns an exact copy of the physical memory. In particular, 3654 in-memory Fortran order is preserved. For non-contiguous views, the 3655 data is converted to C first. *order=None* is the same as *order='C'*. 3656 3657 .. method:: hex([sep[, bytes_per_sep]]) 3658 3659 Return a string object containing two hexadecimal digits for each 3660 byte in the buffer. :: 3661 3662 >>> m = memoryview(b"abc") 3663 >>> m.hex() 3664 '616263' 3665 3666 .. versionadded:: 3.5 3667 3668 .. versionchanged:: 3.8 3669 Similar to :meth:`bytes.hex`, :meth:`memoryview.hex` now supports 3670 optional *sep* and *bytes_per_sep* parameters to insert separators 3671 between bytes in the hex output. 3672 3673 .. method:: tolist() 3674 3675 Return the data in the buffer as a list of elements. :: 3676 3677 >>> memoryview(b'abc').tolist() 3678 [97, 98, 99] 3679 >>> import array 3680 >>> a = array.array('d', [1.1, 2.2, 3.3]) 3681 >>> m = memoryview(a) 3682 >>> m.tolist() 3683 [1.1, 2.2, 3.3] 3684 3685 .. versionchanged:: 3.3 3686 :meth:`tolist` now supports all single character native formats in 3687 :mod:`struct` module syntax as well as multi-dimensional 3688 representations. 3689 3690 .. method:: toreadonly() 3691 3692 Return a readonly version of the memoryview object. The original 3693 memoryview object is unchanged. :: 3694 3695 >>> m = memoryview(bytearray(b'abc')) 3696 >>> mm = m.toreadonly() 3697 >>> mm.tolist() 3698 [89, 98, 99] 3699 >>> mm[0] = 42 3700 Traceback (most recent call last): 3701 File "<stdin>", line 1, in <module> 3702 TypeError: cannot modify read-only memory 3703 >>> m[0] = 43 3704 >>> mm.tolist() 3705 [43, 98, 99] 3706 3707 .. versionadded:: 3.8 3708 3709 .. method:: release() 3710 3711 Release the underlying buffer exposed by the memoryview object. Many 3712 objects take special actions when a view is held on them (for example, 3713 a :class:`bytearray` would temporarily forbid resizing); therefore, 3714 calling release() is handy to remove these restrictions (and free any 3715 dangling resources) as soon as possible. 3716 3717 After this method has been called, any further operation on the view 3718 raises a :class:`ValueError` (except :meth:`release()` itself which can 3719 be called multiple times):: 3720 3721 >>> m = memoryview(b'abc') 3722 >>> m.release() 3723 >>> m[0] 3724 Traceback (most recent call last): 3725 File "<stdin>", line 1, in <module> 3726 ValueError: operation forbidden on released memoryview object 3727 3728 The context management protocol can be used for a similar effect, 3729 using the ``with`` statement:: 3730 3731 >>> with memoryview(b'abc') as m: 3732 ... m[0] 3733 ... 3734 97 3735 >>> m[0] 3736 Traceback (most recent call last): 3737 File "<stdin>", line 1, in <module> 3738 ValueError: operation forbidden on released memoryview object 3739 3740 .. versionadded:: 3.2 3741 3742 .. method:: cast(format[, shape]) 3743 3744 Cast a memoryview to a new format or shape. *shape* defaults to 3745 ``[byte_length//new_itemsize]``, which means that the result view 3746 will be one-dimensional. The return value is a new memoryview, but 3747 the buffer itself is not copied. Supported casts are 1D -> C-:term:`contiguous` 3748 and C-contiguous -> 1D. 3749 3750 The destination format is restricted to a single element native format in 3751 :mod:`struct` syntax. One of the formats must be a byte format 3752 ('B', 'b' or 'c'). The byte length of the result must be the same 3753 as the original length. 3754 3755 Cast 1D/long to 1D/unsigned bytes:: 3756 3757 >>> import array 3758 >>> a = array.array('l', [1,2,3]) 3759 >>> x = memoryview(a) 3760 >>> x.format 3761 'l' 3762 >>> x.itemsize 3763 8 3764 >>> len(x) 3765 3 3766 >>> x.nbytes 3767 24 3768 >>> y = x.cast('B') 3769 >>> y.format 3770 'B' 3771 >>> y.itemsize 3772 1 3773 >>> len(y) 3774 24 3775 >>> y.nbytes 3776 24 3777 3778 Cast 1D/unsigned bytes to 1D/char:: 3779 3780 >>> b = bytearray(b'zyz') 3781 >>> x = memoryview(b) 3782 >>> x[0] = b'a' 3783 Traceback (most recent call last): 3784 File "<stdin>", line 1, in <module> 3785 ValueError: memoryview: invalid value for format "B" 3786 >>> y = x.cast('c') 3787 >>> y[0] = b'a' 3788 >>> b 3789 bytearray(b'ayz') 3790 3791 Cast 1D/bytes to 3D/ints to 1D/signed char:: 3792 3793 >>> import struct 3794 >>> buf = struct.pack("i"*12, *list(range(12))) 3795 >>> x = memoryview(buf) 3796 >>> y = x.cast('i', shape=[2,2,3]) 3797 >>> y.tolist() 3798 [[[0, 1, 2], [3, 4, 5]], [[6, 7, 8], [9, 10, 11]]] 3799 >>> y.format 3800 'i' 3801 >>> y.itemsize 3802 4 3803 >>> len(y) 3804 2 3805 >>> y.nbytes 3806 48 3807 >>> z = y.cast('b') 3808 >>> z.format 3809 'b' 3810 >>> z.itemsize 3811 1 3812 >>> len(z) 3813 48 3814 >>> z.nbytes 3815 48 3816 3817 Cast 1D/unsigned long to 2D/unsigned long:: 3818 3819 >>> buf = struct.pack("L"*6, *list(range(6))) 3820 >>> x = memoryview(buf) 3821 >>> y = x.cast('L', shape=[2,3]) 3822 >>> len(y) 3823 2 3824 >>> y.nbytes 3825 48 3826 >>> y.tolist() 3827 [[0, 1, 2], [3, 4, 5]] 3828 3829 .. versionadded:: 3.3 3830 3831 .. versionchanged:: 3.5 3832 The source format is no longer restricted when casting to a byte view. 3833 3834 There are also several readonly attributes available: 3835 3836 .. attribute:: obj 3837 3838 The underlying object of the memoryview:: 3839 3840 >>> b = bytearray(b'xyz') 3841 >>> m = memoryview(b) 3842 >>> m.obj is b 3843 True 3844 3845 .. versionadded:: 3.3 3846 3847 .. attribute:: nbytes 3848 3849 ``nbytes == product(shape) * itemsize == len(m.tobytes())``. This is 3850 the amount of space in bytes that the array would use in a contiguous 3851 representation. It is not necessarily equal to ``len(m)``:: 3852 3853 >>> import array 3854 >>> a = array.array('i', [1,2,3,4,5]) 3855 >>> m = memoryview(a) 3856 >>> len(m) 3857 5 3858 >>> m.nbytes 3859 20 3860 >>> y = m[::2] 3861 >>> len(y) 3862 3 3863 >>> y.nbytes 3864 12 3865 >>> len(y.tobytes()) 3866 12 3867 3868 Multi-dimensional arrays:: 3869 3870 >>> import struct 3871 >>> buf = struct.pack("d"*12, *[1.5*x for x in range(12)]) 3872 >>> x = memoryview(buf) 3873 >>> y = x.cast('d', shape=[3,4]) 3874 >>> y.tolist() 3875 [[0.0, 1.5, 3.0, 4.5], [6.0, 7.5, 9.0, 10.5], [12.0, 13.5, 15.0, 16.5]] 3876 >>> len(y) 3877 3 3878 >>> y.nbytes 3879 96 3880 3881 .. versionadded:: 3.3 3882 3883 .. attribute:: readonly 3884 3885 A bool indicating whether the memory is read only. 3886 3887 .. attribute:: format 3888 3889 A string containing the format (in :mod:`struct` module style) for each 3890 element in the view. A memoryview can be created from exporters with 3891 arbitrary format strings, but some methods (e.g. :meth:`tolist`) are 3892 restricted to native single element formats. 3893 3894 .. versionchanged:: 3.3 3895 format ``'B'`` is now handled according to the struct module syntax. 3896 This means that ``memoryview(b'abc')[0] == b'abc'[0] == 97``. 3897 3898 .. attribute:: itemsize 3899 3900 The size in bytes of each element of the memoryview:: 3901 3902 >>> import array, struct 3903 >>> m = memoryview(array.array('H', [32000, 32001, 32002])) 3904 >>> m.itemsize 3905 2 3906 >>> m[0] 3907 32000 3908 >>> struct.calcsize('H') == m.itemsize 3909 True 3910 3911 .. attribute:: ndim 3912 3913 An integer indicating how many dimensions of a multi-dimensional array the 3914 memory represents. 3915 3916 .. attribute:: shape 3917 3918 A tuple of integers the length of :attr:`ndim` giving the shape of the 3919 memory as an N-dimensional array. 3920 3921 .. versionchanged:: 3.3 3922 An empty tuple instead of ``None`` when ndim = 0. 3923 3924 .. attribute:: strides 3925 3926 A tuple of integers the length of :attr:`ndim` giving the size in bytes to 3927 access each element for each dimension of the array. 3928 3929 .. versionchanged:: 3.3 3930 An empty tuple instead of ``None`` when ndim = 0. 3931 3932 .. attribute:: suboffsets 3933 3934 Used internally for PIL-style arrays. The value is informational only. 3935 3936 .. attribute:: c_contiguous 3937 3938 A bool indicating whether the memory is C-:term:`contiguous`. 3939 3940 .. versionadded:: 3.3 3941 3942 .. attribute:: f_contiguous 3943 3944 A bool indicating whether the memory is Fortran :term:`contiguous`. 3945 3946 .. versionadded:: 3.3 3947 3948 .. attribute:: contiguous 3949 3950 A bool indicating whether the memory is :term:`contiguous`. 3951 3952 .. versionadded:: 3.3 3953 3954 3955.. _types-set: 3956 3957Set Types --- :class:`set`, :class:`frozenset` 3958============================================== 3959 3960.. index:: object: set 3961 3962A :dfn:`set` object is an unordered collection of distinct :term:`hashable` objects. 3963Common uses include membership testing, removing duplicates from a sequence, and 3964computing mathematical operations such as intersection, union, difference, and 3965symmetric difference. 3966(For other containers see the built-in :class:`dict`, :class:`list`, 3967and :class:`tuple` classes, and the :mod:`collections` module.) 3968 3969Like other collections, sets support ``x in set``, ``len(set)``, and ``for x in 3970set``. Being an unordered collection, sets do not record element position or 3971order of insertion. Accordingly, sets do not support indexing, slicing, or 3972other sequence-like behavior. 3973 3974There are currently two built-in set types, :class:`set` and :class:`frozenset`. 3975The :class:`set` type is mutable --- the contents can be changed using methods 3976like :meth:`~set.add` and :meth:`~set.remove`. Since it is mutable, it has no 3977hash value and cannot be used as either a dictionary key or as an element of 3978another set. The :class:`frozenset` type is immutable and :term:`hashable` --- 3979its contents cannot be altered after it is created; it can therefore be used as 3980a dictionary key or as an element of another set. 3981 3982Non-empty sets (not frozensets) can be created by placing a comma-separated list 3983of elements within braces, for example: ``{'jack', 'sjoerd'}``, in addition to the 3984:class:`set` constructor. 3985 3986The constructors for both classes work the same: 3987 3988.. class:: set([iterable]) 3989 frozenset([iterable]) 3990 3991 Return a new set or frozenset object whose elements are taken from 3992 *iterable*. The elements of a set must be :term:`hashable`. To 3993 represent sets of sets, the inner sets must be :class:`frozenset` 3994 objects. If *iterable* is not specified, a new empty set is 3995 returned. 3996 3997 Sets can be created by several means: 3998 3999 * Use a comma-separated list of elements within braces: ``{'jack', 'sjoerd'}`` 4000 * Use a set comprehension: ``{c for c in 'abracadabra' if c not in 'abc'}`` 4001 * Use the type constructor: ``set()``, ``set('foobar')``, ``set(['a', 'b', 'foo'])`` 4002 4003 Instances of :class:`set` and :class:`frozenset` provide the following 4004 operations: 4005 4006 .. describe:: len(s) 4007 4008 Return the number of elements in set *s* (cardinality of *s*). 4009 4010 .. describe:: x in s 4011 4012 Test *x* for membership in *s*. 4013 4014 .. describe:: x not in s 4015 4016 Test *x* for non-membership in *s*. 4017 4018 .. method:: isdisjoint(other) 4019 4020 Return ``True`` if the set has no elements in common with *other*. Sets are 4021 disjoint if and only if their intersection is the empty set. 4022 4023 .. method:: issubset(other) 4024 set <= other 4025 4026 Test whether every element in the set is in *other*. 4027 4028 .. method:: set < other 4029 4030 Test whether the set is a proper subset of *other*, that is, 4031 ``set <= other and set != other``. 4032 4033 .. method:: issuperset(other) 4034 set >= other 4035 4036 Test whether every element in *other* is in the set. 4037 4038 .. method:: set > other 4039 4040 Test whether the set is a proper superset of *other*, that is, ``set >= 4041 other and set != other``. 4042 4043 .. method:: union(*others) 4044 set | other | ... 4045 4046 Return a new set with elements from the set and all others. 4047 4048 .. method:: intersection(*others) 4049 set & other & ... 4050 4051 Return a new set with elements common to the set and all others. 4052 4053 .. method:: difference(*others) 4054 set - other - ... 4055 4056 Return a new set with elements in the set that are not in the others. 4057 4058 .. method:: symmetric_difference(other) 4059 set ^ other 4060 4061 Return a new set with elements in either the set or *other* but not both. 4062 4063 .. method:: copy() 4064 4065 Return a shallow copy of the set. 4066 4067 4068 Note, the non-operator versions of :meth:`union`, :meth:`intersection`, 4069 :meth:`difference`, and :meth:`symmetric_difference`, :meth:`issubset`, and 4070 :meth:`issuperset` methods will accept any iterable as an argument. In 4071 contrast, their operator based counterparts require their arguments to be 4072 sets. This precludes error-prone constructions like ``set('abc') & 'cbs'`` 4073 in favor of the more readable ``set('abc').intersection('cbs')``. 4074 4075 Both :class:`set` and :class:`frozenset` support set to set comparisons. Two 4076 sets are equal if and only if every element of each set is contained in the 4077 other (each is a subset of the other). A set is less than another set if and 4078 only if the first set is a proper subset of the second set (is a subset, but 4079 is not equal). A set is greater than another set if and only if the first set 4080 is a proper superset of the second set (is a superset, but is not equal). 4081 4082 Instances of :class:`set` are compared to instances of :class:`frozenset` 4083 based on their members. For example, ``set('abc') == frozenset('abc')`` 4084 returns ``True`` and so does ``set('abc') in set([frozenset('abc')])``. 4085 4086 The subset and equality comparisons do not generalize to a total ordering 4087 function. For example, any two nonempty disjoint sets are not equal and are not 4088 subsets of each other, so *all* of the following return ``False``: ``a<b``, 4089 ``a==b``, or ``a>b``. 4090 4091 Since sets only define partial ordering (subset relationships), the output of 4092 the :meth:`list.sort` method is undefined for lists of sets. 4093 4094 Set elements, like dictionary keys, must be :term:`hashable`. 4095 4096 Binary operations that mix :class:`set` instances with :class:`frozenset` 4097 return the type of the first operand. For example: ``frozenset('ab') | 4098 set('bc')`` returns an instance of :class:`frozenset`. 4099 4100 The following table lists operations available for :class:`set` that do not 4101 apply to immutable instances of :class:`frozenset`: 4102 4103 .. method:: update(*others) 4104 set |= other | ... 4105 4106 Update the set, adding elements from all others. 4107 4108 .. method:: intersection_update(*others) 4109 set &= other & ... 4110 4111 Update the set, keeping only elements found in it and all others. 4112 4113 .. method:: difference_update(*others) 4114 set -= other | ... 4115 4116 Update the set, removing elements found in others. 4117 4118 .. method:: symmetric_difference_update(other) 4119 set ^= other 4120 4121 Update the set, keeping only elements found in either set, but not in both. 4122 4123 .. method:: add(elem) 4124 4125 Add element *elem* to the set. 4126 4127 .. method:: remove(elem) 4128 4129 Remove element *elem* from the set. Raises :exc:`KeyError` if *elem* is 4130 not contained in the set. 4131 4132 .. method:: discard(elem) 4133 4134 Remove element *elem* from the set if it is present. 4135 4136 .. method:: pop() 4137 4138 Remove and return an arbitrary element from the set. Raises 4139 :exc:`KeyError` if the set is empty. 4140 4141 .. method:: clear() 4142 4143 Remove all elements from the set. 4144 4145 4146 Note, the non-operator versions of the :meth:`update`, 4147 :meth:`intersection_update`, :meth:`difference_update`, and 4148 :meth:`symmetric_difference_update` methods will accept any iterable as an 4149 argument. 4150 4151 Note, the *elem* argument to the :meth:`__contains__`, :meth:`remove`, and 4152 :meth:`discard` methods may be a set. To support searching for an equivalent 4153 frozenset, a temporary one is created from *elem*. 4154 4155 4156.. _typesmapping: 4157 4158Mapping Types --- :class:`dict` 4159=============================== 4160 4161.. index:: 4162 object: mapping 4163 object: dictionary 4164 triple: operations on; mapping; types 4165 triple: operations on; dictionary; type 4166 statement: del 4167 builtin: len 4168 4169A :term:`mapping` object maps :term:`hashable` values to arbitrary objects. 4170Mappings are mutable objects. There is currently only one standard mapping 4171type, the :dfn:`dictionary`. (For other containers see the built-in 4172:class:`list`, :class:`set`, and :class:`tuple` classes, and the 4173:mod:`collections` module.) 4174 4175A dictionary's keys are *almost* arbitrary values. Values that are not 4176:term:`hashable`, that is, values containing lists, dictionaries or other 4177mutable types (that are compared by value rather than by object identity) may 4178not be used as keys. Numeric types used for keys obey the normal rules for 4179numeric comparison: if two numbers compare equal (such as ``1`` and ``1.0``) 4180then they can be used interchangeably to index the same dictionary entry. (Note 4181however, that since computers store floating-point numbers as approximations it 4182is usually unwise to use them as dictionary keys.) 4183 4184Dictionaries can be created by placing a comma-separated list of ``key: value`` 4185pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098: 4186'jack', 4127: 'sjoerd'}``, or by the :class:`dict` constructor. 4187 4188.. class:: dict(**kwarg) 4189 dict(mapping, **kwarg) 4190 dict(iterable, **kwarg) 4191 4192 Return a new dictionary initialized from an optional positional argument 4193 and a possibly empty set of keyword arguments. 4194 4195 Dictionaries can be created by several means: 4196 4197 * Use a comma-separated list of ``key: value`` pairs within braces: 4198 ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098: 'jack', 4127: 'sjoerd'}`` 4199 * Use a dict comprehension: ``{}``, ``{x: x ** 2 for x in range(10)}`` 4200 * Use the type constructor: ``dict()``, 4201 ``dict([('foo', 100), ('bar', 200)])``, ``dict(foo=100, bar=200)`` 4202 4203 If no positional argument is given, an empty dictionary is created. 4204 If a positional argument is given and it is a mapping object, a dictionary 4205 is created with the same key-value pairs as the mapping object. Otherwise, 4206 the positional argument must be an :term:`iterable` object. Each item in 4207 the iterable must itself be an iterable with exactly two objects. The 4208 first object of each item becomes a key in the new dictionary, and the 4209 second object the corresponding value. If a key occurs more than once, the 4210 last value for that key becomes the corresponding value in the new 4211 dictionary. 4212 4213 If keyword arguments are given, the keyword arguments and their values are 4214 added to the dictionary created from the positional argument. If a key 4215 being added is already present, the value from the keyword argument 4216 replaces the value from the positional argument. 4217 4218 To illustrate, the following examples all return a dictionary equal to 4219 ``{"one": 1, "two": 2, "three": 3}``:: 4220 4221 >>> a = dict(one=1, two=2, three=3) 4222 >>> b = {'one': 1, 'two': 2, 'three': 3} 4223 >>> c = dict(zip(['one', 'two', 'three'], [1, 2, 3])) 4224 >>> d = dict([('two', 2), ('one', 1), ('three', 3)]) 4225 >>> e = dict({'three': 3, 'one': 1, 'two': 2}) 4226 >>> a == b == c == d == e 4227 True 4228 4229 Providing keyword arguments as in the first example only works for keys that 4230 are valid Python identifiers. Otherwise, any valid keys can be used. 4231 4232 4233 These are the operations that dictionaries support (and therefore, custom 4234 mapping types should support too): 4235 4236 .. describe:: list(d) 4237 4238 Return a list of all the keys used in the dictionary *d*. 4239 4240 .. describe:: len(d) 4241 4242 Return the number of items in the dictionary *d*. 4243 4244 .. describe:: d[key] 4245 4246 Return the item of *d* with key *key*. Raises a :exc:`KeyError` if *key* is 4247 not in the map. 4248 4249 .. index:: __missing__() 4250 4251 If a subclass of dict defines a method :meth:`__missing__` and *key* 4252 is not present, the ``d[key]`` operation calls that method with the key *key* 4253 as argument. The ``d[key]`` operation then returns or raises whatever is 4254 returned or raised by the ``__missing__(key)`` call. 4255 No other operations or methods invoke :meth:`__missing__`. If 4256 :meth:`__missing__` is not defined, :exc:`KeyError` is raised. 4257 :meth:`__missing__` must be a method; it cannot be an instance variable:: 4258 4259 >>> class Counter(dict): 4260 ... def __missing__(self, key): 4261 ... return 0 4262 >>> c = Counter() 4263 >>> c['red'] 4264 0 4265 >>> c['red'] += 1 4266 >>> c['red'] 4267 1 4268 4269 The example above shows part of the implementation of 4270 :class:`collections.Counter`. A different ``__missing__`` method is used 4271 by :class:`collections.defaultdict`. 4272 4273 .. describe:: d[key] = value 4274 4275 Set ``d[key]`` to *value*. 4276 4277 .. describe:: del d[key] 4278 4279 Remove ``d[key]`` from *d*. Raises a :exc:`KeyError` if *key* is not in the 4280 map. 4281 4282 .. describe:: key in d 4283 4284 Return ``True`` if *d* has a key *key*, else ``False``. 4285 4286 .. describe:: key not in d 4287 4288 Equivalent to ``not key in d``. 4289 4290 .. describe:: iter(d) 4291 4292 Return an iterator over the keys of the dictionary. This is a shortcut 4293 for ``iter(d.keys())``. 4294 4295 .. method:: clear() 4296 4297 Remove all items from the dictionary. 4298 4299 .. method:: copy() 4300 4301 Return a shallow copy of the dictionary. 4302 4303 .. classmethod:: fromkeys(iterable[, value]) 4304 4305 Create a new dictionary with keys from *iterable* and values set to *value*. 4306 4307 :meth:`fromkeys` is a class method that returns a new dictionary. *value* 4308 defaults to ``None``. All of the values refer to just a single instance, 4309 so it generally doesn't make sense for *value* to be a mutable object 4310 such as an empty list. To get distinct values, use a :ref:`dict 4311 comprehension <dict>` instead. 4312 4313 .. method:: get(key[, default]) 4314 4315 Return the value for *key* if *key* is in the dictionary, else *default*. 4316 If *default* is not given, it defaults to ``None``, so that this method 4317 never raises a :exc:`KeyError`. 4318 4319 .. method:: items() 4320 4321 Return a new view of the dictionary's items (``(key, value)`` pairs). 4322 See the :ref:`documentation of view objects <dict-views>`. 4323 4324 .. method:: keys() 4325 4326 Return a new view of the dictionary's keys. See the :ref:`documentation 4327 of view objects <dict-views>`. 4328 4329 .. method:: pop(key[, default]) 4330 4331 If *key* is in the dictionary, remove it and return its value, else return 4332 *default*. If *default* is not given and *key* is not in the dictionary, 4333 a :exc:`KeyError` is raised. 4334 4335 .. method:: popitem() 4336 4337 Remove and return a ``(key, value)`` pair from the dictionary. 4338 Pairs are returned in :abbr:`LIFO (last-in, first-out)` order. 4339 4340 :meth:`popitem` is useful to destructively iterate over a dictionary, as 4341 often used in set algorithms. If the dictionary is empty, calling 4342 :meth:`popitem` raises a :exc:`KeyError`. 4343 4344 .. versionchanged:: 3.7 4345 LIFO order is now guaranteed. In prior versions, :meth:`popitem` would 4346 return an arbitrary key/value pair. 4347 4348 .. describe:: reversed(d) 4349 4350 Return a reverse iterator over the keys of the dictionary. This is a 4351 shortcut for ``reversed(d.keys())``. 4352 4353 .. versionadded:: 3.8 4354 4355 .. method:: setdefault(key[, default]) 4356 4357 If *key* is in the dictionary, return its value. If not, insert *key* 4358 with a value of *default* and return *default*. *default* defaults to 4359 ``None``. 4360 4361 .. method:: update([other]) 4362 4363 Update the dictionary with the key/value pairs from *other*, overwriting 4364 existing keys. Return ``None``. 4365 4366 :meth:`update` accepts either another dictionary object or an iterable of 4367 key/value pairs (as tuples or other iterables of length two). If keyword 4368 arguments are specified, the dictionary is then updated with those 4369 key/value pairs: ``d.update(red=1, blue=2)``. 4370 4371 .. method:: values() 4372 4373 Return a new view of the dictionary's values. See the 4374 :ref:`documentation of view objects <dict-views>`. 4375 4376 An equality comparison between one ``dict.values()`` view and another 4377 will always return ``False``. This also applies when comparing 4378 ``dict.values()`` to itself:: 4379 4380 >>> d = {'a': 1} 4381 >>> d.values() == d.values() 4382 False 4383 4384 Dictionaries compare equal if and only if they have the same ``(key, 4385 value)`` pairs (regardless of ordering). Order comparisons ('<', '<=', '>=', '>') raise 4386 :exc:`TypeError`. 4387 4388 Dictionaries preserve insertion order. Note that updating a key does not 4389 affect the order. Keys added after deletion are inserted at the end. :: 4390 4391 >>> d = {"one": 1, "two": 2, "three": 3, "four": 4} 4392 >>> d 4393 {'one': 1, 'two': 2, 'three': 3, 'four': 4} 4394 >>> list(d) 4395 ['one', 'two', 'three', 'four'] 4396 >>> list(d.values()) 4397 [1, 2, 3, 4] 4398 >>> d["one"] = 42 4399 >>> d 4400 {'one': 42, 'two': 2, 'three': 3, 'four': 4} 4401 >>> del d["two"] 4402 >>> d["two"] = None 4403 >>> d 4404 {'one': 42, 'three': 3, 'four': 4, 'two': None} 4405 4406 .. versionchanged:: 3.7 4407 Dictionary order is guaranteed to be insertion order. This behavior was 4408 an implementation detail of CPython from 3.6. 4409 4410 Dictionaries and dictionary views are reversible. :: 4411 4412 >>> d = {"one": 1, "two": 2, "three": 3, "four": 4} 4413 >>> d 4414 {'one': 1, 'two': 2, 'three': 3, 'four': 4} 4415 >>> list(reversed(d)) 4416 ['four', 'three', 'two', 'one'] 4417 >>> list(reversed(d.values())) 4418 [4, 3, 2, 1] 4419 >>> list(reversed(d.items())) 4420 [('four', 4), ('three', 3), ('two', 2), ('one', 1)] 4421 4422 .. versionchanged:: 3.8 4423 Dictionaries are now reversible. 4424 4425 4426.. seealso:: 4427 :class:`types.MappingProxyType` can be used to create a read-only view 4428 of a :class:`dict`. 4429 4430 4431.. _dict-views: 4432 4433Dictionary view objects 4434----------------------- 4435 4436The objects returned by :meth:`dict.keys`, :meth:`dict.values` and 4437:meth:`dict.items` are *view objects*. They provide a dynamic view on the 4438dictionary's entries, which means that when the dictionary changes, the view 4439reflects these changes. 4440 4441Dictionary views can be iterated over to yield their respective data, and 4442support membership tests: 4443 4444.. describe:: len(dictview) 4445 4446 Return the number of entries in the dictionary. 4447 4448.. describe:: iter(dictview) 4449 4450 Return an iterator over the keys, values or items (represented as tuples of 4451 ``(key, value)``) in the dictionary. 4452 4453 Keys and values are iterated over in insertion order. 4454 This allows the creation of ``(value, key)`` pairs 4455 using :func:`zip`: ``pairs = zip(d.values(), d.keys())``. Another way to 4456 create the same list is ``pairs = [(v, k) for (k, v) in d.items()]``. 4457 4458 Iterating views while adding or deleting entries in the dictionary may raise 4459 a :exc:`RuntimeError` or fail to iterate over all entries. 4460 4461 .. versionchanged:: 3.7 4462 Dictionary order is guaranteed to be insertion order. 4463 4464.. describe:: x in dictview 4465 4466 Return ``True`` if *x* is in the underlying dictionary's keys, values or 4467 items (in the latter case, *x* should be a ``(key, value)`` tuple). 4468 4469.. describe:: reversed(dictview) 4470 4471 Return a reverse iterator over the keys, values or items of the dictionary. 4472 The view will be iterated in reverse order of the insertion. 4473 4474 .. versionchanged:: 3.8 4475 Dictionary views are now reversible. 4476 4477 4478Keys views are set-like since their entries are unique and hashable. If all 4479values are hashable, so that ``(key, value)`` pairs are unique and hashable, 4480then the items view is also set-like. (Values views are not treated as set-like 4481since the entries are generally not unique.) For set-like views, all of the 4482operations defined for the abstract base class :class:`collections.abc.Set` are 4483available (for example, ``==``, ``<``, or ``^``). 4484 4485An example of dictionary view usage:: 4486 4487 >>> dishes = {'eggs': 2, 'sausage': 1, 'bacon': 1, 'spam': 500} 4488 >>> keys = dishes.keys() 4489 >>> values = dishes.values() 4490 4491 >>> # iteration 4492 >>> n = 0 4493 >>> for val in values: 4494 ... n += val 4495 >>> print(n) 4496 504 4497 4498 >>> # keys and values are iterated over in the same order (insertion order) 4499 >>> list(keys) 4500 ['eggs', 'sausage', 'bacon', 'spam'] 4501 >>> list(values) 4502 [2, 1, 1, 500] 4503 4504 >>> # view objects are dynamic and reflect dict changes 4505 >>> del dishes['eggs'] 4506 >>> del dishes['sausage'] 4507 >>> list(keys) 4508 ['bacon', 'spam'] 4509 4510 >>> # set operations 4511 >>> keys & {'eggs', 'bacon', 'salad'} 4512 {'bacon'} 4513 >>> keys ^ {'sausage', 'juice'} 4514 {'juice', 'sausage', 'bacon', 'spam'} 4515 4516 4517.. _typecontextmanager: 4518 4519Context Manager Types 4520===================== 4521 4522.. index:: 4523 single: context manager 4524 single: context management protocol 4525 single: protocol; context management 4526 4527Python's :keyword:`with` statement supports the concept of a runtime context 4528defined by a context manager. This is implemented using a pair of methods 4529that allow user-defined classes to define a runtime context that is entered 4530before the statement body is executed and exited when the statement ends: 4531 4532 4533.. method:: contextmanager.__enter__() 4534 4535 Enter the runtime context and return either this object or another object 4536 related to the runtime context. The value returned by this method is bound to 4537 the identifier in the :keyword:`!as` clause of :keyword:`with` statements using 4538 this context manager. 4539 4540 An example of a context manager that returns itself is a :term:`file object`. 4541 File objects return themselves from __enter__() to allow :func:`open` to be 4542 used as the context expression in a :keyword:`with` statement. 4543 4544 An example of a context manager that returns a related object is the one 4545 returned by :func:`decimal.localcontext`. These managers set the active 4546 decimal context to a copy of the original decimal context and then return the 4547 copy. This allows changes to be made to the current decimal context in the body 4548 of the :keyword:`with` statement without affecting code outside the 4549 :keyword:`!with` statement. 4550 4551 4552.. method:: contextmanager.__exit__(exc_type, exc_val, exc_tb) 4553 4554 Exit the runtime context and return a Boolean flag indicating if any exception 4555 that occurred should be suppressed. If an exception occurred while executing the 4556 body of the :keyword:`with` statement, the arguments contain the exception type, 4557 value and traceback information. Otherwise, all three arguments are ``None``. 4558 4559 Returning a true value from this method will cause the :keyword:`with` statement 4560 to suppress the exception and continue execution with the statement immediately 4561 following the :keyword:`!with` statement. Otherwise the exception continues 4562 propagating after this method has finished executing. Exceptions that occur 4563 during execution of this method will replace any exception that occurred in the 4564 body of the :keyword:`!with` statement. 4565 4566 The exception passed in should never be reraised explicitly - instead, this 4567 method should return a false value to indicate that the method completed 4568 successfully and does not want to suppress the raised exception. This allows 4569 context management code to easily detect whether or not an :meth:`__exit__` 4570 method has actually failed. 4571 4572Python defines several context managers to support easy thread synchronisation, 4573prompt closure of files or other objects, and simpler manipulation of the active 4574decimal arithmetic context. The specific types are not treated specially beyond 4575their implementation of the context management protocol. See the 4576:mod:`contextlib` module for some examples. 4577 4578Python's :term:`generator`\s and the :class:`contextlib.contextmanager` decorator 4579provide a convenient way to implement these protocols. If a generator function is 4580decorated with the :class:`contextlib.contextmanager` decorator, it will return a 4581context manager implementing the necessary :meth:`__enter__` and 4582:meth:`__exit__` methods, rather than the iterator produced by an undecorated 4583generator function. 4584 4585Note that there is no specific slot for any of these methods in the type 4586structure for Python objects in the Python/C API. Extension types wanting to 4587define these methods must provide them as a normal Python accessible method. 4588Compared to the overhead of setting up the runtime context, the overhead of a 4589single class dictionary lookup is negligible. 4590 4591 4592.. _typesother: 4593 4594Other Built-in Types 4595==================== 4596 4597The interpreter supports several other kinds of objects. Most of these support 4598only one or two operations. 4599 4600 4601.. _typesmodules: 4602 4603Modules 4604------- 4605 4606The only special operation on a module is attribute access: ``m.name``, where 4607*m* is a module and *name* accesses a name defined in *m*'s symbol table. 4608Module attributes can be assigned to. (Note that the :keyword:`import` 4609statement is not, strictly speaking, an operation on a module object; ``import 4610foo`` does not require a module object named *foo* to exist, rather it requires 4611an (external) *definition* for a module named *foo* somewhere.) 4612 4613A special attribute of every module is :attr:`~object.__dict__`. This is the 4614dictionary containing the module's symbol table. Modifying this dictionary will 4615actually change the module's symbol table, but direct assignment to the 4616:attr:`~object.__dict__` attribute is not possible (you can write 4617``m.__dict__['a'] = 1``, which defines ``m.a`` to be ``1``, but you can't write 4618``m.__dict__ = {}``). Modifying :attr:`~object.__dict__` directly is 4619not recommended. 4620 4621Modules built into the interpreter are written like this: ``<module 'sys' 4622(built-in)>``. If loaded from a file, they are written as ``<module 'os' from 4623'/usr/local/lib/pythonX.Y/os.pyc'>``. 4624 4625 4626.. _typesobjects: 4627 4628Classes and Class Instances 4629--------------------------- 4630 4631See :ref:`objects` and :ref:`class` for these. 4632 4633 4634.. _typesfunctions: 4635 4636Functions 4637--------- 4638 4639Function objects are created by function definitions. The only operation on a 4640function object is to call it: ``func(argument-list)``. 4641 4642There are really two flavors of function objects: built-in functions and 4643user-defined functions. Both support the same operation (to call the function), 4644but the implementation is different, hence the different object types. 4645 4646See :ref:`function` for more information. 4647 4648 4649.. _typesmethods: 4650 4651Methods 4652------- 4653 4654.. index:: object: method 4655 4656Methods are functions that are called using the attribute notation. There are 4657two flavors: built-in methods (such as :meth:`append` on lists) and class 4658instance methods. Built-in methods are described with the types that support 4659them. 4660 4661If you access a method (a function defined in a class namespace) through an 4662instance, you get a special object: a :dfn:`bound method` (also called 4663:dfn:`instance method`) object. When called, it will add the ``self`` argument 4664to the argument list. Bound methods have two special read-only attributes: 4665``m.__self__`` is the object on which the method operates, and ``m.__func__`` is 4666the function implementing the method. Calling ``m(arg-1, arg-2, ..., arg-n)`` 4667is completely equivalent to calling ``m.__func__(m.__self__, arg-1, arg-2, ..., 4668arg-n)``. 4669 4670Like function objects, bound method objects support getting arbitrary 4671attributes. However, since method attributes are actually stored on the 4672underlying function object (``meth.__func__``), setting method attributes on 4673bound methods is disallowed. Attempting to set an attribute on a method 4674results in an :exc:`AttributeError` being raised. In order to set a method 4675attribute, you need to explicitly set it on the underlying function object:: 4676 4677 >>> class C: 4678 ... def method(self): 4679 ... pass 4680 ... 4681 >>> c = C() 4682 >>> c.method.whoami = 'my name is method' # can't set on the method 4683 Traceback (most recent call last): 4684 File "<stdin>", line 1, in <module> 4685 AttributeError: 'method' object has no attribute 'whoami' 4686 >>> c.method.__func__.whoami = 'my name is method' 4687 >>> c.method.whoami 4688 'my name is method' 4689 4690See :ref:`types` for more information. 4691 4692 4693.. index:: object; code, code object 4694 4695.. _bltin-code-objects: 4696 4697Code Objects 4698------------ 4699 4700.. index:: 4701 builtin: compile 4702 single: __code__ (function object attribute) 4703 4704Code objects are used by the implementation to represent "pseudo-compiled" 4705executable Python code such as a function body. They differ from function 4706objects because they don't contain a reference to their global execution 4707environment. Code objects are returned by the built-in :func:`compile` function 4708and can be extracted from function objects through their :attr:`__code__` 4709attribute. See also the :mod:`code` module. 4710 4711Accessing ``__code__`` raises an :ref:`auditing event <auditing>` 4712``object.__getattr__`` with arguments ``obj`` and ``"__code__"``. 4713 4714.. index:: 4715 builtin: exec 4716 builtin: eval 4717 4718A code object can be executed or evaluated by passing it (instead of a source 4719string) to the :func:`exec` or :func:`eval` built-in functions. 4720 4721See :ref:`types` for more information. 4722 4723 4724.. _bltin-type-objects: 4725 4726Type Objects 4727------------ 4728 4729.. index:: 4730 builtin: type 4731 module: types 4732 4733Type objects represent the various object types. An object's type is accessed 4734by the built-in function :func:`type`. There are no special operations on 4735types. The standard module :mod:`types` defines names for all standard built-in 4736types. 4737 4738Types are written like this: ``<class 'int'>``. 4739 4740 4741.. _bltin-null-object: 4742 4743The Null Object 4744--------------- 4745 4746This object is returned by functions that don't explicitly return a value. It 4747supports no special operations. There is exactly one null object, named 4748``None`` (a built-in name). ``type(None)()`` produces the same singleton. 4749 4750It is written as ``None``. 4751 4752 4753.. index:: single: ...; ellipsis literal 4754.. _bltin-ellipsis-object: 4755 4756The Ellipsis Object 4757------------------- 4758 4759This object is commonly used by slicing (see :ref:`slicings`). It supports no 4760special operations. There is exactly one ellipsis object, named 4761:const:`Ellipsis` (a built-in name). ``type(Ellipsis)()`` produces the 4762:const:`Ellipsis` singleton. 4763 4764It is written as ``Ellipsis`` or ``...``. 4765 4766 4767.. _bltin-notimplemented-object: 4768 4769The NotImplemented Object 4770------------------------- 4771 4772This object is returned from comparisons and binary operations when they are 4773asked to operate on types they don't support. See :ref:`comparisons` for more 4774information. There is exactly one ``NotImplemented`` object. 4775``type(NotImplemented)()`` produces the singleton instance. 4776 4777It is written as ``NotImplemented``. 4778 4779 4780.. _bltin-boolean-values: 4781 4782Boolean Values 4783-------------- 4784 4785Boolean values are the two constant objects ``False`` and ``True``. They are 4786used to represent truth values (although other values can also be considered 4787false or true). In numeric contexts (for example when used as the argument to 4788an arithmetic operator), they behave like the integers 0 and 1, respectively. 4789The built-in function :func:`bool` can be used to convert any value to a 4790Boolean, if the value can be interpreted as a truth value (see section 4791:ref:`truth` above). 4792 4793.. index:: 4794 single: False 4795 single: True 4796 pair: Boolean; values 4797 4798They are written as ``False`` and ``True``, respectively. 4799 4800 4801.. _typesinternal: 4802 4803Internal Objects 4804---------------- 4805 4806See :ref:`types` for this information. It describes stack frame objects, 4807traceback objects, and slice objects. 4808 4809 4810.. _specialattrs: 4811 4812Special Attributes 4813================== 4814 4815The implementation adds a few special read-only attributes to several object 4816types, where they are relevant. Some of these are not reported by the 4817:func:`dir` built-in function. 4818 4819 4820.. attribute:: object.__dict__ 4821 4822 A dictionary or other mapping object used to store an object's (writable) 4823 attributes. 4824 4825 4826.. attribute:: instance.__class__ 4827 4828 The class to which a class instance belongs. 4829 4830 4831.. attribute:: class.__bases__ 4832 4833 The tuple of base classes of a class object. 4834 4835 4836.. attribute:: definition.__name__ 4837 4838 The name of the class, function, method, descriptor, or 4839 generator instance. 4840 4841 4842.. attribute:: definition.__qualname__ 4843 4844 The :term:`qualified name` of the class, function, method, descriptor, 4845 or generator instance. 4846 4847 .. versionadded:: 3.3 4848 4849 4850.. attribute:: class.__mro__ 4851 4852 This attribute is a tuple of classes that are considered when looking for 4853 base classes during method resolution. 4854 4855 4856.. method:: class.mro() 4857 4858 This method can be overridden by a metaclass to customize the method 4859 resolution order for its instances. It is called at class instantiation, and 4860 its result is stored in :attr:`~class.__mro__`. 4861 4862 4863.. method:: class.__subclasses__ 4864 4865 Each class keeps a list of weak references to its immediate subclasses. This 4866 method returns a list of all those references still alive. 4867 Example:: 4868 4869 >>> int.__subclasses__() 4870 [<class 'bool'>] 4871 4872 4873.. rubric:: Footnotes 4874 4875.. [1] Additional information on these special methods may be found in the Python 4876 Reference Manual (:ref:`customization`). 4877 4878.. [2] As a consequence, the list ``[1, 2]`` is considered equal to ``[1.0, 2.0]``, and 4879 similarly for tuples. 4880 4881.. [3] They must have since the parser can't tell the type of the operands. 4882 4883.. [4] Cased characters are those with general category property being one of 4884 "Lu" (Letter, uppercase), "Ll" (Letter, lowercase), or "Lt" (Letter, titlecase). 4885 4886.. [5] To format only a tuple you should therefore provide a singleton tuple whose only 4887 element is the tuple to be formatted. 4888