2. Built-in Functions¶

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

		Built-in Functions
`abs()`	`dict()`	`help()`	`min()`	`setattr()`
`all()`	`dir()`	`hex()`	`next()`	`slice()`
`any()`	`divmod()`	`id()`	`object()`	`sorted()`
`ascii()`	`enumerate()`	`input()`	`oct()`	`staticmethod()`
`bin()`	`eval()`	`int()`	`open()`	`str()`
`bool()`	`exec()`	`isinstance()`	`ord()`	`sum()`
`bytearray()`	`filter()`	`issubclass()`	`pow()`	`super()`
`bytes()`	`float()`	`iter()`	`print()`	`tuple()`
`callable()`	`format()`	`len()`	`property()`	`type()`
`chr()`	`frozenset()`	`list()`	`range()`	`vars()`
`classmethod()`	`getattr()`	`locals()`	`repr()`	`zip()`
`compile()`	`globals()`	`map()`	`reversed()`	`__import__()`
`complex()`	`hasattr()`	`max()`	`round()`
`delattr()`	`hash()`	`memoryview()`	`set()`

abs(x)¶: Return the absolute value of a number. The argument may be aninteger or a floating point number. If the argument is a complex number, itsmagnitude is returned.

all(iterable)¶

ReturnTrue if all elements of theiterable are true (or if the iterableis empty). Equivalent to:

defall(iterable):forelementiniterable:ifnotelement:returnFalsereturnTrue

any(iterable)¶

ReturnTrue if any element of theiterable is true. If the iterableis empty, returnFalse. Equivalent to:

defany(iterable):forelementiniterable:ifelement:returnTruereturnFalse

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

bin(x)¶: Convert an integer number to a binary string. The result is a valid Pythonexpression. Ifx is not a Pythonint object, it has to define an__index__() method that returns an integer.

classbool([x])¶: Return a Boolean value, i.e. one ofTrue orFalse.x is convertedusing the standardtruth testing procedure. Ifx is falseor omitted, this returnsFalse; otherwise it returnsTrue. Thebool class is a subclass ofint (seeNumeric Types — int, float, complex).It cannot be subclassed further. Its only instances areFalse andTrue (seeBoolean Values).

classbytearray([source[,encoding[,errors]]])¶

Return a new array of bytes. Thebytearray class is a mutablesequence of integers in the range 0 <= x < 256. It has most of the usualmethods of mutable sequences, described inMutable Sequence Types, as wellas most methods that thebytes type has, seeBytes and Bytearray Operations.

The optionalsource parameter can be used to initialize the array in a fewdifferent ways:

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

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

classbytes([source[,encoding[,errors]]])¶

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

Accordingly, constructor arguments are interpreted as forbytearray().

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

callable(object)¶: ReturnTrue if theobject argument appears callable,False if not. If this returns true, it is still possible that acall fails, but if it is false, callingobject will never succeed.Note that classes are callable (calling a class returns a new instance);instances are callable if their class has a__call__() method.
New in version 3.2:This function was first removed in Python 3.0 and then brought backin Python 3.2.

chr(i)¶

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

The valid range for the argument is from 0 through 1,114,111 (0x10FFFF inbase 16).ValueError will be raised ifi is outside that range.

classmethod(function)¶

Return a class method forfunction.

A class method receives the class as implicit first argument, just like aninstance method receives the instance. To declare a class method, use thisidiom:

classC:@classmethoddeff(cls,arg1,arg2,...):...

The@classmethod form is a functiondecorator – see the descriptionof function definitions inFunction definitions for details.

It can be called either on the class (such asC.f()) or on an instance (suchasC().f()). The instance is ignored except for its class. If a classmethod is called for a derived class, the derived class object is passed as theimplied 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, consult the documentation on the standardtype hierarchy inThe standard type hierarchy.

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

Compile thesource into a code or AST object. Code objects can be executedbyexec() oreval().source can either be a normal string, abyte string, or an AST object. Refer to theast module documentationfor information on how to work with AST objects.

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

Themode argument specifies what kind of code must be compiled; it can be'exec' ifsource consists of a sequence of statements,'eval' if itconsists of a single expression, or'single' if it consists of a singleinteractive statement (in the latter case, expression statements thatevaluate to something other thanNone will be printed).

