Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`operator` --- Standard operators as functions |
| 2 | =================================================== |
| 3 | |
| 4 | .. module:: operator |
| 5 | :synopsis: Functions corresponding to the standard operators. |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 6 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 7 | .. sectionauthor:: Skip Montanaro <skip@automatrix.com> |
| 8 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 9 | **Source code:** :source:`Lib/operator.py` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 10 | |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 11 | .. testsetup:: |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 12 | |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 13 | import operator |
Alexander Belopolsky | 287d1fd | 2011-01-12 16:37:14 +0000 | [diff] [blame] | 14 | from operator import itemgetter, iadd |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 15 | |
Raymond Hettinger | 3f5228d | 2013-05-10 19:57:44 -0700 | [diff] [blame] | 16 | -------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 17 | |
Benjamin Peterson | 0f1e3ac | 2011-12-20 10:12:41 -0600 | [diff] [blame] | 18 | The :mod:`operator` module exports a set of efficient functions corresponding to |
| 19 | the intrinsic operators of Python. For example, ``operator.add(x, y)`` is |
Sanket Dasgupta | 5b9299d | 2017-09-24 23:59:22 +0530 | [diff] [blame] | 20 | equivalent to the expression ``x+y``. Many function names are those used for |
| 21 | special methods, without the double underscores. For backward compatibility, |
| 22 | many of these have a variant with the double underscores kept. The variants |
| 23 | without the double underscores are preferred for clarity. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 24 | |
| 25 | The functions fall into categories that perform object comparisons, logical |
Georg Brandl | b30f330 | 2011-01-06 09:23:56 +0000 | [diff] [blame] | 26 | operations, mathematical operations and sequence operations. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 27 | |
| 28 | The object comparison functions are useful for all objects, and are named after |
| 29 | the rich comparison operators they support: |
| 30 | |
| 31 | |
| 32 | .. function:: lt(a, b) |
| 33 | le(a, b) |
| 34 | eq(a, b) |
| 35 | ne(a, b) |
| 36 | ge(a, b) |
| 37 | gt(a, b) |
| 38 | __lt__(a, b) |
| 39 | __le__(a, b) |
| 40 | __eq__(a, b) |
| 41 | __ne__(a, b) |
| 42 | __ge__(a, b) |
| 43 | __gt__(a, b) |
| 44 | |
| 45 | Perform "rich comparisons" between *a* and *b*. Specifically, ``lt(a, b)`` is |
| 46 | equivalent to ``a < b``, ``le(a, b)`` is equivalent to ``a <= b``, ``eq(a, |
| 47 | b)`` is equivalent to ``a == b``, ``ne(a, b)`` is equivalent to ``a != b``, |
| 48 | ``gt(a, b)`` is equivalent to ``a > b`` and ``ge(a, b)`` is equivalent to ``a |
Mark Dickinson | c48d834 | 2009-02-01 14:18:10 +0000 | [diff] [blame] | 49 | >= b``. Note that these functions can return any value, which may |
| 50 | or may not be interpretable as a Boolean value. See |
| 51 | :ref:`comparisons` for more information about rich comparisons. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 52 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 53 | |
| 54 | The logical operations are also generally applicable to all objects, and support |
| 55 | truth tests, identity tests, and boolean operations: |
| 56 | |
| 57 | |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 58 | .. function:: not_(obj) |
| 59 | __not__(obj) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 60 | |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 61 | Return the outcome of :keyword:`not` *obj*. (Note that there is no |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 62 | :meth:`__not__` method for object instances; only the interpreter core defines |
| 63 | this operation. The result is affected by the :meth:`__bool__` and |
| 64 | :meth:`__len__` methods.) |
| 65 | |
| 66 | |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 67 | .. function:: truth(obj) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 68 | |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 69 | Return :const:`True` if *obj* is true, and :const:`False` otherwise. This is |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 70 | equivalent to using the :class:`bool` constructor. |
| 71 | |
| 72 | |
| 73 | .. function:: is_(a, b) |
| 74 | |
| 75 | Return ``a is b``. Tests object identity. |
| 76 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 77 | |
| 78 | .. function:: is_not(a, b) |
| 79 | |
| 80 | Return ``a is not b``. Tests object identity. |
| 81 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 82 | |
| 83 | The mathematical and bitwise operations are the most numerous: |
| 84 | |
| 85 | |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 86 | .. function:: abs(obj) |
| 87 | __abs__(obj) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 88 | |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 89 | Return the absolute value of *obj*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 90 | |
| 91 | |
| 92 | .. function:: add(a, b) |
| 93 | __add__(a, b) |
| 94 | |
| 95 | Return ``a + b``, for *a* and *b* numbers. |
| 96 | |
| 97 | |
| 98 | .. function:: and_(a, b) |
| 99 | __and__(a, b) |
| 100 | |
| 101 | Return the bitwise and of *a* and *b*. |
| 102 | |
| 103 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 104 | .. function:: floordiv(a, b) |
| 105 | __floordiv__(a, b) |
| 106 | |
| 107 | Return ``a // b``. |
| 108 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 109 | |
Benjamin Peterson | a0dfa82 | 2009-11-13 02:25:08 +0000 | [diff] [blame] | 110 | .. function:: index(a) |
| 111 | __index__(a) |
| 112 | |
| 113 | Return *a* converted to an integer. Equivalent to ``a.__index__()``. |
| 114 | |
Benjamin Peterson | a0dfa82 | 2009-11-13 02:25:08 +0000 | [diff] [blame] | 115 | |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 116 | .. function:: inv(obj) |
| 117 | invert(obj) |
| 118 | __inv__(obj) |
| 119 | __invert__(obj) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 120 | |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 121 | Return the bitwise inverse of the number *obj*. This is equivalent to ``~obj``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 122 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 123 | |
| 124 | .. function:: lshift(a, b) |
| 125 | __lshift__(a, b) |
| 126 | |
| 127 | Return *a* shifted left by *b*. |
| 128 | |
| 129 | |
| 130 | .. function:: mod(a, b) |
| 131 | __mod__(a, b) |
| 132 | |
| 133 | Return ``a % b``. |
| 134 | |
| 135 | |
| 136 | .. function:: mul(a, b) |
| 137 | __mul__(a, b) |
| 138 | |
| 139 | Return ``a * b``, for *a* and *b* numbers. |
| 140 | |
| 141 | |
Benjamin Peterson | d51374e | 2014-04-09 23:55:56 -0400 | [diff] [blame] | 142 | .. function:: matmul(a, b) |
| 143 | __matmul__(a, b) |
| 144 | |
| 145 | Return ``a @ b``. |
| 146 | |
| 147 | .. versionadded:: 3.5 |
| 148 | |
| 149 | |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 150 | .. function:: neg(obj) |
| 151 | __neg__(obj) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 152 | |
Benjamin Peterson | a0dfa82 | 2009-11-13 02:25:08 +0000 | [diff] [blame] | 153 | Return *obj* negated (``-obj``). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 154 | |
| 155 | |
| 156 | .. function:: or_(a, b) |
| 157 | __or__(a, b) |
| 158 | |
| 159 | Return the bitwise or of *a* and *b*. |
| 160 | |
| 161 | |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 162 | .. function:: pos(obj) |
| 163 | __pos__(obj) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 164 | |
Benjamin Peterson | a0dfa82 | 2009-11-13 02:25:08 +0000 | [diff] [blame] | 165 | Return *obj* positive (``+obj``). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 166 | |
| 167 | |
| 168 | .. function:: pow(a, b) |
| 169 | __pow__(a, b) |
| 170 | |
| 171 | Return ``a ** b``, for *a* and *b* numbers. |
| 172 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 173 | |
| 174 | .. function:: rshift(a, b) |
| 175 | __rshift__(a, b) |
| 176 | |
| 177 | Return *a* shifted right by *b*. |
| 178 | |
| 179 | |
| 180 | .. function:: sub(a, b) |
| 181 | __sub__(a, b) |
| 182 | |
| 183 | Return ``a - b``. |
| 184 | |
| 185 | |
| 186 | .. function:: truediv(a, b) |
| 187 | __truediv__(a, b) |
| 188 | |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 189 | Return ``a / b`` where 2/3 is .66 rather than 0. This is also known as |
| 190 | "true" division. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 191 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 192 | |
| 193 | .. function:: xor(a, b) |
| 194 | __xor__(a, b) |
| 195 | |
| 196 | Return the bitwise exclusive or of *a* and *b*. |
| 197 | |
| 198 | |
Benjamin Peterson | a0dfa82 | 2009-11-13 02:25:08 +0000 | [diff] [blame] | 199 | Operations which work with sequences (some of them with mappings too) include: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 200 | |
| 201 | .. function:: concat(a, b) |
| 202 | __concat__(a, b) |
| 203 | |
| 204 | Return ``a + b`` for *a* and *b* sequences. |
| 205 | |
| 206 | |
| 207 | .. function:: contains(a, b) |
| 208 | __contains__(a, b) |
| 209 | |
| 210 | Return the outcome of the test ``b in a``. Note the reversed operands. |
| 211 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 212 | |
| 213 | .. function:: countOf(a, b) |
| 214 | |
| 215 | Return the number of occurrences of *b* in *a*. |
| 216 | |
| 217 | |
| 218 | .. function:: delitem(a, b) |
| 219 | __delitem__(a, b) |
| 220 | |
| 221 | Remove the value of *a* at index *b*. |
| 222 | |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 223 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 224 | .. function:: getitem(a, b) |
| 225 | __getitem__(a, b) |
| 226 | |
| 227 | Return the value of *a* at index *b*. |
| 228 | |
| 229 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 230 | .. function:: indexOf(a, b) |
| 231 | |
| 232 | Return the index of the first of occurrence of *b* in *a*. |
| 233 | |
| 234 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 235 | .. function:: setitem(a, b, c) |
| 236 | __setitem__(a, b, c) |
| 237 | |
| 238 | Set the value of *a* at index *b* to *c*. |
| 239 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 240 | |
Armin Ronacher | aa9a79d | 2012-10-06 14:03:24 +0200 | [diff] [blame] | 241 | .. function:: length_hint(obj, default=0) |
| 242 | |
R David Murray | e8db162 | 2014-03-10 15:00:33 -0400 | [diff] [blame] | 243 | Return an estimated length for the object *o*. First try to return its |
Ezio Melotti | e12dc28 | 2012-10-07 12:09:36 +0300 | [diff] [blame] | 244 | actual length, then an estimate using :meth:`object.__length_hint__`, and |
R David Murray | e8db162 | 2014-03-10 15:00:33 -0400 | [diff] [blame] | 245 | finally return the default value. |
Armin Ronacher | aa9a79d | 2012-10-06 14:03:24 +0200 | [diff] [blame] | 246 | |
Armin Ronacher | 74b38b1 | 2012-10-07 10:29:32 +0200 | [diff] [blame] | 247 | .. versionadded:: 3.4 |
| 248 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 249 | The :mod:`operator` module also defines tools for generalized attribute and item |
| 250 | lookups. These are useful for making fast field extractors as arguments for |
| 251 | :func:`map`, :func:`sorted`, :meth:`itertools.groupby`, or other functions that |
| 252 | expect a function argument. |
| 253 | |
| 254 | |
Ezio Melotti | babc822 | 2013-05-08 10:53:11 +0300 | [diff] [blame] | 255 | .. function:: attrgetter(attr) |
| 256 | attrgetter(*attrs) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 257 | |
Ezio Melotti | babc822 | 2013-05-08 10:53:11 +0300 | [diff] [blame] | 258 | Return a callable object that fetches *attr* from its operand. |
| 259 | If more than one attribute is requested, returns a tuple of attributes. |
| 260 | The attribute names can also contain dots. For example: |
| 261 | |
| 262 | * After ``f = attrgetter('name')``, the call ``f(b)`` returns ``b.name``. |
| 263 | |
| 264 | * After ``f = attrgetter('name', 'date')``, the call ``f(b)`` returns |
| 265 | ``(b.name, b.date)``. |
| 266 | |
| 267 | * After ``f = attrgetter('name.first', 'name.last')``, the call ``f(b)`` |
Zachary Ware | 0bffca0 | 2013-12-18 12:21:49 -0600 | [diff] [blame] | 268 | returns ``(b.name.first, b.name.last)``. |
Ezio Melotti | babc822 | 2013-05-08 10:53:11 +0300 | [diff] [blame] | 269 | |
| 270 | Equivalent to:: |
Benjamin Peterson | 2d55e2a | 2010-08-21 20:08:36 +0000 | [diff] [blame] | 271 | |
| 272 | def attrgetter(*items): |
Antoine Pitrou | e974571 | 2010-10-31 15:26:04 +0000 | [diff] [blame] | 273 | if any(not isinstance(item, str) for item in items): |
| 274 | raise TypeError('attribute name must be a string') |
Benjamin Peterson | 2d55e2a | 2010-08-21 20:08:36 +0000 | [diff] [blame] | 275 | if len(items) == 1: |
| 276 | attr = items[0] |
| 277 | def g(obj): |
| 278 | return resolve_attr(obj, attr) |
| 279 | else: |
| 280 | def g(obj): |
Georg Brandl | f6d6347 | 2013-10-06 19:14:35 +0200 | [diff] [blame] | 281 | return tuple(resolve_attr(obj, attr) for attr in items) |
Benjamin Peterson | 2d55e2a | 2010-08-21 20:08:36 +0000 | [diff] [blame] | 282 | return g |
| 283 | |
| 284 | def resolve_attr(obj, attr): |
| 285 | for name in attr.split("."): |
| 286 | obj = getattr(obj, name) |
| 287 | return obj |
| 288 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 289 | |
Ezio Melotti | babc822 | 2013-05-08 10:53:11 +0300 | [diff] [blame] | 290 | .. function:: itemgetter(item) |
| 291 | itemgetter(*items) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 292 | |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 293 | Return a callable object that fetches *item* from its operand using the |
| 294 | operand's :meth:`__getitem__` method. If multiple items are specified, |
Ezio Melotti | babc822 | 2013-05-08 10:53:11 +0300 | [diff] [blame] | 295 | returns a tuple of lookup values. For example: |
| 296 | |
| 297 | * After ``f = itemgetter(2)``, the call ``f(r)`` returns ``r[2]``. |
| 298 | |
| 299 | * After ``g = itemgetter(2, 5, 3)``, the call ``g(r)`` returns |
| 300 | ``(r[2], r[5], r[3])``. |
| 301 | |
| 302 | Equivalent to:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 303 | |
Benjamin Peterson | ffec810 | 2010-08-21 20:01:28 +0000 | [diff] [blame] | 304 | def itemgetter(*items): |
| 305 | if len(items) == 1: |
| 306 | item = items[0] |
| 307 | def g(obj): |
| 308 | return obj[item] |
| 309 | else: |
| 310 | def g(obj): |
| 311 | return tuple(obj[item] for item in items) |
| 312 | return g |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 313 | |
| 314 | The items can be any type accepted by the operand's :meth:`__getitem__` |
| 315 | method. Dictionaries accept any hashable value. Lists, tuples, and |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 316 | strings accept an index or a slice: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 317 | |
WeizhongTu | ffa2c3e | 2018-04-13 09:33:08 +0800 | [diff] [blame] | 318 | >>> itemgetter('name')({'name': 'tu', 'age': 18}) |
| 319 | 'tu' |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 320 | >>> itemgetter(1)('ABCDEFG') |
| 321 | 'B' |
| 322 | >>> itemgetter(1,3,5)('ABCDEFG') |
| 323 | ('B', 'D', 'F') |
| 324 | >>> itemgetter(slice(2,None))('ABCDEFG') |
| 325 | 'CDEFG' |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 326 | |
Raymond Hettinger | 70c2dd3 | 2017-09-07 23:53:07 -0700 | [diff] [blame] | 327 | >>> soldier = dict(rank='captain', name='dotterbart') |
| 328 | >>> itemgetter('rank')(soldier) |
| 329 | 'captain' |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 330 | |
| 331 | Example of using :func:`itemgetter` to retrieve specific fields from a |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 332 | tuple record: |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 333 | |
Benjamin Peterson | c16f8b3 | 2010-08-21 20:03:15 +0000 | [diff] [blame] | 334 | >>> inventory = [('apple', 3), ('banana', 2), ('pear', 5), ('orange', 1)] |
| 335 | >>> getcount = itemgetter(1) |
Raymond Hettinger | d292a17 | 2010-09-01 07:46:54 +0000 | [diff] [blame] | 336 | >>> list(map(getcount, inventory)) |
Benjamin Peterson | c16f8b3 | 2010-08-21 20:03:15 +0000 | [diff] [blame] | 337 | [3, 2, 5, 1] |
| 338 | >>> sorted(inventory, key=getcount) |
| 339 | [('orange', 1), ('banana', 2), ('apple', 3), ('pear', 5)] |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 340 | |
| 341 | |
Christian Heimes | d3eb5a15 | 2008-02-24 00:38:49 +0000 | [diff] [blame] | 342 | .. function:: methodcaller(name[, args...]) |
| 343 | |
| 344 | Return a callable object that calls the method *name* on its operand. If |
| 345 | additional arguments and/or keyword arguments are given, they will be given |
Ezio Melotti | babc822 | 2013-05-08 10:53:11 +0300 | [diff] [blame] | 346 | to the method as well. For example: |
| 347 | |
| 348 | * After ``f = methodcaller('name')``, the call ``f(b)`` returns ``b.name()``. |
| 349 | |
| 350 | * After ``f = methodcaller('name', 'foo', bar=1)``, the call ``f(b)`` |
| 351 | returns ``b.name('foo', bar=1)``. |
| 352 | |
| 353 | Equivalent to:: |
Benjamin Peterson | 2d55e2a | 2010-08-21 20:08:36 +0000 | [diff] [blame] | 354 | |
| 355 | def methodcaller(name, *args, **kwargs): |
| 356 | def caller(obj): |
| 357 | return getattr(obj, name)(*args, **kwargs) |
| 358 | return caller |
Christian Heimes | d3eb5a15 | 2008-02-24 00:38:49 +0000 | [diff] [blame] | 359 | |
| 360 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 361 | .. _operator-map: |
| 362 | |
| 363 | Mapping Operators to Functions |
| 364 | ------------------------------ |
| 365 | |
| 366 | This table shows how abstract operations correspond to operator symbols in the |
| 367 | Python syntax and the functions in the :mod:`operator` module. |
| 368 | |
Benjamin Peterson | a0dfa82 | 2009-11-13 02:25:08 +0000 | [diff] [blame] | 369 | +-----------------------+-------------------------+---------------------------------------+ |
| 370 | | Operation | Syntax | Function | |
| 371 | +=======================+=========================+=======================================+ |
| 372 | | Addition | ``a + b`` | ``add(a, b)`` | |
| 373 | +-----------------------+-------------------------+---------------------------------------+ |
| 374 | | Concatenation | ``seq1 + seq2`` | ``concat(seq1, seq2)`` | |
| 375 | +-----------------------+-------------------------+---------------------------------------+ |
| 376 | | Containment Test | ``obj in seq`` | ``contains(seq, obj)`` | |
| 377 | +-----------------------+-------------------------+---------------------------------------+ |
Sandro Tosi | 83c4882 | 2012-02-28 22:28:28 +0100 | [diff] [blame] | 378 | | Division | ``a / b`` | ``truediv(a, b)`` | |
Benjamin Peterson | a0dfa82 | 2009-11-13 02:25:08 +0000 | [diff] [blame] | 379 | +-----------------------+-------------------------+---------------------------------------+ |
| 380 | | Division | ``a // b`` | ``floordiv(a, b)`` | |
| 381 | +-----------------------+-------------------------+---------------------------------------+ |
| 382 | | Bitwise And | ``a & b`` | ``and_(a, b)`` | |
| 383 | +-----------------------+-------------------------+---------------------------------------+ |
| 384 | | Bitwise Exclusive Or | ``a ^ b`` | ``xor(a, b)`` | |
| 385 | +-----------------------+-------------------------+---------------------------------------+ |
| 386 | | Bitwise Inversion | ``~ a`` | ``invert(a)`` | |
| 387 | +-----------------------+-------------------------+---------------------------------------+ |
| 388 | | Bitwise Or | ``a | b`` | ``or_(a, b)`` | |
| 389 | +-----------------------+-------------------------+---------------------------------------+ |
| 390 | | Exponentiation | ``a ** b`` | ``pow(a, b)`` | |
| 391 | +-----------------------+-------------------------+---------------------------------------+ |
| 392 | | Identity | ``a is b`` | ``is_(a, b)`` | |
| 393 | +-----------------------+-------------------------+---------------------------------------+ |
| 394 | | Identity | ``a is not b`` | ``is_not(a, b)`` | |
| 395 | +-----------------------+-------------------------+---------------------------------------+ |
| 396 | | Indexed Assignment | ``obj[k] = v`` | ``setitem(obj, k, v)`` | |
| 397 | +-----------------------+-------------------------+---------------------------------------+ |
| 398 | | Indexed Deletion | ``del obj[k]`` | ``delitem(obj, k)`` | |
| 399 | +-----------------------+-------------------------+---------------------------------------+ |
| 400 | | Indexing | ``obj[k]`` | ``getitem(obj, k)`` | |
| 401 | +-----------------------+-------------------------+---------------------------------------+ |
| 402 | | Left Shift | ``a << b`` | ``lshift(a, b)`` | |
| 403 | +-----------------------+-------------------------+---------------------------------------+ |
| 404 | | Modulo | ``a % b`` | ``mod(a, b)`` | |
| 405 | +-----------------------+-------------------------+---------------------------------------+ |
| 406 | | Multiplication | ``a * b`` | ``mul(a, b)`` | |
| 407 | +-----------------------+-------------------------+---------------------------------------+ |
Benjamin Peterson | d51374e | 2014-04-09 23:55:56 -0400 | [diff] [blame] | 408 | | Matrix Multiplication | ``a @ b`` | ``matmul(a, b)`` | |
| 409 | +-----------------------+-------------------------+---------------------------------------+ |
Benjamin Peterson | a0dfa82 | 2009-11-13 02:25:08 +0000 | [diff] [blame] | 410 | | Negation (Arithmetic) | ``- a`` | ``neg(a)`` | |
| 411 | +-----------------------+-------------------------+---------------------------------------+ |
| 412 | | Negation (Logical) | ``not a`` | ``not_(a)`` | |
| 413 | +-----------------------+-------------------------+---------------------------------------+ |
| 414 | | Positive | ``+ a`` | ``pos(a)`` | |
| 415 | +-----------------------+-------------------------+---------------------------------------+ |
| 416 | | Right Shift | ``a >> b`` | ``rshift(a, b)`` | |
| 417 | +-----------------------+-------------------------+---------------------------------------+ |
Benjamin Peterson | a0dfa82 | 2009-11-13 02:25:08 +0000 | [diff] [blame] | 418 | | Slice Assignment | ``seq[i:j] = values`` | ``setitem(seq, slice(i, j), values)`` | |
| 419 | +-----------------------+-------------------------+---------------------------------------+ |
| 420 | | Slice Deletion | ``del seq[i:j]`` | ``delitem(seq, slice(i, j))`` | |
| 421 | +-----------------------+-------------------------+---------------------------------------+ |
| 422 | | Slicing | ``seq[i:j]`` | ``getitem(seq, slice(i, j))`` | |
| 423 | +-----------------------+-------------------------+---------------------------------------+ |
| 424 | | String Formatting | ``s % obj`` | ``mod(s, obj)`` | |
| 425 | +-----------------------+-------------------------+---------------------------------------+ |
| 426 | | Subtraction | ``a - b`` | ``sub(a, b)`` | |
| 427 | +-----------------------+-------------------------+---------------------------------------+ |
| 428 | | Truth Test | ``obj`` | ``truth(obj)`` | |
| 429 | +-----------------------+-------------------------+---------------------------------------+ |
| 430 | | Ordering | ``a < b`` | ``lt(a, b)`` | |
| 431 | +-----------------------+-------------------------+---------------------------------------+ |
| 432 | | Ordering | ``a <= b`` | ``le(a, b)`` | |
| 433 | +-----------------------+-------------------------+---------------------------------------+ |
| 434 | | Equality | ``a == b`` | ``eq(a, b)`` | |
| 435 | +-----------------------+-------------------------+---------------------------------------+ |
| 436 | | Difference | ``a != b`` | ``ne(a, b)`` | |
| 437 | +-----------------------+-------------------------+---------------------------------------+ |
| 438 | | Ordering | ``a >= b`` | ``ge(a, b)`` | |
| 439 | +-----------------------+-------------------------+---------------------------------------+ |
| 440 | | Ordering | ``a > b`` | ``gt(a, b)`` | |
| 441 | +-----------------------+-------------------------+---------------------------------------+ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 442 | |
Raymond Hettinger | 83b1ab0 | 2011-01-08 10:26:53 +0000 | [diff] [blame] | 443 | Inplace Operators |
Sandro Tosi | 3f7d1d3 | 2012-06-01 20:23:20 +0200 | [diff] [blame] | 444 | ----------------- |
Raymond Hettinger | 83b1ab0 | 2011-01-08 10:26:53 +0000 | [diff] [blame] | 445 | |
| 446 | Many operations have an "in-place" version. Listed below are functions |
| 447 | providing a more primitive access to in-place operators than the usual syntax |
| 448 | does; for example, the :term:`statement` ``x += y`` is equivalent to |
| 449 | ``x = operator.iadd(x, y)``. Another way to put it is to say that |
| 450 | ``z = operator.iadd(x, y)`` is equivalent to the compound statement |
| 451 | ``z = x; z += y``. |
| 452 | |
| 453 | In those examples, note that when an in-place method is called, the computation |
| 454 | and assignment are performed in two separate steps. The in-place functions |
| 455 | listed below only do the first step, calling the in-place method. The second |
| 456 | step, assignment, is not handled. |
| 457 | |
| 458 | For immutable targets such as strings, numbers, and tuples, the updated |
| 459 | value is computed, but not assigned back to the input variable: |
| 460 | |
| 461 | >>> a = 'hello' |
| 462 | >>> iadd(a, ' world') |
| 463 | 'hello world' |
| 464 | >>> a |
| 465 | 'hello' |
| 466 | |
| 467 | For mutable targets such as lists and dictionaries, the inplace method |
| 468 | will perform the update, so no subsequent assignment is necessary: |
| 469 | |
| 470 | >>> s = ['h', 'e', 'l', 'l', 'o'] |
| 471 | >>> iadd(s, [' ', 'w', 'o', 'r', 'l', 'd']) |
| 472 | ['h', 'e', 'l', 'l', 'o', ' ', 'w', 'o', 'r', 'l', 'd'] |
| 473 | >>> s |
| 474 | ['h', 'e', 'l', 'l', 'o', ' ', 'w', 'o', 'r', 'l', 'd'] |
| 475 | |
| 476 | .. function:: iadd(a, b) |
| 477 | __iadd__(a, b) |
| 478 | |
| 479 | ``a = iadd(a, b)`` is equivalent to ``a += b``. |
| 480 | |
| 481 | |
| 482 | .. function:: iand(a, b) |
| 483 | __iand__(a, b) |
| 484 | |
| 485 | ``a = iand(a, b)`` is equivalent to ``a &= b``. |
| 486 | |
| 487 | |
| 488 | .. function:: iconcat(a, b) |
| 489 | __iconcat__(a, b) |
| 490 | |
| 491 | ``a = iconcat(a, b)`` is equivalent to ``a += b`` for *a* and *b* sequences. |
| 492 | |
| 493 | |
| 494 | .. function:: ifloordiv(a, b) |
| 495 | __ifloordiv__(a, b) |
| 496 | |
| 497 | ``a = ifloordiv(a, b)`` is equivalent to ``a //= b``. |
| 498 | |
| 499 | |
| 500 | .. function:: ilshift(a, b) |
| 501 | __ilshift__(a, b) |
| 502 | |
| 503 | ``a = ilshift(a, b)`` is equivalent to ``a <<= b``. |
| 504 | |
| 505 | |
| 506 | .. function:: imod(a, b) |
| 507 | __imod__(a, b) |
| 508 | |
| 509 | ``a = imod(a, b)`` is equivalent to ``a %= b``. |
| 510 | |
| 511 | |
| 512 | .. function:: imul(a, b) |
| 513 | __imul__(a, b) |
| 514 | |
| 515 | ``a = imul(a, b)`` is equivalent to ``a *= b``. |
| 516 | |
| 517 | |
Benjamin Peterson | d51374e | 2014-04-09 23:55:56 -0400 | [diff] [blame] | 518 | .. function:: imatmul(a, b) |
| 519 | __imatmul__(a, b) |
| 520 | |
| 521 | ``a = imatmul(a, b)`` is equivalent to ``a @= b``. |
| 522 | |
| 523 | .. versionadded:: 3.5 |
| 524 | |
| 525 | |
Raymond Hettinger | 83b1ab0 | 2011-01-08 10:26:53 +0000 | [diff] [blame] | 526 | .. function:: ior(a, b) |
| 527 | __ior__(a, b) |
| 528 | |
| 529 | ``a = ior(a, b)`` is equivalent to ``a |= b``. |
| 530 | |
| 531 | |
| 532 | .. function:: ipow(a, b) |
| 533 | __ipow__(a, b) |
| 534 | |
| 535 | ``a = ipow(a, b)`` is equivalent to ``a **= b``. |
| 536 | |
| 537 | |
| 538 | .. function:: irshift(a, b) |
| 539 | __irshift__(a, b) |
| 540 | |
| 541 | ``a = irshift(a, b)`` is equivalent to ``a >>= b``. |
| 542 | |
| 543 | |
| 544 | .. function:: isub(a, b) |
| 545 | __isub__(a, b) |
| 546 | |
| 547 | ``a = isub(a, b)`` is equivalent to ``a -= b``. |
| 548 | |
| 549 | |
| 550 | .. function:: itruediv(a, b) |
| 551 | __itruediv__(a, b) |
| 552 | |
| 553 | ``a = itruediv(a, b)`` is equivalent to ``a /= b``. |
| 554 | |
| 555 | |
| 556 | .. function:: ixor(a, b) |
| 557 | __ixor__(a, b) |
| 558 | |
| 559 | ``a = ixor(a, b)`` is equivalent to ``a ^= b``. |