Built-in Functions¶

The Python interpreter has a number of functions and types built into it that are always available. They are listed here in alphabetical order.

Built-in Functions
A `abs()` `aiter()` `all()` `anext()` `any()` `ascii()` B `bin()` `bool()` `breakpoint()` `bytearray()` `bytes()` C `callable()` `chr()` `classmethod()` `compile()` `complex()` D `delattr()` `dict()` `dir()` `divmod()`	E `enumerate()` `eval()` `exec()` F `filter()` `float()` `format()` `frozenset()` G `getattr()` `globals()` H `hasattr()` `hash()` `help()` `hex()` I `id()` `input()` `int()` `isinstance()` `issubclass()` `iter()`	L `len()` `list()` `locals()` M `map()` `max()` `memoryview()` `min()` N `next()` O `object()` `oct()` `open()` `ord()` P `pow()` `print()` `property()`	R `range()` `repr()` `reversed()` `round()` S `set()` `setattr()` `slice()` `sorted()` `staticmethod()` `str()` `sum()` `super()` T `tuple()` `type()` V `vars()` Z `zip()` _ `__import__()`

abs(x)¶: Return the absolute value of a number. The argument may be an integer, a floating-point number, or an object implementing __abs__(). If the argument is a complex number, its magnitude is returned.

aiter(async_iterable)¶

Return anasynchronous iteratorfor anasynchronous iterable. Equivalent to callingx.__aiter__().

Note: Unlikeiter(),aiter()has no 2-argument variant.

Added in version 3.10.

all(iterable)¶

ReturnTrueif all elements of theiterableare true (or if the iterable is empty). Equivalent to:

defall(iterable):
forelementiniterable:
ifnotelement:
returnFalse
returnTrue

awaitableanext(async_iterator)¶

awaitableanext(async_iterator,default)

When awaited, return the next item from the givenasynchronous iterator,ordefaultif given and the iterator is exhausted.

This is the async variant of thenext()builtin, and behaves similarly.

This calls the__anext__()method ofasync_iterator, returning anawaitable.Awaiting this returns the next value of the iterator. Ifdefaultis given, it is returned if the iterator is exhausted, otherwiseStopAsyncIterationis raised.

Added in version 3.10.

any(iterable)¶

ReturnTrueif any element of theiterableis true. If the iterable is empty, returnFalse.Equivalent to:

defany(iterable):
forelementiniterable:
ifelement:
returnTrue
returnFalse

ascii(object)¶: Asrepr(),return a string containing a printable representation of an object, but escape the non-ASCII characters in the string returned by repr()using\x,\u,or\Uescapes. This generates a string similar to that returned byrepr()in Python 2.

bin(x)¶

Convert an integer number to a binary string prefixed with “0b”. The result is a valid Python expression. Ifxis not a Pythonintobject, it has to define an__index__()method that returns an integer. Some examples:

>>>bin(3)
'0b11'
>>>bin(-10)
'-0b1010'

If the prefix “0b” is desired or not, you can use either of the following ways.

>>>format(14,'#b'),format(14,'b')
('0b1110', '1110')
>>>f'{14:#b}',f'{14:b}'
('0b1110', '1110')

See alsoformat()for more information.

classbool(object=False,/)¶: Return a Boolean value, i.e. one ofTrueorFalse.The argument is converted using the standardtruth testing procedure. If the argument is false or omitted, this returnsFalse;otherwise, it returnsTrue.The boolclass is a subclass ofint(seeNumeric Types — int, float, complex). It cannot be subclassed further. Its only instances areFalseand True(seeBoolean Type - bool).

Changed in version 3.7:The parameter is now positional-only.

breakpoint(*args,**kws)¶

This function drops you into the debugger at the call site. Specifically, it callssys.breakpointhook(),passingargsandkwsstraight through. By default,sys.breakpointhook()calls pdb.set_trace()expecting no arguments. In this case, it is purely a convenience function so you don’t have to explicitly import pdbor type as much code to enter the debugger. However, sys.breakpointhook()can be set to some other function and breakpoint()will automatically call that, allowing you to drop into the debugger of choice. Ifsys.breakpointhook()is not accessible, this function will raiseRuntimeError.

By default, the behavior ofbreakpoint()can be changed with thePYTHONBREAKPOINTenvironment variable. Seesys.breakpointhook()for usage details.

Note that this is not guaranteed ifsys.breakpointhook() has been replaced.

Raises anauditing eventbuiltins.breakpointwith argumentbreakpointhook.

Added in version 3.7.

classbytearray(source=b'')

classbytearray(source,encoding)

classbytearray(source,encoding,errors)

Return a new array of bytes. Thebytearrayclass is a mutable sequence of integers in the range 0 <= x < 256. It has most of the usual methods of mutable sequences, described inMutable Sequence Types,as well as most methods that thebytestype has, seeBytes and Bytearray Operations.

The optionalsourceparameter can be used to initialize the array in a few different ways:

If it is astring,you must also give theencoding(and optionally, errors) parameters;bytearray()then converts the string to bytes usingstr.encode().
If it is aninteger,the array will have that size and will be initialized with null bytes.
If it is an object conforming to thebuffer interface, a read-only buffer of the object will be used to initialize the bytes array.
If it is aniterable,it must be an iterable of integers in the range 0<=x<256,which are used as the initial contents of the array.

Without an argument, an array of size 0 is created.

classbytes(source=b'')

classbytes(source,encoding)

classbytes(source,encoding,errors)

Return a new “bytes” object which is an immutable sequence of integers in the range0<=x<256.bytesis an immutable version of bytearray– it has the same non-mutating methods and the same indexing and slicing behavior.

Accordingly, constructor arguments are interpreted as forbytearray().

Bytes objects can also be created with literals, seeString and Bytes literals.

callable(object)¶: ReturnTrueif theobjectargument appears callable, Falseif not. If this returnsTrue,it is still possible that a call fails, but if it isFalse,callingobjectwill never succeed. Note that classes are callable (calling a class returns a new instance); instances are callable if their class has a__call__()method.

