operator — Standard operators as functions

Source code:Lib/operator.py

Theoperator module exports a set of efficient functions corresponding tothe intrinsic operators of Python. For example,operator.add(x,y) isequivalent to the expressionx+y. Many function names are those used forspecial methods, without the double underscores. For backward compatibility,many of these have a variant with the double underscores kept. The variantswithout the double underscores are preferred for clarity.

The functions fall into categories that perform object comparisons, logicaloperations, mathematical operations and sequence operations.

The object comparison functions are useful for all objects, and are named afterthe rich comparison operators they support:

operator.lt(a,b)
operator.le(a,b)
operator.eq(a,b)
operator.ne(a,b)
operator.ge(a,b)
operator.gt(a,b)
operator.__lt__(a,b)
operator.__le__(a,b)
operator.__eq__(a,b)
operator.__ne__(a,b)
operator.__ge__(a,b)
operator.__gt__(a,b)

Perform “rich comparisons” betweena andb. Specifically,lt(a,b) isequivalent toa<b,le(a,b) is equivalent toa<=b,eq(a,b) is equivalent toa==b,ne(a,b) is equivalent toa!=b,gt(a,b) is equivalent toa>b andge(a,b) is equivalent toa>=b. Note that these functions can return any value, which mayor may not be interpretable as a Boolean value. SeeComparisons for more information about rich comparisons.

The logical operations are also generally applicable to all objects, and supporttruth tests, identity tests, and boolean operations:

operator.not_(obj)
operator.__not__(obj)

Return the outcome ofnotobj. (Note that there is no__not__() method for object instances; only the interpreter core definesthis operation. The result is affected by the__bool__() and__len__() methods.)

operator.truth(obj)

ReturnTrue ifobj is true, andFalse otherwise. This isequivalent to using thebool constructor.

operator.is_(a,b)

Returnaisb. Tests object identity.

operator.is_not(a,b)

Returnaisnotb. Tests object identity.

The mathematical and bitwise operations are the most numerous:

operator.abs(obj)
operator.__abs__(obj)

Return the absolute value ofobj.

operator.add(a,b)
operator.__add__(a,b)

Returna+b, fora andb numbers.

operator.and_(a,b)
operator.__and__(a,b)

Return the bitwise and ofa andb.

operator.floordiv(a,b)
operator.__floordiv__(a,b)

Returna//b.

operator.index(a)
operator.__index__(a)

Returna converted to an integer. Equivalent toa.__index__().

Changed in version 3.10:The result always has exact typeint. Previously, the resultcould have been an instance of a subclass ofint.

operator.inv(obj)
operator.invert(obj)
operator.__inv__(obj)
operator.__invert__(obj)

Return the bitwise inverse of the numberobj. This is equivalent to~obj.

operator.lshift(a,b)
operator.__lshift__(a,b)

Returna shifted left byb.

operator.mod(a,b)
operator.__mod__(a,b)

Returna%b.

operator.mul(a,b)
operator.__mul__(a,b)

Returna*b, fora andb numbers.

operator.matmul(a,b)
operator.__matmul__(a,b)

Returna@b.

Added in version 3.5.

operator.neg(obj)
operator.__neg__(obj)

Returnobj negated (-obj).

operator.or_(a,b)
operator.__or__(a,b)

Return the bitwise or ofa andb.

operator.pos(obj)
operator.__pos__(obj)

Returnobj positive (+obj).

operator.pow(a,b)
operator.__pow__(a,b)

Returna**b, fora andb numbers.

operator.rshift(a,b)
operator.__rshift__(a,b)

Returna shifted right byb.

operator.sub(a,b)
operator.__sub__(a,b)

Returna-b.

operator.truediv(a,b)
operator.__truediv__(a,b)

Returna/b where 2/3 is .66 rather than 0. This is also known as“true” division.

operator.xor(a,b)
operator.__xor__(a,b)

Return the bitwise exclusive or ofa andb.

Operations which work with sequences (some of them with mappings too) include:

