3.2.1.None¶

This type has a single value. There is a single object with this value. Thisobject is accessed through the built-in nameNone. It is used to signify theabsence of a value in many situations, e.g., it is returned from functions thatdon’t explicitly return anything. Its truth value is false.

3.2.2.NotImplemented¶

This type has a single value. There is a single object with this value. Thisobject is accessed through the built-in nameNotImplemented. Numeric methodsand rich comparison methods should return this value if they do not implement theoperation for the operands provided. (The interpreter will then try thereflected operation, or some other fallback, depending on the operator.) Itshould not be evaluated in a boolean context.

SeeImplementing the arithmetic operationsfor more details.

3.2.3.Ellipsis¶

This type has a single value. There is a single object with this value. Thisobject is accessed through the literal... or the built-in nameEllipsis. Its truth value is true.

3.2.4.numbers.Number¶

These are created by numeric literals and returned as results by arithmeticoperators and arithmetic built-in functions. Numeric objects are immutable;once created their value never changes. Python numbers are of course stronglyrelated to mathematical numbers, but subject to the limitations of numericalrepresentation in computers.

The string representations of the numeric classes, computed by__repr__() and__str__(), have the followingproperties:

• They are valid numeric literals which, when passed to theirclass constructor, produce an object having the value of theoriginal numeric.

• The representation is in base 10, when possible.

• Leading zeros, possibly excepting a single zero before adecimal point, are not shown.

• Trailing zeros, possibly excepting a single zero after adecimal point, are not shown.

• A sign is shown only when the number is negative.

Python distinguishes between integers, floating-point numbers, and complexnumbers:

3.2.5.Sequences¶

These represent finite ordered sets indexed by non-negative numbers. Thebuilt-in functionlen() returns the number of items of a sequence. Whenthe length of a sequence isn, the index set contains the numbers 0, 1,…,n-1. Itemi of sequencea is selected bya[i]. Some sequences,including built-in sequences, interpret negative subscripts by adding thesequence length. For example,a[-2] equalsa[n-2], the second to lastitem of sequence a with lengthn.

Sequences also support slicing:a[i:j] selects all items with indexk suchthati<=k<j. When used as an expression, a slice is asequence of the same type. The comment above about negative indexes also appliesto negative slice positions.

Some sequences also support “extended slicing” with a third “step” parameter:a[i:j:k] selects all items ofa with indexx wherex=i+n*k,n>=0 andi<=x<j.

Sequences are distinguished according to their mutability:

3.2.6.Set types¶

These represent unordered, finite sets of unique, immutable objects. As such,they cannot be indexed by any subscript. However, they can be iterated over, andthe built-in functionlen() returns the number of items in a set. Commonuses for sets are fast membership testing, removing duplicates from a sequence,and computing mathematical operations such as intersection, union, difference,and symmetric difference.

For set elements, the same immutability rules apply as for dictionary keys. Notethat numeric types obey the normal rules for numeric comparison: if two numberscompare equal (e.g.,1 and1.0), only one of them can be contained in aset.

There are currently two intrinsic set types:

Sets

These represent a mutable set. They are created by the built-inset()constructor and can be modified afterwards by several methods, such asadd().

Frozen sets

These represent an immutable set. They are created by the built-infrozenset() constructor. As a frozenset is immutable andhashable, it can be used again as an element of another set, or asa dictionary key.

3.2.7.Mappings¶

These represent finite sets of objects indexed by arbitrary index sets. Thesubscript notationa[k] selects the item indexed byk from the mappinga; this can be used in expressions and as the target of assignments ordel statements. The built-in functionlen() returns the numberof items in a mapping.

There is currently a single intrinsic mapping type:

3.2.8.Callable types¶

These are the types to which the function call operation (see sectionCalls) can be applied:

3.2.9.Modules¶

Modules are a basic organizational unit of Python code, and are created bytheimport system as invoked either by theimport statement, or by callingfunctions such asimportlib.import_module() and built-in__import__(). A module object has a namespace implemented by adictionary object (this is the dictionary referenced by the__globals__attribute of functions defined in the module). Attribute references aretranslated to lookups in this dictionary, e.g.,m.x is equivalent tom.__dict__["x"]. A module object does not contain the code object usedto initialize the module (since it isn’t needed once the initialization isdone).

Attribute assignment updates the module’s namespace dictionary, e.g.,m.x=1 is equivalent tom.__dict__["x"]=1.

>>>importtyping>>>typing.__name__,typing.__spec__.name('typing', 'typing')>>>typing.__spec__.name='spelling'>>>typing.__name__,typing.__spec__.name('typing', 'spelling')>>>typing.__name__='keyboard_smashing'>>>typing.__name__,typing.__spec__.name('keyboard_smashing', 'spelling')

3.2.10.Custom classes¶

Custom class types are typically created by class definitions (see sectionClass definitions). A class has a namespace implemented by a dictionary object.Class attribute references are translated to lookups in this dictionary, e.g.,C.x is translated toC.__dict__["x"] (although there are a number ofhooks which allow for other means of locating attributes). When the attributename is not found there, the attribute search continues in the base classes.This search of the base classes uses the C3 method resolution order whichbehaves correctly even in the presence of ‘diamond’ inheritance structureswhere there are multiple inheritance paths leading back to a common ancestor.Additional details on the C3 MRO used by Python can be found atThe Python 2.3 Method Resolution Order.

When a class attribute reference (for classC, say) would yield aclass method object, it is transformed into an instance method object whose__self__ attribute isC.When it would yield astaticmethod object,it is transformed into the object wrapped by the static methodobject. See sectionImplementing Descriptors for another way in which attributesretrieved from a class may differ from those actually contained in its__dict__.

Class attribute assignments update the class’s dictionary, never the dictionaryof a base class.