The optional argumentsflags anddont_inherit control which futurestatements (seePEP 236) affect the compilation ofsource. If neitheris present (or both are zero) the code is compiled with those futurestatements that are in effect in the code that is callingcompile(). If theflags argument is given anddont_inherit is not (or is zero) then thefuture statements specified by theflags argument are used in addition tothose that would be used anyway. Ifdont_inherit is a non-zero integer thentheflags argument is it – the future statements in effect around the callto compile are ignored.

Future statements are specified by bits which can be bitwise ORed together tospecify multiple statements. The bitfield required to specify a given featurecan be found as thecompiler_flag attribute onthe_Feature instance in the__future__ module.

The argumentoptimize specifies the optimization level of the compiler; thedefault value of-1 selects the optimization level of the interpreter asgiven by-O options. Explicit levels are0 (no optimization;__debug__ is true),1 (asserts are removed,__debug__ is false)or2 (docstrings are removed too).

This function raisesSyntaxError if the compiled source is invalid,andValueError if the source contains null bytes.

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

Note

When compiling a string with multi-line code in'single' or'eval' mode, input must be terminated by at least one newlinecharacter. This is to facilitate detection of incomplete and completestatements in thecode module.

Changed in version 3.2:Allowed use of Windows and Mac newlines. Also input in'exec' modedoes not have to end in a newline anymore. Added theoptimize parameter.

Changed in version 3.5:Previously,TypeError was raised when null bytes were encounteredinsource.

classcomplex([real[,imag]])¶

Return a complex number with the valuereal +imag*1j or convert a stringor number to a complex number. If the first parameter is a string, it willbe interpreted as a complex number and the function must be called without asecond parameter. The second parameter can never be a string. Each argumentmay be any numeric type (including complex). Ifimag is omitted, itdefaults to zero and the constructor serves as a numeric conversion likeint andfloat. If both arguments are omitted, returns0j.

Note

When converting from a string, the string must not contain whitespacearound the central+ or- operator. For example,complex('1+2j') is fine, butcomplex('1+2j') raisesValueError.

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

delattr(object,name)¶: This is a relative ofsetattr(). The arguments are an object and astring. The string must be the name of one of the object’s attributes. Thefunction deletes the named attribute, provided the object allows it. Forexample,delattr(x,'foobar') is equivalent todelx.foobar.

classdict(**kwarg)

classdict(mapping,**kwarg)

classdict(iterable,**kwarg)

Create a new dictionary. Thedict object is the dictionary class.Seedict andMapping Types — dict for documentation about this class.

For other containers see the built-inlist,set, andtuple classes, as well as thecollections module.

dir([object])¶

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

If the object has a method named__dir__(), this method will be called andmust return the list of attributes. This allows objects that implement a custom__getattr__() or__getattribute__() function to customize the waydir() reports their attributes.

If the object does not provide__dir__(), the function tries its best togather information from the object’s__dict__ attribute, if defined, andfrom its type object. The resulting list is not necessarily complete, and maybe inaccurate when the object has a custom__getattr__().

The defaultdir() mechanism behaves differently with different types ofobjects, 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’sattributes.
If the object is a type or class object, the list contains the names of itsattributes, and recursively of the attributes of its bases.
Otherwise, the list contains the object’s attributes’ names, the names of itsclass’s attributes, and recursively of the attributes of its class’s baseclasses.

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 aninteractive prompt, it tries to supply an interesting set of names morethan 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 aclass.

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

enumerate(iterable,start=0)¶