operator.concat(a,b)
operator.__concat__(a,b)

Returna+b fora andb sequences.

operator.contains(a,b)
operator.__contains__(a,b)

Return the outcome of the testbina. Note the reversed operands.

operator.countOf(a,b)

Return the number of occurrences ofb ina.

operator.delitem(a,b)
operator.__delitem__(a,b)

Remove the value ofa at indexb.

operator.getitem(a,b)
operator.__getitem__(a,b)

Return the value ofa at indexb.

operator.indexOf(a,b)

Return the index of the first of occurrence ofb ina.

operator.setitem(a,b,c)
operator.__setitem__(a,b,c)

Set the value ofa at indexb toc.

operator.length_hint(obj,default=0)

Return an estimated length for the objectobj. First try to return itsactual length, then an estimate usingobject.__length_hint__(), andfinally return the default value.

Added in version 3.4.

The following operation works with callables:

operator.call(obj,/,*args,**kwargs)
operator.__call__(obj,/,*args,**kwargs)

Returnobj(*args,**kwargs).

Added in version 3.11.

Theoperator module also defines tools for generalized attribute and itemlookups. These are useful for making fast field extractors as arguments formap(),sorted(),itertools.groupby(), or other functions thatexpect a function argument.

operator.attrgetter(attr)
operator.attrgetter(*attrs)

Return a callable object that fetchesattr from its operand.If more than one attribute is requested, returns a tuple of attributes.The attribute names can also contain dots. For example:

  • Afterf=attrgetter('name'), the callf(b) returnsb.name.

  • Afterf=attrgetter('name','date'), the callf(b) returns(b.name,b.date).

  • Afterf=attrgetter('name.first','name.last'), the callf(b)returns(b.name.first,b.name.last).

Equivalent to:

defattrgetter(*items):ifany(notisinstance(item,str)foriteminitems):raiseTypeError('attribute name must be a string')iflen(items)==1:attr=items[0]defg(obj):returnresolve_attr(obj,attr)else:defg(obj):returntuple(resolve_attr(obj,attr)forattrinitems)returngdefresolve_attr(obj,attr):fornameinattr.split("."):obj=getattr(obj,name)returnobj
operator.itemgetter(item)
operator.itemgetter(*items)

Return a callable object that fetchesitem from its operand using theoperand’s__getitem__() method. If multiple items are specified,returns a tuple of lookup values. For example:

  • Afterf=itemgetter(2), the callf(r) returnsr[2].

  • Afterg=itemgetter(2,5,3), the callg(r) returns(r[2],r[5],r[3]).

Equivalent to:

defitemgetter(*items):iflen(items)==1:item=items[0]defg(obj):returnobj[item]else:defg(obj):returntuple(obj[item]foriteminitems)returng

The items can be any type accepted by the operand’s__getitem__()method. Dictionaries accept anyhashable value. Lists, tuples, andstrings accept an index or a slice:

>>>itemgetter(1)('ABCDEFG')'B'>>>itemgetter(1,3,5)('ABCDEFG')('B', 'D', 'F')>>>itemgetter(slice(2,None))('ABCDEFG')'CDEFG'>>>soldier=dict(rank='captain',name='dotterbart')>>>itemgetter('rank')(soldier)'captain'

Example of usingitemgetter() to retrieve specific fields from atuple record:

>>>inventory=[('apple',3),('banana',2),('pear',5),('orange',1)]>>>getcount=itemgetter(1)>>>list(map(getcount,inventory))[3, 2, 5, 1]>>>sorted(inventory,key=getcount)[('orange', 1), ('banana', 2), ('apple', 3), ('pear', 5)]
operator.methodcaller(name,/,*args,**kwargs)

Return a callable object that calls the methodname on its operand. Ifadditional arguments and/or keyword arguments are given, they will be givento the method as well. For example:

  • Afterf=methodcaller('name'), the callf(b) returnsb.name().

  • Afterf=methodcaller('name','foo',bar=1), the callf(b)returnsb.name('foo',bar=1).

