The @classmethod form is a function decorator – see Function definitions for ... Changed in version 3.10: Class methods now inherit the method attributes ...
Navigation
index
modules|
next|
previous|
Python»
3.10.3Documentation»
ThePythonStandardLibrary»
Built-inFunctions
|
Built-inFunctions¶
ThePythoninterpreterhasanumberoffunctionsandtypesbuiltintoitthat
arealwaysavailable.Theyarelistedhereinalphabeticalorder.
A
abs()
aiter()
all()
any()
anext()
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)¶
Returntheabsolutevalueofanumber.Theargumentmaybean
integer,afloatingpointnumber,oranobjectimplementing__abs__().
Iftheargumentisacomplexnumber,itsmagnitudeisreturned.
aiter(async_iterable)¶
Returnanasynchronousiteratorforanasynchronousiterable.
Equivalenttocallingx.__aiter__().
Note:Unlikeiter(),aiter()hasno2-argumentvariant.
Newinversion3.10.
all(iterable)¶
ReturnTrueifallelementsoftheiterablearetrue(oriftheiterable
isempty).Equivalentto:
defall(iterable):
forelementiniterable:
ifnotelement:
returnFalse
returnTrue
awaitableanext(async_iterator[,default])¶
Whenawaited,returnthenextitemfromthegivenasynchronous
iterator,ordefaultifgivenandtheiteratorisexhausted.
Thisistheasyncvariantofthenext()builtin,andbehaves
similarly.
Thiscallsthe__anext__()methodofasync_iterator,
returninganawaitable.Awaitingthisreturnsthenextvalueofthe
iterator.Ifdefaultisgiven,itisreturnediftheiteratorisexhausted,
otherwiseStopAsyncIterationisraised.
Newinversion3.10.
any(iterable)¶
ReturnTrueifanyelementoftheiterableistrue.Iftheiterable
isempty,returnFalse.Equivalentto:
defany(iterable):
forelementiniterable:
ifelement:
returnTrue
returnFalse
ascii(object)¶
Asrepr(),returnastringcontainingaprintablerepresentationofan
object,butescapethenon-ASCIIcharactersinthestringreturnedby
repr()using\x,\u,or\Uescapes.Thisgeneratesastring
similartothatreturnedbyrepr()inPython2.
bin(x)¶
Convertanintegernumbertoabinarystringprefixedwith“0b”.Theresult
isavalidPythonexpression.IfxisnotaPythonintobject,it
hastodefinean__index__()methodthatreturnsaninteger.Some
examples:
>>>bin(3)
'0b11'
>>>bin(-10)
'-0b1010'
Iftheprefix“0b”isdesiredornot,youcanuseeitherofthefollowingways.
>>>format(14,'#b'),format(14,'b')
('0b1110','1110')
>>>f'{14:#b}',f'{14:b}'
('0b1110','1110')
Seealsoformat()formoreinformation.
classbool([x])¶
ReturnaBooleanvalue,i.e.oneofTrueorFalse.xisconverted
usingthestandardtruthtestingprocedure.Ifxisfalse
oromitted,thisreturnsFalse;otherwise,itreturnsTrue.The
boolclassisasubclassofint(seeNumericTypes—int,float,complex).
Itcannotbesubclassedfurther.ItsonlyinstancesareFalseand
True(seeBooleanValues).
Changedinversion3.7:xisnowapositional-onlyparameter.
breakpoint(*args,**kws)¶
Thisfunctiondropsyouintothedebuggeratthecallsite.Specifically,
itcallssys.breakpointhook(),passingargsandkwsstraight
through.Bydefault,sys.breakpointhook()calls
pdb.set_trace()expectingnoarguments.Inthiscase,itis
purelyaconveniencefunctionsoyoudon’thavetoexplicitlyimport
pdbortypeasmuchcodetoenterthedebugger.However,
sys.breakpointhook()canbesettosomeotherfunctionand
breakpoint()willautomaticallycallthat,allowingyoutodropinto
thedebuggerofchoice.
Raisesanauditingeventbuiltins.breakpointwithargumentbreakpointhook.
Newinversion3.7.
classbytearray([source[,encoding[,errors]]])
Returnanewarrayofbytes.Thebytearrayclassisamutable
sequenceofintegersintherange0<=x<256.Ithasmostoftheusual
methodsofmutablesequences,describedinMutableSequenceTypes,aswell
asmostmethodsthatthebytestypehas,seeBytesandBytearrayOperations.
Theoptionalsourceparametercanbeusedtoinitializethearrayinafew
differentways:
Ifitisastring,youmustalsogivetheencoding(andoptionally,
errors)parameters;bytearray()thenconvertsthestringto
bytesusingstr.encode().
Ifitisaninteger,thearraywillhavethatsizeandwillbe
initializedwithnullbytes.
Ifitisanobjectconformingtothebufferinterface,
aread-onlybufferoftheobjectwillbeusedtoinitializethebytesarray.
Ifitisaniterable,itmustbeaniterableofintegersintherange
0<=x<256,whichareusedastheinitialcontentsofthearray.
Withoutanargument,anarrayofsize0iscreated.
SeealsoBinarySequenceTypes—bytes,bytearray,memoryviewandBytearrayObjects.
classbytes([source[,encoding[,errors]]])
Returnanew“bytes”objectwhichisanimmutablesequenceofintegersin
therange0<=x<256.bytesisanimmutableversionof
bytearray–ithasthesamenon-mutatingmethodsandthesame
indexingandslicingbehavior.
Accordingly,constructorargumentsareinterpretedasforbytearray().
Bytesobjectscanalsobecreatedwithliterals,seeStringandBytesliterals.
SeealsoBinarySequenceTypes—bytes,bytearray,memoryview,BytesObjects,andBytesandBytearrayOperations.
callable(object)¶
ReturnTrueiftheobjectargumentappearscallable,
Falseifnot.IfthisreturnsTrue,itisstillpossiblethata
callfails,butifitisFalse,callingobjectwillneversucceed.
Notethatclassesarecallable(callingaclassreturnsanewinstance);
instancesarecallableiftheirclasshasa__call__()method.
Newinversion3.2:ThisfunctionwasfirstremovedinPython3.0andthenbroughtback
inPython3.2.
chr(i)¶
ReturnthestringrepresentingacharacterwhoseUnicodecodepointisthe
integeri.Forexample,chr(97)returnsthestring'a',while
chr(8364)returnsthestring'€'.Thisistheinverseoford().
Thevalidrangefortheargumentisfrom0through1,114,111(0x10FFFFin
base16).ValueErrorwillberaisedifiisoutsidethatrange.
@classmethod¶
Transformamethodintoaclassmethod.
Aclassmethodreceivestheclassasanimplicitfirstargument,justlikean
instancemethodreceivestheinstance.Todeclareaclassmethod,usethis
idiom:
classC:
@classmethod
deff(cls,arg1,arg2):...
The@classmethodformisafunctiondecorator–see
Functiondefinitionsfordetails.
Aclassmethodcanbecalledeitherontheclass(suchasC.f())oronaninstance(such
asC().f()).Theinstanceisignoredexceptforitsclass.Ifaclass
methodiscalledforaderivedclass,thederivedclassobjectispassedasthe
impliedfirstargument.
ClassmethodsaredifferentthanC++orJavastaticmethods.Ifyouwantthose,
seestaticmethod()inthissection.
Formoreinformationonclassmethods,seeThestandardtypehierarchy.
Changedinversion3.9:Classmethodscannowwrapotherdescriptorssuchas
property().
Changedinversion3.10:Classmethodsnowinheritthemethodattributes(__module__,
__name__,__qualname__,__doc__and__annotations__)and
haveanew__wrapped__attribute.
compile(source,filename,mode,flags=0,dont_inherit=False,optimize=-1)¶
CompilethesourceintoacodeorASTobject.Codeobjectscanbeexecuted
byexec()oreval().sourcecaneitherbeanormalstring,a
bytestring,oranASTobject.Refertotheastmoduledocumentation
forinformationonhowtoworkwithASTobjects.
Thefilenameargumentshouldgivethefilefromwhichthecodewasread;
passsomerecognizablevalueifitwasn’treadfromafile(''is
commonlyused).
Themodeargumentspecifieswhatkindofcodemustbecompiled;itcanbe
'exec'ifsourceconsistsofasequenceofstatements,'eval'ifit
consistsofasingleexpression,or'single'ifitconsistsofasingle
interactivestatement(inthelattercase,expressionstatementsthat
evaluatetosomethingotherthanNonewillbeprinted).
Theoptionalargumentsflagsanddont_inheritcontrolwhich
compileroptionsshouldbeactivated
andwhichfuturefeaturesshouldbeallowed.Ifneither
ispresent(orbotharezero)thecodeiscompiledwiththesameflagsthat
affectthecodethatiscallingcompile().Iftheflags
argumentisgivenanddont_inheritisnot(oriszero)thenthecompiler
optionsandthefuturestatementsspecifiedbytheflagsargumentareused
inadditiontothosethatwouldbeusedanyway.Ifdont_inheritisa
non-zerointegerthentheflagsargumentisit–theflags(future
featuresandcompileroptions)inthesurroundingcodeareignored.
Compileroptionsandfuturestatementsarespecifiedbybitswhichcanbe
bitwiseORedtogethertospecifymultipleoptions.Thebitfieldrequiredto
specifyagivenfuturefeaturecanbefoundasthe
compiler_flagattributeonthe
_Featureinstanceinthe__future__module.
Compilerflagscanbefoundinast
module,withPyCF_prefix.
Theargumentoptimizespecifiestheoptimizationlevelofthecompiler;the
defaultvalueof-1selectstheoptimizationleveloftheinterpreteras
givenby-Ooptions.Explicitlevelsare0(nooptimization;
__debug__istrue),1(assertsareremoved,__debug__isfalse)
or2(docstringsareremovedtoo).
ThisfunctionraisesSyntaxErrorifthecompiledsourceisinvalid,
andValueErrorifthesourcecontainsnullbytes.
IfyouwanttoparsePythoncodeintoitsASTrepresentation,see
ast.parse().
Raisesanauditingeventcompilewitharguments
sourceandfilename.Thiseventmayalsoberaisedbyimplicit
compilation.
Note
Whencompilingastringwithmulti-linecodein'single'or
'eval'mode,inputmustbeterminatedbyatleastonenewline
character.Thisistofacilitatedetectionofincompleteandcomplete
statementsinthecodemodule.
Warning
ItispossibletocrashthePythoninterpreterwitha
sufficientlylarge/complexstringwhencompilingtoanAST
objectduetostackdepthlimitationsinPython’sASTcompiler.
Changedinversion3.2:AlloweduseofWindowsandMacnewlines.Also,inputin'exec'mode
doesnothavetoendinanewlineanymore.Addedtheoptimizeparameter.
Changedinversion3.5:Previously,TypeErrorwasraisedwhennullbyteswereencountered
insource.
Newinversion3.8:ast.PyCF_ALLOW_TOP_LEVEL_AWAITcannowbepassedinflagstoenable
supportfortop-levelawait,asyncfor,andasyncwith.
classcomplex([real[,imag]])¶
Returnacomplexnumberwiththevaluereal+imag*1jorconvertastring
ornumbertoacomplexnumber.Ifthefirstparameterisastring,itwill
beinterpretedasacomplexnumberandthefunctionmustbecalledwithouta
secondparameter.Thesecondparametercanneverbeastring.Eachargument
maybeanynumerictype(includingcomplex).Ifimagisomitted,it
defaultstozeroandtheconstructorservesasanumericconversionlike
intandfloat.Ifbothargumentsareomitted,returns
0j.
ForageneralPythonobjectx,complex(x)delegatesto
x.__complex__().If__complex__()isnotdefinedthenitfallsback
to__float__().If__float__()isnotdefinedthenitfallsback
to__index__().
Note
Whenconvertingfromastring,thestringmustnotcontainwhitespace
aroundthecentral+or-operator.Forexample,
complex('1+2j')isfine,butcomplex('1+2j')raises
ValueError.
ThecomplextypeisdescribedinNumericTypes—int,float,complex.
Changedinversion3.6:Groupingdigitswithunderscoresasincodeliteralsisallowed.
Changedinversion3.8:Fallsbackto__index__()if__complex__()and
__float__()arenotdefined.
delattr(object,name)¶
Thisisarelativeofsetattr().Theargumentsareanobjectanda
string.Thestringmustbethenameofoneoftheobject’sattributes.The
functiondeletesthenamedattribute,providedtheobjectallowsit.For
example,delattr(x,'foobar')isequivalenttodelx.foobar.
classdict(**kwarg)
classdict(mapping,**kwarg)
classdict(iterable,**kwarg)
Createanewdictionary.Thedictobjectisthedictionaryclass.
SeedictandMappingTypes—dictfordocumentationaboutthisclass.
Forothercontainersseethebuilt-inlist,set,and
tupleclasses,aswellasthecollectionsmodule.
dir([object])¶
Withoutarguments,returnthelistofnamesinthecurrentlocalscope.Withan
argument,attempttoreturnalistofvalidattributesforthatobject.
Iftheobjecthasamethodnamed__dir__(),thismethodwillbecalledand
mustreturnthelistofattributes.Thisallowsobjectsthatimplementacustom
__getattr__()or__getattribute__()functiontocustomizetheway
dir()reportstheirattributes.
Iftheobjectdoesnotprovide__dir__(),thefunctiontriesitsbestto
gatherinformationfromtheobject’s__dict__attribute,ifdefined,and
fromitstypeobject.Theresultinglistisnotnecessarilycompleteandmay
beinaccuratewhentheobjecthasacustom__getattr__().
Thedefaultdir()mechanismbehavesdifferentlywithdifferenttypesof
objects,asitattemptstoproducethemostrelevant,ratherthancomplete,
information:
Iftheobjectisamoduleobject,thelistcontainsthenamesofthemodule’s
attributes.
Iftheobjectisatypeorclassobject,thelistcontainsthenamesofits
attributes,andrecursivelyoftheattributesofitsbases.
Otherwise,thelistcontainstheobject’sattributes’names,thenamesofits
class’sattributes,andrecursivelyoftheattributesofitsclass’sbase
classes.
Theresultinglistissortedalphabetically.Forexample:
>>>importstruct
>>>dir()#showthenamesinthemodulenamespace
['__builtins__','__name__','struct']
>>>dir(struct)#showthenamesinthestructmodule
['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()issuppliedprimarilyasaconvenienceforuseatan
interactiveprompt,ittriestosupplyaninterestingsetofnamesmore
thanittriestosupplyarigorouslyorconsistentlydefinedsetofnames,
anditsdetailedbehaviormaychangeacrossreleases.Forexample,
metaclassattributesarenotintheresultlistwhentheargumentisa
class.
divmod(a,b)¶
Taketwo(non-complex)numbersasargumentsandreturnapairofnumbers
consistingoftheirquotientandremainderwhenusingintegerdivision.With
mixedoperandtypes,therulesforbinaryarithmeticoperatorsapply.For
integers,theresultisthesameas(a//b,a%b).Forfloatingpoint
numberstheresultis(q,a%b),whereqisusuallymath.floor(a/
b)butmaybe1lessthanthat.Inanycaseq*b+a%bisvery
closetoa,ifa%bisnon-zeroithasthesamesignasb,and0
<=abs(a%b)>>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')]
Equivalentto:
defenumerate(sequence,start=0):
n=start
foreleminsequence:
yieldn,elem
n+=1
eval(expression[,globals[,locals]])¶
Theargumentsareastringandoptionalglobalsandlocals.Ifprovided,
globalsmustbeadictionary.Ifprovided,localscanbeanymapping
object.
TheexpressionargumentisparsedandevaluatedasaPythonexpression
(technicallyspeaking,aconditionlist)usingtheglobalsandlocals
dictionariesasglobalandlocalnamespace.Iftheglobalsdictionaryis
presentanddoesnotcontainavalueforthekey__builtins__,a
referencetothedictionaryofthebuilt-inmodulebuiltinsis
insertedunderthatkeybeforeexpressionisparsed.Thatwayyoucan
controlwhatbuiltinsareavailabletotheexecutedcodebyinsertingyour
own__builtins__dictionaryintoglobalsbeforepassingitto
eval().Ifthelocalsdictionaryisomitteditdefaultstothe
globalsdictionary.Ifbothdictionariesareomitted,theexpressionis
executedwiththeglobalsandlocalsintheenvironmentwhere
eval()iscalled.Note,eval()doesnothaveaccesstothe
nestedscopes(non-locals)intheenclosing
environment.
Thereturnvalueistheresultof
theevaluatedexpression.Syntaxerrorsarereportedasexceptions.Example:
>>>x=1
>>>eval('x+1')
2
Thisfunctioncanalsobeusedtoexecutearbitrarycodeobjects(suchas
thosecreatedbycompile()).Inthiscase,passacodeobjectinstead
ofastring.Ifthecodeobjecthasbeencompiledwith'exec'asthe
modeargument,eval()'sreturnvaluewillbeNone.
Hints:dynamicexecutionofstatementsissupportedbytheexec()
function.Theglobals()andlocals()functions
returnthecurrentglobalandlocaldictionary,respectively,whichmaybe
usefultopassaroundforusebyeval()orexec().
Ifthegivensourceisastring,thenleadingandtrailingspacesandtabs
arestripped.
Seeast.literal_eval()forafunctionthatcansafelyevaluatestrings
withexpressionscontainingonlyliterals.
Raisesanauditingeventexecwiththecodeobject
astheargument.Codecompilationeventsmayalsoberaised.
exec(object[,globals[,locals]])¶
ThisfunctionsupportsdynamicexecutionofPythoncode.objectmustbe
eitherastringoracodeobject.Ifitisastring,thestringisparsedas
asuiteofPythonstatementswhichisthenexecuted(unlessasyntaxerror
occurs).1Ifitisacodeobject,itissimplyexecuted.Inallcases,
thecodethat’sexecutedisexpectedtobevalidasfileinput(seethe
sectionFileinputintheReferenceManual).Beawarethatthe
nonlocal,yield,andreturn
statementsmaynotbeusedoutsideof
functiondefinitionsevenwithinthecontextofcodepassedtothe
exec()function.ThereturnvalueisNone.
Inallcases,iftheoptionalpartsareomitted,thecodeisexecutedinthe
currentscope.Ifonlyglobalsisprovided,itmustbeadictionary
(andnotasubclassofdictionary),which
willbeusedforboththeglobalandthelocalvariables.Ifglobalsand
localsaregiven,theyareusedfortheglobalandlocalvariables,
respectively.Ifprovided,localscanbeanymappingobject.Remember
thatatthemodulelevel,globalsandlocalsarethesamedictionary.Ifexec
getstwoseparateobjectsasglobalsandlocals,thecodewillbe
executedasifitwereembeddedinaclassdefinition.
Iftheglobalsdictionarydoesnotcontainavalueforthekey
__builtins__,areferencetothedictionaryofthebuilt-inmodule
builtinsisinsertedunderthatkey.Thatwayyoucancontrolwhat
builtinsareavailabletotheexecutedcodebyinsertingyourown
__builtins__dictionaryintoglobalsbeforepassingittoexec().
Raisesanauditingeventexecwiththecodeobject
astheargument.Codecompilationeventsmayalsoberaised.
Note
Thebuilt-infunctionsglobals()andlocals()returnthecurrent
globalandlocaldictionary,respectively,whichmaybeusefultopassaround
foruseasthesecondandthirdargumenttoexec().
Note
Thedefaultlocalsactasdescribedforfunctionlocals()below:
modificationstothedefaultlocalsdictionaryshouldnotbeattempted.
Passanexplicitlocalsdictionaryifyouneedtoseeeffectsofthe
codeonlocalsafterfunctionexec()returns.
filter(function,iterable)¶
Constructaniteratorfromthoseelementsofiterableforwhichfunction
returnstrue.iterablemaybeeitherasequence,acontainerwhich
supportsiteration,oraniterator.IffunctionisNone,theidentity
functionisassumed,thatis,allelementsofiterablethatarefalseare
removed.
Notethatfilter(function,iterable)isequivalenttothegenerator
expression(itemforiteminiterableiffunction(item))iffunctionis
notNoneand(itemforiteminiterableifitem)iffunctionis
None.
Seeitertools.filterfalse()forthecomplementaryfunctionthatreturns
elementsofiterableforwhichfunctionreturnsfalse.
classfloat([x])¶
Returnafloatingpointnumberconstructedfromanumberorstringx.
Iftheargumentisastring,itshouldcontainadecimalnumber,optionally
precededbyasign,andoptionallyembeddedinwhitespace.Theoptional
signmaybe'+'or'-';a'+'signhasnoeffectonthevalue
produced.TheargumentmayalsobeastringrepresentingaNaN
(not-a-number),orpositiveornegativeinfinity.Moreprecisely,the
inputmustconformtothefollowinggrammarafterleadingandtrailing
whitespacecharactersareremoved:
sign::="+"|"-"
infinity::="Infinity"|"inf"
nan::="nan"
numeric_value::=floatnumber|infinity|nan
numeric_string::=[sign]numeric_value
HerefloatnumberistheformofaPythonfloating-pointliteral,
describedinFloatingpointliterals.Caseisnotsignificant,so,forexample,
“inf”,“Inf”,“INFINITY”,and“iNfINity”areallacceptablespellingsfor
positiveinfinity.
Otherwise,iftheargumentisanintegerorafloatingpointnumber,a
floatingpointnumberwiththesamevalue(withinPython’sfloatingpoint
precision)isreturned.IftheargumentisoutsidetherangeofaPython
float,anOverflowErrorwillberaised.
ForageneralPythonobjectx,float(x)delegatesto
x.__float__().If__float__()isnotdefinedthenitfallsback
to__index__().
Ifnoargumentisgiven,0.0isreturned.
Examples:
>>>float('+1.23')
1.23
>>>float('-12345\n')
-12345.0
>>>float('1e-003')
0.001
>>>float('+1E6')
1000000.0
>>>float('-Infinity')
-inf
ThefloattypeisdescribedinNumericTypes—int,float,complex.
Changedinversion3.6:Groupingdigitswithunderscoresasincodeliteralsisallowed.
Changedinversion3.7:xisnowapositional-onlyparameter.
Changedinversion3.8:Fallsbackto__index__()if__float__()isnotdefined.
format(value[,format_spec])¶
Convertavaluetoa“formatted”representation,ascontrolledby
format_spec.Theinterpretationofformat_specwilldependonthetype
ofthevalueargument;however,thereisastandardformattingsyntaxthat
isusedbymostbuilt-intypes:FormatSpecificationMini-Language.
Thedefaultformat_specisanemptystringwhichusuallygivesthesame
effectascallingstr(value).
Acalltoformat(value,format_spec)istranslatedto
type(value).__format__(value,format_spec)whichbypassestheinstance
dictionarywhensearchingforthevalue’s__format__()method.A
TypeErrorexceptionisraisedifthemethodsearchreaches
objectandtheformat_specisnon-empty,orifeitherthe
format_specorthereturnvaluearenotstrings.
Changedinversion3.4:object().__format__(format_spec)raisesTypeError
ifformat_specisnotanemptystring.
classfrozenset([iterable])
Returnanewfrozensetobject,optionallywithelementstakenfrom
iterable.frozensetisabuilt-inclass.Seefrozensetand
SetTypes—set,frozensetfordocumentationaboutthisclass.
Forothercontainersseethebuilt-inset,list,
tuple,anddictclasses,aswellasthecollections
module.
getattr(object,name[,default])¶
Returnthevalueofthenamedattributeofobject.namemustbeastring.
Ifthestringisthenameofoneoftheobject’sattributes,theresultisthe
valueofthatattribute.Forexample,getattr(x,'foobar')isequivalentto
x.foobar.Ifthenamedattributedoesnotexist,defaultisreturnedif
provided,otherwiseAttributeErrorisraised.
Note
Sinceprivatenamemanglinghappensat
compilationtime,onemustmanuallymangleaprivateattribute’s
(attributeswithtwoleadingunderscores)nameinordertoretrieveitwith
getattr().
globals()¶
Returnthedictionaryimplementingthecurrentmodulenamespace.Forcodewithin
functions,thisissetwhenthefunctionisdefinedandremainsthesame
regardlessofwherethefunctioniscalled.
hasattr(object,name)¶
Theargumentsareanobjectandastring.TheresultisTrueifthe
stringisthenameofoneoftheobject’sattributes,Falseifnot.(This
isimplementedbycallinggetattr(object,name)andseeingwhetherit
raisesanAttributeErrorornot.)
hash(object)¶
Returnthehashvalueoftheobject(ifithasone).Hashvaluesare
integers.Theyareusedtoquicklycomparedictionarykeysduringa
dictionarylookup.Numericvaluesthatcompareequalhavethesamehash
value(eveniftheyareofdifferenttypes,asisthecasefor1and1.0).
Note
Forobjectswithcustom__hash__()methods,notethathash()
truncatesthereturnvaluebasedonthebitwidthofthehostmachine.
See__hash__()fordetails.
help([object])¶
Invokethebuilt-inhelpsystem.(Thisfunctionisintendedforinteractive
use.)Ifnoargumentisgiven,theinteractivehelpsystemstartsonthe
interpreterconsole.Iftheargumentisastring,thenthestringislookedup
asthenameofamodule,function,class,method,keyword,ordocumentation
topic,andahelppageisprintedontheconsole.Iftheargumentisanyother
kindofobject,ahelppageontheobjectisgenerated.
Notethatifaslash(/)appearsintheparameterlistofafunctionwhen
invokinghelp(),itmeansthattheparameterspriortotheslashare
positional-only.Formoreinfo,see
theFAQentryonpositional-onlyparameters.
Thisfunctionisaddedtothebuilt-innamespacebythesitemodule.
Changedinversion3.4:Changestopydocandinspectmeanthatthereported
signaturesforcallablesarenowmorecomprehensiveandconsistent.
hex(x)¶
Convertanintegernumbertoalowercasehexadecimalstringprefixedwith
“0x”.IfxisnotaPythonintobject,ithastodefinean
__index__()methodthatreturnsaninteger.Someexamples:
>>>hex(255)
'0xff'
>>>hex(-42)
'-0x2a'
Ifyouwanttoconvertanintegernumbertoanuppercaseorlowerhexadecimal
stringwithprefixornot,youcanuseeitherofthefollowingways:
>>>'%#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')
Seealsoformat()formoreinformation.
Seealsoint()forconvertingahexadecimalstringtoan
integerusingabaseof16.
Note
Toobtainahexadecimalstringrepresentationforafloat,usethe
float.hex()method.
id(object)¶
Returnthe“identity”ofanobject.Thisisanintegerwhich
isguaranteedtobeuniqueandconstantforthisobjectduringitslifetime.
Twoobjectswithnon-overlappinglifetimesmayhavethesameid()
value.
CPythonimplementationdetail:Thisistheaddressoftheobjectinmemory.
Raisesanauditingeventbuiltins.idwithargumentid.
input([prompt])¶
Ifthepromptargumentispresent,itiswrittentostandardoutputwithout
atrailingnewline.Thefunctionthenreadsalinefrominput,convertsit
toastring(strippingatrailingnewline),andreturnsthat.WhenEOFis
read,EOFErrorisraised.Example:
>>>s=input('-->')
-->MontyPython'sFlyingCircus
>>>s
"MontyPython'sFlyingCircus"
Ifthereadlinemodulewasloaded,theninput()willuseit
toprovideelaboratelineeditingandhistoryfeatures.
Raisesanauditingeventbuiltins.inputwith
argumentpromptbeforereadinginput
Raisesanauditingeventbuiltins.input/resultwiththeresultafter
successfullyreadinginput.
classint([x])¶
classint(x,base=10)
Returnanintegerobjectconstructedfromanumberorstringx,orreturn
0ifnoargumentsaregiven.Ifxdefines__int__(),
int(x)returnsx.__int__().Ifxdefines__index__(),
itreturnsx.__index__().Ifxdefines__trunc__(),
itreturnsx.__trunc__().
Forfloatingpointnumbers,thistruncatestowardszero.
Ifxisnotanumberorifbaseisgiven,thenxmustbeastring,
bytes,orbytearrayinstancerepresentinganinteger
literalinradixbase.Optionally,theliteralcanbe
precededby+or-(withnospaceinbetween)andsurroundedby
whitespace.Abase-nliteralconsistsofthedigits0ton-1,witha
toz(orAtoZ)having
values10to35.Thedefaultbaseis10.Theallowedvaluesare0and2–36.
Base-2,-8,and-16literalscanbeoptionallyprefixedwith0b/0B,
0o/0O,or0x/0X,aswithintegerliteralsincode.Base0
meanstointerpretexactlyasacodeliteral,sothattheactualbaseis2,
8,10,or16,andsothatint('010',0)isnotlegal,while
int('010')is,aswellasint('010',8).
TheintegertypeisdescribedinNumericTypes—int,float,complex.
Changedinversion3.4:Ifbaseisnotaninstanceofintandthebaseobjecthasa
base.__index__method,thatmethodiscalled
toobtainanintegerforthebase.Previousversionsused
base.__int__insteadofbase.__index__.
Changedinversion3.6:Groupingdigitswithunderscoresasincodeliteralsisallowed.
Changedinversion3.7:xisnowapositional-onlyparameter.
Changedinversion3.8:Fallsbackto__index__()if__int__()isnotdefined.
isinstance(object,classinfo)¶
ReturnTrueiftheobjectargumentisaninstanceoftheclassinfo
argument,orofa(direct,indirect,orvirtual)subclassthereof.Ifobjectisnot
anobjectofthegiventype,thefunctionalwaysreturnsFalse.
Ifclassinfoisatupleoftypeobjects(orrecursively,othersuch
tuples)oraUnionTypeofmultipletypes,returnTrueif
objectisaninstanceofanyofthetypes.
Ifclassinfoisnotatypeortupleoftypesandsuchtuples,
aTypeErrorexceptionisraised.
Changedinversion3.10:classinfocanbeaUnionType.
issubclass(class,classinfo)¶
ReturnTrueifclassisasubclass(direct,indirect,orvirtual)ofclassinfo.A
classisconsideredasubclassofitself.classinfomaybeatupleofclass
objectsoraUnionType,inwhichcasereturnTrueifclassisa
subclassofanyentryinclassinfo.Inanyothercase,aTypeError
exceptionisraised.
Changedinversion3.10:classinfocanbeaUnionType.
iter(object[,sentinel])¶
Returnaniteratorobject.Thefirstargumentisinterpretedvery
differentlydependingonthepresenceofthesecondargument.Withouta
secondargument,objectmustbeacollectionobjectwhichsupportsthe
iterableprotocol(the__iter__()method),oritmustsupport
thesequenceprotocol(the__getitem__()methodwithintegerarguments
startingat0).Ifitdoesnotsupporteitherofthoseprotocols,
TypeErrorisraised.Ifthesecondargument,sentinel,isgiven,
thenobjectmustbeacallableobject.Theiteratorcreatedinthiscase
willcallobjectwithnoargumentsforeachcalltoits
__next__()method;ifthevaluereturnedisequalto
sentinel,StopIterationwillberaised,otherwisethevaluewill
bereturned.
SeealsoIteratorTypes.
Oneusefulapplicationofthesecondformofiter()istobuilda
block-reader.Forexample,readingfixed-widthblocksfromabinary
databasefileuntiltheendoffileisreached:
fromfunctoolsimportpartial
withopen('mydata.db','rb')asf:
forblockiniter(partial(f.read,64),b''):
process_block(block)
len(s)¶
Returnthelength(thenumberofitems)ofanobject.Theargumentmaybea
sequence(suchasastring,bytes,tuple,list,orrange)oracollection
(suchasadictionary,set,orfrozenset).
CPythonimplementationdetail:lenraisesOverflowErroronlengthslargerthan
sys.maxsize,suchasrange(2**100).
classlist([iterable])
Ratherthanbeingafunction,listisactuallyamutable
sequencetype,asdocumentedinListsandSequenceTypes—list,tuple,range.
locals()¶
Updateandreturnadictionaryrepresentingthecurrentlocalsymboltable.
Freevariablesarereturnedbylocals()whenitiscalledinfunction
blocks,butnotinclassblocks.Notethatatthemodulelevel,locals()
andglobals()arethesamedictionary.
Note
Thecontentsofthisdictionaryshouldnotbemodified;changesmaynot
affectthevaluesoflocalandfreevariablesusedbytheinterpreter.
map(function,iterable,...)¶
Returnaniteratorthatappliesfunctiontoeveryitemofiterable,
yieldingtheresults.Ifadditionaliterableargumentsarepassed,
functionmusttakethatmanyargumentsandisappliedtotheitemsfromall
iterablesinparallel.Withmultipleiterables,theiteratorstopswhenthe
shortestiterableisexhausted.Forcaseswherethefunctioninputsare
alreadyarrangedintoargumenttuples,seeitertools.starmap().
max(iterable,*[,key,default])¶
max(arg1,arg2,*args[,key])
Returnthelargestiteminaniterableorthelargestoftwoormore
arguments.
Ifonepositionalargumentisprovided,itshouldbeaniterable.
Thelargestitemintheiterableisreturned.Iftwoormorepositional
argumentsareprovided,thelargestofthepositionalargumentsis
returned.
Therearetwooptionalkeyword-onlyarguments.Thekeyargumentspecifies
aone-argumentorderingfunctionlikethatusedforlist.sort().The
defaultargumentspecifiesanobjecttoreturniftheprovidediterableis
empty.Iftheiterableisemptyanddefaultisnotprovided,a
ValueErrorisraised.
Ifmultipleitemsaremaximal,thefunctionreturnsthefirstone
encountered.Thisisconsistentwithothersort-stabilitypreservingtools
suchassorted(iterable,key=keyfunc,reverse=True)[0]and
heapq.nlargest(1,iterable,key=keyfunc).
Newinversion3.4:Thedefaultkeyword-onlyargument.
Changedinversion3.8:ThekeycanbeNone.
classmemoryview(object)
Returna“memoryview”objectcreatedfromthegivenargument.See
MemoryViewsformoreinformation.
min(iterable,*[,key,default])¶
min(arg1,arg2,*args[,key])
Returnthesmallestiteminaniterableorthesmallestoftwoormore
arguments.
Ifonepositionalargumentisprovided,itshouldbeaniterable.
Thesmallestitemintheiterableisreturned.Iftwoormorepositional
argumentsareprovided,thesmallestofthepositionalargumentsis
returned.
Therearetwooptionalkeyword-onlyarguments.Thekeyargumentspecifies
aone-argumentorderingfunctionlikethatusedforlist.sort().The
defaultargumentspecifiesanobjecttoreturniftheprovidediterableis
empty.Iftheiterableisemptyanddefaultisnotprovided,a
ValueErrorisraised.
Ifmultipleitemsareminimal,thefunctionreturnsthefirstone
encountered.Thisisconsistentwithothersort-stabilitypreservingtools
suchassorted(iterable,key=keyfunc)[0]andheapq.nsmallest(1,
iterable,key=keyfunc).
Newinversion3.4:Thedefaultkeyword-onlyargument.
Changedinversion3.8:ThekeycanbeNone.
next(iterator[,default])¶
Retrievethenextitemfromtheiteratorbycallingits
__next__()method.Ifdefaultisgiven,itisreturned
iftheiteratorisexhausted,otherwiseStopIterationisraised.
classobject¶
Returnanewfeaturelessobject.objectisabaseforallclasses.
IthasmethodsthatarecommontoallinstancesofPythonclasses.This
functiondoesnotacceptanyarguments.
Note
objectdoesnothavea__dict__,soyoucan’t
assignarbitraryattributestoaninstanceoftheobjectclass.
oct(x)¶
Convertanintegernumbertoanoctalstringprefixedwith“0o”.Theresult
isavalidPythonexpression.IfxisnotaPythonintobject,it
hastodefinean__index__()methodthatreturnsaninteger.For
example:
>>>oct(8)
'0o10'
>>>oct(-56)
'-0o70'
Ifyouwanttoconvertanintegernumbertoanoctalstringeitherwiththeprefix
“0o”ornot,youcanuseeitherofthefollowingways.
>>>'%#o'%10,'%o'%10
('0o12','12')
>>>format(10,'#o'),format(10,'o')
('0o12','12')
>>>f'{10:#o}',f'{10:o}'
('0o12','12')
Seealsoformat()formoreinformation.
open(file,mode='r',buffering=-1,encoding=None,errors=None,newline=None,closefd=True,opener=None)¶
Openfileandreturnacorrespondingfileobject.Ifthefile
cannotbeopened,anOSErrorisraised.See
ReadingandWritingFilesformoreexamplesofhowtousethisfunction.
fileisapath-likeobjectgivingthepathname(absoluteor
relativetothecurrentworkingdirectory)ofthefiletobeopenedoran
integerfiledescriptorofthefiletobewrapped.(Ifafiledescriptoris
given,itisclosedwhenthereturnedI/Oobjectisclosedunlessclosefd
issettoFalse.)
modeisanoptionalstringthatspecifiesthemodeinwhichthefileis
opened.Itdefaultsto'r'whichmeansopenforreadingintextmode.
Othercommonvaluesare'w'forwriting(truncatingthefileifit
alreadyexists),'x'forexclusivecreation,and'a'forappending
(whichonsomeUnixsystems,meansthatallwritesappendtotheendof
thefileregardlessofthecurrentseekposition).Intextmode,if
encodingisnotspecifiedtheencodingusedisplatform-dependent:
locale.getpreferredencoding(False)iscalledtogetthecurrentlocale
encoding.(Forreadingandwritingrawbytesusebinarymodeandleave
encodingunspecified.)Theavailablemodesare:
'r'
openforreading(default)
'w'
openforwriting,truncatingthefilefirst
'x'
openforexclusivecreation,failingifthefilealreadyexists
'a'
openforwriting,appendingtotheendoffileifitexists
'b'
binarymode
't'
textmode(default)
'+'
openforupdating(readingandwriting)
Thedefaultmodeis'r'(openforreadingtext,asynonymof'rt').
Modes'w+'and'w+b'openandtruncatethefile.Modes'r+'
and'r+b'openthefilewithnotruncation.
AsmentionedintheOverview,Pythondistinguishesbetweenbinary
andtextI/O.Filesopenedinbinarymode(including'b'inthemode
argument)returncontentsasbytesobjectswithoutanydecoding.In
textmode(thedefault,orwhen't'isincludedinthemodeargument),
thecontentsofthefilearereturnedasstr,thebyteshavingbeen
firstdecodedusingaplatform-dependentencodingorusingthespecified
encodingifgiven.
Thereisanadditionalmodecharacterpermitted,'U',whichnolonger
hasanyeffect,andisconsidereddeprecated.Itpreviouslyenabled
universalnewlinesintextmode,whichbecamethedefaultbehavior
inPython3.0.Refertothedocumentationofthe
newlineparameterforfurtherdetails.
Note
Pythondoesn’tdependontheunderlyingoperatingsystem’snotionoftext
files;alltheprocessingisdonebyPythonitself,andistherefore
platform-independent.
bufferingisanoptionalintegerusedtosetthebufferingpolicy.Pass0
toswitchbufferingoff(onlyallowedinbinarymode),1toselectline
buffering(onlyusableintextmode),andaninteger>1toindicatethesize
inbytesofafixed-sizechunkbuffer.Whennobufferingargumentis
given,thedefaultbufferingpolicyworksasfollows:
Binaryfilesarebufferedinfixed-sizechunks;thesizeofthebufferis
chosenusingaheuristictryingtodeterminetheunderlyingdevice’s“block
size”andfallingbackonio.DEFAULT_BUFFER_SIZE.Onmanysystems,
thebufferwilltypicallybe4096or8192byteslong.
“Interactive”textfiles(filesforwhichisatty()
returnsTrue)uselinebuffering.Othertextfilesusethepolicy
describedaboveforbinaryfiles.
encodingisthenameoftheencodingusedtodecodeorencodethefile.
Thisshouldonlybeusedintextmode.Thedefaultencodingisplatform
dependent(whateverlocale.getpreferredencoding()returns),butany
textencodingsupportedbyPython
canbeused.Seethecodecsmodulefor
thelistofsupportedencodings.
errorsisanoptionalstringthatspecifieshowencodinganddecoding
errorsaretobehandled—thiscannotbeusedinbinarymode.
Avarietyofstandarderrorhandlersareavailable
(listedunderErrorHandlers),thoughany
errorhandlingnamethathasbeenregisteredwith
codecs.register_error()isalsovalid.Thestandardnames
include:
'strict'toraiseaValueErrorexceptionifthereis
anencodingerror.ThedefaultvalueofNonehasthesame
effect.
'ignore'ignoreserrors.Notethatignoringencodingerrors
canleadtodataloss.
'replace'causesareplacementmarker(suchas'?')tobeinserted
wherethereismalformeddata.
'surrogateescape'willrepresentanyincorrectbytesaslow
surrogatecodeunitsrangingfromU+DC80toU+DCFF.
Thesesurrogatecodeunitswillthenbeturnedbackinto
thesamebyteswhenthesurrogateescapeerrorhandlerisused
whenwritingdata.Thisisusefulforprocessingfilesinan
unknownencoding.
'xmlcharrefreplace'isonlysupportedwhenwritingtoafile.
Charactersnotsupportedbytheencodingarereplacedwiththe
appropriateXMLcharacterreferencennn;.
'backslashreplace'replacesmalformeddatabyPython’sbackslashed
escapesequences.
'namereplace'(alsoonlysupportedwhenwriting)
replacesunsupportedcharacterswith\N{...}escapesequences.
newlinecontrolshowuniversalnewlinesmodeworks(itonly
appliestotextmode).ItcanbeNone,'','\n','\r',and
'\r\n'.Itworksasfollows:
Whenreadinginputfromthestream,ifnewlineisNone,universal
newlinesmodeisenabled.Linesintheinputcanendin'\n',
'\r',or'\r\n',andthesearetranslatedinto'\n'before
beingreturnedtothecaller.Ifitis'',universalnewlinesmodeis
enabled,butlineendingsarereturnedtothecalleruntranslated.Ifit
hasanyoftheotherlegalvalues,inputlinesareonlyterminatedbythe
givenstring,andthelineendingisreturnedtothecalleruntranslated.
Whenwritingoutputtothestream,ifnewlineisNone,any'\n'
characterswrittenaretranslatedtothesystemdefaultlineseparator,
os.linesep.Ifnewlineis''or'\n',notranslation
takesplace.Ifnewlineisanyoftheotherlegalvalues,any'\n'
characterswrittenaretranslatedtothegivenstring.
IfclosefdisFalseandafiledescriptorratherthanafilenamewas
given,theunderlyingfiledescriptorwillbekeptopenwhenthefileis
closed.IfafilenameisgivenclosefdmustbeTrue(thedefault);
otherwise,anerrorwillberaised.
Acustomopenercanbeusedbypassingacallableasopener.Theunderlying
filedescriptorforthefileobjectisthenobtainedbycallingopenerwith
(file,flags).openermustreturnanopenfiledescriptor(passing
os.openasopenerresultsinfunctionalitysimilartopassing
None).
Thenewlycreatedfileisnon-inheritable.
Thefollowingexampleusesthedir_fdparameterofthe
os.open()functiontoopenafilerelativetoagivendirectory:
>>>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('Thiswillbewrittentosomedir/spamspam.txt',file=f)
...
>>>os.close(dir_fd)#don'tleakafiledescriptor
Thetypeoffileobjectreturnedbytheopen()function
dependsonthemode.Whenopen()isusedtoopenafileinatext
mode('w','r','wt','rt',etc.),itreturnsasubclassof
io.TextIOBase(specificallyio.TextIOWrapper).Whenused
toopenafileinabinarymodewithbuffering,thereturnedclassisa
subclassofio.BufferedIOBase.Theexactclassvaries:inread
binarymode,itreturnsanio.BufferedReader;inwritebinaryand
appendbinarymodes,itreturnsanio.BufferedWriter,andin
read/writemode,itreturnsanio.BufferedRandom.Whenbufferingis
disabled,therawstream,asubclassofio.RawIOBase,
io.FileIO,isreturned.
Seealsothefilehandlingmodules,suchasfileinput,io
(whereopen()isdeclared),os,os.path,tempfile,
andshutil.
Raisesanauditingeventopenwithargumentsfile,mode,flags.
Themodeandflagsargumentsmayhavebeenmodifiedorinferredfrom
theoriginalcall.
Changedinversion3.3:
Theopenerparameterwasadded.
The'x'modewasadded.
IOErrorusedtoberaised,itisnowanaliasofOSError.
FileExistsErrorisnowraisedifthefileopenedinexclusive
creationmode('x')alreadyexists.
Changedinversion3.4:
Thefileisnownon-inheritable.
Deprecatedsinceversion3.4,removedinversion3.10:The'U'mode.
Changedinversion3.5:
Ifthesystemcallisinterruptedandthesignalhandlerdoesnotraisean
exception,thefunctionnowretriesthesystemcallinsteadofraisingan
InterruptedErrorexception(seePEP475fortherationale).
The'namereplace'errorhandlerwasadded.
Changedinversion3.6:
Supportaddedtoacceptobjectsimplementingos.PathLike.
OnWindows,openingaconsolebuffermayreturnasubclassof
io.RawIOBaseotherthanio.FileIO.
ord(c)¶
GivenastringrepresentingoneUnicodecharacter,returnaninteger
representingtheUnicodecodepointofthatcharacter.Forexample,
ord('a')returnstheinteger97andord('€')(Eurosign)
returns8364.Thisistheinverseofchr().
pow(base,exp[,mod])¶
Returnbasetothepowerexp;ifmodispresent,returnbasetothe
powerexp,modulomod(computedmoreefficientlythan
pow(base,exp)%mod).Thetwo-argumentformpow(base,exp)is
equivalenttousingthepoweroperator:base**exp.
Theargumentsmusthavenumerictypes.Withmixedoperandtypes,the
coercionrulesforbinaryarithmeticoperatorsapply.Forint
operands,theresulthasthesametypeastheoperands(aftercoercion)
unlessthesecondargumentisnegative;inthatcase,allargumentsare
convertedtofloatandafloatresultisdelivered.Forexample,pow(10,2)
returns100,butpow(10,-2)returns0.01.Foranegativebaseof
typeintorfloatandanon-integralexponent,acomplex
resultisdelivered.Forexample,pow(-9,0.5)returnsavalueclose
to3j.
Forintoperandsbaseandexp,ifmodispresent,modmust
alsobeofintegertypeandmodmustbenonzero.Ifmodispresentand
expisnegative,basemustberelativelyprimetomod.Inthatcase,
pow(inv_base,-exp,mod)isreturned,whereinv_baseisaninverseto
basemodulomod.
Here’sanexampleofcomputinganinversefor38modulo97:
>>>pow(38,-1,mod=97)
23
>>>23*38%97==1
True
Changedinversion3.8:Forintoperands,thethree-argumentformofpownowallows
thesecondargumenttobenegative,permittingcomputationofmodular
inverses.
Changedinversion3.8:Allowkeywordarguments.Formerly,onlypositionalargumentswere
supported.
print(*objects,sep='',end='\n',file=sys.stdout,flush=False)¶
Printobjectstothetextstreamfile,separatedbysepandfollowed
byend.sep,end,file,andflush,ifpresent,mustbegivenaskeyword
arguments.
Allnon-keywordargumentsareconvertedtostringslikestr()doesand
writtentothestream,separatedbysepandfollowedbyend.Bothsep
andendmustbestrings;theycanalsobeNone,whichmeanstousethe
defaultvalues.Ifnoobjectsaregiven,print()willjustwrite
end.
Thefileargumentmustbeanobjectwithawrite(string)method;ifit
isnotpresentorNone,sys.stdoutwillbeused.Sinceprinted
argumentsareconvertedtotextstrings,print()cannotbeusedwith
binarymodefileobjects.Forthese,usefile.write(...)instead.
Whethertheoutputisbufferedisusuallydeterminedbyfile,butifthe
flushkeywordargumentistrue,thestreamisforciblyflushed.
Changedinversion3.3:Addedtheflushkeywordargument.
classproperty(fget=None,fset=None,fdel=None,doc=None)¶
Returnapropertyattribute.
fgetisafunctionforgettinganattributevalue.fsetisafunction
forsettinganattributevalue.fdelisafunctionfordeletinganattribute
value.Anddoccreatesadocstringfortheattribute.
Atypicaluseistodefineamanagedattributex:
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'mthe'x'property.")
IfcisaninstanceofC,c.xwillinvokethegetter,
c.x=valuewillinvokethesetter,anddelc.xthedeleter.
Ifgiven,docwillbethedocstringofthepropertyattribute.Otherwise,the
propertywillcopyfget’sdocstring(ifitexists).Thismakesitpossibleto
createread-onlypropertieseasilyusingproperty()asadecorator:
classParrot:
def__init__(self):
self._voltage=100000
@property
defvoltage(self):
"""Getthecurrentvoltage."""
returnself._voltage
The@propertydecoratorturnsthevoltage()methodintoa“getter”
foraread-onlyattributewiththesamename,anditsetsthedocstringfor
voltageto“Getthecurrentvoltage.”
Apropertyobjecthasgetter,setter,
anddeletermethodsusableasdecoratorsthatcreatea
copyofthepropertywiththecorrespondingaccessorfunctionsettothe
decoratedfunction.Thisisbestexplainedwithanexample:
classC:
def__init__(self):
self._x=None
@property
defx(self):
"""I'mthe'x'property."""
returnself._x
@x.setter
defx(self,value):
self._x=value
@x.deleter
defx(self):
delself._x
Thiscodeisexactlyequivalenttothefirstexample.Besuretogivethe
additionalfunctionsthesamenameastheoriginalproperty(xinthis
case.)
Thereturnedpropertyobjectalsohastheattributesfget,fset,and
fdelcorrespondingtotheconstructorarguments.
Changedinversion3.5:Thedocstringsofpropertyobjectsarenowwriteable.
classrange(stop)
classrange(start,stop[,step])
Ratherthanbeingafunction,rangeisactuallyanimmutable
sequencetype,asdocumentedinRangesandSequenceTypes—list,tuple,range.
repr(object)¶
Returnastringcontainingaprintablerepresentationofanobject.Formany
types,thisfunctionmakesanattempttoreturnastringthatwouldyieldan
objectwiththesamevaluewhenpassedtoeval();otherwise,the
representationisastringenclosedinanglebracketsthatcontainsthename
ofthetypeoftheobjecttogetherwithadditionalinformationoften
includingthenameandaddressoftheobject.Aclasscancontrolwhatthis
functionreturnsforitsinstancesbydefininga__repr__()method.
reversed(seq)¶
Returnareverseiterator.seqmustbeanobjectwhichhas
a__reversed__()methodorsupportsthesequenceprotocol(the
__len__()methodandthe__getitem__()methodwithinteger
argumentsstartingat0).
round(number[,ndigits])¶
Returnnumberroundedtondigitsprecisionafterthedecimal
point.IfndigitsisomittedorisNone,itreturnsthe
nearestintegertoitsinput.
Forthebuilt-intypessupportinground(),valuesareroundedtothe
closestmultipleof10tothepowerminusndigits;iftwomultiplesare
equallyclose,roundingisdonetowardtheevenchoice(so,forexample,
bothround(0.5)andround(-0.5)are0,andround(1.5)is
2).Anyintegervalueisvalidforndigits(positive,zero,or
negative).Thereturnvalueisanintegerifndigitsisomittedor
None.
Otherwise,thereturnvaluehasthesametypeasnumber.
ForageneralPythonobjectnumber,rounddelegatesto
number.__round__.
Note
Thebehaviorofround()forfloatscanbesurprising:forexample,
round(2.675,2)gives2.67insteadoftheexpected2.68.
Thisisnotabug:it’saresultofthefactthatmostdecimalfractions
can’tberepresentedexactlyasafloat.SeeFloatingPointArithmetic:IssuesandLimitationsfor
moreinformation.
classset([iterable])
Returnanewsetobject,optionallywithelementstakenfrom
iterable.setisabuilt-inclass.Seesetand
SetTypes—set,frozensetfordocumentationaboutthisclass.
Forothercontainersseethebuilt-infrozenset,list,
tuple,anddictclasses,aswellasthecollections
module.
setattr(object,name,value)¶
Thisisthecounterpartofgetattr().Theargumentsareanobject,a
string,andanarbitraryvalue.Thestringmaynameanexistingattributeora
newattribute.Thefunctionassignsthevaluetotheattribute,providedthe
objectallowsit.Forexample,setattr(x,'foobar',123)isequivalentto
x.foobar=123.
Note
Sinceprivatenamemanglinghappensat
compilationtime,onemustmanuallymangleaprivateattribute’s
(attributeswithtwoleadingunderscores)nameinordertosetitwith
setattr().
classslice(stop)¶
classslice(start,stop[,step])
Returnasliceobjectrepresentingthesetofindicesspecifiedby
range(start,stop,step).Thestartandstepargumentsdefaultto
None.Sliceobjectshaveread-onlydataattributesstart,
stop,andstepwhichmerelyreturntheargument
values(ortheirdefault).Theyhavenootherexplicitfunctionality;
however,theyareusedbyNumPyandotherthird-partypackages.
Sliceobjectsarealsogeneratedwhenextendedindexingsyntaxisused.For
example:a[start:stop:step]ora[start:stop,i].See
itertools.islice()foranalternateversionthatreturnsaniterator.
sorted(iterable,/,*,key=None,reverse=False)¶
Returnanewsortedlistfromtheitemsiniterable.
Hastwooptionalargumentswhichmustbespecifiedaskeywordarguments.
keyspecifiesafunctionofoneargumentthatisusedtoextractacomparison
keyfromeachelementiniterable(forexample,key=str.lower).The
defaultvalueisNone(comparetheelementsdirectly).
reverseisabooleanvalue.IfsettoTrue,thenthelistelementsare
sortedasifeachcomparisonwerereversed.
Usefunctools.cmp_to_key()toconvertanold-stylecmpfunctiontoa
keyfunction.
Thebuilt-insorted()functionisguaranteedtobestable.Asortis
stableifitguaranteesnottochangetherelativeorderofelementsthat
compareequal—thisishelpfulforsortinginmultiplepasses(for
example,sortbydepartment,thenbysalarygrade).
ThesortalgorithmusesonlyB->C->A->objectandthevalueoftypeisB,
thensuper()searchesC->A->object.
The__mro__attributeoftheobject-or-typeliststhemethod
resolutionsearchorderusedbybothgetattr()andsuper().The
attributeisdynamicandcanchangewhenevertheinheritancehierarchyis
updated.
Ifthesecondargumentisomitted,thesuperobjectreturnedisunbound.If
thesecondargumentisanobject,isinstance(obj,type)mustbetrue.If
thesecondargumentisatype,issubclass(type2,type)mustbetrue(this
isusefulforclassmethods).
Therearetwotypicalusecasesforsuper.Inaclasshierarchywith
singleinheritance,supercanbeusedtorefertoparentclasseswithout
namingthemexplicitly,thusmakingthecodemoremaintainable.Thisuse
closelyparallelstheuseofsuperinotherprogramminglanguages.
Thesecondusecaseistosupportcooperativemultipleinheritanceina
dynamicexecutionenvironment.ThisusecaseisuniquetoPythonandis
notfoundinstaticallycompiledlanguagesorlanguagesthatonlysupport
singleinheritance.Thismakesitpossibletoimplement“diamonddiagrams”
wheremultiplebaseclassesimplementthesamemethod.Gooddesigndictates
thatsuchimplementationshavethesamecallingsignatureineverycase(becausethe
orderofcallsisdeterminedatruntime,becausethatorderadapts
tochangesintheclasshierarchy,andbecausethatordercaninclude
siblingclassesthatareunknownpriortoruntime).
Forbothusecases,atypicalsuperclasscalllookslikethis:
classC(B):
defmethod(self,arg):
super().method(arg)#Thisdoesthesamethingas:
#super(C,self).method(arg)
Inadditiontomethodlookups,super()alsoworksforattribute
lookups.Onepossibleusecaseforthisiscallingdescriptors
inaparentorsiblingclass.
Notethatsuper()isimplementedaspartofthebindingprocessfor
explicitdottedattributelookupssuchassuper().__getitem__(name).
Itdoessobyimplementingitsown__getattribute__()methodforsearching
classesinapredictableorderthatsupportscooperativemultipleinheritance.
Accordingly,super()isundefinedforimplicitlookupsusingstatementsor
operatorssuchassuper()[name].
Alsonotethat,asidefromthezeroargumentform,super()isnot
limitedtouseinsidemethods.Thetwoargumentformspecifiesthe
argumentsexactlyandmakestheappropriatereferences.Thezero
argumentformonlyworksinsideaclassdefinition,asthecompilerfills
inthenecessarydetailstocorrectlyretrievetheclassbeingdefined,
aswellasaccessingthecurrentinstanceforordinarymethods.
Forpracticalsuggestionsonhowtodesigncooperativeclassesusing
super(),seeguidetousingsuper().
classtuple([iterable])
Ratherthanbeingafunction,tupleisactuallyanimmutable
sequencetype,asdocumentedinTuplesandSequenceTypes—list,tuple,range.
classtype(object)¶
classtype(name,bases,dict,**kwds)
Withoneargument,returnthetypeofanobject.Thereturnvalueisa
typeobjectandgenerallythesameobjectasreturnedby
object.__class__.
Theisinstance()built-infunctionisrecommendedfortestingthetype
ofanobject,becauseittakessubclassesintoaccount.
Withthreearguments,returnanewtypeobject.Thisisessentiallya
dynamicformoftheclassstatement.Thenamestringis
theclassnameandbecomesthe__name__attribute.
Thebasestuplecontainsthebaseclassesandbecomesthe
__bases__attribute;ifempty,object,the
ultimatebaseofallclasses,isadded.Thedictdictionarycontains
attributeandmethoddefinitionsfortheclassbody;itmaybecopied
orwrappedbeforebecomingthe__dict__attribute.
Thefollowingtwostatementscreateidenticaltypeobjects:
>>>classX:
...a=1
...
>>>X=type('X',(),dict(a=1))
SeealsoTypeObjects.
Keywordargumentsprovidedtothethreeargumentformarepassedtothe
appropriatemetaclassmachinery(usually__init_subclass__())
inthesamewaythatkeywordsinaclass
definition(besidesmetaclass)would.
SeealsoCustomizingclasscreation.
Changedinversion3.6:Subclassesoftypewhichdon’toverridetype.__new__mayno
longerusetheone-argumentformtogetthetypeofanobject.
vars([object])¶
Returnthe__dict__attributeforamodule,class,instance,
oranyotherobjectwitha__dict__attribute.
Objectssuchasmodulesandinstanceshaveanupdateable__dict__
attribute;however,otherobjectsmayhavewriterestrictionsontheir
__dict__attributes(forexample,classesusea
types.MappingProxyTypetopreventdirectdictionaryupdates).
Withoutanargument,vars()actslikelocals().Note,the
localsdictionaryisonlyusefulforreadssinceupdatestothelocals
dictionaryareignored.
ATypeErrorexceptionisraisedifanobjectisspecifiedbut
itdoesn’thavea__dict__attribute(forexample,if
itsclassdefinesthe__slots__attribute).
zip(*iterables,strict=False)¶
Iterateoverseveraliterablesinparallel,producingtupleswithanitem
fromeachone.
Example:
>>>foriteminzip([1,2,3],['sugar','spice','everythingnice']):
...print(item)
...
(1,'sugar')
(2,'spice')
(3,'everythingnice')
Moreformally:zip()returnsaniteratoroftuples,wherethei-th
tuplecontainsthei-thelementfromeachoftheargumentiterables.
Anotherwaytothinkofzip()isthatitturnsrowsintocolumns,and
columnsintorows.Thisissimilartotransposingamatrix.
zip()islazy:Theelementswon’tbeprocesseduntiltheiterableis
iteratedon,e.g.byaforlooporbywrappingina
list.
Onethingtoconsideristhattheiterablespassedtozip()couldhave
differentlengths;sometimesbydesign,andsometimesbecauseofabugin
thecodethatpreparedtheseiterables.Pythonoffersthreedifferent
approachestodealingwiththisissue:
Bydefault,zip()stopswhentheshortestiterableisexhausted.
Itwillignoretheremainingitemsinthelongeriterables,cuttingoff
theresulttothelengthoftheshortestiterable:
>>>list(zip(range(3),['fee','fi','fo','fum']))
[(0,'fee'),(1,'fi'),(2,'fo')]
zip()isoftenusedincaseswheretheiterablesareassumedtobe
ofequallength.Insuchcases,it’srecommendedtousethestrict=True
option.Itsoutputisthesameasregularzip():
>>>list(zip(('a','b','c'),(1,2,3),strict=True))
[('a',1),('b',2),('c',3)]
Unlikethedefaultbehavior,itchecksthatthelengthsofiterablesare
identical,raisingaValueErroriftheyaren’t:
>>>list(zip(range(3),['fee','fi','fo','fum'],strict=True))
Traceback(mostrecentcalllast):
...
ValueError:zip()argument2islongerthanargument1
Withoutthestrict=Trueargument,anybugthatresultsiniterablesof
differentlengthswillbesilenced,possiblymanifestingasahard-to-find
buginanotherpartoftheprogram.
Shorteriterablescanbepaddedwithaconstantvaluetomakeallthe
iterableshavethesamelength.Thisisdoneby
itertools.zip_longest().
Edgecases:Withasingleiterableargument,zip()returnsan
iteratorof1-tuples.Withnoarguments,itreturnsanemptyiterator.
Tipsandtricks:
Theleft-to-rightevaluationorderoftheiterablesisguaranteed.This
makespossibleanidiomforclusteringadataseriesinton-lengthgroups
usingzip(*[iter(s)]*n,strict=True).Thisrepeatsthesameiterator
ntimessothateachoutputtuplehastheresultofncallstothe
iterator.Thishastheeffectofdividingtheinputinton-lengthchunks.
zip()inconjunctionwiththe*operatorcanbeusedtounzipa
list:
>>>x=[1,2,3]
>>>y=[4,5,6]
>>>list(zip(x,y))
[(1,4),(2,5),(3,6)]
>>>x2,y2=zip(*zip(x,y))
>>>x==list(x2)andy==list(y2)
True
Changedinversion3.10:Addedthestrictargument.
__import__(name,globals=None,locals=None,fromlist=(),level=0)¶
Note
ThisisanadvancedfunctionthatisnotneededineverydayPython
programming,unlikeimportlib.import_module().
Thisfunctionisinvokedbytheimportstatement.Itcanbe
replaced(byimportingthebuiltinsmoduleandassigningto
builtins.__import__)inordertochangesemanticsofthe
importstatement,butdoingsoisstronglydiscouragedasit
isusuallysimplertouseimporthooks(seePEP302)toattainthesame
goalsanddoesnotcauseissueswithcodewhichassumesthedefaultimport
implementationisinuse.Directuseof__import__()isalso
discouragedinfavorofimportlib.import_module().
Thefunctionimportsthemodulename,potentiallyusingthegivenglobals
andlocalstodeterminehowtointerpretthenameinapackagecontext.
Thefromlistgivesthenamesofobjectsorsubmodulesthatshouldbe
importedfromthemodulegivenbyname.Thestandardimplementationdoes
notuseitslocalsargumentatallandusesitsglobalsonlyto
determinethepackagecontextoftheimportstatement.
levelspecifieswhethertouseabsoluteorrelativeimports.0(the
default)meansonlyperformabsoluteimports.Positivevaluesfor
levelindicatethenumberofparentdirectoriestosearchrelativetothe
directoryofthemodulecalling__import__()(seePEP328forthe
details).
Whenthenamevariableisoftheformpackage.module,normally,the
top-levelpackage(thenameuptillthefirstdot)isreturned,notthe
modulenamedbyname.However,whenanon-emptyfromlistargumentis
given,themodulenamedbynameisreturned.
Forexample,thestatementimportspamresultsinbytecoderesemblingthe
followingcode:
spam=__import__('spam',globals(),locals(),[],0)
Thestatementimportspam.hamresultsinthiscall:
spam=__import__('spam.ham',globals(),locals(),[],0)
Notehow__import__()returnsthetoplevelmoduleherebecausethisis
theobjectthatisboundtoanamebytheimportstatement.
Ontheotherhand,thestatementfromspam.hamimporteggs,sausageas
sausresultsin
_temp=__import__('spam.ham',globals(),locals(),['eggs','sausage'],0)
eggs=_temp.eggs
saus=_temp.sausage
Here,thespam.hammoduleisreturnedfrom__import__().Fromthis
object,thenamestoimportareretrievedandassignedtotheirrespective
names.
Ifyousimplywanttoimportamodule(potentiallywithinapackage)byname,
useimportlib.import_module().
Changedinversion3.3:Negativevaluesforlevelarenolongersupported(whichalsochanges
thedefaultvalueto0).
Changedinversion3.9:Whenthecommandlineoptions-Eor-Iarebeingused,
theenvironmentvariablePYTHONCASEOKisnowignored.
Footnotes
1
NotethattheparseronlyacceptstheUnix-styleendoflineconvention.
Ifyouarereadingthecodefromafile,makesuretousenewlineconversion
modetoconvertWindowsorMac-stylenewlines.
Previoustopic
Introduction
Nexttopic
Built-inConstants
ThisPage
ReportaBug
ShowSource
Navigation
index
modules|
next|
previous|
Python»
3.10.3Documentation»
ThePythonStandardLibrary»
Built-inFunctions
|
Python decorator