Added in version 3.2:This function was first removed in Python 3.0 and then brought back in Python 3.2.

chr(i)¶

Return the string representing a character whose Unicode code point is the integeri.For example,chr(97)returns the string'a',while chr(8364)returns the string'€'.This is the inverse oford().

The valid range for the argument is from 0 through 1,114,111 (0x10FFFF in base 16).ValueErrorwill be raised ifiis outside that range.

@classmethod¶

Transform a method into a class method.

A class method receives the class as an implicit first argument, just like an instance method receives the instance. To declare a class method, use this idiom:

classC:
@classmethod
deff(cls,arg1,arg2):...

The@classmethodform is a functiondecorator– see Function definitionsfor details.

A class method can be called either on the class (such asC.f()) or on an instance (such asC().f()). The instance is ignored except for its class. If a class method is called for a derived class, the derived class object is passed as the implied first argument.

Class methods are different than C++ or Java static methods. If you want those, seestaticmethod()in this section. For more information on class methods, seeThe standard type hierarchy.

Changed in version 3.9:Class methods can now wrap otherdescriptorssuch as property().

Changed in version 3.10:Class methods now inherit the method attributes (__module__,__name__, __qualname__,__doc__and __annotations__) and have a new__wrapped__ attribute.

Deprecated since version 3.11, removed in version 3.13:Class methods can no longer wrap otherdescriptorssuch as property().

compile(source,filename,mode,flags=0,dont_inherit=False,optimize=-1)¶

Compile thesourceinto a code or AST object. Code objects can be executed byexec()oreval().sourcecan either be a normal string, a byte string, or an AST object. Refer to theastmodule documentation for information on how to work with AST objects.

Thefilenameargument should give the file from which the code was read; pass some recognizable value if it wasn’t read from a file ('<string>'is commonly used).

Themodeargument specifies what kind of code must be compiled; it can be 'exec'ifsourceconsists of a sequence of statements,'eval'if it consists of a single expression, or'single'if it consists of a single interactive statement (in the latter case, expression statements that evaluate to something other thanNonewill be printed).

The optional argumentsflagsanddont_inheritcontrol which compiler optionsshould be activated and whichfuture featuresshould be allowed. If neither is present (or both are zero) the code is compiled with the same flags that affect the code that is callingcompile().If theflags argument is given anddont_inheritis not (or is zero) then the compiler options and the future statements specified by theflagsargument are used in addition to those that would be used anyway. Ifdont_inheritis a non-zero integer then theflagsargument is it – the flags (future features and compiler options) in the surrounding code are ignored.

Compiler options and future statements are specified by bits which can be bitwise ORed together to specify multiple options. The bitfield required to specify a given future feature can be found as the compiler_flagattribute on the _Featureinstance in the__future__module. Compiler flagscan be found inast module, withPyCF_prefix.

The argumentoptimizespecifies the optimization level of the compiler; the default value of-1selects the optimization level of the interpreter as given by-Ooptions. Explicit levels are0(no optimization; __debug__is true),1(asserts are removed,__debug__is false) or2(docstrings are removed too).

This function raisesSyntaxErrorif the compiled source is invalid, andValueErrorif the source contains null bytes.

If you want to parse Python code into its AST representation, see ast.parse().

Raises anauditing eventcompilewith arguments sourceandfilename.This event may also be raised by implicit compilation.

Note

When compiling a string with multi-line code in'single'or 'eval'mode, input must be terminated by at least one newline character. This is to facilitate detection of incomplete and complete statements in thecodemodule.

Warning

It is possible to crash the Python interpreter with a sufficiently large/complex string when compiling to an AST object due to stack depth limitations in Python’s AST compiler.

Changed in version 3.2:Allowed use of Windows and Mac newlines. Also, input in'exec'mode does not have to end in a newline anymore. Added theoptimizeparameter.

Changed in version 3.5:Previously,TypeErrorwas raised when null bytes were encountered insource.

Added in version 3.8:ast.PyCF_ALLOW_TOP_LEVEL_AWAITcan now be passed in flags to enable support for top-levelawait,asyncfor,andasyncwith.

classcomplex(number=0,/)¶

classcomplex(string,/)

classcomplex(real=0,imag=0)

Convert a single string or number to a complex number, or create a complex number from real and imaginary parts.

Examples:

>>>complex('+1.23')
(1.23+0j)
>>>complex('-4.5j')
-4.5j
>>>complex('-1.23+4.5j')
(-1.23+4.5j)
>>>complex('\t( -1.23+4.5J )\n')
(-1.23+4.5j)
>>>complex('-Infinity+NaNj')
(-inf+nanj)
>>>complex(1.23)
(1.23+0j)
>>>complex(imag=-4.5)
-4.5j
>>>complex(-1.23,4.5)
(-1.23+4.5j)

If the argument is a string, it must contain either a real part (in the same format as forfloat()) or an imaginary part (in the same format but with a'j'or'J'suffix), or both real and imaginary parts (the sign of the imaginary part is mandatory in this case). The string can optionally be surrounded by whitespaces and the round parentheses'('and')',which are ignored. The string must not contain whitespace between'+','-',the 'j'or'J'suffix, and the decimal number. For example,complex('1+2j')is fine, butcomplex('1+2j')raises ValueError. More precisely, the input must conform to thecomplexvalue production rule in the following grammar, after parentheses and leading and trailing whitespace characters are removed:

complexvalue::=floatvalue|
floatvalue( "j" | "J" ) |
floatvaluesignabsfloatvalue( "j" | "J" )

If the argument is a number, the constructor serves as a numeric conversion likeintandfloat. For a general Python objectx,complex(x)delegates to x.__complex__(). If__complex__()is not defined then it falls back to__float__(). If__float__()is not defined then it falls back to__index__().

If two arguments are provided or keyword arguments are used, each argument may be any numeric type (including complex). If both arguments are real numbers, return a complex number with the real componentrealand the imaginary componentimag. If both arguments are complex numbers, return a complex number with the real componentreal.real-imag.imagand the imaginary component real.imag+imag.real. If one of arguments is a real number, only its real component is used in the above expressions.