A class object can be called (see above) to yield a class instance (see below).

3.2.11.Class instances¶

A class instance is created by calling a class object (see above). A classinstance has a namespace implemented as a dictionary which is the first placein which attribute references are searched. When an attribute is not foundthere, and the instance’s class has an attribute by that name, the searchcontinues with the class attributes. If a class attribute is found that is auser-defined function object, it is transformed into an instance methodobject whose__self__ attribute is the instance. Static method andclass method objects are also transformed; see above under “Classes”. SeesectionImplementing Descriptors for another way in which attributes of a classretrieved via its instances may differ from the objects actually stored inthe class’s__dict__. If no class attribute is found, and theobject’s class has a__getattr__() method, that is called to satisfythe lookup.

Attribute assignments and deletions update the instance’s dictionary, never aclass’s dictionary. If the class has a__setattr__() or__delattr__() method, this is called instead of updating the instancedictionary directly.

Class instances can pretend to be numbers, sequences, or mappings if they havemethods with certain special names. See sectionSpecial method names.

3.2.12.I/O objects (also known as file objects)¶

Afile object represents an open file. Various shortcuts areavailable to create file objects: theopen() built-in function, andalsoos.popen(),os.fdopen(), and themakefile() method of socket objects (and perhaps byother functions or methods provided by extension modules).

The objectssys.stdin,sys.stdout andsys.stderr areinitialized to file objects corresponding to the interpreter’s standardinput, output and error streams; they are all open in text mode andtherefore follow the interface defined by theio.TextIOBaseabstract class.

3.2.13.Internal types¶

A few types used internally by the interpreter are exposed to the user. Theirdefinitions may change with future versions of the interpreter, but they arementioned here for completeness.

3.3.1.Basic customization¶

object.__new__(cls[,...])¶

Called to create a new instance of classcls.__new__() is a staticmethod (special-cased so you need not declare it as such) that takes the classof which an instance was requested as its first argument. The remainingarguments are those passed to the object constructor expression (the call to theclass). The return value of__new__() should be the new object instance(usually an instance ofcls).

Typical implementations create a new instance of the class by invoking thesuperclass’s__new__() method usingsuper().__new__(cls[,...])with appropriate arguments and then modifying the newly created instanceas necessary before returning it.

If__new__() is invoked during object construction and it returns aninstance ofcls, then the new instance’s__init__() methodwill be invoked like__init__(self[,...]), whereself is the new instanceand the remaining arguments are the same as were passed to the object constructor.

If__new__() does not return an instance ofcls, then the new instance’s__init__() method will not be invoked.

__new__() is intended mainly to allow subclasses of immutable types (likeint, str, or tuple) to customize instance creation. It is also commonlyoverridden in custom metaclasses in order to customize class creation.

object.__init__(self[,...])¶

Called after the instance has been created (by__new__()), but beforeit is returned to the caller. The arguments are those passed to theclass constructor expression. If a base class has an__init__()method, the derived class’s__init__() method, if any, must explicitlycall it to ensure proper initialization of the base class part of theinstance; for example:super().__init__([args...]).

Because__new__() and__init__() work together in constructingobjects (__new__() to create it, and__init__() to customize it),no non-None value may be returned by__init__(); doing so willcause aTypeError to be raised at runtime.

object.__del__(self)¶

Called when the instance is about to be destroyed. This is also called afinalizer or (improperly) a destructor. If a base class has a__del__() method, the derived class’s__del__() method,if any, must explicitly call it to ensure proper deletion of the baseclass part of the instance.

It is possible (though not recommended!) for the__del__() methodto postpone destruction of the instance by creating a new reference toit. This is called objectresurrection. It is implementation-dependentwhether__del__() is called a second time when a resurrected objectis about to be destroyed; the currentCPython implementationonly calls it once.

It is not guaranteed that__del__() methods are called for objectsthat still exist when the interpreter exits.weakref.finalize provides a straightforward way to registera cleanup function to be called when an object is garbage collected.

Note

delx doesn’t directly callx.__del__() — the former decrementsthe reference count forx by one, and the latter is only called whenx’s reference count reaches zero.

CPython implementation detail: It is possible for a reference cycle to prevent the reference countof an object from going to zero. In this case, the cycle will belater detected and deleted by thecyclic garbage collector. A common cause of reference cycles is whenan exception has been caught in a local variable. The frame’slocals then reference the exception, which references its owntraceback, which references the locals of all frames caught in thetraceback.

See also

Documentation for thegc module.

Warning

Due to the precarious circumstances under which__del__() methods areinvoked, exceptions that occur during their execution are ignored, and a warningis printed tosys.stderr instead. In particular:

• __del__() can be invoked when arbitrary code is being executed,including from any arbitrary thread. If__del__() needs to takea lock or invoke any other blocking resource, it may deadlock asthe resource may already be taken by the code that gets interruptedto execute__del__().

• __del__() can be executed during interpreter shutdown. As aconsequence, the global variables it needs to access (including othermodules) may already have been deleted or set toNone. Pythonguarantees that globals whose name begins with a single underscoreare deleted from their module before other globals are deleted; ifno other references to such globals exist, this may help in assuringthat imported modules are still available at the time when the__del__() method is called.

object.__repr__(self)¶

Called by therepr() built-in function to compute the “official” stringrepresentation of an object. If at all possible, this should look like avalid Python expression that could be used to recreate an object with thesame value (given an appropriate environment). If this is not possible, astring of the form<...someusefuldescription...> should be returned.The return value must be a string object. If a class defines__repr__()but not__str__(), then__repr__() is also used when an“informal” string representation of instances of that class is required.

This is typically used for debugging, so it is important that the representationis information-rich and unambiguous. A default implementation is provided by theobject class itself.

