From efc285880c4fbc3adaad03d667b46702327a95e4 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 4 Nov 2009 07:38:12 +0000 Subject: #7259: show correct equivalent for operator.i* operations in docstring; fix minor issues in operator docs. --- Doc/library/operator.rst | 176 ++++++++++++++++++++++++----------------------- Modules/operator.c | 32 ++++----- 2 files changed, 105 insertions(+), 103 deletions(-) diff --git a/Doc/library/operator.rst b/Doc/library/operator.rst index 18747bb..20a82bd 100644 --- a/Doc/library/operator.rst +++ b/Doc/library/operator.rst @@ -117,6 +117,14 @@ The mathematical and bitwise operations are the most numerous: .. versionadded:: 2.2 +.. function:: index(a) + __index__(a) + + Return *a* converted to an integer. Equivalent to ``a.__index__()``. + + .. versionadded:: 2.5 + + .. function:: inv(obj) invert(obj) __inv__(obj) @@ -149,7 +157,7 @@ The mathematical and bitwise operations are the most numerous: .. function:: neg(obj) __neg__(obj) - Return *obj* negated. + Return *obj* negated (``-obj``). .. function:: or_(a, b) @@ -161,7 +169,7 @@ The mathematical and bitwise operations are the most numerous: .. function:: pos(obj) __pos__(obj) - Return *obj* positive. + Return *obj* positive (``+obj``). .. function:: pow(a, b) @@ -199,15 +207,7 @@ The mathematical and bitwise operations are the most numerous: 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: +Operations which work with sequences (some of them with mappings too) include: .. function:: concat(a, b) __concat__(a, b) @@ -359,7 +359,7 @@ example, the :term:`statement` ``x += y`` is equivalent to .. function:: ilshift(a, b) __ilshift__(a, b) - ``a = ilshift(a, b)`` is equivalent to ``a <``\ ``<= b``. + ``a = ilshift(a, b)`` is equivalent to ``a <<= b``. .. versionadded:: 2.5 @@ -572,79 +572,81 @@ 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)`` | -+-----------------------+-------------------------+---------------------------------+ ++-----------------------+-------------------------+---------------------------------------+ +| 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)`` | ++-----------------------+-------------------------+---------------------------------------+ +| Positive | ``+ a`` | ``pos(a)`` | ++-----------------------+-------------------------+---------------------------------------+ +| Right Shift | ``a >> b`` | ``rshift(a, b)`` | ++-----------------------+-------------------------+---------------------------------------+ +| Sequence Repetition | ``seq * i`` | ``repeat(seq, i)`` | ++-----------------------+-------------------------+---------------------------------------+ +| Slice Assignment | ``seq[i:j] = values`` | ``setitem(seq, slice(i, j), values)`` | ++-----------------------+-------------------------+---------------------------------------+ +| Slice Deletion | ``del seq[i:j]`` | ``delitem(seq, slice(i, j))`` | ++-----------------------+-------------------------+---------------------------------------+ +| Slicing | ``seq[i:j]`` | ``getitem(seq, slice(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)`` | ++-----------------------+-------------------------+---------------------------------------+ diff --git a/Modules/operator.c b/Modules/operator.c index 78b7796..f0181de 100644 --- a/Modules/operator.c +++ b/Modules/operator.c @@ -7,7 +7,7 @@ PyDoc_STRVAR(operator_doc, This module exports a set of functions implemented in C corresponding\n\ to the intrinsic operators of Python. For example, operator.add(x, y)\n\ is equivalent to the expression x+y. The function names are those\n\ -used for special class methods; variants without leading and trailing\n\ +used for special methods; variants without leading and trailing\n\ '__' are also provided for convenience."); #define spam1(OP,AOP) static PyObject *OP(PyObject *s, PyObject *a1) { \ @@ -277,26 +277,26 @@ spam2o(not_,__not__, "not_(a) -- Same as not a.") spam2(and_,__and__, "and_(a, b) -- Same as a & b.") spam2(xor,__xor__, "xor(a, b) -- Same as a ^ b.") spam2(or_,__or__, "or_(a, b) -- Same as a | b.") -spam2(iadd,__iadd__, "iadd(a, b) -- Same as a += b.") -spam2(isub,__isub__, "isub(a, b) -- Same as a -= b.") -spam2(imul,__imul__, "imul(a, b) -- Same as a *= b.") -spam2(idiv,__idiv__, "idiv(a, b) -- Same as a /= b when __future__.division is not in effect.") -spam2(ifloordiv,__ifloordiv__, "ifloordiv(a, b) -- Same as a //= b.") -spam2(itruediv,__itruediv__, "itruediv(a, b) -- Same as a /= b when __future__.division is in effect.") -spam2(imod,__imod__, "imod(a, b) -- Same as a %= b.") -spam2(ilshift,__ilshift__, "ilshift(a, b) -- Same as a <<= b.") -spam2(irshift,__irshift__, "irshift(a, b) -- Same as a >>= b.") -spam2(iand,__iand__, "iand(a, b) -- Same as a &= b.") -spam2(ixor,__ixor__, "ixor(a, b) -- Same as a ^= b.") -spam2(ior,__ior__, "ior(a, b) -- Same as a |= b.") +spam2(iadd,__iadd__, "a = iadd(a, b) -- Same as a += b.") +spam2(isub,__isub__, "a = isub(a, b) -- Same as a -= b.") +spam2(imul,__imul__, "a = imul(a, b) -- Same as a *= b.") +spam2(idiv,__idiv__, "a = idiv(a, b) -- Same as a /= b when __future__.division is not in effect.") +spam2(ifloordiv,__ifloordiv__, "a = ifloordiv(a, b) -- Same as a //= b.") +spam2(itruediv,__itruediv__, "a = itruediv(a, b) -- Same as a /= b when __future__.division is in effect.") +spam2(imod,__imod__, "a = imod(a, b) -- Same as a %= b.") +spam2(ilshift,__ilshift__, "a = ilshift(a, b) -- Same as a <<= b.") +spam2(irshift,__irshift__, "a = irshift(a, b) -- Same as a >>= b.") +spam2(iand,__iand__, "a = iand(a, b) -- Same as a &= b.") +spam2(ixor,__ixor__, "a = ixor(a, b) -- Same as a ^= b.") +spam2(ior,__ior__, "a = ior(a, b) -- Same as a |= b.") spam2(concat,__concat__, "concat(a, b) -- Same as a + b, for a and b sequences.") spam2(repeat,__repeat__, "repeat(a, b) -- Return a * b, where a is a sequence, and b is an integer.") spam2(iconcat,__iconcat__, - "iconcat(a, b) -- Same as a += b, for a and b sequences.") + "a = iconcat(a, b) -- Same as a += b, for a and b sequences.") spam2(irepeat,__irepeat__, - "irepeat(a, b) -- Same as a *= b, where a is a sequence, and b is an integer.") + "a = irepeat(a, b) -- Same as a *= b, where a is a sequence, and b is an integer.") spam2(getitem,__getitem__, "getitem(a, b) -- Same as a[b].") spam2(setitem,__setitem__, @@ -304,7 +304,7 @@ spam2(setitem,__setitem__, spam2(delitem,__delitem__, "delitem(a, b) -- Same as del a[b].") spam2(pow,__pow__, "pow(a, b) -- Same as a ** b.") -spam2(ipow,__ipow__, "ipow(a, b) -- Same as a **= b.") +spam2(ipow,__ipow__, "a = ipow(a, b) -- Same as a **= b.") spam2(getslice,__getslice__, "getslice(a, b, c) -- Same as a[b:c].") spam2(setslice,__setslice__, -- cgit v0.12