Equivalent to:

defmethodcaller(name,/,*args,**kwargs):defcaller(obj):returngetattr(obj,name)(*args,**kwargs)returncaller

Mapping Operators to Functions

This table shows how abstract operations correspond to operator symbols in thePython syntax and the functions in theoperator module.

Operation

Syntax

Function

Addition

a+b

add(a,b)

Concatenation

seq1+seq2

concat(seq1,seq2)

Containment Test

objinseq

contains(seq,obj)

Division

a/b

truediv(a,b)

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

aisb

is_(a,b)

Identity

aisnotb

is_not(a,b)

Indexed Assignment

obj[k]=v

setitem(obj,k,v)

Indexed Deletion

delobj[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)

Matrix Multiplication

a@b

matmul(a,b)

Negation (Arithmetic)

-a

neg(a)

Negation (Logical)

nota

not_(a)

Positive

+a

pos(a)

Right Shift

a>>b

rshift(a,b)

Slice Assignment

seq[i:j]=values

setitem(seq,slice(i,j),values)

Slice Deletion

delseq[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)

In-place Operators

Many operations have an “in-place” version. Listed below are functionsproviding a more primitive access to in-place operators than the usual syntaxdoes; for example, thestatementx+=y is equivalent tox=operator.iadd(x,y). Another way to put it is to say thatz=operator.iadd(x,y) is equivalent to the compound statementz=x;z+=y.

In those examples, note that when an in-place method is called, the computationand assignment are performed in two separate steps. The in-place functionslisted below only do the first step, calling the in-place method. The secondstep, assignment, is not handled.

For immutable targets such as strings, numbers, and tuples, the updatedvalue is computed, but not assigned back to the input variable:

>>>a='hello'>>>iadd(a,' world')'hello world'>>>a'hello'

For mutable targets such as lists and dictionaries, the in-place methodwill perform the update, so no subsequent assignment is necessary:

>>>s=['h','e','l','l','o']>>>iadd(s,[' ','w','o','r','l','d'])['h', 'e', 'l', 'l', 'o', ' ', 'w', 'o', 'r', 'l', 'd']>>>s['h', 'e', 'l', 'l', 'o', ' ', 'w', 'o', 'r', 'l', 'd']
operator.iadd(a,b)
operator.__iadd__(a,b)

a=iadd(a,b) is equivalent toa+=b.

operator.iand(a,b)
operator.__iand__(a,b)

a=iand(a,b) is equivalent toa&=b.

operator.iconcat(a,b)
operator.__iconcat__(a,b)

a=iconcat(a,b) is equivalent toa+=b fora andb sequences.

operator.ifloordiv(a,b)
operator.__ifloordiv__(a,b)

a=ifloordiv(a,b) is equivalent toa//=b.

operator.ilshift(a,b)
operator.__ilshift__(a,b)

a=ilshift(a,b) is equivalent toa<<=b.

operator.imod(a,b)
operator.__imod__(a,b)

a=imod(a,b) is equivalent toa%=b.

operator.imul(a,b)
operator.__imul__(a,b)

a=imul(a,b) is equivalent toa*=b.

operator.imatmul(a,b)
operator.__imatmul__(a,b)

a=imatmul(a,b) is equivalent toa@=b.

Added in version 3.5.

operator.ior(a,b)
operator.__ior__(a,b)

a=ior(a,b) is equivalent toa|=b.

operator.ipow(a,b)
operator.__ipow__(a,b)

a=ipow(a,b) is equivalent toa**=b.

operator.irshift(a,b)
operator.__irshift__(a,b)

a=irshift(a,b) is equivalent toa>>=b.

operator.isub(a,b)
operator.__isub__(a,b)

a=isub(a,b) is equivalent toa-=b.

operator.itruediv(a,b)
operator.__itruediv__(a,b)

a=itruediv(a,b) is equivalent toa/=b.

operator.ixor(a,b)
operator.__ixor__(a,b)

a=ixor(a,b) is equivalent toa^=b.