object.__str__(self)¶

Called bystr(object), the default__format__() implementation,and the built-in functionprint(), to compute the “informal” or nicelyprintable string representation of an object. The return value must be astr object.

This method differs fromobject.__repr__() in that there is noexpectation that__str__() return a valid Python expression: a moreconvenient or concise representation can be used.

The default implementation defined by the built-in typeobjectcallsobject.__repr__().

object.__bytes__(self)¶

Called bybytes to compute a byte-string representationof an object. This should return abytes object. Theobjectclass itself does not provide this method.

object.__format__(self,format_spec)¶

Called by theformat() built-in function,and by extension, evaluation offormatted string literals and thestr.format() method, to produce a “formatted”string representation of an object. Theformat_spec argument isa string that contains a description of the formatting options desired.The interpretation of theformat_spec argument is up to the typeimplementing__format__(), however most classes will eitherdelegate formatting to one of the built-in types, or use a similarformatting option syntax.

SeeFormat Specification Mini-Language for a description of the standard formatting syntax.

The return value must be a string object.

The default implementation by theobject class should be givenan emptyformat_spec string. It delegates to__str__().

Changed in version 3.4:The __format__ method ofobject itself raises aTypeErrorif passed any non-empty string.

Changed in version 3.7:object.__format__(x,'') is now equivalent tostr(x) ratherthanformat(str(x),'').

object.__lt__(self,other)¶

object.__le__(self,other)¶

object.__eq__(self,other)¶

object.__ne__(self,other)¶

object.__gt__(self,other)¶

object.__ge__(self,other)¶

These are the so-called “rich comparison” methods. The correspondence betweenoperator symbols and method names is as follows:x<y callsx.__lt__(y),x<=y callsx.__le__(y),x==y callsx.__eq__(y),x!=y callsx.__ne__(y),x>y callsx.__gt__(y), andx>=y callsx.__ge__(y).

A rich comparison method may return the singletonNotImplemented if it doesnot implement the operation for a given pair of arguments. By convention,False andTrue are returned for a successful comparison. However, thesemethods can return any value, so if the comparison operator is used in a Booleancontext (e.g., in the condition of anif statement), Python will callbool() on the value to determine if the result is true or false.

By default,object implements__eq__() by usingis, returningNotImplemented in the case of a false comparison:TrueifxisyelseNotImplemented. For__ne__(), by default itdelegates to__eq__() and inverts the result unless it isNotImplemented. There are no other implied relationships among thecomparison operators or default implementations; for example, the truth of(x<yorx==y) does not implyx<=y. To automatically generate orderingoperations from a single root operation, seefunctools.total_ordering().

By default, theobject class provides implementations consistentwithValue comparisons: equality compares according toobject identity, and order comparisons raiseTypeError. Each defaultmethod may generate these results directly, but may also returnNotImplemented.

See the paragraph on__hash__() forsome important notes on creatinghashable objects which supportcustom comparison operations and are usable as dictionary keys.

There are no swapped-argument versions of these methods (to be used when theleft argument does not support the operation but the right argument does);rather,__lt__() and__gt__() are each other’s reflection,__le__() and__ge__() are each other’s reflection, and__eq__() and__ne__() are their own reflection.If the operands are of different types, and the right operand’s type isa direct or indirect subclass of the left operand’s type,the reflected method of the right operand has priority, otherwisethe left operand’s method has priority. Virtual subclassing isnot considered.

When no appropriate method returns any value other thanNotImplemented, the== and!= operators will fall back tois andisnot, respectively.

object.__hash__(self)¶

Called by built-in functionhash() and for operations on members ofhashed collections includingset,frozenset, anddict. The__hash__() method should return an integer. The only requiredproperty is that objects which compare equal have the same hash value; it isadvised to mix together the hash values of the components of the object thatalso play a part in comparison of objects by packing them into a tuple andhashing the tuple. Example:

def__hash__(self):returnhash((self.name,self.nick,self.color))

Note

hash() truncates the value returned from an object’s custom__hash__() method to the size of aPy_ssize_t. This istypically 8 bytes on 64-bit builds and 4 bytes on 32-bit builds. If anobject’s__hash__() must interoperate on builds of different bitsizes, be sure to check the width on all supported builds. An easy wayto do this is withpython-c"importsys;print(sys.hash_info.width)".

If a class does not define an__eq__() method it should not define a__hash__() operation either; if it defines__eq__() but not__hash__(), its instances will not be usable as items in hashablecollections. If a class defines mutable objects and implements an__eq__() method, it should not implement__hash__(), since theimplementation ofhashable collections requires that a key’s hash value isimmutable (if the object’s hash value changes, it will be in the wrong hashbucket).

User-defined classes have__eq__() and__hash__() methodsby default (inherited from theobject class); with them, all objects compareunequal (except with themselves) andx.__hash__() returns an appropriatevalue such thatx==y implies both thatxisy andhash(x)==hash(y).

A class that overrides__eq__() and does not define__hash__()will have its__hash__() implicitly set toNone. When the__hash__() method of a class isNone, instances of the class willraise an appropriateTypeError when a program attempts to retrievetheir hash value, and will also be correctly identified as unhashable whencheckingisinstance(obj,collections.abc.Hashable).

If a class that overrides__eq__() needs to retain the implementationof__hash__() from a parent class, the interpreter must be told thisexplicitly by setting__hash__=<ParentClass>.__hash__.

If a class that does not override__eq__() wishes to suppress hashsupport, it should include__hash__=None in the class definition.A class which defines its own__hash__() that explicitly raisesaTypeError would be incorrectly identified as hashable byanisinstance(obj,collections.abc.Hashable) call.

Note

