/Doc/library/operator.rst
http://unladen-swallow.googlecode.com/ · ReStructuredText · 650 lines · 410 code · 240 blank · 0 comment · 0 complexity · 37c5c813c5c4b4fbb08d5d5286aa09c4 MD5 · raw file
- :mod:`operator` --- Standard operators as functions
- ===================================================
- .. module:: operator
- :synopsis: Functions corresponding to the standard operators.
- .. sectionauthor:: Skip Montanaro <skip@automatrix.com>
- .. testsetup::
- import operator
- from operator import itemgetter
- 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.
- .. versionadded:: 2.2
- The logical operations are also generally applicable to all objects, and support
- truth tests, identity tests, and boolean operations:
- .. function:: not_(obj)
- __not__(obj)
- Return the outcome of :keyword:`not` *obj*. (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:`__nonzero__` and
- :meth:`__len__` methods.)
- .. function:: truth(obj)
- Return :const:`True` if *obj* 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.
- .. versionadded:: 2.3
- .. function:: is_not(a, b)
- Return ``a is not b``. Tests object identity.
- .. versionadded:: 2.3
- The mathematical and bitwise operations are the most numerous:
- .. function:: abs(obj)
- __abs__(obj)
- Return the absolute value of *obj*.
- .. 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``.
- .. versionadded:: 2.2
- .. function:: inv(obj)
- invert(obj)
- __inv__(obj)
- __invert__(obj)
- Return the bitwise inverse of the number *obj*. This is equivalent to ``~obj``.
- .. versionadded:: 2.0
- The names :func:`invert` and :func:`__invert__`.
- .. 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(obj)
- __neg__(obj)
- Return *obj* negated.
- .. function:: or_(a, b)
- __or__(a, b)
- Return the bitwise or of *a* and *b*.
- .. function:: pos(obj)
- __pos__(obj)
- Return *obj* positive.
- .. function:: pow(a, b)
- __pow__(a, b)
- Return ``a ** b``, for *a* and *b* numbers.
- .. versionadded:: 2.3
- .. 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.
- .. versionadded:: 2.2
- .. 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__()``.
- .. versionadded:: 2.5
- 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.
- .. versionadded:: 2.0
- The name :func:`__contains__`.
- .. 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*.
- .. deprecated:: 2.6
- This function is removed in Python 3.0. Use :func:`delitem` with a slice
- index.
- .. 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*.
- .. deprecated:: 2.6
- This function is removed in Python 3.0. Use :func:`getitem` with a slice
- index.
- .. function:: indexOf(a, b)
- Return the index of the first of occurrence of *b* in *a*.
- .. function:: repeat(a, b)
- __repeat__(a, b)
- .. deprecated:: 2.6
- This function is removed in Python 3.0. Use :func:`__mul__` instead.
- 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*.
- .. deprecated:: 2.6
- This function is removed in Python 3.0. Use :func:`setitem` with a slice
- index.
- Example use of operator functions::
- >>> # Elementwise multiplication
- >>> map(mul, [0, 1, 2, 3], [10, 20, 30, 40])
- [0, 20, 60, 120]
- >>> # Dot product
- >>> sum(map(mul, [0, 1, 2, 3], [10, 20, 30, 40]))
- 200
- 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 :term:`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``.
- .. versionadded:: 2.5
- .. function:: iand(a, b)
- __iand__(a, b)
- ``a = iand(a, b)`` is equivalent to ``a &= b``.
- .. versionadded:: 2.5
- .. function:: iconcat(a, b)
- __iconcat__(a, b)
- ``a = iconcat(a, b)`` is equivalent to ``a += b`` for *a* and *b* sequences.
- .. versionadded:: 2.5
- .. function:: idiv(a, b)
- __idiv__(a, b)
- ``a = idiv(a, b)`` is equivalent to ``a /= b`` when ``__future__.division`` is
- not in effect.
- .. versionadded:: 2.5
- .. function:: ifloordiv(a, b)
- __ifloordiv__(a, b)
- ``a = ifloordiv(a, b)`` is equivalent to ``a //= b``.
- .. versionadded:: 2.5
- .. function:: ilshift(a, b)
- __ilshift__(a, b)
- ``a = ilshift(a, b)`` is equivalent to ``a <``\ ``<= b``.
- .. versionadded:: 2.5
- .. function:: imod(a, b)
- __imod__(a, b)
- ``a = imod(a, b)`` is equivalent to ``a %= b``.
- .. versionadded:: 2.5
- .. function:: imul(a, b)
- __imul__(a, b)
- ``a = imul(a, b)`` is equivalent to ``a *= b``.
- .. versionadded:: 2.5
- .. function:: ior(a, b)
- __ior__(a, b)
- ``a = ior(a, b)`` is equivalent to ``a |= b``.
- .. versionadded:: 2.5
- .. function:: ipow(a, b)
- __ipow__(a, b)
- ``a = ipow(a, b)`` is equivalent to ``a **= b``.
- .. versionadded:: 2.5
- .. function:: irepeat(a, b)
- __irepeat__(a, b)
- .. deprecated:: 2.6
- This function is removed in Python 3.0. Use :func:`__imul__` instead.
- ``a = irepeat(a, b)`` is equivalent to ``a *= b`` where *a* is a sequence and
- *b* is an integer.
- .. versionadded:: 2.5
- .. function:: irshift(a, b)
- __irshift__(a, b)
- ``a = irshift(a, b)`` is equivalent to ``a >>= b``.
- .. versionadded:: 2.5
- .. function:: isub(a, b)
- __isub__(a, b)
- ``a = isub(a, b)`` is equivalent to ``a -= b``.
- .. versionadded:: 2.5
- .. function:: itruediv(a, b)
- __itruediv__(a, b)
- ``a = itruediv(a, b)`` is equivalent to ``a /= b`` when ``__future__.division``
- is in effect.
- .. versionadded:: 2.5
- .. function:: ixor(a, b)
- __ixor__(a, b)
- ``a = ixor(a, b)`` is equivalent to ``a ^= b``.
- .. versionadded:: 2.5
- The :mod:`operator` module also defines a few predicates to test the type of
- objects; however, these are not all reliable. It is preferable to test
- abstract base classes instead (see :mod:`collections` and
- :mod:`numbers` for details).
- .. function:: isCallable(obj)
- .. deprecated:: 2.0
- Use ``isinstance(x, collections.Callable)`` instead.
- Returns true if the object *obj* 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(obj)
- .. deprecated:: 2.6
- This function is removed in Python 3.0. Use ``isinstance(x, collections.Mapping)`` instead.
- Returns true if the object *obj* supports the mapping interface. This is true for
- dictionaries and all instance objects defining :meth:`__getitem__`.
- .. function:: isNumberType(obj)
- .. deprecated:: 2.6
- This function is removed in Python 3.0. Use ``isinstance(x, numbers.Number)`` instead.
- Returns true if the object *obj* represents a number. This is true for all
- numeric types implemented in C.
- .. function:: isSequenceType(obj)
- .. deprecated:: 2.6
- This function is removed in Python 3.0. Use ``isinstance(x, collections.Sequence)`` instead.
- Returns true if the object *obj* supports the sequence protocol. This returns true
- for all objects which define sequence methods in C, and for all instance objects
- defining :meth:`__getitem__`.
- 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)``.
- The attribute names can also contain dots; after ``f = attrgetter('date.month')``,
- the call ``f(b)`` returns ``b.date.month``.
- .. versionadded:: 2.4
- .. versionchanged:: 2.5
- Added support for multiple attributes.
- .. versionchanged:: 2.6
- Added support for dotted attributes.
- .. function:: itemgetter(item[, args...])
- Return a callable object that fetches *item* from its operand using the
- operand's :meth:`__getitem__` method. If multiple items are specified,
- returns a tuple of lookup values. Equivalent to::
- def itemgetter(*items):
- if len(items) == 1:
- item = items[0]
- def g(obj):
- return obj[item]
- else:
- def g(obj):
- return tuple(obj[item] for item in items)
- return g
- The items can be any type accepted by the operand's :meth:`__getitem__`
- method. Dictionaries accept any hashable value. Lists, tuples, and
- strings accept an index or a slice:
- >>> itemgetter(1)('ABCDEFG')
- 'B'
- >>> itemgetter(1,3,5)('ABCDEFG')
- ('B', 'D', 'F')
- >>> itemgetter(slice(2,None))('ABCDEFG')
- 'CDEFG'
- .. versionadded:: 2.4
- .. versionchanged:: 2.5
- Added support for multiple item extraction.
- Example of using :func:`itemgetter` to retrieve specific fields from a
- tuple record:
- >>> 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)]
- .. function:: methodcaller(name[, args...])
- Return a callable object that calls the method *name* on its operand. If
- additional arguments and/or keyword arguments are given, they will be given
- to the method as well. After ``f = methodcaller('name')``, the call ``f(b)``
- returns ``b.name()``. After ``f = methodcaller('name', 'foo', bar=1)``, the
- call ``f(b)`` returns ``b.name('foo', bar=1)``.
- .. versionadded:: 2.6
- .. _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 | ``obj in seq`` | ``contains(seq, obj)`` |
- +-----------------------+-------------------------+---------------------------------+
- | 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 | ``obj[k] = v`` | ``setitem(obj, k, v)`` |
- +-----------------------+-------------------------+---------------------------------+
- | Indexed Deletion | ``del obj[k]`` | ``delitem(obj, k)`` |
- +-----------------------+-------------------------+---------------------------------+
- | Indexing | ``obj[k]`` | ``getitem(obj, 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 Repetition | ``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 % obj`` | ``mod(s, obj)`` |
- +-----------------------+-------------------------+---------------------------------+
- | Subtraction | ``a - b`` | ``sub(a, b)`` |
- +-----------------------+-------------------------+---------------------------------+
- | Truth Test | ``obj`` | ``truth(obj)`` |
- +-----------------------+-------------------------+---------------------------------+
- | 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)`` |
- +-----------------------+-------------------------+---------------------------------+