If all arguments are omitted, returns0j.

The complex type is described inNumeric Types — int, float, complex.

Changed in version 3.6:Grouping digits with underscores as in code literals is allowed.

Changed in version 3.8:Falls back to__index__()if__complex__()and __float__()are not defined.

delattr(object,name)¶: This is a relative ofsetattr().The arguments are an object and a string. The string must be the name of one of the object’s attributes. The function deletes the named attribute, provided the object allows it. For example,delattr(x,'foobar')is equivalent todelx.foobar. nameneed not be a Python identifier (seesetattr()).

classdict(**kwarg)

classdict(mapping,**kwarg)

classdict(iterable,**kwarg)

Create a new dictionary. Thedictobject is the dictionary class. SeedictandMapping Types — dictfor documentation about this class.

For other containers see the built-inlist,set,and tupleclasses, as well as thecollectionsmodule.

dir()¶

dir(object)

Without arguments, return the list of names in the current local scope. With an argument, attempt to return a list of valid attributes for that object.

If the object has a method named__dir__(), this method will be called and must return the list of attributes. This allows objects that implement a custom __getattr__()or__getattribute__()function to customize the way dir()reports their attributes.

If the object does not provide__dir__(), the function tries its best to gather information from the object’s __dict__attribute, if defined, and from its type object. The resulting list is not necessarily complete and may be inaccurate when the object has a custom__getattr__().

The defaultdir()mechanism behaves differently with different types of objects, as it attempts to produce the most relevant, rather than complete, information:

If the object is a module object, the list contains the names of the module’s attributes.
If the object is a type or class object, the list contains the names of its attributes, and recursively of the attributes of its bases.
Otherwise, the list contains the object’s attributes’ names, the names of its class’s attributes, and recursively of the attributes of its class’s base classes.

The resulting list is sorted alphabetically. For example:

>>>importstruct
>>>dir()# show the names in the module namespace
['__builtins__', '__name__', 'struct']
>>>dir(struct)# show the names in the struct module
['Struct', '__all__', '__builtins__', '__cached__', '__doc__', '__file__',
'__initializing__', '__loader__', '__name__', '__package__',
'_clearcache', 'calcsize', 'error', 'pack', 'pack_into',
'unpack', 'unpack_from']
>>>classShape:
...def__dir__(self):
...return['area','perimeter','location']
...
>>>s=Shape()
>>>dir(s)
['area', 'location', 'perimeter']

Note

Becausedir()is supplied primarily as a convenience for use at an interactive prompt, it tries to supply an interesting set of names more than it tries to supply a rigorously or consistently defined set of names, and its detailed behavior may change across releases. For example, metaclass attributes are not in the result list when the argument is a class.

