1:mod:`operator` --- Standard operators as functions 2=================================================== 3 4.. module:: operator 5 :synopsis: Functions corresponding to the standard operators. 6 7.. sectionauthor:: Skip Montanaro <skip@automatrix.com> 8 9**Source code:** :source:`Lib/operator.py` 10 11.. testsetup:: 12 13 import operator 14 from operator import itemgetter, iadd 15 16-------------- 17 18The :mod:`operator` module exports a set of efficient functions corresponding to 19the intrinsic operators of Python. For example, ``operator.add(x, y)`` is 20equivalent to the expression ``x+y``. Many function names are those used for 21special methods, without the double underscores. For backward compatibility, 22many of these have a variant with the double underscores kept. The variants 23without the double underscores are preferred for clarity. 24 25The functions fall into categories that perform object comparisons, logical 26operations, mathematical operations and sequence operations. 27 28The object comparison functions are useful for all objects, and are named after 29the 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 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. 52 53 54The logical operations are also generally applicable to all objects, and support 55truth tests, identity tests, and boolean operations: 56 57 58.. function:: not_(obj) 59 __not__(obj) 60 61 Return the outcome of :keyword:`not` *obj*. (Note that there is no 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 67.. function:: truth(obj) 68 69 Return :const:`True` if *obj* is true, and :const:`False` otherwise. This is 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 77 78.. function:: is_not(a, b) 79 80 Return ``a is not b``. Tests object identity. 81 82 83The mathematical and bitwise operations are the most numerous: 84 85 86.. function:: abs(obj) 87 __abs__(obj) 88 89 Return the absolute value of *obj*. 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 104.. function:: floordiv(a, b) 105 __floordiv__(a, b) 106 107 Return ``a // b``. 108 109 110.. function:: index(a) 111 __index__(a) 112 113 Return *a* converted to an integer. Equivalent to ``a.__index__()``. 114 115 116.. function:: inv(obj) 117 invert(obj) 118 __inv__(obj) 119 __invert__(obj) 120 121 Return the bitwise inverse of the number *obj*. This is equivalent to ``~obj``. 122 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 142.. function:: matmul(a, b) 143 __matmul__(a, b) 144 145 Return ``a @ b``. 146 147 .. versionadded:: 3.5 148 149 150.. function:: neg(obj) 151 __neg__(obj) 152 153 Return *obj* negated (``-obj``). 154 155 156.. function:: or_(a, b) 157 __or__(a, b) 158 159 Return the bitwise or of *a* and *b*. 160 161 162.. function:: pos(obj) 163 __pos__(obj) 164 165 Return *obj* positive (``+obj``). 166 167 168.. function:: pow(a, b) 169 __pow__(a, b) 170 171 Return ``a ** b``, for *a* and *b* numbers. 172 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 189 Return ``a / b`` where 2/3 is .66 rather than 0. This is also known as 190 "true" division. 191 192 193.. function:: xor(a, b) 194 __xor__(a, b) 195 196 Return the bitwise exclusive or of *a* and *b*. 197 198 199Operations which work with sequences (some of them with mappings too) include: 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 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 223 224.. function:: getitem(a, b) 225 __getitem__(a, b) 226 227 Return the value of *a* at index *b*. 228 229 230.. function:: indexOf(a, b) 231 232 Return the index of the first of occurrence of *b* in *a*. 233 234 235.. function:: setitem(a, b, c) 236 __setitem__(a, b, c) 237 238 Set the value of *a* at index *b* to *c*. 239 240 241.. function:: length_hint(obj, default=0) 242 243 Return an estimated length for the object *o*. First try to return its 244 actual length, then an estimate using :meth:`object.__length_hint__`, and 245 finally return the default value. 246 247 .. versionadded:: 3.4 248 249The :mod:`operator` module also defines tools for generalized attribute and item 250lookups. These are useful for making fast field extractors as arguments for 251:func:`map`, :func:`sorted`, :meth:`itertools.groupby`, or other functions that 252expect a function argument. 253 254 255.. function:: attrgetter(attr) 256 attrgetter(*attrs) 257 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)`` 268 returns ``(b.name.first, b.name.last)``. 269 270 Equivalent to:: 271 272 def attrgetter(*items): 273 if any(not isinstance(item, str) for item in items): 274 raise TypeError('attribute name must be a string') 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): 281 return tuple(resolve_attr(obj, attr) for attr in items) 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 289 290.. function:: itemgetter(item) 291 itemgetter(*items) 292 293 Return a callable object that fetches *item* from its operand using the 294 operand's :meth:`__getitem__` method. If multiple items are specified, 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:: 303 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 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 316 strings accept an index or a slice: 317 318 >>> itemgetter('name')({'name': 'tu', 'age': 18}) 319 'tu' 320 >>> itemgetter(1)('ABCDEFG') 321 'B' 322 >>> itemgetter(1,3,5)('ABCDEFG') 323 ('B', 'D', 'F') 324 >>> itemgetter(slice(2,None))('ABCDEFG') 325 'CDEFG' 326 327 >>> soldier = dict(rank='captain', name='dotterbart') 328 >>> itemgetter('rank')(soldier) 329 'captain' 330 331 Example of using :func:`itemgetter` to retrieve specific fields from a 332 tuple record: 333 334 >>> inventory = [('apple', 3), ('banana', 2), ('pear', 5), ('orange', 1)] 335 >>> getcount = itemgetter(1) 336 >>> list(map(getcount, inventory)) 337 [3, 2, 5, 1] 338 >>> sorted(inventory, key=getcount) 339 [('orange', 1), ('banana', 2), ('apple', 3), ('pear', 5)] 340 341 342.. function:: methodcaller(name, /, *args, **kwargs) 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 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:: 354 355 def methodcaller(name, /, *args, **kwargs): 356 def caller(obj): 357 return getattr(obj, name)(*args, **kwargs) 358 return caller 359 360 361.. _operator-map: 362 363Mapping Operators to Functions 364------------------------------ 365 366This table shows how abstract operations correspond to operator symbols in the 367Python syntax and the functions in the :mod:`operator` module. 368 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+-----------------------+-------------------------+---------------------------------------+ 378| Division | ``a / b`` | ``truediv(a, b)`` | 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+-----------------------+-------------------------+---------------------------------------+ 408| Matrix Multiplication | ``a @ b`` | ``matmul(a, b)`` | 409+-----------------------+-------------------------+---------------------------------------+ 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+-----------------------+-------------------------+---------------------------------------+ 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+-----------------------+-------------------------+---------------------------------------+ 442 443In-place Operators 444------------------ 445 446Many operations have an "in-place" version. Listed below are functions 447providing a more primitive access to in-place operators than the usual syntax 448does; 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 453In those examples, note that when an in-place method is called, the computation 454and assignment are performed in two separate steps. The in-place functions 455listed below only do the first step, calling the in-place method. The second 456step, assignment, is not handled. 457 458For immutable targets such as strings, numbers, and tuples, the updated 459value 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 467For mutable targets such as lists and dictionaries, the in-place method 468will 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 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 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``. 560