By default, the__hash__() values of str and bytes objects are“salted” with an unpredictable random value. Although theyremain constant within an individual Python process, they are notpredictable between repeated invocations of Python.

This is intended to provide protection against a denial-of-service causedby carefully chosen inputs that exploit the worst case performance of adict insertion,O(n²) complexity. Seehttp://ocert.org/advisories/ocert-2011-003.html for details.

Changing hash values affects the iteration order of sets.Python has never made guarantees about this ordering(and it typically varies between 32-bit and 64-bit builds).

See alsoPYTHONHASHSEED.

Changed in version 3.3:Hash randomization is enabled by default.

object.__bool__(self)¶

Called to implement truth value testing and the built-in operationbool(); should returnFalse orTrue. When this method is notdefined,__len__() is called, if it is defined, and the object isconsidered true if its result is nonzero. If a class defines neither__len__() nor__bool__() (which is true of theobjectclass itself), all its instances are considered true.

3.3.2.Customizing attribute access¶

The following methods can be defined to customize the meaning of attributeaccess (use of, assignment to, or deletion ofx.name) for class instances.

object.__getattr__(self,name)¶

Called when the default attribute access fails with anAttributeError(either__getattribute__() raises anAttributeError becausename is not an instance attribute or an attribute in the class treeforself; or__get__() of aname property raisesAttributeError). This method should either return the (computed)attribute value or raise anAttributeError exception.Theobject class itself does not provide this method.

Note that if the attribute is found through the normal mechanism,__getattr__() is not called. (This is an intentional asymmetry between__getattr__() and__setattr__().) This is done both for efficiencyreasons and because otherwise__getattr__() would have no way to accessother attributes of the instance. Note that at least for instance variables,you can take total control by not inserting any values in the instance attributedictionary (but instead inserting them in another object). See the__getattribute__() method below for a way to actually get total controlover attribute access.

object.__getattribute__(self,name)¶

Called unconditionally to implement attribute accesses for instances of theclass. If the class also defines__getattr__(), the latter will not becalled unless__getattribute__() either calls it explicitly or raises anAttributeError. This method should return the (computed) attribute valueor raise anAttributeError exception. In order to avoid infiniterecursion in this method, its implementation should always call the base classmethod with the same name to access any attributes it needs, for example,object.__getattribute__(self,name).

Note

This method may still be bypassed when looking up special methods as theresult of implicit invocation via language syntax orbuilt-in functions.SeeSpecial method lookup.

For certain sensitive attribute accesses, raises anauditing eventobject.__getattr__ with argumentsobj andname.

object.__setattr__(self,name,value)¶

Called when an attribute assignment is attempted. This is called instead ofthe normal mechanism (i.e. store the value in the instance dictionary).name is the attribute name,value is the value to be assigned to it.

If__setattr__() wants to assign to an instance attribute, it shouldcall the base class method with the same name, for example,object.__setattr__(self,name,value).

For certain sensitive attribute assignments, raises anauditing eventobject.__setattr__ with argumentsobj,name,value.

object.__delattr__(self,name)¶

Like__setattr__() but for attribute deletion instead of assignment. Thisshould only be implemented ifdelobj.name is meaningful for the object.

For certain sensitive attribute deletions, raises anauditing eventobject.__delattr__ with argumentsobj andname.

object.__dir__(self)¶

Called whendir() is called on the object. An iterable must bereturned.dir() converts the returned iterable to a list and sorts it.

importsysfromtypesimportModuleTypeclassVerboseModule(ModuleType):def__repr__(self):returnf'Verbose{self.__name__}'def__setattr__(self,attr,value):print(f'Setting{attr}...')super().__setattr__(attr,value)sys.modules[__name__].__class__=VerboseModule

3.3.3.Customizing class creation¶

Whenever a class inherits from another class,__init_subclass__() iscalled on the parent class. This way, it is possible to write classes whichchange the behavior of subclasses. This is closely related to classdecorators, but where class decorators only affect the specific class they’reapplied to,__init_subclass__ solely applies to future subclasses of theclass defining the method.

classmethodobject.__init_subclass__(cls)¶

This method is called whenever the containing class is subclassed.cls is then the new subclass. If defined as a normal instance method,this method is implicitly converted to a class method.

Keyword arguments which are given to a new class are passed tothe parent class’s__init_subclass__. For compatibility withother classes using__init_subclass__, one should take out theneeded keyword arguments and pass the others over to the baseclass, as in:

classPhilosopher:def__init_subclass__(cls,/,default_name,**kwargs):super().__init_subclass__(**kwargs)cls.default_name=default_nameclassAustralianPhilosopher(Philosopher,default_name="Bruce"):pass

The default implementationobject.__init_subclass__ doesnothing, but raises an error if it is called with any arguments.

Note

The metaclass hintmetaclass is consumed by the rest of the typemachinery, and is never passed to__init_subclass__ implementations.The actual metaclass (rather than the explicit hint) can be accessed astype(cls).

Added in version 3.6.

When a class is created,type.__new__() scans the class variablesand makes callbacks to those with a__set_name__() hook.

object.__set_name__(self,owner,name)¶

Automatically called at the time the owning classowner iscreated. The object has been assigned toname in that class:

classA:x=C()# Automatically calls: x.__set_name__(A, 'x')

If the class variable is assigned after the class is created,__set_name__() will not be called automatically.If needed,__set_name__() can be called directly:

classA:passc=C()A.x=c# The hook is not calledc.__set_name__(A,'x')# Manually invoke the hook

SeeCreating the class object for more details.

Added in version 3.6.

classMeta(type):passclassMyClass(metaclass=Meta):passclassMySubclass(MyClass):pass

3.3.4.Customizing instance and subclass checks¶

The following methods are used to override the default behavior of theisinstance() andissubclass() built-in functions.