divmod(a,b)¶: Take two (non-complex) numbers as arguments and return a pair of numbers consisting of their quotient and remainder when using integer division. With mixed operand types, the rules for binary arithmetic operators apply. For integers, the result is the same as(a//b,a%b).For floating-point numbers the result is(q,a%b),whereqis usuallymath.floor(a/ b)but may be 1 less than that. In any caseq*b+a%bis very close toa,ifa%bis non-zero it has the same sign asb,and0 <=abs(a%b)<abs(b).

enumerate(iterable,start=0)¶

Return an enumerate object.iterablemust be a sequence, an iterator,or some other object which supports iteration. The__next__()method of the iterator returned by enumerate()returns a tuple containing a count (fromstartwhich defaults to 0) and the values obtained from iterating overiterable.

>>>seasons=['Spring','Summer','Fall','Winter']
>>>list(enumerate(seasons))
[(0, 'Spring'), (1, 'Summer'), (2, 'Fall'), (3, 'Winter')]
>>>list(enumerate(seasons,start=1))
[(1, 'Spring'), (2, 'Summer'), (3, 'Fall'), (4, 'Winter')]

Equivalent to:

defenumerate(iterable,start=0):
n=start
foreleminiterable:
yieldn,elem
n+=1

eval(source,/,globals=None,locals=None)¶

Parameters:

source(str|code object) – A Python expression.
globals(dict|None) – The global namespace (default:None).
locals(mapping|None) – The local namespace (default:None).

Returns:

The result of the evaluated expression.

Raises:

Syntax errors are reported as exceptions.

Warning

This function executes arbitrary code. Calling it with user-supplied input may lead to security vulnerabilities.

Theexpressionargument is parsed and evaluated as a Python expression (technically speaking, a condition list) using theglobalsandlocals mappings as global and local namespace. If theglobalsdictionary is present and does not contain a value for the key__builtins__,a reference to the dictionary of the built-in modulebuiltinsis inserted under that key beforeexpressionis parsed. That way you can control what builtins are available to the executed code by inserting your own__builtins__dictionary intoglobalsbefore passing it to eval().If thelocalsmapping is omitted it defaults to the globalsdictionary. If both mappings are omitted, the expression is executed with theglobalsandlocalsin the environment where eval()is called. Note,eval()will only have access to the nested scopes(non-locals) in the enclosing environment if they are already referenced in the scope that is calling eval()(e.g. via anonlocalstatement).

Example:

>>>x=1
>>>eval('x+1')
2

This function can also be used to execute arbitrary code objects (such as those created bycompile()). In this case, pass a code object instead of a string. If the code object has been compiled with'exec'as the modeargument,eval()'s return value will beNone.

Hints: dynamic execution of statements is supported by theexec() function. Theglobals()andlocals()functions return the current global and local dictionary, respectively, which may be useful to pass around for use byeval()orexec().

If the given source is a string, then leading and trailing spaces and tabs are stripped.

Seeast.literal_eval()for a function that can safely evaluate strings with expressions containing only literals.

Raises anauditing eventexecwith the code object as the argument. Code compilation events may also be raised.

Changed in version 3.13:Theglobalsandlocalsarguments can now be passed as keywords.

Changed in version 3.13:The semantics of the defaultlocalsnamespace have been adjusted as described for thelocals()builtin.

exec(source,/,globals=None,locals=None,*,closure=None)¶

Warning

This function executes arbitrary code. Calling it with user-supplied input may lead to security vulnerabilities.

This function supports dynamic execution of Python code.sourcemust be either a string or a code object. If it is a string, the string is parsed as a suite of Python statements which is then executed (unless a syntax error occurs).[1]If it is a code object, it is simply executed. In all cases, the code that’s executed is expected to be valid as file input (see the sectionFile inputin the Reference Manual). Be aware that the nonlocal,yield,andreturn statements may not be used outside of function definitions even within the context of code passed to the exec()function. The return value isNone.

In all cases, if the optional parts are omitted, the code is executed in the current scope. If onlyglobalsis provided, it must be a dictionary (and not a subclass of dictionary), which will be used for both the global and the local variables. Ifglobalsand localsare given, they are used for the global and local variables, respectively. If provided,localscan be any mapping object. Remember that at the module level, globals and locals are the same dictionary.

Note

Whenexecgets two separate objects asglobalsandlocals,the code will be executed as if it were embedded in a class definition. This means functions and classes defined in the executed code will not be able to access variables assigned at the top level (as the “top level” variables are treated as class variables in a class definition).

If theglobalsdictionary does not contain a value for the key __builtins__,a reference to the dictionary of the built-in module builtinsis inserted under that key. That way you can control what builtins are available to the executed code by inserting your own __builtins__dictionary intoglobalsbefore passing it toexec().

Theclosureargument specifies a closure–a tuple of cellvars. It’s only valid when theobjectis a code object containing free (closure) variables. The length of the tuple must exactly match the length of the code object’s co_freevarsattribute.

Raises anauditing eventexecwith the code object as the argument. Code compilation events may also be raised.

Note

The built-in functionsglobals()andlocals()return the current global and local namespace, respectively, which may be useful to pass around for use as the second and third argument toexec().

Note

The defaultlocalsact as described for functionlocals()below. Pass an explicitlocalsdictionary if you need to see effects of the code onlocalsafter functionexec()returns.

Changed in version 3.11:Added theclosureparameter.

Changed in version 3.13:Theglobalsandlocalsarguments can now be passed as keywords.

Changed in version 3.13:The semantics of the defaultlocalsnamespace have been adjusted as described for thelocals()builtin.

filter(function,iterable)¶

Construct an iterator from those elements ofiterablefor whichfunction is true.iterablemay be either a sequence, a container which supports iteration, or an iterator. IffunctionisNone,the identity function is assumed, that is, all elements ofiterablethat are false are removed.

Note thatfilter(function,iterable)is equivalent to the generator expression(itemforiteminiterableiffunction(item))if function is notNoneand(itemforiteminiterableifitem)if function is None.

Seeitertools.filterfalse()for the complementary function that returns elements ofiterablefor whichfunctionis false.

classfloat(number=0.0,/)¶

classfloat(string,/)

Return a floating-point number constructed from a number or a string.

Examples:

>>>float('+1.23')
1.23
>>>float(' -12345\n')
-12345.0
>>>float('1e-003')
0.001
>>>float('+1E6')
1000000.0
>>>float('-Infinity')
-inf

If the argument is a string, it should contain a decimal number, optionally preceded by a sign, and optionally embedded in whitespace. The optional sign may be'+'or'-';a'+'sign has no effect on the value produced. The argument may also be a string representing a NaN (not-a-number), or positive or negative infinity. More precisely, the input must conform to thefloatvalue production rule in the following grammar, after leading and trailing whitespace characters are removed:

sign::= "+" | "-"
infinity::= "Infinity" | "inf"
nan::= "nan"
digit::= <a Unicode decimal digit, i.e. characters in Unicode general category Nd>
digitpart::=digit([ "_" ]digit)*
number::= [digitpart] "."digitpart|digitpart[ "." ]
exponent::= ( "e" | "E" ) [sign]digitpart
floatnumber::=number[exponent]
absfloatvalue::=floatnumber|infinity|nan
floatvalue::= [sign]absfloatvalue

Case is not significant, so, for example, “inf”, “Inf”, “INFINITY”, and “iNfINity” are all acceptable spellings for positive infinity.

Otherwise, if the argument is an integer or a floating-point number, a floating-point number with the same value (within Python’s floating-point precision) is returned. If the argument is outside the range of a Python float, anOverflowErrorwill be raised.

For a general Python objectx,float(x)delegates to x.__float__().If__float__()is not defined then it falls back to__index__().

If no argument is given,0.0is returned.

The float type is described inNumeric Types — int, float, complex.

Changed in version 3.6:Grouping digits with underscores as in code literals is allowed.

Changed in version 3.7:The parameter is now positional-only.

Changed in version 3.8:Falls back to__index__()if__float__()is not defined.

format(value,format_spec='')¶

Convert avalueto a “formatted” representation, as controlled by format_spec.The interpretation offormat_specwill depend on the type of thevalueargument; however, there is a standard formatting syntax that is used by most built-in types:Format Specification Mini-Language.

The defaultformat_specis an empty string which usually gives the same effect as callingstr(value).

A call toformat(value,format_spec)is translated to type(value).__format__(value,format_spec)which bypasses the instance dictionary when searching for the value’s__format__()method. ATypeErrorexception is raised if the method search reaches objectand theformat_specis non-empty, or if either the format_specor the return value are not strings.

Changed in version 3.4:object().__format__(format_spec)raisesTypeError ifformat_specis not an empty string.

classfrozenset(iterable=set())

Return a newfrozensetobject, optionally with elements taken from iterable.frozensetis a built-in class. Seefrozensetand Set Types — set, frozensetfor documentation about this class.

For other containers see the built-inset,list, tuple,anddictclasses, as well as thecollections module.

getattr(object,name)¶
getattr(object,name,default): Return the value of the named attribute ofobject.namemust be a string. If the string is the name of one of the object’s attributes, the result is the value of that attribute. For example,getattr(x,'foobar')is equivalent to x.foobar.If the named attribute does not exist,defaultis returned if provided, otherwiseAttributeErroris raised. nameneed not be a Python identifier (seesetattr()).

Note

Sinceprivate name manglinghappens at compilation time, one must manually mangle a private attribute’s (attributes with two leading underscores) name in order to retrieve it with getattr().

globals()¶: Return the dictionary implementing the current module namespace. For code within functions, this is set when the function is defined and remains the same regardless of where the function is called.

hasattr(object,name)¶: The arguments are an object and a string. The result isTrueif the string is the name of one of the object’s attributes,Falseif not. (This is implemented by callinggetattr(object,name)and seeing whether it raises anAttributeErroror not.)

hash(object)¶: Return the hash value of the object (if it has one). Hash values are integers. They are used to quickly compare dictionary keys during a dictionary lookup. Numeric values that compare equal have the same hash value (even if they are of different types, as is the case for 1 and 1.0).

Note

For objects with custom__hash__()methods, note thathash() truncates the return value based on the bit width of the host machine.

help()¶

help(request)

Invoke the built-in help system. (This function is intended for interactive use.) If no argument is given, the interactive help system starts on the interpreter console. If the argument is a string, then the string is looked up as the name of a module, function, class, method, keyword, or documentation topic, and a help page is printed on the console. If the argument is any other kind of object, a help page on the object is generated.

Note that if a slash(/) appears in the parameter list of a function when invokinghelp(),it means that the parameters prior to the slash are positional-only. For more info, see the FAQ entry on positional-only parameters.

This function is added to the built-in namespace by thesitemodule.

Changed in version 3.4:Changes topydocandinspectmean that the reported signatures for callables are now more comprehensive and consistent.

hex(x)¶

Convert an integer number to a lowercase hexadecimal string prefixed with “0x”. Ifxis not a Pythonintobject, it has to define an __index__()method that returns an integer. Some examples:

>>>hex(255)
'0xff'
>>>hex(-42)
'-0x2a'

If you want to convert an integer number to an uppercase or lower hexadecimal string with prefix or not, you can use either of the following ways:

>>>'%#x'%255,'%x'%255,'%X'%255
('0xff', 'ff', 'FF')
>>>format(255,'#x'),format(255,'x'),format(255,'X')
('0xff', 'ff', 'FF')
>>>f'{255:#x}',f'{255:x}',f'{255:X}'
('0xff', 'ff', 'FF')

See alsoformat()for more information.

open(file,mode='r',buffering=-1,encoding=None,errors=None,newline=None,closefd=True,opener=None)¶

Openfileand return a correspondingfile object.If the file cannot be opened, anOSErroris raised. See Reading and Writing Filesfor more examples of how to use this function.

fileis apath-like objectgiving the pathname (absolute or relative to the current working directory) of the file to be opened or an integer file descriptor of the file to be wrapped. (If a file descriptor is given, it is closed when the returned I/O object is closed unlessclosefd is set toFalse.)

modeis an optional string that specifies the mode in which the file is opened. It defaults to'r'which means open for reading in text mode. Other common values are'w'for writing (truncating the file if it already exists),'x'for exclusive creation, and'a'for appending (which onsomeUnix systems, means thatallwrites append to the end of the file regardless of the current seek position). In text mode, if encodingis not specified the encoding used is platform-dependent: locale.getencoding()is called to get the current locale encoding. (For reading and writing raw bytes use binary mode and leave encodingunspecified.) The available modes are:

Character	Meaning
`'r'`	open for reading (default)
`'w'`	open for writing, truncating the file first
`'x'`	open for exclusive creation, failing if the file already exists
`'a'`	open for writing, appending to the end of file if it exists
`'b'`	binary mode
`'t'`	text mode (default)
`'+'`	open for updating (reading and writing)

The default mode is'r'(open for reading text, a synonym of'rt'). Modes'w+'and'w+b'open and truncate the file. Modes'r+' and'r+b'open the file with no truncation.

As mentioned in theOverview,Python distinguishes between binary and text I/O. Files opened in binary mode (including'b'in themode argument) return contents asbytesobjects without any decoding. In text mode (the default, or when't'is included in themodeargument), the contents of the file are returned asstr,the bytes having been first decoded using a platform-dependent encoding or using the specified encodingif given.

Note

Python doesn’t depend on the underlying operating system’s notion of text files; all the processing is done by Python itself, and is therefore platform-independent.

bufferingis an optional integer used to set the buffering policy. Pass 0 to switch buffering off (only allowed in binary mode), 1 to select line buffering (only usable when writing in text mode), and an integer > 1 to indicate the size in bytes of a fixed-size chunk buffer. Note that specifying a buffer size this way applies for binary buffered I/O, butTextIOWrapper(i.e., files opened withmode='r+') would have another buffering. To disable buffering in TextIOWrapper,consider using thewrite_throughflag for io.TextIOWrapper.reconfigure().When nobufferingargument is given, the default buffering policy works as follows:

Binary files are buffered in fixed-size chunks; the size of the buffer is chosen using a heuristic trying to determine the underlying device’s “block size” and falling back onio.DEFAULT_BUFFER_SIZE.On many systems, the buffer will typically be 4096 or 8192 bytes long.
“Interactive” text files (files for whichisatty() returnsTrue) use line buffering. Other text files use the policy described above for binary files.

encodingis the name of the encoding used to decode or encode the file. This should only be used in text mode. The default encoding is platform dependent (whateverlocale.getencoding()returns), but any text encodingsupported by Python can be used. See thecodecsmodule for the list of supported encodings.

errorsis an optional string that specifies how encoding and decoding errors are to be handled—this cannot be used in binary mode. A variety of standard error handlers are available (listed underError Handlers), though any error handling name that has been registered with codecs.register_error()is also valid. The standard names include:

'strict'to raise aValueErrorexception if there is an encoding error. The default value ofNonehas the same effect.
'ignore'ignores errors. Note that ignoring encoding errors can lead to data loss.
'replace'causes a replacement marker (such as'?') to be inserted where there is malformed data.
'surrogateescape'will represent any incorrect bytes as low surrogate code units ranging from U+DC80 to U+DCFF. These surrogate code units will then be turned back into the same bytes when thesurrogateescapeerror handler is used when writing data. This is useful for processing files in an unknown encoding.
'xmlcharrefreplace'is only supported when writing to a file. Characters not supported by the encoding are replaced with the appropriate XML character reference&#nnn;.
'backslashreplace'replaces malformed data by Python’s backslashed escape sequences.
'namereplace'(also only supported when writing) replaces unsupported characters with\N{...}escape sequences.

newlinedetermines how to parse newline characters from the stream. It can beNone,'','\n','\r',and '\r\n'.It works as follows:

When reading input from the stream, ifnewlineisNone,universal newlines mode is enabled. Lines in the input can end in'\n', '\r',or'\r\n',and these are translated into'\n'before being returned to the caller. If it is'',universal newlines mode is enabled, but line endings are returned to the caller untranslated. If it has any of the other legal values, input lines are only terminated by the given string, and the line ending is returned to the caller untranslated.
When writing output to the stream, ifnewlineisNone,any'\n' characters written are translated to the system default line separator, os.linesep.Ifnewlineis''or'\n',no translation takes place. Ifnewlineis any of the other legal values, any'\n' characters written are translated to the given string.

IfclosefdisFalseand a file descriptor rather than a filename was given, the underlying file descriptor will be kept open when the file is closed. If a filename is givenclosefdmust beTrue(the default); otherwise, an error will be raised.

A custom opener can be used by passing a callable asopener.The underlying file descriptor for the file object is then obtained by callingopenerwith (file,flags).openermust return an open file descriptor (passing os.openasopenerresults in functionality similar to passing None).

The newly created file isnon-inheritable.

The following example uses thedir_fdparameter of the os.open()function to open a file relative to a given directory:

>>>importos
>>>dir_fd=os.open('somedir',os.O_RDONLY)
>>>defopener(path,flags):
...returnos.open(path,flags,dir_fd=dir_fd)
...
>>>withopen('spamspam.txt','w',opener=opener)asf:
...print('This will be written to somedir/spamspam.txt',file=f)
...
>>>os.close(dir_fd)# don't leak a file descriptor

The type offile objectreturned by theopen()function depends on the mode. Whenopen()is used to open a file in a text mode ('w','r','wt','rt',etc.), it returns a subclass of io.TextIOBase(specificallyio.TextIOWrapper). When used to open a file in a binary mode with buffering, the returned class is a subclass ofio.BufferedIOBase.The exact class varies: in read binary mode, it returns anio.BufferedReader;in write binary and append binary modes, it returns anio.BufferedWriter,and in read/write mode, it returns anio.BufferedRandom.When buffering is disabled, the raw stream, a subclass ofio.RawIOBase, io.FileIO,is returned.

See also the file handling modules, such asfileinput,io (whereopen()is declared),os,os.path,tempfile, andshutil.

Raises anauditing eventopenwith argumentspath,mode,flags.

Themodeandflagsarguments may have been modified or inferred from the original call.

Changed in version 3.3:

Theopenerparameter was added.
The'x'mode was added.
IOErrorused to be raised, it is now an alias ofOSError.
FileExistsErroris now raised if the file opened in exclusive creation mode ('x') already exists.

Changed in version 3.4:

The file is now non-inheritable.

Changed in version 3.5:

If the system call is interrupted and the signal handler does not raise an exception, the function now retries the system call instead of raising an InterruptedErrorexception (seePEP 475for the rationale).
The'namereplace'error handler was added.

Changed in version 3.6:

Support added to accept objects implementingos.PathLike.
On Windows, opening a console buffer may return a subclass of io.RawIOBaseother thanio.FileIO.

Changed in version 3.11:The'U'mode has been removed.

ord(c)¶: Given a string representing one Unicode character, return an integer representing the Unicode code point of that character. For example, ord('a')returns the integer97andord('€')(Euro sign) returns8364.This is the inverse ofchr().

pow(base,exp,mod=None)¶

Returnbaseto the powerexp;ifmodis present, returnbaseto the powerexp,modulomod(computed more efficiently than pow(base,exp)%mod). The two-argument formpow(base,exp)is equivalent to using the power operator:base**exp.

The arguments must have numeric types. With mixed operand types, the coercion rules for binary arithmetic operators apply. Forint operands, the result has the same type as the operands (after coercion) unless the second argument is negative; in that case, all arguments are converted to float and a float result is delivered. For example,pow(10,2) returns100,butpow(10,-2)returns0.01.For a negative base of typeintorfloatand a non-integral exponent, a complex result is delivered. For example,pow(-9,0.5)returns a value close to3j.Whereas, for a negative base of typeintorfloat with an integral exponent, a float result is delivered. For example, pow(-9,2.0)returns81.0.

Forintoperandsbaseandexp,ifmodis present,modmust also be of integer type andmodmust be nonzero. Ifmodis present and expis negative,basemust be relatively prime tomod.In that case, pow(inv_base,-exp,mod)is returned, whereinv_baseis an inverse to basemodulomod.

Here’s an example of computing an inverse for38modulo97:

>>>pow(38,-1,mod=97)
23
>>>23*38%97==1
True

Changed in version 3.8:Forintoperands, the three-argument form ofpownow allows the second argument to be negative, permitting computation of modular inverses.

Changed in version 3.8:Allow keyword arguments. Formerly, only positional arguments were supported.

print(*objects,sep='',end='\n',file=None,flush=False)¶

Printobjectsto the text streamfile,separated bysepand followed byend.sep,end,file,andflush,if present, must be given as keyword arguments.

All non-keyword arguments are converted to strings likestr()does and written to the stream, separated bysepand followed byend.Bothsep andendmust be strings; they can also beNone,which means to use the default values. If noobjectsare given,print()will just write end.

Thefileargument must be an object with awrite(string)method; if it is not present orNone,sys.stdoutwill be used. Since printed arguments are converted to text strings,print()cannot be used with binary mode file objects. For these, usefile.write(...)instead.

Output buffering is usually determined byfile. However, ifflushis true, the stream is forcibly flushed.

Changed in version 3.3:Added theflushkeyword argument.

classproperty(fget=None,fset=None,fdel=None,doc=None)¶

Return a property attribute.

fgetis a function for getting an attribute value.fsetis a function for setting an attribute value.fdelis a function for deleting an attribute value. Anddoccreates a docstring for the attribute.

A typical use is to define a managed attributex:

classC:
def__init__(self):
self._x=None

defgetx(self):
returnself._x

defsetx(self,value):
self._x=value

defdelx(self):
delself._x

x=property(getx,setx,delx,"I'm the 'x' property.")

Ifcis an instance ofC,c.xwill invoke the getter, c.x=valuewill invoke the setter, anddelc.xthe deleter.

If given,docwill be the docstring of the property attribute. Otherwise, the property will copyfget’s docstring (if it exists). This makes it possible to create read-only properties easily usingproperty()as adecorator:

classParrot:
def__init__(self):
self._voltage=100000

@property
defvoltage(self):
"""Get the current voltage." ""
returnself._voltage

The@propertydecorator turns thevoltage()method into a “getter” for a read-only attribute with the same name, and it sets the docstring for voltageto “Get the current voltage.”

@getter¶

@setter¶

@deleter¶

A property object hasgetter,setter, anddeletermethods usable as decorators that create a copy of the property with the corresponding accessor function set to the decorated function. This is best explained with an example:

classC:
def__init__(self):
self._x=None

@property
defx(self):
"""I'm the 'x' property." ""
returnself._x

@x.setter
defx(self,value):
self._x=value

@x.deleter
defx(self):
delself._x

This code is exactly equivalent to the first example. Be sure to give the additional functions the same name as the original property (xin this case.)

The returned property object also has the attributesfget,fset,and fdelcorresponding to the constructor arguments.

Changed in version 3.5:The docstrings of property objects are now writeable.

__name__¶: Attribute holding the name of the property. The name of the property can be changed at runtime.

Added in version 3.13.

classrange(stop)
classrange(start,stop,step=1): Rather than being a function,rangeis actually an immutable sequence type, as documented inRangesandSequence Types — list, tuple, range.

repr(object)¶

Return a string containing a printable representation of an object. For many types, this function makes an attempt to return a string that would yield an object with the same value when passed toeval();otherwise, the representation is a string enclosed in angle brackets that contains the name of the type of the object together with additional information often including the name and address of the object. A class can control what this function returns for its instances by defining a__repr__()method. Ifsys.displayhook()is not accessible, this function will raise RuntimeError.

This class has a custom representation that can be evaluated:

classPerson:
def__init__(self,name,age):
self.name=name
self.age=age

def__repr__(self):
returnf"Person('{self.name}',{self.age}) "

reversed(seq)¶: Return a reverseiterator.seqmust be an object which has a__reversed__()method or supports the sequence protocol (the __len__()method and the__getitem__()method with integer arguments starting at0).

round(number,ndigits=None)¶

Returnnumberrounded tondigitsprecision after the decimal point. Ifndigitsis omitted or isNone,it returns the nearest integer to its input.

For the built-in types supportinground(),values are rounded to the closest multiple of 10 to the power minusndigits;if two multiples are equally close, rounding is done toward the even choice (so, for example, bothround(0.5)andround(-0.5)are0,andround(1.5)is 2). Any integer value is valid forndigits(positive, zero, or negative). The return value is an integer ifndigitsis omitted or None. Otherwise, the return value has the same type asnumber.

For a general Python objectnumber,rounddelegates to number.__round__.

Note

The behavior ofround()for floats can be surprising: for example, round(2.675,2)gives2.67instead of the expected2.68. This is not a bug: it’s a result of the fact that most decimal fractions can’t be represented exactly as a float. SeeFloating-Point Arithmetic: Issues and Limitationsfor more information.

classset

classset(iterable)

Return a newsetobject, optionally with elements taken from iterable.setis a built-in class. Seesetand Set Types — set, frozensetfor documentation about this class.

For other containers see the built-infrozenset,list, tuple,anddictclasses, as well as thecollections module.

setattr(object,name,value)¶

This is the counterpart ofgetattr().The arguments are an object, a string, and an arbitrary value. The string may name an existing attribute or a new attribute. The function assigns the value to the attribute, provided the object allows it. For example,setattr(x,'foobar',123)is equivalent to x.foobar=123.

nameneed not be a Python identifier as defined inIdentifiers and keywords unless the object chooses to enforce that, for example in a custom __getattribute__()or via__slots__. An attribute whose name is not an identifier will not be accessible using the dot notation, but is accessible throughgetattr()etc..

Note

Sinceprivate name manglinghappens at compilation time, one must manually mangle a private attribute’s (attributes with two leading underscores) name in order to set it with setattr().

classslice(stop)¶

classslice(start,stop,step=None)

Return asliceobject representing the set of indices specified by range(start,stop,step).Thestartandsteparguments default to None.

start¶

stop¶

step¶: Slice objects have read-only data attributesstart, stop,andstepwhich merely return the argument values (or their default). They have no other explicit functionality; however, they are used by NumPy and other third-party packages.

Slice objects are also generated when extended indexing syntax is used. For example:a[start:stop:step]ora[start:stop,i].See itertools.islice()for an alternate version that returns an iterator.

Changed in version 3.12:Slice objects are nowhashable(providedstart, stop,andstepare hashable).

sorted(iterable,/,*,key=None,reverse=False)¶

Return a new sorted list from the items initerable.

Has two optional arguments which must be specified as keyword arguments.

keyspecifies a function of one argument that is used to extract a comparison key from each element initerable(for example,key=str.lower). The default value isNone(compare the elements directly).

reverseis a boolean value. If set toTrue,then the list elements are sorted as if each comparison were reversed.

Usefunctools.cmp_to_key()to convert an old-stylecmpfunction to a keyfunction.

The built-insorted()function is guaranteed to be stable. A sort is stable if it guarantees not to change the relative order of elements that compare equal — this is helpful for sorting in multiple passes (for example, sort by department, then by salary grade).

The sort algorithm uses only<comparisons between items. While defining an__lt__()method will suffice for sorting, PEP 8recommends that all sixrich comparisonsbe implemented. This will help avoid bugs when using the same data with other ordering tools such asmax()that rely on a different underlying method. Implementing all six comparisons also helps avoid confusion for mixed type comparisons which can call reflected the__gt__()method.

For sorting examples and a brief sorting tutorial, seeSorting Techniques.

@staticmethod¶

Transform a method into a static method.

A static method does not receive an implicit first argument. To declare a static method, use this idiom:

classC:
@staticmethod
deff(arg1,arg2,argN):...

The@staticmethodform is a functiondecorator– see Function definitionsfor details.

A static method can be called either on the class (such asC.f()) or on an instance (such asC().f()). Moreover, the static methoddescriptoris also callable, so it can be used in the class definition (such asf()).

Static methods in Python are similar to those found in Java or C++. Also, see classmethod()for a variant that is useful for creating alternate class constructors.

Like all decorators, it is also possible to callstaticmethodas a regular function and do something with its result. This is needed in some cases where you need a reference to a function from a class body and you want to avoid the automatic transformation to instance method. For these cases, use this idiom:

defregular_function():
...

classC:
method=staticmethod(regular_function)

For more information on static methods, seeThe standard type hierarchy.

Changed in version 3.10:Static methods now inherit the method attributes (__module__,__name__, __qualname__,__doc__and __annotations__), have a new__wrapped__attribute, and are now callable as regular functions.

classstr(object='')

classstr(object=b'',encoding='utf-8',errors='strict')

Return astrversion ofobject.Seestr()for details.

stris the built-in stringclass.For general information about strings, seeText Sequence Type — str.

sum(iterable,/,start=0)¶

Sumsstartand the items of aniterablefrom left to right and returns the total. Theiterable’s items are normally numbers, and the start value is not allowed to be a string.

For some use cases, there are good alternatives tosum(). The preferred, fast way to concatenate a sequence of strings is by calling ''.join(sequence).To add floating-point values with extended precision, seemath.fsum().To concatenate a series of iterables, consider using itertools.chain().

Changed in version 3.8:Thestartparameter can be specified as a keyword argument.

Changed in version 3.12:Summation of floats switched to an algorithm that gives higher accuracy and better commutativity on most builds.

classsuper¶

classsuper(type,object_or_type=None)

Return a proxy object that delegates method calls to a parent or sibling class oftype.This is useful for accessing inherited methods that have been overridden in a class.

Theobject_or_typedetermines themethod resolution order to be searched. The search starts from the class right after the type.

For example, if__mro__ofobject_or_typeis D->B->C->A->objectand the value oftypeisB, thensuper()searchesC->A->object.

The__mro__attribute of the class corresponding to object_or_typelists the method resolution search order used by both getattr()andsuper().The attribute is dynamic and can change whenever the inheritance hierarchy is updated.

If the second argument is omitted, the super object returned is unbound. If the second argument is an object,isinstance(obj,type)must be true. If the second argument is a type,issubclass(type2,type)must be true (this is useful for classmethods).

When called directly within an ordinary method of a class, both arguments may be omitted ( “zero-argumentsuper()”). In this case,typewill be the enclosing class, andobjwill be the first argument of the immediately enclosing function (typicallyself). (This means that zero-argument super()will not work as expected within nested functions, including generator expressions, which implicitly create nested functions.)

There are two typical use cases forsuper.In a class hierarchy with single inheritance,supercan be used to refer to parent classes without naming them explicitly, thus making the code more maintainable. This use closely parallels the use ofsuperin other programming languages.

The second use case is to support cooperative multiple inheritance in a dynamic execution environment. This use case is unique to Python and is not found in statically compiled languages or languages that only support single inheritance. This makes it possible to implement “diamond diagrams” where multiple base classes implement the same method. Good design dictates that such implementations have the same calling signature in every case (because the order of calls is determined at runtime, because that order adapts to changes in the class hierarchy, and because that order can include sibling classes that are unknown prior to runtime).

For both use cases, a typical superclass call looks like this:

classC(B):
defmethod(self,arg):
super().method(arg)# This does the same thing as:
# super(C, self).method(arg)

In addition to method lookups,super()also works for attribute lookups. One possible use case for this is callingdescriptors in a parent or sibling class.

Note thatsuper()is implemented as part of the binding process for explicit dotted attribute lookups such assuper().__getitem__(name). It does so by implementing its own__getattribute__()method for searching classes in a predictable order that supports cooperative multiple inheritance. Accordingly,super()is undefined for implicit lookups using statements or operators such assuper()[name].

Also note that, aside from the zero argument form,super()is not limited to use inside methods. The two argument form specifies the arguments exactly and makes the appropriate references. The zero argument form only works inside a class definition, as the compiler fills in the necessary details to correctly retrieve the class being defined, as well as accessing the current instance for ordinary methods.

For practical suggestions on how to design cooperative classes using super(),seeguide to using super().

classtuple
classtuple(iterable): Rather than being a function,tupleis actually an immutable sequence type, as documented inTuplesandSequence Types — list, tuple, range.

classtype(object)¶

classtype(name,bases,dict,**kwds)

With one argument, return the type of anobject.The return value is a type object and generally the same object as returned by object.__class__.

Theisinstance()built-in function is recommended for testing the type of an object, because it takes subclasses into account.

With three arguments, return a new type object. This is essentially a dynamic form of theclassstatement. Thenamestring is the class name and becomes the__name__attribute. Thebasestuple contains the base classes and becomes the __bases__attribute; if empty,object,the ultimate base of all classes, is added. Thedictdictionary contains attribute and method definitions for the class body; it may be copied or wrapped before becoming the__dict__attribute. The following two statements create identicaltypeobjects:

>>>classX:
...a=1
...
>>>X=type('X',(),dict(a=1))

Built-in Functions¶

Table of Contents

Previous topic

Next topic

This Page