/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
 15The :mod:`operator` module exports a set of functions implemented in C
 16corresponding to the intrinsic operators of Python.  For example,
 17``operator.add(x, y)`` is equivalent to the expression ``x+y``.  The function
 18names are those used for special class methods; variants without leading and
 19trailing ``__`` are also provided for convenience.
 20
 21The functions fall into categories that perform object comparisons, logical
 22operations, mathematical operations, sequence operations, and abstract type
 23tests.
 24
 25The object comparison functions are useful for all objects, and are named after
 26the 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
 52The logical operations are also generally applicable to all objects, and support
 53truth 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
 84The 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
210Operations 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.0.  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.0.  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.6
273      This function is removed in Python 3.0.  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.0.  Use :func:`setitem` with a slice
299      index.
300
301Example 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
311Many operations have an "in-place" version.  The following functions provide a
312more primitive access to in-place operators than the usual syntax does; for
313example, 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.6
403      This function is removed in Python 3.0.  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
444The :mod:`operator` module also defines a few predicates to test the type of
445objects; however, these are not all reliable.  It is preferable to test
446abstract 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.6
462      This function is removed in Python 3.0.  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.6
471      This function is removed in Python 3.0.  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.6
480      This function is removed in Python 3.0.  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
487The :mod:`operator` module also defines tools for generalized attribute and item
488lookups.  These are useful for making fast field extractors as arguments for
489:func:`map`, :func:`sorted`, :meth:`itertools.groupby`, or other functions that
490expect 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
569Mapping Operators to Functions
570------------------------------
571
572This table shows how abstract operations correspond to operator symbols in the
573Python 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