In particular, the metaclassabc.ABCMeta implements these methods inorder to allow the addition of Abstract Base Classes (ABCs) as “virtual baseclasses” to any class or type (including built-in types), including otherABCs.

type.__instancecheck__(self,instance)¶

Return true ifinstance should be considered a (direct or indirect)instance ofclass. If defined, called to implementisinstance(instance,class).

type.__subclasscheck__(self,subclass)¶

Return true ifsubclass should be considered a (direct or indirect)subclass ofclass. If defined, called to implementissubclass(subclass,class).

Note that these methods are looked up on the type (metaclass) of a class. Theycannot be defined as class methods in the actual class. This is consistent withthe lookup of special methods that are called on instances, only in thiscase the instance is itself a class.

3.3.5.Emulating generic types¶

When usingtype annotations, it is often useful toparameterize ageneric type using Python’s square-brackets notation.For example, the annotationlist[int] might be used to signify alist in which all the elements are of typeint.

A class cangenerally only be parameterized if it defines the specialclass method__class_getitem__().

classmethodobject.__class_getitem__(cls,key)¶

Return an object representing the specialization of a generic classby type arguments found inkey.

When defined on a class,__class_getitem__() is automatically a classmethod. As such, there is no need for it to be decorated with@classmethod when it is defined.

frominspectimportisclassdefsubscribe(obj,x):"""Return the result of the expression 'obj[x]'"""class_of_obj=type(obj)# If the class of obj defines __getitem__,# call class_of_obj.__getitem__(obj, x)ifhasattr(class_of_obj,'__getitem__'):returnclass_of_obj.__getitem__(obj,x)# Else, if obj is a class and defines __class_getitem__,# call obj.__class_getitem__(x)elifisclass(obj)andhasattr(obj,'__class_getitem__'):returnobj.__class_getitem__(x)# Else, raise an exceptionelse:raiseTypeError(f"'{class_of_obj.__name__}' object is not subscriptable")

>>># list has class "type" as its metaclass, like most classes:>>>type(list)<class 'type'>>>>type(dict)==type(list)==type(tuple)==type(str)==type(bytes)True>>># "list[int]" calls "list.__class_getitem__(int)">>>list[int]list[int]>>># list.__class_getitem__ returns a GenericAlias object:>>>type(list[int])<class 'types.GenericAlias'>

>>>fromenumimportEnum>>>classMenu(Enum):..."""A breakfast menu"""...SPAM='spam'...BACON='bacon'...>>># Enum classes have a custom metaclass:>>>type(Menu)<class 'enum.EnumMeta'>>>># EnumMeta defines __getitem__,>>># so __class_getitem__ is not called,>>># and the result is not a GenericAlias object:>>>Menu['SPAM']<Menu.SPAM: 'spam'>>>>type(Menu['SPAM'])<enum 'Menu'>

3.3.6.Emulating callable objects¶

object.__call__(self[,args...])¶

Called when the instance is “called” as a function; if this method is defined,x(arg1,arg2,...) roughly translates totype(x).__call__(x,arg1,...).Theobject class itself does not provide this method.

3.3.7.Emulating container types¶

The following methods can be defined to implement container objects. None of themare provided by theobject class itself. Containers usually aresequences (such aslists ortuples) ormappings (likedictionaries),but can represent other containers as well. The first set of methods is usedeither to emulate a sequence or to emulate a mapping; the difference is that fora sequence, the allowable keys should be the integersk for which0<=k<N whereN is the length of the sequence, orslice objects, which define arange of items. It is also recommended that mappings provide the methodskeys(),values(),items(),get(),clear(),setdefault(),pop(),popitem(),copy(), andupdate() behaving similar to those for Python’s standarddictionaryobjects. Thecollections.abc module provides aMutableMappingabstract base class to help create those methods from a base set of__getitem__(),__setitem__(),__delitem__(), andkeys().Mutable sequences should provide methodsappend(),count(),index(),extend(),insert(),pop(),remove(),reverse() andsort(), like Python standardlistobjects. Finally,sequence types should implement addition (meaning concatenation) andmultiplication (meaning repetition) by defining the methods__add__(),__radd__(),__iadd__(),__mul__(),__rmul__() and__imul__()described below; they should not define other numericaloperators. It is recommended that both mappings and sequences implement the__contains__() method to allow efficient use of theinoperator; formappings,in should search the mapping’s keys; for sequences, it shouldsearch through the values. It is further recommended that both mappings andsequences implement the__iter__() method to allow efficient iterationthrough the container; for mappings,__iter__() should iteratethrough the object’s keys; for sequences, it should iterate through the values.

object.__len__(self)¶

Called to implement the built-in functionlen(). Should return the lengthof the object, an integer>= 0. Also, an object that doesn’t define a__bool__() method and whose__len__() method returns zero isconsidered to be false in a Boolean context.

CPython implementation detail: In CPython, the length is required to be at mostsys.maxsize.If the length is larger thansys.maxsize some features (such aslen()) may raiseOverflowError. To prevent raisingOverflowError by truth value testing, an object must define a__bool__() method.

object.__length_hint__(self)¶

Called to implementoperator.length_hint(). Should return an estimatedlength for the object (which may be greater or less than the actual length).The length must be an integer>= 0. The return value may also beNotImplemented, which is treated the same as if the__length_hint__ method didn’t exist at all. This method is purely anoptimization and is never required for correctness.

Added in version 3.4.

a[1:2]=b

a[slice(1,2,None)]=b

object.__getitem__(self,key)¶

Called to implement evaluation ofself[key]. Forsequence types,the accepted keys should be integers. Optionally, they may supportslice objects as well. Negative index support is also optional.Ifkey isof an inappropriate type,TypeError may be raised; ifkey is a valueoutside the set of indexes for the sequence (after any specialinterpretation of negative values),IndexError should be raised. Formapping types, ifkey is missing (not in the container),KeyError should be raised.