Return an enumerate object.iterable must be a sequence, aniterator, or some other object which supports iteration.The__next__() method of the iterator returned byenumerate() returns a tuple containing a count (fromstart whichdefaults 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(sequence,start=0):n=startforeleminsequence:yieldn,elemn+=1

eval(expression,globals=None,locals=None)¶

The arguments are a string and optional globals and locals. If provided,globals must be a dictionary. If provided,locals can be any mappingobject.

Theexpression argument is parsed and evaluated as a Python expression(technically speaking, a condition list) using theglobals andlocalsdictionaries as global and local namespace. If theglobals dictionary ispresent and lacks ‘__builtins__’, the current globals are copied intoglobalsbeforeexpression is parsed. This means thatexpression normally has fullaccess to the standardbuiltins module and restricted environments arepropagated. If thelocals dictionary is omitted it defaults to theglobalsdictionary. If both dictionaries are omitted, the expression is executed in theenvironment whereeval() is called. The return value is the result ofthe evaluated expression. Syntax errors are reported as exceptions. Example:

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

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

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

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

exec(object[,globals[,locals]])¶

This function supports dynamic execution of Python code.object must beeither a string or a code object. If it is a string, the string is parsed asa suite of Python statements which is then executed (unless a syntax erroroccurs).[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 thesection “File input” in the Reference Manual). Be aware that thereturn andyield statements may not be used outside offunction definitions even within the context of code passed to theexec() function. The return value isNone.

In all cases, if the optional parts are omitted, the code is executed in thecurrent scope. If onlyglobals is provided, it must be a dictionary, whichwill be used for both the global and the local variables. Ifglobals andlocals are given, they are used for the global and local variables,respectively. If provided,locals can be any mapping object. Rememberthat at module level, globals and locals are the same dictionary. If execgets two separate objects asglobals andlocals, the code will beexecuted as if it were embedded in a class definition.

If theglobals dictionary does not contain a value for the key__builtins__, a reference to the dictionary of the built-in modulebuiltins is inserted under that key. That way you can control whatbuiltins are available to the executed code by inserting your own__builtins__ dictionary intoglobals before passing it toexec().

Note

The built-in functionsglobals() andlocals() return the currentglobal and local dictionary, respectively, which may be useful to pass aroundfor use as the second and third argument toexec().

Note

The defaultlocals act as described for functionlocals() below:modifications to the defaultlocals dictionary should not be attempted.Pass an explicitlocals dictionary if you need to see effects of thecode onlocals after functionexec() returns.

filter(function,iterable)¶

Construct an iterator from those elements ofiterable for whichfunctionreturns true.iterable may be either a sequence, a container whichsupports iteration, or an iterator. Iffunction isNone, the identityfunction is assumed, that is, all elements ofiterable that are false areremoved.

Note thatfilter(function,iterable) is equivalent to the generatorexpression(itemforiteminiterableiffunction(item)) if function isnotNone and(itemforiteminiterableifitem) if function isNone.

Seeitertools.filterfalse() for the complementary function that returnselements ofiterable for whichfunction returns false.

classfloat([x])¶

Return a floating point number constructed from a number or stringx.

If the argument is a string, it should contain a decimal number, optionallypreceded by a sign, and optionally embedded in whitespace. The optionalsign may be'+' or'-'; a'+' sign has no effect on the valueproduced. The argument may also be a string representing a NaN(not-a-number), or a positive or negative infinity. More precisely, theinput must conform to the following grammar after leading and trailingwhitespace characters are removed:

sign ::=  "+" | "-"infinity ::=  "Infinity" | "inf"nan ::=  "nan"numeric_value ::=floatnumber |infinity |nannumeric_string ::=  [sign]numeric_value

Herefloatnumber is the form of a Python floating-point literal,described inFloating point literals. Case is not significant, so, for example,“inf”, “Inf”, “INFINITY” and “iNfINity” are all acceptable spellings forpositive infinity.

Otherwise, if the argument is an integer or a floating point number, afloating point number with the same value (within Python’s floating pointprecision) is returned. If the argument is outside the range of a Pythonfloat, anOverflowError will be raised.

For a general Python objectx,float(x) delegates tox.__float__().

If no argument is given,0.0 is returned.

Examples:

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

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

format(value[,format_spec])¶

Convert avalue to a “formatted” representation, as controlled byformat_spec. The interpretation offormat_spec will depend on the typeof thevalue argument, however there is a standard formatting syntax thatis used by most built-in types:Format Specification Mini-Language.

The defaultformat_spec is an empty string which usually gives the sameeffect as callingstr(value).

A call toformat(value,format_spec) is translated totype(value).__format__(value,format_spec) which bypasses the instancedictionary when searching for the value’s__format__() method. ATypeError exception is raised if the method search reachesobject and theformat_spec is non-empty, or if either theformat_spec or the return value are not strings.

Changed in version 3.4:object().__format__(format_spec) raisesTypeErrorifformat_spec is not an empty string.

classfrozenset([iterable])

Return a newfrozenset object, optionally with elements taken fromiterable.frozenset is a built-in class. Seefrozenset andSet Types — set, frozenset for documentation about this class.

For other containers see the built-inset,list,tuple, anddict classes, as well as thecollectionsmodule.

getattr(object,name[,default])¶: Return the value of the named attribute ofobject.name must be a string.If the string is the name of one of the object’s attributes, the result is thevalue of that attribute. For example,getattr(x,'foobar') is equivalent tox.foobar. If the named attribute does not exist,default is returned ifprovided, otherwiseAttributeError is raised.

globals()¶: Return a dictionary representing the current global symbol table. This is alwaysthe dictionary of the current module (inside a function or method, this is themodule where it is defined, not the module from which it is called).

hasattr(object,name)¶: The arguments are an object and a string. The result isTrue if thestring is the name of one of the object’s attributes,False if not. (Thisis implemented by callinggetattr(object,name) and seeing whether itraises anAttributeError or not.)

hash(object)¶: Return the hash value of the object (if it has one). Hash values areintegers. They are used to quickly compare dictionary keys during adictionary lookup. Numeric values that compare equal have the same hashvalue (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.See__hash__() for details.

help([object])¶

Invoke the built-in help system. (This function is intended for interactiveuse.) If no argument is given, the interactive help system starts on theinterpreter console. If the argument is a string, then the string is looked upas the name of a module, function, class, method, keyword, or documentationtopic, and a help page is printed on the console. If the argument is any otherkind of object, a help page on the object is generated.

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

Changed in version 3.4:Changes topydoc andinspect mean that the reportedsignatures for callables are now more comprehensive and consistent.

hex(x)¶

Convert an integer number to a lowercase hexadecimal stringprefixed with “0x”, for example:

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

If x is not a Pythonint object, it has to define an __index__()method that returns an integer.

See alsoint() for converting a hexadecimal string to aninteger using a base of 16.

Note

To obtain a hexadecimal string representation for a float, use thefloat.hex() method.

id(object)¶: Return the “identity” of an object. This is an integer whichis guaranteed to be unique and constant for this object during its lifetime.Two objects with non-overlapping lifetimes may have the sameid()value.
CPython implementation detail: This is the address of the object in memory.

input([prompt])¶

If theprompt argument is present, it is written to standard output withouta trailing newline. The function then reads a line from input, converts itto a string (stripping a trailing newline), and returns that. When EOF isread,EOFError is raised. Example:

>>>s=input('--> ')--> Monty Python's Flying Circus>>>s"Monty Python's Flying Circus"

If thereadline module was loaded, theninput() will use itto provide elaborate line editing and history features.

classint(x=0)¶

classint(x,base=10)

Return an integer object constructed from a number or stringx, or return0 if no arguments are given. Ifx is a number, returnx.__int__(). For floating point numbers, thistruncates towards zero.

Ifx is not a number or ifbase is given, thenx must be a string,bytes, orbytearray instance representing anintegerliteral in radixbase. Optionally, the literal can bepreceded by+ or- (with no space in between) and surrounded bywhitespace. A base-n literal consists of the digits 0 to n-1, withatoz (orA toZ) havingvalues 10 to 35. The defaultbase is 10. The allowed values are 0 and 2–36.Base-2, -8, and -16 literals can be optionally prefixed with0b/0B,0o/0O, or0x/0X, as with integer literals in code. Base 0means to interpret exactly as a code literal, so that the actual base is 2,8, 10, or 16, and so thatint('010',0) is not legal, whileint('010') is, as well asint('010',8).

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

Changed in version 3.4:Ifbase is not an instance ofint and thebase object has abase.__index__ method, that method is calledto obtain an integer for the base. Previous versions usedbase.__int__ instead ofbase.__index__.

isinstance(object,classinfo)¶: Return true if theobject argument is an instance of theclassinfoargument, or of a (direct, indirect orvirtual) subclass thereof. Ifobject is notan object of the given type, the function always returns false.Ifclassinfo is a tuple of type objects (or recursively, other suchtuples), return true ifobject is an instance of any of the types.Ifclassinfo is not a type or tuple of types and such tuples,aTypeError exception is raised.

issubclass(class,classinfo)¶: Return true ifclass is a subclass (direct, indirect orvirtual) ofclassinfo. Aclass is considered a subclass of itself.classinfo may be a tuple of classobjects, in which case every entry inclassinfo will be checked. In any othercase, aTypeError exception is raised.

iter(object[,sentinel])¶

Return aniterator object. The first argument is interpreted verydifferently depending on the presence of the second argument. Without asecond argument,object must be a collection object which supports theiteration protocol (the__iter__() method), or it must support thesequence protocol (the__getitem__() method with integer argumentsstarting at0). If it does not support either of those protocols,TypeError is raised. If the second argument,sentinel, is given,thenobject must be a callable object. The iterator created in this casewill callobject with no arguments for each call to its__next__() method; if the value returned is equal tosentinel,StopIteration will be raised, otherwise the value willbe returned.

See alsoIterator Types.

One useful application of the second form ofiter() is to read lines ofa file until a certain line is reached. The following example reads a fileuntil thereadline() method returns an empty string:

withopen('mydata.txt')asfp:forlineiniter(fp.readline,''):process_line(line)

len(s)¶: Return the length (the number of items) of an object. The argument may be asequence (such as a string, bytes, tuple, list, or range) or a collection(such as a dictionary, set, or frozen set).

classlist([iterable]): Rather than being a function,list is actually a mutablesequence type, as documented inLists andSequence Types — list, tuple, range.

locals()¶: Update and return a dictionary representing the current local symbol table.Free variables are returned bylocals() when it is called in functionblocks, but not in class blocks.
Note
The contents of this dictionary should not be modified; changes may notaffect the values of local and free variables used by the interpreter.

map(function,iterable,...)¶: Return an iterator that appliesfunction to every item ofiterable,yielding the results. If additionaliterable arguments are passed,function must take that many arguments and is applied to the items from alliterables in parallel. With multiple iterables, the iterator stops when theshortest iterable is exhausted. For cases where the function inputs arealready arranged into argument tuples, seeitertools.starmap().

max(iterable,*[,key,default])¶

max(arg1,arg2,*args[,key])

Return the largest item in an iterable or the largest of two or morearguments.

If one positional argument is provided, it should be aniterable.The largest item in the iterable is returned. If two or more positionalarguments are provided, the largest of the positional arguments isreturned.

There are two optional keyword-only arguments. Thekey argument specifiesa one-argument ordering function like that used forlist.sort(). Thedefault argument specifies an object to return if the provided iterable isempty. If the iterable is empty anddefault is not provided, aValueError is raised.

If multiple items are maximal, the function returns the first oneencountered. This is consistent with other sort-stability preserving toolssuch assorted(iterable,key=keyfunc,reverse=True)[0] andheapq.nlargest(1,iterable,key=keyfunc).

New in version 3.4:Thedefault keyword-only argument.

memoryview(obj): Return a “memory view” object created from the given argument. SeeMemory Views for more information.

min(iterable,*[,key,default])¶

min(arg1,arg2,*args[,key])

Return the smallest item in an iterable or the smallest of two or morearguments.

If one positional argument is provided, it should be aniterable.The smallest item in the iterable is returned. If two or more positionalarguments are provided, the smallest of the positional arguments isreturned.

If multiple items are minimal, the function returns the first oneencountered. This is consistent with other sort-stability preserving toolssuch assorted(iterable,key=keyfunc)[0] andheapq.nsmallest(1,iterable,key=keyfunc).

New in version 3.4:Thedefault keyword-only argument.

next(iterator[,default])¶: Retrieve the next item from theiterator by calling its__next__() method. Ifdefault is given, it is returnedif the iterator is exhausted, otherwiseStopIteration is raised.

classobject¶: Return a new featureless object.object is a base for all classes.It has the methods that are common to all instances of Python classes. Thisfunction does not accept any arguments.
Note
object doesnot have a__dict__, so you can’tassign arbitrary attributes to an instance of theobject class.

oct(x)¶: Convert an integer number to an octal string. The result is a valid Pythonexpression. Ifx is not a Pythonint object, it has to define an__index__() method that returns an integer.

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

Openfile and return a correspondingfile object. If the filecannot be opened, anOSError is raised.

file is either a string or bytes object giving the pathname (absolute orrelative to the current working directory) of the file to be opened oran integer file descriptor of the file to be wrapped. (If a file descriptoris given, it is closed when the returned I/O object is closed, unlessclosefd is set toFalse.)

mode is an optional string that specifies the mode in which the file isopened. It defaults to'r' which means open for reading in text mode.Other common values are'w' for writing (truncating the file if italready exists),'x' for exclusive creation and'a' for appending(which onsome Unix systems, means thatall writes append to the end ofthe file regardless of the current seek position). In text mode, ifencoding is not specified the encoding used is platform dependent:locale.getpreferredencoding(False) is called to get the current localeencoding. (For reading and writing raw bytes use binary mode and leaveencoding unspecified.) 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 the file if it exists
`'b'`	binary mode
`'t'`	text mode (default)
`'+'`	open a disk file for updating (reading and writing)
`'U'`	universal newlines mode (deprecated)

The default mode is'r' (open for reading text, synonym of'rt').For binary read-write access, the mode'w+b' opens and truncates the fileto 0 bytes.'r+b' opens the file without truncation.

As mentioned in theOverview, Python distinguishes between binaryand text I/O. Files opened in binary mode (including'b' in themodeargument) return contents asbytes objects without any decoding. Intext mode (the default, or when't' is included in themode argument),the contents of the file are returned asstr, the bytes having beenfirst decoded using a platform-dependent encoding or using the specifiedencoding if given.

Note

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

buffering is an optional integer used to set the buffering policy. Pass 0to switch buffering off (only allowed in binary mode), 1 to select linebuffering (only usable in text mode), and an integer > 1 to indicate the sizein bytes of a fixed-size chunk buffer. When nobuffering argument isgiven, the default buffering policy works as follows:

Binary files are buffered in fixed-size chunks; the size of the buffer ischosen using a heuristic trying to determine the underlying device’s “blocksize” 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 policydescribed above for binary files.

encoding is the name of the encoding used to decode or encode the file.This should only be used in text mode. The default encoding is platformdependent (whateverlocale.getpreferredencoding() returns), but anytext encoding supported by Pythoncan be used. See thecodecs module forthe list of supported encodings.

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

'strict' to raise aValueError exception if there isan encoding error. The default value ofNone has the sameeffect.
'ignore' ignores errors. Note that ignoring encoding errorscan lead to data loss.
'replace' causes a replacement marker (such as'?') to be insertedwhere there is malformed data.
'surrogateescape' will represent any incorrect bytes as codepoints in the Unicode Private Use Area ranging from U+DC80 toU+DCFF. These private code points will then be turned back intothe same bytes when thesurrogateescape error handler is usedwhen writing data. This is useful for processing files in anunknown encoding.
'xmlcharrefreplace' is only supported when writing to a file.Characters not supported by the encoding are replaced with theappropriate XML character reference&#nnn;.
'backslashreplace' replaces malformed data by Python’s backslashedescape sequences.
'namereplace' (also only supported when writing)replaces unsupported characters with\N{...} escape sequences.

newline controls howuniversal newlines mode works (it onlyapplies to text mode). It can beNone,'','\n','\r', and'\r\n'. It works as follows:

When reading input from the stream, ifnewline isNone, universalnewlines mode is enabled. Lines in the input can end in'\n','\r', or'\r\n', and these are translated into'\n' beforebeing returned to the caller. If it is'', universal newlines mode isenabled, but line endings are returned to the caller untranslated. If ithas any of the other legal values, input lines are only terminated by thegiven string, and the line ending is returned to the caller untranslated.
When writing output to the stream, ifnewline isNone, any'\n'characters written are translated to the system default line separator,os.linesep. Ifnewline is'' or'\n', no translationtakes place. Ifnewline is any of the other legal values, any'\n'characters written are translated to the given string.

Ifclosefd isFalse and a file descriptor rather than a filename wasgiven, the underlying file descriptor will be kept open when the file isclosed. If a filename is givenclosefd must beTrue (the default)otherwise an error will be raised.

A custom opener can be used by passing a callable asopener. The underlyingfile descriptor for the file object is then obtained by callingopener with(file,flags).opener must return an open file descriptor (passingos.open asopener results in functionality similar to passingNone).

The newly created file isnon-inheritable.

The following example uses thedir_fd parameter of theos.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 object returned by theopen() functiondepends on the mode. Whenopen() is used to open a file in a textmode ('w','r','wt','rt', etc.), it returns a subclass ofio.TextIOBase (specificallyio.TextIOWrapper). When usedto open a file in a binary mode with buffering, the returned class is asubclass ofio.BufferedIOBase. The exact class varies: in readbinary mode, it returns anio.BufferedReader; in write binary andappend binary modes, it returns anio.BufferedWriter, and inread/write mode, it returns anio.BufferedRandom. When buffering isdisabled, the raw stream, a subclass ofio.RawIOBase,io.FileIO, is returned.

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

Changed in version 3.3:Theopener parameter was added.The'x' mode was added.IOError used to be raised, it is now an alias ofOSError.FileExistsError is now raised if the file opened in exclusivecreation mode ('x') already exists.

Changed in version 3.4:The file is now non-inheritable.

Deprecated since version 3.4, will be removed in version 4.0:The'U' mode.

Changed in version 3.5:If the system call is interrupted and the signal handler does not raise anexception, the function now retries the system call instead of raising anInterruptedError exception (seePEP 475 for the rationale).

Changed in version 3.5:The'namereplace' error handler was added.

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

pow(x,y[,z])¶

Returnx to the powery; ifz is present, returnx to the powery,moduloz (computed more efficiently thanpow(x,y)%z). The two-argumentformpow(x,y) is equivalent to using the power operator:x**y.

The arguments must have numeric types. With mixed operand types, thecoercion rules for binary arithmetic operators apply. Forintoperands, the result has the same type as the operands (after coercion)unless the second argument is negative; in that case, all arguments areconverted to float and a float result is delivered. For example,10**2returns100, but10**-2 returns0.01. If the second argument isnegative, the third argument must be omitted. Ifz is present,x andymust be of integer types, andy must be non-negative.

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

Printobjects to the text streamfile, separated bysep and followedbyend.sep,end,file andflush, if present, must be given as keywordarguments.

All non-keyword arguments are converted to strings likestr() does andwritten to the stream, separated bysep and followed byend. Bothsepandend must be strings; they can also beNone, which means to use thedefault values. If noobjects are given,print() will just writeend.

Thefile argument must be an object with awrite(string) method; if itis not present orNone,sys.stdout will be used. Since printedarguments are converted to text strings,print() cannot be used withbinary mode file objects. For these, usefile.write(...) instead.

Whether output is buffered is usually determined byfile, but if theflush keyword argument is true, the stream is forcibly flushed.

Changed in version 3.3:Added theflush keyword argument.

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

Return a property attribute.

fget is a function for getting an attribute value.fset is a functionfor setting an attribute value.fdel is a function for deleting an attributevalue. Anddoc creates a docstring for the attribute.

A typical use is to define a managed attributex:

classC:def__init__(self):self._x=Nonedefgetx(self):returnself._xdefsetx(self,value):self._x=valuedefdelx(self):delself._xx=property(getx,setx,delx,"I'm the 'x' property.")

Ifc is an instance ofC,c.x will invoke the getter,c.x=value will invoke the setter anddelc.x the deleter.

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

classParrot:def__init__(self):self._voltage=100000@propertydefvoltage(self):"""Get the current voltage."""returnself._voltage

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

A property object hasgetter,setter,anddeleter methods usable as decorators that create acopy of the property with the corresponding accessor function set to thedecorated function. This is best explained with an example:

classC:def__init__(self):self._x=None@propertydefx(self):"""I'm the 'x' property."""returnself._x@x.setterdefx(self,value):self._x=value@x.deleterdefx(self):delself._x

This code is exactly equivalent to the first example. Be sure to give theadditional functions the same name as the original property (x in thiscase.)

The returned property object also has the attributesfget,fset, andfdel corresponding to the constructor arguments.

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

range(stop)
range(start,stop[,step]): Rather than being a function,range is actually an immutablesequence type, as documented inRanges andSequence Types — list, tuple, range.

repr(object)¶: Return a string containing a printable representation of an object. For manytypes, this function makes an attempt to return a string that would yield anobject with the same value when passed toeval(), otherwise therepresentation is a string enclosed in angle brackets that contains the nameof the type of the object together with additional information oftenincluding the name and address of the object. A class can control what thisfunction returns for its instances by defining a__repr__() method.

reversed(seq)¶: Return a reverseiterator.seq must be an object which hasa__reversed__() method or supports the sequence protocol (the__len__() method and the__getitem__() method with integerarguments starting at0).

round(number[,ndigits])¶

Returnnumber rounded tondigits precision after the decimalpoint. Ifndigits is omitted or isNone, it returns thenearest integer to its input.

For the built-in types supportinground(), values are rounded to theclosest multiple of 10 to the power minusndigits; if two multiples areequally close, rounding is done toward the even choice (so, for example,bothround(0.5) andround(-0.5) are0, andround(1.5) is2). Any integer value is valid forndigits (positive, zero, ornegative). The return value is an integer if called with one argument,otherwise of the same type asnumber.

For a general Python objectnumber,round(number,ndigits) delegates tonumber.__round__(ndigits).

Note

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

classset([iterable])

Return a newset object, optionally with elements taken fromiterable.set is a built-in class. Seeset andSet Types — set, frozenset for documentation about this class.

For other containers see the built-infrozenset,list,tuple, anddict classes, as well as thecollectionsmodule.

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

classslice(stop)¶
classslice(start,stop[,step]): Return aslice object representing the set of indices specified byrange(start,stop,step). Thestart andstep arguments default toNone. Slice objects have read-only data attributesstart,stop andstep which merely return the argumentvalues (or their default). They have no other explicit functionality;however they are used by Numerical Python and other third party extensions.Slice objects are also generated when extended indexing syntax is used. Forexample:a[start:stop:step] ora[start:stop,i]. Seeitertools.islice() for an alternate version that returns an iterator.

sorted(iterable[, key][, reverse])¶

Return a new sorted list from the items initerable.

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

key specifies a function of one argument that is used to extract a comparisonkey from each list element:key=str.lower. The default value isNone(compare the elements directly).

reverse is a boolean value. If set toTrue, then the list elements aresorted as if each comparison were reversed.

Usefunctools.cmp_to_key() to convert an old-stylecmp function to akey function.

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

For sorting examples and a brief sorting tutorial, seeSorting HOW TO.

staticmethod(function)¶

Return a static method forfunction.

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

classC:@staticmethoddeff(arg1,arg2,...):...

The@staticmethod form is a functiondecorator – see thedescription of function definitions inFunction definitions for details.

It can be called either on the class (such asC.f()) or on an instance (suchasC().f()). The instance is ignored except for its class.

Static methods in Python are similar to those found in Java or C++. Also seeclassmethod() for a variant that is useful for creating alternate classconstructors.

For more information on static methods, consult the documentation on thestandard type hierarchy inThe standard type hierarchy.

classstr(object='')

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

Return astr version ofobject. Seestr() for details.

str is the built-in stringclass. For general informationabout strings, seeText Sequence Type — str.

sum(iterable[,start])¶

Sumsstart and the items of aniterable from left to right and returns thetotal.start defaults to0. 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 usingitertools.chain().

super([type[,object-or-type]])¶

Return a proxy object that delegates method calls to a parent or siblingclass oftype. This is useful for accessing inherited methods that havebeen overridden in a class. The search order is same as that used bygetattr() except that thetype itself is skipped.

The__mro__ attribute of thetype lists the methodresolution search order used by bothgetattr() andsuper(). Theattribute is dynamic and can change whenever the inheritance hierarchy isupdated.

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

There are two typical use cases forsuper. In a class hierarchy withsingle inheritance,super can be used to refer to parent classes withoutnaming them explicitly, thus making the code more maintainable. This useclosely parallels the use ofsuper in other programming languages.

The second use case is to support cooperative multiple inheritance in adynamic execution environment. This use case is unique to Python and isnot found in statically compiled languages or languages that only supportsingle inheritance. This makes it possible to implement “diamond diagrams”where multiple base classes implement the same method. Good design dictatesthat this method have the same calling signature in every case (because theorder of calls is determined at runtime, because that order adaptsto changes in the class hierarchy, and because that order can includesibling 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)

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

Also note that, aside from the zero argument form,super() is notlimited to use inside methods. The two argument form specifies thearguments exactly and makes the appropriate references. The zeroargument form only works inside a class definition, as the compiler fillsin 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 usingsuper(), seeguide to using super().

tuple([iterable]): Rather than being a function,tuple is actually an immutablesequence type, as documented inTuples andSequence Types — list, tuple, range.

classtype(object)¶

classtype(name,bases,dict)

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

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

With three arguments, return a new type object. This is essentially adynamic form of theclass statement. Thename string is theclass name and becomes the__name__ attribute; thebasestuple itemizes the base classes and becomes the__bases__attribute; and thedict dictionary is the namespace containing definitionsfor class body and is copied to a standard dictionary to become the__dict__ attribute. For example, the following twostatements create identicaltype objects:

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

Movatterモバイル変換

Navigation

2. Built-in Functions¶

Previous topic

Next topic

This Page

Navigation