Doc/library/operator.rst

   1 :mod:`operator` --- Standard operators as functions
   2 ===================================================
   3
   4 .. module:: operator
   5    :synopsis: Functions corresponding to the standard operators.
   6 .. sectionauthor:: Skip Montanaro <skip@automatrix.com>
   7
   8
   9 .. testsetup::
  10
  11    import operator
  12    from operator import itemgetter
  13
  14
  15 The :mod:`operator` module exports a set of functions implemented in C
  16 corresponding to the intrinsic operators of Python.  For example,
  17 ``operator.add(x, y)`` is equivalent to the expression ``x+y``.  The function
  18 names are those used for special class methods; variants without leading and
  19 trailing ``__`` are also provided for convenience.
  20
  21 The functions fall into categories that perform object comparisons, logical
  22 operations, mathematical operations, sequence operations, and abstract type
  23 tests.
  24
  25 The object comparison functions are useful for all objects, and are named after
  26 the rich comparison operators they support:
  27
  28
  29 .. function:: lt(a, b)
  30               le(a, b)
  31               eq(a, b)
  32               ne(a, b)
  33               ge(a, b)
  34               gt(a, b)
  35               __lt__(a, b)
  36               __le__(a, b)
  37               __eq__(a, b)
  38               __ne__(a, b)
  39               __ge__(a, b)
  40               __gt__(a, b)
  41
  42    Perform "rich comparisons" between *a* and *b*. Specifically, ``lt(a, b)`` is
  43    equivalent to ``a < b``, ``le(a, b)`` is equivalent to ``a <= b``, ``eq(a,
  44    b)`` is equivalent to ``a == b``, ``ne(a, b)`` is equivalent to ``a != b``,
  45    ``gt(a, b)`` is equivalent to ``a > b`` and ``ge(a, b)`` is equivalent to ``a
  46    >= b``.  Note that unlike the built-in :func:`cmp`, these functions can
  47    return any value, which may or may not be interpretable as a Boolean value.
  48    See :ref:`comparisons` for more information about rich comparisons.
  49
  50    .. versionadded:: 2.2
  51
  52 The logical operations are also generally applicable to all objects, and support
  53 truth tests, identity tests, and boolean operations:
  54
  55
  56 .. function:: not_(obj)
  57               __not__(obj)
  58
  59    Return the outcome of :keyword:`not` *obj*.  (Note that there is no
  60    :meth:`__not__` method for object instances; only the interpreter core defines
  61    this operation.  The result is affected by the :meth:`__nonzero__` and
  62    :meth:`__len__` methods.)
  63
  64
  65 .. function:: truth(obj)
  66
  67    Return :const:`True` if *obj* is true, and :const:`False` otherwise.  This is
  68    equivalent to using the :class:`bool` constructor.
  69
  70
  71 .. function:: is_(a, b)
  72
  73    Return ``a is b``.  Tests object identity.
  74
  75    .. versionadded:: 2.3
  76
  77
  78 .. function:: is_not(a, b)
  79
  80    Return ``a is not b``.  Tests object identity.
  81
  82    .. versionadded:: 2.3
  83
  84 The mathematical and bitwise operations are the most numerous:
  85
  86
  87 .. function:: abs(obj)
  88               __abs__(obj)
  89
  90    Return the absolute value of *obj*.
  91
  92
  93 .. function:: add(a, b)
  94               __add__(a, b)
  95
  96    Return ``a + b``, for *a* and *b* numbers.
  97
  98
  99 .. function:: and_(a, b)
 100               __and__(a, b)
 101
 102    Return the bitwise and of *a* and *b*.
 103
 104
 105 .. function:: div(a, b)
 106               __div__(a, b)
 107
 108    Return ``a / b`` when ``__future__.division`` is not in effect.  This is
 109    also known as "classic" division.
 110
 111
 112 .. function:: floordiv(a, b)
 113               __floordiv__(a, b)
 114
 115    Return ``a // b``.
 116
 117    .. versionadded:: 2.2
 118
 119
 120 .. function:: inv(obj)
 121               invert(obj)
 122               __inv__(obj)
 123               __invert__(obj)
 124
 125    Return the bitwise inverse of the number *obj*.  This is equivalent to ``~obj``.
 126
 127    .. versionadded:: 2.0
 128       The names :func:`invert` and :func:`__invert__`.
 129
 130
 131 .. function:: lshift(a, b)
 132               __lshift__(a, b)
 133
 134    Return *a* shifted left by *b*.
 135
 136
 137 .. function:: mod(a, b)
 138               __mod__(a, b)
 139
 140    Return ``a % b``.
 141
 142
 143 .. function:: mul(a, b)
 144               __mul__(a, b)
 145
 146    Return ``a * b``, for *a* and *b* numbers.
 147
 148
 149 .. function:: neg(obj)
 150               __neg__(obj)
 151
 152    Return *obj* negated.
 153
 154
 155 .. function:: or_(a, b)
 156               __or__(a, b)
 157
 158    Return the bitwise or of *a* and *b*.
 159
 160
 161 .. function:: pos(obj)
 162               __pos__(obj)
 163
 164    Return *obj* positive.
 165
 166
 167 .. function:: pow(a, b)
 168               __pow__(a, b)
 169
 170    Return ``a ** b``, for *a* and *b* numbers.
 171
 172    .. versionadded:: 2.3
 173
 174
 175 .. function:: rshift(a, b)
 176               __rshift__(a, b)
 177
 178    Return *a* shifted right by *b*.
 179
 180
 181 .. function:: sub(a, b)
 182               __sub__(a, b)
 183
 184    Return ``a - b``.
 185
 186
 187 .. function:: truediv(a, b)
 188               __truediv__(a, b)
 189
 190    Return ``a / b`` when ``__future__.division`` is in effect.  This is also
 191    known as "true" division.
 192
 193    .. versionadded:: 2.2
 194
 195
 196 .. function:: xor(a, b)
 197               __xor__(a, b)
 198
 199    Return the bitwise exclusive or of *a* and *b*.
 200
 201
 202 .. function:: index(a)
 203               __index__(a)
 204
 205    Return *a* converted to an integer.  Equivalent to ``a.__index__()``.
 206
 207    .. versionadded:: 2.5
 208
 209
 210 Operations which work with sequences include:
 211
 212 .. function:: concat(a, b)
 213               __concat__(a, b)
 214
 215    Return ``a + b`` for *a* and *b* sequences.
 216
 217
 218 .. function:: contains(a, b)
 219               __contains__(a, b)
 220
 221    Return the outcome of the test ``b in a``. Note the reversed operands.
 222
 223    .. versionadded:: 2.0
 224       The name :func:`__contains__`.
 225
 226
 227 .. function:: countOf(a, b)
 228
 229    Return the number of occurrences of *b* in *a*.
 230
 231
 232 .. function:: delitem(a, b)
 233               __delitem__(a, b)
 234
 235    Remove the value of *a* at index *b*.
 236
 237
 238 .. function:: delslice(a, b, c)
 239               __delslice__(a, b, c)
 240
 241    Delete the slice of *a* from index *b* to index *c-1*.
 242
 243    .. deprecated:: 2.6
 244       This function is removed in Python 3.x.  Use :func:`delitem` with a slice
 245       index.
 246
 247
 248 .. function:: getitem(a, b)
 249               __getitem__(a, b)
 250
 251    Return the value of *a* at index *b*.
 252
 253
 254 .. function:: getslice(a, b, c)
 255               __getslice__(a, b, c)
 256
 257    Return the slice of *a* from index *b* to index *c-1*.
 258
 259    .. deprecated:: 2.6
 260       This function is removed in Python 3.x.  Use :func:`getitem` with a slice
 261       index.
 262
 263
 264 .. function:: indexOf(a, b)
 265
 266    Return the index of the first of occurrence of *b* in *a*.
 267
 268
 269 .. function:: repeat(a, b)
 270               __repeat__(a, b)
 271
 272    .. deprecated:: 2.7
 273       Use :func:`__mul__` instead.
 274
 275    Return ``a * b`` where *a* is a sequence and *b* is an integer.
 276
 277
 278 .. function:: sequenceIncludes(...)
 279
 280    .. deprecated:: 2.0
 281       Use :func:`contains` instead.
 282
 283    Alias for :func:`contains`.
 284
 285
 286 .. function:: setitem(a, b, c)
 287               __setitem__(a, b, c)
 288
 289    Set the value of *a* at index *b* to *c*.
 290
 291
 292 .. function:: setslice(a, b, c, v)
 293               __setslice__(a, b, c, v)
 294
 295    Set the slice of *a* from index *b* to index *c-1* to the sequence *v*.
 296
 297    .. deprecated:: 2.6
 298       This function is removed in Python 3.x.  Use :func:`setitem` with a slice
 299       index.
 300
 301 Example use of operator functions::
 302
 303     >>> # Elementwise multiplication
 304     >>> map(mul, [0, 1, 2, 3], [10, 20, 30, 40])
 305     [0, 20, 60, 120]
 306
 307     >>> # Dot product
 308     >>> sum(map(mul, [0, 1, 2, 3], [10, 20, 30, 40]))
 309     200
 310
 311 Many operations have an "in-place" version.  The following functions provide a
 312 more primitive access to in-place operators than the usual syntax does; for
 313 example, the :term:`statement` ``x += y`` is equivalent to
 314 ``x = operator.iadd(x, y)``.  Another way to put it is to say that
 315 ``z = operator.iadd(x, y)`` is equivalent to the compound statement
 316 ``z = x; z += y``.
 317
 318 .. function:: iadd(a, b)
 319               __iadd__(a, b)
 320
 321    ``a = iadd(a, b)`` is equivalent to ``a += b``.
 322
 323    .. versionadded:: 2.5
 324
 325
 326 .. function:: iand(a, b)
 327               __iand__(a, b)
 328
 329    ``a = iand(a, b)`` is equivalent to ``a &= b``.
 330
 331    .. versionadded:: 2.5
 332
 333
 334 .. function:: iconcat(a, b)
 335               __iconcat__(a, b)
 336
 337    ``a = iconcat(a, b)`` is equivalent to ``a += b`` for *a* and *b* sequences.
 338
 339    .. versionadded:: 2.5
 340
 341
 342 .. function:: idiv(a, b)
 343               __idiv__(a, b)
 344
 345    ``a = idiv(a, b)`` is equivalent to ``a /= b`` when ``__future__.division`` is
 346    not in effect.
 347
 348    .. versionadded:: 2.5
 349
 350
 351 .. function:: ifloordiv(a, b)
 352               __ifloordiv__(a, b)
 353
 354    ``a = ifloordiv(a, b)`` is equivalent to ``a //= b``.
 355
 356    .. versionadded:: 2.5
 357
 358
 359 .. function:: ilshift(a, b)
 360               __ilshift__(a, b)
 361
 362    ``a = ilshift(a, b)`` is equivalent to ``a <``\ ``<= b``.
 363
 364    .. versionadded:: 2.5
 365
 366
 367 .. function:: imod(a, b)
 368               __imod__(a, b)
 369
 370    ``a = imod(a, b)`` is equivalent to ``a %= b``.
 371
 372    .. versionadded:: 2.5
 373
 374
 375 .. function:: imul(a, b)
 376               __imul__(a, b)
 377
 378    ``a = imul(a, b)`` is equivalent to ``a *= b``.
 379
 380    .. versionadded:: 2.5
 381
 382
 383 .. function:: ior(a, b)
 384               __ior__(a, b)
 385
 386    ``a = ior(a, b)`` is equivalent to ``a |= b``.
 387
 388    .. versionadded:: 2.5
 389
 390
 391 .. function:: ipow(a, b)
 392               __ipow__(a, b)
 393
 394    ``a = ipow(a, b)`` is equivalent to ``a **= b``.
 395
 396    .. versionadded:: 2.5
 397
 398
 399 .. function:: irepeat(a, b)
 400               __irepeat__(a, b)
 401
 402    .. deprecated:: 2.7
 403       Use :func:`__imul__` instead.
 404
 405    ``a = irepeat(a, b)`` is equivalent to ``a *= b`` where *a* is a sequence and
 406    *b* is an integer.
 407
 408    .. versionadded:: 2.5
 409
 410
 411 .. function:: irshift(a, b)
 412               __irshift__(a, b)
 413
 414    ``a = irshift(a, b)`` is equivalent to ``a >>= b``.
 415
 416    .. versionadded:: 2.5
 417
 418
 419 .. function:: isub(a, b)
 420               __isub__(a, b)
 421
 422    ``a = isub(a, b)`` is equivalent to ``a -= b``.
 423
 424    .. versionadded:: 2.5
 425
 426
 427 .. function:: itruediv(a, b)
 428               __itruediv__(a, b)
 429
 430    ``a = itruediv(a, b)`` is equivalent to ``a /= b`` when ``__future__.division``
 431    is in effect.
 432
 433    .. versionadded:: 2.5
 434
 435
 436 .. function:: ixor(a, b)
 437               __ixor__(a, b)
 438
 439    ``a = ixor(a, b)`` is equivalent to ``a ^= b``.
 440
 441    .. versionadded:: 2.5
 442
 443
 444 The :mod:`operator` module also defines a few predicates to test the type of
 445 objects; however, these are not all reliable.  It is preferable to test
 446 abstract base classes instead (see :mod:`collections` and
 447 :mod:`numbers` for details).
 448
 449 .. function:: isCallable(obj)
 450
 451    .. deprecated:: 2.0
 452       Use ``isinstance(x, collections.Callable)`` instead.
 453
 454    Returns true if the object *obj* can be called like a function, otherwise it
 455    returns false.  True is returned for functions, bound and unbound methods, class
 456    objects, and instance objects which support the :meth:`__call__` method.
 457
 458
 459 .. function:: isMappingType(obj)
 460
 461    .. deprecated:: 2.7
 462       Use ``isinstance(x, collections.Mapping)`` instead.
 463
 464    Returns true if the object *obj* supports the mapping interface. This is true for
 465    dictionaries and all instance objects defining :meth:`__getitem__`.
 466
 467
 468 .. function:: isNumberType(obj)
 469
 470    .. deprecated:: 2.7
 471       Use ``isinstance(x, numbers.Number)`` instead.
 472
 473    Returns true if the object *obj* represents a number.  This is true for all
 474    numeric types implemented in C.
 475
 476
 477 .. function:: isSequenceType(obj)
 478
 479    .. deprecated:: 2.7
 480       Use ``isinstance(x, collections.Sequence)`` instead.
 481
 482    Returns true if the object *obj* supports the sequence protocol. This returns true
 483    for all objects which define sequence methods in C, and for all instance objects
 484    defining :meth:`__getitem__`.
 485
 486
 487 The :mod:`operator` module also defines tools for generalized attribute and item
 488 lookups.  These are useful for making fast field extractors as arguments for
 489 :func:`map`, :func:`sorted`, :meth:`itertools.groupby`, or other functions that
 490 expect a function argument.
 491
 492
 493 .. function:: attrgetter(attr[, args...])
 494
 495    Return a callable object that fetches *attr* from its operand. If more than one
 496    attribute is requested, returns a tuple of attributes. After,
 497    ``f = attrgetter('name')``, the call ``f(b)`` returns ``b.name``.  After,
 498    ``f = attrgetter('name', 'date')``, the call ``f(b)`` returns ``(b.name,
 499    b.date)``.
 500
 501    The attribute names can also contain dots; after ``f = attrgetter('date.month')``,
 502    the call ``f(b)`` returns ``b.date.month``.
 503
 504    .. versionadded:: 2.4
 505
 506    .. versionchanged:: 2.5
 507       Added support for multiple attributes.
 508
 509    .. versionchanged:: 2.6
 510       Added support for dotted attributes.
 511
 512
 513 .. function:: itemgetter(item[, args...])
 514
 515    Return a callable object that fetches *item* from its operand using the
 516    operand's :meth:`__getitem__` method.  If multiple items are specified,
 517    returns a tuple of lookup values.  Equivalent to::
 518
 519         def itemgetter(*items):
 520             if len(items) == 1:
 521                 item = items[0]
 522                 def g(obj):
 523                     return obj[item]
 524             else:
 525                 def g(obj):
 526                     return tuple(obj[item] for item in items)
 527             return g
 528
 529    The items can be any type accepted by the operand's :meth:`__getitem__`
 530    method.  Dictionaries accept any hashable value.  Lists, tuples, and
 531    strings accept an index or a slice:
 532
 533       >>> itemgetter(1)('ABCDEFG')
 534       'B'
 535       >>> itemgetter(1,3,5)('ABCDEFG')
 536       ('B', 'D', 'F')
 537       >>> itemgetter(slice(2,None))('ABCDEFG')
 538       'CDEFG'
 539
 540    .. versionadded:: 2.4
 541
 542    .. versionchanged:: 2.5
 543       Added support for multiple item extraction.
 544
 545    Example of using :func:`itemgetter` to retrieve specific fields from a
 546    tuple record:
 547
 548        >>> inventory = [('apple', 3), ('banana', 2), ('pear', 5), ('orange', 1)]
 549        >>> getcount = itemgetter(1)
 550        >>> map(getcount, inventory)
 551        [3, 2, 5, 1]
 552        >>> sorted(inventory, key=getcount)
 553        [('orange', 1), ('banana', 2), ('apple', 3), ('pear', 5)]
 554
 555
 556 .. function:: methodcaller(name[, args...])
 557
 558    Return a callable object that calls the method *name* on its operand.  If
 559    additional arguments and/or keyword arguments are given, they will be given
 560    to the method as well.  After ``f = methodcaller('name')``, the call ``f(b)``
 561    returns ``b.name()``.  After ``f = methodcaller('name', 'foo', bar=1)``, the
 562    call ``f(b)`` returns ``b.name('foo', bar=1)``.
 563
 564    .. versionadded:: 2.6
 565
 566
 567 .. _operator-map:
 568
 569 Mapping Operators to Functions
 570 ------------------------------
 571
 572 This table shows how abstract operations correspond to operator symbols in the
 573 Python syntax and the functions in the :mod:`operator` module.
 574
 575 +-----------------------+-------------------------+---------------------------------+
 576 | Operation             | Syntax                  | Function                        |
 577 +=======================+=========================+=================================+
 578 | Addition              | ``a + b``               | ``add(a, b)``                   |
 579 +-----------------------+-------------------------+---------------------------------+
 580 | Concatenation         | ``seq1 + seq2``         | ``concat(seq1, seq2)``          |
 581 +-----------------------+-------------------------+---------------------------------+
 582 | Containment Test      | ``obj in seq``          | ``contains(seq, obj)``          |
 583 +-----------------------+-------------------------+---------------------------------+
 584 | Division              | ``a / b``               | ``div(a, b)`` (without          |
 585 |                       |                         | ``__future__.division``)        |
 586 +-----------------------+-------------------------+---------------------------------+
 587 | Division              | ``a / b``               | ``truediv(a, b)`` (with         |
 588 |                       |                         | ``__future__.division``)        |
 589 +-----------------------+-------------------------+---------------------------------+
 590 | Division              | ``a // b``              | ``floordiv(a, b)``              |
 591 +-----------------------+-------------------------+---------------------------------+
 592 | Bitwise And           | ``a & b``               | ``and_(a, b)``                  |
 593 +-----------------------+-------------------------+---------------------------------+
 594 | Bitwise Exclusive Or  | ``a ^ b``               | ``xor(a, b)``                   |
 595 +-----------------------+-------------------------+---------------------------------+
 596 | Bitwise Inversion     | ``~ a``                 | ``invert(a)``                   |
 597 +-----------------------+-------------------------+---------------------------------+
 598 | Bitwise Or            | ``a | b``               | ``or_(a, b)``                   |
 599 +-----------------------+-------------------------+---------------------------------+
 600 | Exponentiation        | ``a ** b``              | ``pow(a, b)``                   |
 601 +-----------------------+-------------------------+---------------------------------+
 602 | Identity              | ``a is b``              | ``is_(a, b)``                   |
 603 +-----------------------+-------------------------+---------------------------------+
 604 | Identity              | ``a is not b``          | ``is_not(a, b)``                |
 605 +-----------------------+-------------------------+---------------------------------+
 606 | Indexed Assignment    | ``obj[k] = v``          | ``setitem(obj, k, v)``          |
 607 +-----------------------+-------------------------+---------------------------------+
 608 | Indexed Deletion      | ``del obj[k]``          | ``delitem(obj, k)``             |
 609 +-----------------------+-------------------------+---------------------------------+
 610 | Indexing              | ``obj[k]``              | ``getitem(obj, k)``             |
 611 +-----------------------+-------------------------+---------------------------------+
 612 | Left Shift            | ``a << b``              | ``lshift(a, b)``                |
 613 +-----------------------+-------------------------+---------------------------------+
 614 | Modulo                | ``a % b``               | ``mod(a, b)``                   |
 615 +-----------------------+-------------------------+---------------------------------+
 616 | Multiplication        | ``a * b``               | ``mul(a, b)``                   |
 617 +-----------------------+-------------------------+---------------------------------+
 618 | Negation (Arithmetic) | ``- a``                 | ``neg(a)``                      |
 619 +-----------------------+-------------------------+---------------------------------+
 620 | Negation (Logical)    | ``not a``               | ``not_(a)``                     |
 621 +-----------------------+-------------------------+---------------------------------+
 622 | Right Shift           | ``a >> b``              | ``rshift(a, b)``                |
 623 +-----------------------+-------------------------+---------------------------------+
 624 | Sequence Repetition   | ``seq * i``             | ``repeat(seq, i)``              |
 625 +-----------------------+-------------------------+---------------------------------+
 626 | Slice Assignment      | ``seq[i:j] = values``   | ``setslice(seq, i, j, values)`` |
 627 +-----------------------+-------------------------+---------------------------------+
 628 | Slice Deletion        | ``del seq[i:j]``        | ``delslice(seq, i, j)``         |
 629 +-----------------------+-------------------------+---------------------------------+
 630 | Slicing               | ``seq[i:j]``            | ``getslice(seq, i, j)``         |
 631 +-----------------------+-------------------------+---------------------------------+
 632 | String Formatting     | ``s % obj``             | ``mod(s, obj)``                 |
 633 +-----------------------+-------------------------+---------------------------------+
 634 | Subtraction           | ``a - b``               | ``sub(a, b)``                   |
 635 +-----------------------+-------------------------+---------------------------------+
 636 | Truth Test            | ``obj``                 | ``truth(obj)``                  |
 637 +-----------------------+-------------------------+---------------------------------+
 638 | Ordering              | ``a < b``               | ``lt(a, b)``                    |
 639 +-----------------------+-------------------------+---------------------------------+
 640 | Ordering              | ``a <= b``              | ``le(a, b)``                    |
 641 +-----------------------+-------------------------+---------------------------------+
 642 | Equality              | ``a == b``              | ``eq(a, b)``                    |
 643 +-----------------------+-------------------------+---------------------------------+
 644 | Difference            | ``a != b``              | ``ne(a, b)``                    |
 645 +-----------------------+-------------------------+---------------------------------+
 646 | Ordering              | ``a >= b``              | ``ge(a, b)``                    |
 647 +-----------------------+-------------------------+---------------------------------+
 648 | Ordering              | ``a > b``               | ``gt(a, b)``                    |
 649 +-----------------------+-------------------------+---------------------------------+
 650