Note

for loops expect that anIndexError will be raised forillegal indexes to allow proper detection of the end of the sequence.

Note

Whensubscripting aclass, the specialclass method__class_getitem__() may be called instead of__getitem__(). See__class_getitem__ versus __getitem__ for moredetails.

object.__setitem__(self,key,value)¶

Called to implement assignment toself[key]. Same note as for__getitem__(). This should only be implemented for mappings if theobjects support changes to the values for keys, or if new keys can be added, orfor sequences if elements can be replaced. The same exceptions should be raisedfor improperkey values as for the__getitem__() method.

object.__delitem__(self,key)¶

Called to implement deletion ofself[key]. Same note as for__getitem__(). This should only be implemented for mappings if theobjects support removal of keys, or for sequences if elements can be removedfrom the sequence. The same exceptions should be raised for improperkeyvalues as for the__getitem__() method.

object.__missing__(self,key)¶

Called bydict.__getitem__() to implementself[key] for dict subclasseswhen key is not in the dictionary.

object.__iter__(self)¶

This method is called when aniterator is required for a container.This method should return a new iterator object that can iterate over all theobjects in the container. For mappings, it should iterate over the keys ofthe container.

object.__reversed__(self)¶

Called (if present) by thereversed() built-in to implementreverse iteration. It should return a new iterator object that iteratesover all the objects in the container in reverse order.

If the__reversed__() method is not provided, thereversed()built-in will fall back to using the sequence protocol (__len__() and__getitem__()). Objects that support the sequence protocol shouldonly provide__reversed__() if they can provide an implementationthat is more efficient than the one provided byreversed().

The membership test operators (in andnotin) are normallyimplemented as an iteration through a container. However, container objects cansupply the following special method with a more efficient implementation, whichalso does not require the object be iterable.

object.__contains__(self,item)¶

Called to implement membership test operators. Should return true ifitemis inself, false otherwise. For mapping objects, this should consider thekeys of the mapping rather than the values or the key-item pairs.

For objects that don’t define__contains__(), the membership test firsttries iteration via__iter__(), then the old sequence iterationprotocol via__getitem__(), seethis section in the languagereference.

3.3.8.Emulating numeric types¶

The following methods can be defined to emulate numeric objects. Methodscorresponding to operations that are not supported by the particular kind ofnumber implemented (e.g., bitwise operations for non-integral numbers) should beleft undefined.

object.__add__(self,other)¶

object.__sub__(self,other)¶

object.__mul__(self,other)¶

object.__matmul__(self,other)¶

object.__truediv__(self,other)¶

object.__floordiv__(self,other)¶

object.__mod__(self,other)¶

object.__divmod__(self,other)¶

object.__pow__(self,other[,modulo])¶

object.__lshift__(self,other)¶

object.__rshift__(self,other)¶

object.__and__(self,other)¶

object.__xor__(self,other)¶

object.__or__(self,other)¶

