Move the 3k reST doc tree in place.

1 files changed, 612 insertions, 0 deletions

diff --git a/Doc/library/operator.rst b/Doc/library/operator.rst
new file mode 100644
index 0000000..4e85569
--- /dev/null
+++ b/Doc/library/operator.rst
@@ -0,0 +1,612 @@
+: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.
+
+   .. versionadded:: 2.2
+
+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.
+
+   .. 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(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``.
+
+   .. versionadded:: 2.2
+
+
+.. function:: inv(o)
+              invert(o)
+              __inv__(o)
+              __invert__(o)
+
+   Return the bitwise inverse of the number *o*.  This is equivalent to ``~o``.
+
+   .. 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(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.
+
+   .. 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*.
+
+
+.. 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``.
+
+   .. 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)
+
+   ``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.
+
+.. 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)``.
+
+   .. versionadded:: 2.4
+
+   .. versionchanged:: 2.5
+      Added support for multiple attributes.
+
+
+.. 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])``.
+
+   .. versionadded:: 2.4
+
+   .. versionchanged:: 2.5
+      Added support for multiple item extraction.
+
+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)``                    |
++-----------------------+-------------------------+---------------------------------+
+