| :mod:`operator` --- Standard operators as functions |
| =================================================== |
| |
| .. module:: operator |
| :synopsis: Functions corresponding to the standard operators. |
| .. sectionauthor:: Skip Montanaro <skip@automatrix.com> |
| |
| |
| |
| The :mod:`operator` module exports a set of functions implemented in C |
| corresponding to the intrinsic operators of Python. For example, |
| ``operator.add(x, y)`` is equivalent to the expression ``x+y``. The function |
| names are those used for special class methods; variants without leading and |
| trailing ``__`` are also provided for convenience. |
| |
| The functions fall into categories that perform object comparisons, logical |
| operations, mathematical operations, sequence operations, and abstract type |
| tests. |
| |
| The object comparison functions are useful for all objects, and are named after |
| the rich comparison operators they support: |
| |
| |
| .. function:: lt(a, b) |
| le(a, b) |
| eq(a, b) |
| ne(a, b) |
| ge(a, b) |
| gt(a, b) |
| __lt__(a, b) |
| __le__(a, b) |
| __eq__(a, b) |
| __ne__(a, b) |
| __ge__(a, b) |
| __gt__(a, b) |
| |
| Perform "rich comparisons" between *a* and *b*. Specifically, ``lt(a, b)`` is |
| equivalent to ``a < b``, ``le(a, b)`` is equivalent to ``a <= b``, ``eq(a, |
| b)`` is equivalent to ``a == b``, ``ne(a, b)`` is equivalent to ``a != b``, |
| ``gt(a, b)`` is equivalent to ``a > b`` and ``ge(a, b)`` is equivalent to ``a |
| >= b``. Note that unlike the built-in :func:`cmp`, these functions can |
| return any value, which may or may not be interpretable as a Boolean value. |
| See :ref:`comparisons` for more information about rich comparisons. |
| |
| |
| The logical operations are also generally applicable to all objects, and support |
| truth tests, identity tests, and boolean operations: |
| |
| |
| .. function:: not_(o) |
| __not__(o) |
| |
| Return the outcome of :keyword:`not` *o*. (Note that there is no |
| :meth:`__not__` method for object instances; only the interpreter core defines |
| this operation. The result is affected by the :meth:`__bool__` and |
| :meth:`__len__` methods.) |
| |
| |
| .. function:: truth(o) |
| |
| Return :const:`True` if *o* is true, and :const:`False` otherwise. This is |
| equivalent to using the :class:`bool` constructor. |
| |
| |
| .. function:: is_(a, b) |
| |
| Return ``a is b``. Tests object identity. |
| |
| |
| .. function:: is_not(a, b) |
| |
| Return ``a is not b``. Tests object identity. |
| |
| |
| The mathematical and bitwise operations are the most numerous: |
| |
| |
| .. function:: abs(o) |
| __abs__(o) |
| |
| Return the absolute value of *o*. |
| |
| |
| .. function:: add(a, b) |
| __add__(a, b) |
| |
| Return ``a + b``, for *a* and *b* numbers. |
| |
| |
| .. function:: and_(a, b) |
| __and__(a, b) |
| |
| Return the bitwise and of *a* and *b*. |
| |
| |
| .. function:: div(a, b) |
| __div__(a, b) |
| |
| Return ``a / b`` when ``__future__.division`` is not in effect. This is |
| also known as "classic" division. |
| |
| |
| .. function:: floordiv(a, b) |
| __floordiv__(a, b) |
| |
| Return ``a // b``. |
| |
| |
| .. function:: inv(o) |
| invert(o) |
| __inv__(o) |
| __invert__(o) |
| |
| Return the bitwise inverse of the number *o*. This is equivalent to ``~o``. |
| |
| |
| .. function:: lshift(a, b) |
| __lshift__(a, b) |
| |
| Return *a* shifted left by *b*. |
| |
| |
| .. function:: mod(a, b) |
| __mod__(a, b) |
| |
| Return ``a % b``. |
| |
| |
| .. function:: mul(a, b) |
| __mul__(a, b) |
| |
| Return ``a * b``, for *a* and *b* numbers. |
| |
| |
| .. function:: neg(o) |
| __neg__(o) |
| |
| Return *o* negated. |
| |
| |
| .. function:: or_(a, b) |
| __or__(a, b) |
| |
| Return the bitwise or of *a* and *b*. |
| |
| |
| .. function:: pos(o) |
| __pos__(o) |
| |
| Return *o* positive. |
| |
| |
| .. function:: pow(a, b) |
| __pow__(a, b) |
| |
| Return ``a ** b``, for *a* and *b* numbers. |
| |
| |
| .. function:: rshift(a, b) |
| __rshift__(a, b) |
| |
| Return *a* shifted right by *b*. |
| |
| |
| .. function:: sub(a, b) |
| __sub__(a, b) |
| |
| Return ``a - b``. |
| |
| |
| .. function:: truediv(a, b) |
| __truediv__(a, b) |
| |
| Return ``a / b`` when ``__future__.division`` is in effect. This is also |
| known as "true" division. |
| |
| |
| .. function:: xor(a, b) |
| __xor__(a, b) |
| |
| Return the bitwise exclusive or of *a* and *b*. |
| |
| |
| .. function:: index(a) |
| __index__(a) |
| |
| Return *a* converted to an integer. Equivalent to ``a.__index__()``. |
| |
| |
| Operations which work with sequences include: |
| |
| .. function:: concat(a, b) |
| __concat__(a, b) |
| |
| Return ``a + b`` for *a* and *b* sequences. |
| |
| |
| .. function:: contains(a, b) |
| __contains__(a, b) |
| |
| Return the outcome of the test ``b in a``. Note the reversed operands. |
| |
| |
| .. function:: countOf(a, b) |
| |
| Return the number of occurrences of *b* in *a*. |
| |
| |
| .. function:: delitem(a, b) |
| __delitem__(a, b) |
| |
| Remove the value of *a* at index *b*. |
| |
| |
| .. function:: delslice(a, b, c) |
| __delslice__(a, b, c) |
| |
| Delete the slice of *a* from index *b* to index *c-1*. |
| |
| |
| .. function:: getitem(a, b) |
| __getitem__(a, b) |
| |
| Return the value of *a* at index *b*. |
| |
| |
| .. function:: getslice(a, b, c) |
| __getslice__(a, b, c) |
| |
| Return the slice of *a* from index *b* to index *c-1*. |
| |
| |
| .. function:: indexOf(a, b) |
| |
| Return the index of the first of occurrence of *b* in *a*. |
| |
| |
| .. function:: repeat(a, b) |
| __repeat__(a, b) |
| |
| Return ``a * b`` where *a* is a sequence and *b* is an integer. |
| |
| |
| .. function:: sequenceIncludes(...) |
| |
| .. deprecated:: 2.0 |
| Use :func:`contains` instead. |
| |
| Alias for :func:`contains`. |
| |
| |
| .. function:: setitem(a, b, c) |
| __setitem__(a, b, c) |
| |
| Set the value of *a* at index *b* to *c*. |
| |
| |
| .. function:: setslice(a, b, c, v) |
| __setslice__(a, b, c, v) |
| |
| Set the slice of *a* from index *b* to index *c-1* to the sequence *v*. |
| |
| Many operations have an "in-place" version. The following functions provide a |
| more primitive access to in-place operators than the usual syntax does; for |
| example, the statement ``x += y`` is equivalent to ``x = operator.iadd(x, y)``. |
| Another way to put it is to say that ``z = operator.iadd(x, y)`` is equivalent |
| to the compound statement ``z = x; z += y``. |
| |
| |
| .. function:: iadd(a, b) |
| __iadd__(a, b) |
| |
| ``a = iadd(a, b)`` is equivalent to ``a += b``. |
| |
| |
| .. function:: iand(a, b) |
| __iand__(a, b) |
| |
| ``a = iand(a, b)`` is equivalent to ``a &= b``. |
| |
| |
| .. function:: iconcat(a, b) |
| __iconcat__(a, b) |
| |
| ``a = iconcat(a, b)`` is equivalent to ``a += b`` for *a* and *b* sequences. |
| |
| |
| .. function:: idiv(a, b) |
| __idiv__(a, b) |
| |
| ``a = idiv(a, b)`` is equivalent to ``a /= b`` when ``__future__.division`` is |
| not in effect. |
| |
| |
| .. function:: ifloordiv(a, b) |
| __ifloordiv__(a, b) |
| |
| ``a = ifloordiv(a, b)`` is equivalent to ``a //= b``. |
| |
| |
| .. function:: ilshift(a, b) |
| __ilshift__(a, b) |
| |
| ``a = ilshift(a, b)`` is equivalent to ``a <<= b``. |
| |
| |
| .. function:: imod(a, b) |
| __imod__(a, b) |
| |
| ``a = imod(a, b)`` is equivalent to ``a %= b``. |
| |
| |
| .. function:: imul(a, b) |
| __imul__(a, b) |
| |
| ``a = imul(a, b)`` is equivalent to ``a *= b``. |
| |
| |
| .. function:: ior(a, b) |
| __ior__(a, b) |
| |
| ``a = ior(a, b)`` is equivalent to ``a |= b``. |
| |
| |
| .. function:: ipow(a, b) |
| __ipow__(a, b) |
| |
| ``a = ipow(a, b)`` is equivalent to ``a **= b``. |
| |
| |
| .. function:: irepeat(a, b) |
| __irepeat__(a, b) |
| |
| ``a = irepeat(a, b)`` is equivalent to ``a *= b`` where *a* is a sequence and |
| *b* is an integer. |
| |
| |
| .. function:: irshift(a, b) |
| __irshift__(a, b) |
| |
| ``a = irshift(a, b)`` is equivalent to ``a >>= b``. |
| |
| |
| .. function:: isub(a, b) |
| __isub__(a, b) |
| |
| ``a = isub(a, b)`` is equivalent to ``a -= b``. |
| |
| |
| .. function:: itruediv(a, b) |
| __itruediv__(a, b) |
| |
| ``a = itruediv(a, b)`` is equivalent to ``a /= b`` when ``__future__.division`` |
| is in effect. |
| |
| |
| .. function:: ixor(a, b) |
| __ixor__(a, b) |
| |
| ``a = ixor(a, b)`` is equivalent to ``a ^= b``. |
| |
| |
| The :mod:`operator` module also defines a few predicates to test the type of |
| objects. |
| |
| .. note:: |
| |
| Be careful not to misinterpret the results of these functions; only |
| :func:`isCallable` has any measure of reliability with instance objects. |
| For example:: |
| |
| >>> class C: |
| ... pass |
| ... |
| >>> import operator |
| >>> o = C() |
| >>> operator.isMappingType(o) |
| True |
| |
| |
| .. function:: isCallable(o) |
| |
| .. deprecated:: 2.0 |
| Use the :func:`callable` built-in function instead. |
| |
| Returns true if the object *o* can be called like a function, otherwise it |
| returns false. True is returned for functions, bound and unbound methods, class |
| objects, and instance objects which support the :meth:`__call__` method. |
| |
| |
| .. function:: isMappingType(o) |
| |
| Returns true if the object *o* supports the mapping interface. This is true for |
| dictionaries and all instance objects defining :meth:`__getitem__`. |
| |
| .. warning:: |
| |
| There is no reliable way to test if an instance supports the complete mapping |
| protocol since the interface itself is ill-defined. This makes this test less |
| useful than it otherwise might be. |
| |
| |
| .. function:: isNumberType(o) |
| |
| Returns true if the object *o* represents a number. This is true for all |
| numeric types implemented in C. |
| |
| .. warning:: |
| |
| There is no reliable way to test if an instance supports the complete numeric |
| interface since the interface itself is ill-defined. This makes this test less |
| useful than it otherwise might be. |
| |
| |
| .. function:: isSequenceType(o) |
| |
| Returns true if the object *o* supports the sequence protocol. This returns true |
| for all objects which define sequence methods in C, and for all instance objects |
| defining :meth:`__getitem__`. |
| |
| .. warning:: |
| |
| There is no reliable way to test if an instance supports the complete sequence |
| interface since the interface itself is ill-defined. This makes this test less |
| useful than it otherwise might be. |
| |
| Example: Build a dictionary that maps the ordinals from ``0`` to ``255`` to |
| their character equivalents. :: |
| |
| >>> import operator |
| >>> d = {} |
| >>> keys = range(256) |
| >>> vals = map(chr, keys) |
| >>> map(operator.setitem, [d]*len(keys), keys, vals) |
| |
| .. XXX: find a better, readable, example |
| |
| The :mod:`operator` module also defines tools for generalized attribute and item |
| lookups. These are useful for making fast field extractors as arguments for |
| :func:`map`, :func:`sorted`, :meth:`itertools.groupby`, or other functions that |
| expect a function argument. |
| |
| |
| .. function:: attrgetter(attr[, args...]) |
| |
| Return a callable object that fetches *attr* from its operand. If more than one |
| attribute is requested, returns a tuple of attributes. After, |
| ``f=attrgetter('name')``, the call ``f(b)`` returns ``b.name``. After, |
| ``f=attrgetter('name', 'date')``, the call ``f(b)`` returns ``(b.name, |
| b.date)``. |
| |
| |
| .. function:: itemgetter(item[, args...]) |
| |
| Return a callable object that fetches *item* from its operand. If more than one |
| item is requested, returns a tuple of items. After, ``f=itemgetter(2)``, the |
| call ``f(b)`` returns ``b[2]``. After, ``f=itemgetter(2,5,3)``, the call |
| ``f(b)`` returns ``(b[2], b[5], b[3])``. |
| |
| |
| Examples:: |
| |
| >>> from operator import itemgetter |
| >>> inventory = [('apple', 3), ('banana', 2), ('pear', 5), ('orange', 1)] |
| >>> getcount = itemgetter(1) |
| >>> map(getcount, inventory) |
| [3, 2, 5, 1] |
| >>> sorted(inventory, key=getcount) |
| [('orange', 1), ('banana', 2), ('apple', 3), ('pear', 5)] |
| |
| |
| .. _operator-map: |
| |
| Mapping Operators to Functions |
| ------------------------------ |
| |
| This table shows how abstract operations correspond to operator symbols in the |
| Python syntax and the functions in the :mod:`operator` module. |
| |
| +-----------------------+-------------------------+---------------------------------+ |
| | Operation | Syntax | Function | |
| +=======================+=========================+=================================+ |
| | Addition | ``a + b`` | ``add(a, b)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Concatenation | ``seq1 + seq2`` | ``concat(seq1, seq2)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Containment Test | ``o in seq`` | ``contains(seq, o)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Division | ``a / b`` | ``div(a, b)`` (without | |
| | | | ``__future__.division``) | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Division | ``a / b`` | ``truediv(a, b)`` (with | |
| | | | ``__future__.division``) | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Division | ``a // b`` | ``floordiv(a, b)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Bitwise And | ``a & b`` | ``and_(a, b)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Bitwise Exclusive Or | ``a ^ b`` | ``xor(a, b)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Bitwise Inversion | ``~ a`` | ``invert(a)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Bitwise Or | ``a | b`` | ``or_(a, b)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Exponentiation | ``a ** b`` | ``pow(a, b)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Identity | ``a is b`` | ``is_(a, b)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Identity | ``a is not b`` | ``is_not(a, b)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Indexed Assignment | ``o[k] = v`` | ``setitem(o, k, v)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Indexed Deletion | ``del o[k]`` | ``delitem(o, k)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Indexing | ``o[k]`` | ``getitem(o, k)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Left Shift | ``a << b`` | ``lshift(a, b)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Modulo | ``a % b`` | ``mod(a, b)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Multiplication | ``a * b`` | ``mul(a, b)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Negation (Arithmetic) | ``- a`` | ``neg(a)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Negation (Logical) | ``not a`` | ``not_(a)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Right Shift | ``a >> b`` | ``rshift(a, b)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Sequence Repitition | ``seq * i`` | ``repeat(seq, i)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Slice Assignment | ``seq[i:j] = values`` | ``setslice(seq, i, j, values)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Slice Deletion | ``del seq[i:j]`` | ``delslice(seq, i, j)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Slicing | ``seq[i:j]`` | ``getslice(seq, i, j)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| | String Formatting | ``s % o`` | ``mod(s, o)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Subtraction | ``a - b`` | ``sub(a, b)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Truth Test | ``o`` | ``truth(o)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Ordering | ``a < b`` | ``lt(a, b)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Ordering | ``a <= b`` | ``le(a, b)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Equality | ``a == b`` | ``eq(a, b)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Difference | ``a != b`` | ``ne(a, b)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Ordering | ``a >= b`` | ``ge(a, b)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| | Ordering | ``a > b`` | ``gt(a, b)`` | |
| +-----------------------+-------------------------+---------------------------------+ |
| |