These methods are called to implement the binary arithmetic operations(+,-,*,@,/,//,%,divmod(),pow(),**,<<,>>,&,^,|). For instance, toevaluate the expressionx+y, wherex is an instance of a class thathas an__add__() method,type(x).__add__(x,y) is called. The__divmod__() method should be the equivalent to using__floordiv__() and__mod__(); it should not be related to__truediv__(). Note that__pow__() should be defined to acceptan optional third argument if the ternary version of the built-inpow()function is to be supported.

If one of those methods does not support the operation with the suppliedarguments, it should returnNotImplemented.

object.__radd__(self,other)¶

object.__rsub__(self,other)¶

object.__rmul__(self,other)¶

object.__rmatmul__(self,other)¶

object.__rtruediv__(self,other)¶

object.__rfloordiv__(self,other)¶

object.__rmod__(self,other)¶

object.__rdivmod__(self,other)¶

object.__rpow__(self,other[,modulo])¶

object.__rlshift__(self,other)¶

object.__rrshift__(self,other)¶

object.__rand__(self,other)¶

object.__rxor__(self,other)¶

object.__ror__(self,other)¶

These methods are called to implement the binary arithmetic operations(+,-,*,@,/,//,%,divmod(),pow(),**,<<,>>,&,^,|) with reflected(swapped) operands. These functions are only called if the left operand doesnot support the corresponding operation[3] and the operands are of differenttypes.[4] For instance, to evaluate the expressionx-y, wherey isan instance of a class that has an__rsub__() method,type(y).__rsub__(y,x) is called iftype(x).__sub__(x,y) returnsNotImplemented.

Note that ternarypow() will not try calling__rpow__() (thecoercion rules would become too complicated).

Note

If the right operand’s type is a subclass of the left operand’s type andthat subclass provides a different implementation of the reflected methodfor the operation, this method will be called before the left operand’snon-reflected method. This behavior allows subclasses to override theirancestors’ operations.

object.__iadd__(self,other)¶

object.__isub__(self,other)¶

object.__imul__(self,other)¶

object.__imatmul__(self,other)¶

object.__itruediv__(self,other)¶

object.__ifloordiv__(self,other)¶

object.__imod__(self,other)¶

object.__ipow__(self,other[,modulo])¶

object.__ilshift__(self,other)¶

object.__irshift__(self,other)¶

object.__iand__(self,other)¶

object.__ixor__(self,other)¶

object.__ior__(self,other)¶

These methods are called to implement the augmented arithmetic assignments(+=,-=,*=,@=,/=,//=,%=,**=,<<=,>>=,&=,^=,|=). These methods should attempt to do theoperation in-place (modifyingself) and return the result (which could be,but does not have to be,self). If a specific method is not defined, or ifthat method returnsNotImplemented, theaugmented assignment falls back to the normal methods. For instance, ifxis an instance of a class with an__iadd__() method,x+=y isequivalent tox=x.__iadd__(y) . If__iadd__() does not exist, or ifx.__iadd__(y)returnsNotImplemented,x.__add__(y) andy.__radd__(x) are considered, as with the evaluation ofx+y. Incertain situations, augmented assignment can result in unexpected errors (seeWhy does a_tuple[i] += [‘item’] raise an exception when the addition works?), but this behavior is in factpart of the data model.

object.__neg__(self)¶

object.__pos__(self)¶

object.__abs__(self)¶

object.__invert__(self)¶

Called to implement the unary arithmetic operations (-,+,abs()and~).

object.__complex__(self)¶

object.__int__(self)¶

object.__float__(self)¶

Called to implement the built-in functionscomplex(),int() andfloat(). Should return a valueof the appropriate type.

object.__index__(self)¶

Called to implementoperator.index(), and whenever Python needs tolosslessly convert the numeric object to an integer object (such as inslicing, or in the built-inbin(),hex() andoct()functions). Presence of this method indicates that the numeric object isan integer type. Must return an integer.

If__int__(),__float__() and__complex__() are notdefined then corresponding built-in functionsint(),float()andcomplex() fall back to__index__().

object.__round__(self[,ndigits])¶

object.__trunc__(self)¶

object.__floor__(self)¶

object.__ceil__(self)¶

Called to implement the built-in functionround() andmathfunctionstrunc(),floor() andceil().Unlessndigits is passed to__round__() all these methods shouldreturn the value of the object truncated to anIntegral(typically anint).

The built-in functionint() falls back to__trunc__() if neither__int__() nor__index__() is defined.

Changed in version 3.11:The delegation ofint() to__trunc__() is deprecated.

3.3.9.With Statement Context Managers¶

Acontext manager is an object that defines the runtime context to beestablished when executing awith statement. The context managerhandles the entry into, and the exit from, the desired runtime context for theexecution of the block of code. Context managers are normally invoked using thewith statement (described in sectionThe with statement), but can also beused by directly invoking their methods.

Typical uses of context managers include saving and restoring various kinds ofglobal state, locking and unlocking resources, closing opened files, etc.

For more information on context managers, seeContext Manager Types.Theobject class itself does not provide the context manager methods.

object.__enter__(self)¶

Enter the runtime context related to this object. Thewith statementwill bind this method’s return value to the target(s) specified in theas clause of the statement, if any.

object.__exit__(self,exc_type,exc_value,traceback)¶

Exit the runtime context related to this object. The parameters describe theexception that caused the context to be exited. If the context was exitedwithout an exception, all three arguments will beNone.

If an exception is supplied, and the method wishes to suppress the exception(i.e., prevent it from being propagated), it should return a true value.Otherwise, the exception will be processed normally upon exit from this method.

Note that__exit__() methods should not reraise the passed-in exception;this is the caller’s responsibility.

3.3.10.Customizing positional arguments in class pattern matching¶

When using a class name in a pattern, positional arguments in the pattern are notallowed by default, i.e.caseMyClass(x,y) is typically invalid without specialsupport inMyClass. To be able to use that kind of pattern, the class needs todefine a__match_args__ attribute.

object.__match_args__¶

This class variable can be assigned a tuple of strings. When this class isused in a class pattern with positional arguments, each positional argument willbe converted into a keyword argument, using the corresponding value in__match_args__ as the keyword. The absence of this attribute is equivalent tosetting it to().

For example, ifMyClass.__match_args__ is("left","center","right") that meansthatcaseMyClass(x,y) is equivalent tocaseMyClass(left=x,center=y). Notethat the number of arguments in the pattern must be smaller than or equal to the numberof elements in__match_args__; if it is larger, the pattern match attempt will raiseaTypeError.

3.3.11.Emulating buffer types¶

Thebuffer protocol provides a way for Pythonobjects to expose efficient access to a low-level memory array. This protocolis implemented by builtin types such asbytes andmemoryview,and third-party libraries may define additional buffer types.

While buffer types are usually implemented in C, it is also possible toimplement the protocol in Python.

object.__buffer__(self,flags)¶

Called when a buffer is requested fromself (for example, by thememoryview constructor). Theflags argument is an integerrepresenting the kind of buffer requested, affecting for example whetherthe returned buffer is read-only or writable.inspect.BufferFlagsprovides a convenient way to interpret the flags. The method must returnamemoryview object.

object.__release_buffer__(self,buffer)¶

Called when a buffer is no longer needed. Thebuffer argument is amemoryview object that was previously returned by__buffer__(). The method must release any resources associatedwith the buffer. This method should returnNone.Buffer objects that do not need to perform any cleanup are not requiredto implement this method.

3.3.12.Special method lookup¶

For custom classes, implicit invocations of special methods are only guaranteedto work correctly if defined on an object’s type, not in the object’s instancedictionary. That behaviour is the reason why the following code raises anexception:

>>>classC:...pass...>>>c=C()>>>c.__len__=lambda:5>>>len(c)Traceback (most recent call last):  File"<stdin>", line1, in<module>TypeError:object of type 'C' has no len()

The rationale behind this behaviour lies with a number of special methods suchas__hash__() and__repr__() that are implementedby all objects,including type objects. If the implicit lookup of these methods used theconventional lookup process, they would fail when invoked on the type objectitself:

>>>1.__hash__()==hash(1)True>>>int.__hash__()==hash(int)Traceback (most recent call last):  File"<stdin>", line1, in<module>TypeError:descriptor '__hash__' of 'int' object needs an argument

Incorrectly attempting to invoke an unbound method of a class in this way issometimes referred to as ‘metaclass confusion’, and is avoided by bypassingthe instance when looking up special methods:

>>>type(1).__hash__(1)==hash(1)True>>>type(int).__hash__(int)==hash(int)True

In addition to bypassing any instance attributes in the interest ofcorrectness, implicit special method lookup generally also bypasses the__getattribute__() method even of the object’s metaclass:

>>>classMeta(type):...def__getattribute__(*args):...print("Metaclass getattribute invoked")...returntype.__getattribute__(*args)...>>>classC(object,metaclass=Meta):...def__len__(self):...return10...def__getattribute__(*args):...print("Class getattribute invoked")...returnobject.__getattribute__(*args)...>>>c=C()>>>c.__len__()# Explicit lookup via instanceClass getattribute invoked10>>>type(c).__len__(c)# Explicit lookup via typeMetaclass getattribute invoked10>>>len(c)# Implicit lookup10

Bypassing the__getattribute__() machinery in this fashionprovides significant scope for speed optimisations within theinterpreter, at the cost of some flexibility in the handling ofspecial methods (the special methodmust be set on the classobject itself in order to be consistently invoked by the interpreter).

3.4.1.Awaitable Objects¶

Anawaitable object generally implements an__await__() method.Coroutine objects returned fromasyncdef functionsare awaitable.

object.__await__(self)¶

Must return aniterator. Should be used to implementawaitable objects. For instance,asyncio.Future implementsthis method to be compatible with theawait expression.Theobject class itself is not awaitable and does not providethis method.

Note

The language doesn’t place any restriction on the type or value of theobjects yielded by the iterator returned by__await__, as this isspecific to the implementation of the asynchronous execution framework(e.g.asyncio) that will be managing theawaitable object.

3.4.2.Coroutine Objects¶

Coroutine objects areawaitable objects.A coroutine’s execution can be controlled by calling__await__() anditerating over the result. When the coroutine has finished executing andreturns, the iterator raisesStopIteration, and the exception’svalue attribute holds the return value. If thecoroutine raises an exception, it is propagated by the iterator. Coroutinesshould not directly raise unhandledStopIteration exceptions.

Coroutines also have the methods listed below, which are analogous tothose of generators (seeGenerator-iterator methods). However, unlikegenerators, coroutines do not directly support iteration.

coroutine.send(value)¶

Starts or resumes execution of the coroutine. Ifvalue isNone,this is equivalent to advancing the iterator returned by__await__(). Ifvalue is notNone, this method delegatesto thesend() method of the iterator that causedthe coroutine to suspend. The result (return value,StopIteration, or other exception) is the same as wheniterating over the__await__() return value, described above.

coroutine.throw(value)¶

coroutine.throw(type[,value[,traceback]])

Raises the specified exception in the coroutine. This method delegatesto thethrow() method of the iterator that causedthe coroutine to suspend, if it has such a method. Otherwise,the exception is raised at the suspension point. The result(return value,StopIteration, or other exception) is the same aswhen iterating over the__await__() return value, describedabove. If the exception is not caught in the coroutine, it propagatesback to the caller.

Changed in version 3.12:The second signature (type[, value[, traceback]]) is deprecated andmay be removed in a future version of Python.

coroutine.close()¶

Causes the coroutine to clean itself up and exit. If the coroutineis suspended, this method first delegates to theclose()method of the iterator that caused the coroutine to suspend, if ithas such a method. Then it raisesGeneratorExit at thesuspension point, causing the coroutine to immediately clean itself up.Finally, the coroutine is marked as having finished executing, even ifit was never started.

Coroutine objects are automatically closed using the above process whenthey are about to be destroyed.

3.4.3.Asynchronous Iterators¶

Anasynchronous iterator can call asynchronous code inits__anext__ method.

Asynchronous iterators can be used in anasyncfor statement.

Theobject class itself does not provide these methods.

object.__aiter__(self)¶

Must return anasynchronous iterator object.

object.__anext__(self)¶

Must return anawaitable resulting in a next value of the iterator. Shouldraise aStopAsyncIteration error when the iteration is over.

An example of an asynchronous iterable object:

classReader:asyncdefreadline(self):...def__aiter__(self):returnselfasyncdef__anext__(self):val=awaitself.readline()ifval==b'':raiseStopAsyncIterationreturnval

3.4.4.Asynchronous Context Managers¶

Anasynchronous context manager is acontext manager that is able tosuspend execution in its__aenter__ and__aexit__ methods.

Asynchronous context managers can be used in anasyncwith statement.

Theobject class itself does not provide these methods.

object.__aenter__(self)¶

Semantically similar to__enter__(), the onlydifference being that it must return anawaitable.

object.__aexit__(self,exc_type,exc_value,traceback)¶

Semantically similar to__exit__(), the onlydifference being that it must return anawaitable.

An example of an asynchronous context manager class:

classAsyncContextManager:asyncdef__aenter__(self):awaitlog('entering context')asyncdef__aexit__(self,exc_type,exc,tb):awaitlog('exiting context')

Footnotes

Itis possible in some cases to change an object’s type, under certaincontrolled conditions. It generally isn’t a good idea though, since it canlead to some very strange behaviour if it is handled incorrectly.

The__hash__(),__iter__(),__reversed__(),__contains__(),__class_getitem__() and__fspath__()methods have special handling for this. Otherswill still raise aTypeError, but may do so by relying onthe behavior thatNone is not callable.

“Does not support” here means that the class has no such method, orthe method returnsNotImplemented. Do not set the method toNone if you want to force fallback to the right operand’s reflectedmethod—that will instead have the opposite effect of explicitlyblocking such fallback.

For operands of the same type, it is assumed that if the non-reflectedmethod – such as__add__() – fails then the overalloperation is notsupported, which is why the reflected method is not called.