Module Contents¶

This module defines four enumeration classes that can be used to define uniquesets of names and values:Enum,IntEnum,Flag, andIntFlag. It also defines one decorator,unique(), and onehelper,auto.

classenum.Enum¶

Base class for creating enumerated constants. See sectionFunctional API for an alternate construction syntax.

classenum.IntEnum¶

Base class for creating enumerated constants that are alsosubclasses ofint.

classenum.IntFlag¶

Base class for creating enumerated constants that can be combined usingthe bitwise operators without losing theirIntFlag membership.IntFlag members are also subclasses ofint.

classenum.Flag¶

Base class for creating enumerated constants that can be combined usingthe bitwise operations without losing theirFlag membership.

enum.unique()

Enum class decorator that ensures only one name is bound to any one value.

classenum.auto¶

Instances are replaced with an appropriate value for Enum members. Initial value starts at 1.

Creating an Enum¶

Enumerations are created using theclass syntax, which makes themeasy to read and write. An alternative creation method is described inFunctional API. To define an enumeration, subclassEnum asfollows:

>>>fromenumimportEnum>>>classColor(Enum):...RED=1...GREEN=2...BLUE=3...

Enumeration members have human readable string representations:

>>>print(Color.RED)Color.RED

…while theirrepr has more information:

>>>print(repr(Color.RED))<Color.RED: 1>

Thetype of an enumeration member is the enumeration it belongs to:

>>>type(Color.RED)<enum 'Color'>>>>isinstance(Color.GREEN,Color)True>>>

Enum members also have a property that contains just their item name:

>>>print(Color.RED.name)RED

Enumerations support iteration, in definition order:

>>>classShake(Enum):...VANILLA=7...CHOCOLATE=4...COOKIES=9...MINT=3...>>>forshakeinShake:...print(shake)...Shake.VANILLAShake.CHOCOLATEShake.COOKIESShake.MINT

Enumeration members are hashable, so they can be used in dictionaries and sets:

>>>apples={}>>>apples[Color.RED]='red delicious'>>>apples[Color.GREEN]='granny smith'>>>apples=={Color.RED:'red delicious',Color.GREEN:'granny smith'}True

Programmatic access to enumeration members and their attributes¶

Sometimes it’s useful to access members in enumerations programmatically (i.e.situations whereColor.RED won’t do because the exact color is not knownat program-writing time).Enum allows such access:

>>>Color(1)<Color.RED: 1>>>>Color(3)<Color.BLUE: 3>

If you want to access enum members byname, use item access:

>>>Color['RED']<Color.RED: 1>>>>Color['GREEN']<Color.GREEN: 2>

If you have an enum member and need itsname orvalue:

>>>member=Color.RED>>>member.name'RED'>>>member.value1

Duplicating enum members and values¶

Having two enum members with the same name is invalid:

>>>classShape(Enum):...SQUARE=2...SQUARE=3...Traceback (most recent call last):...TypeError:Attempted to reuse key: 'SQUARE'

However, two enum members are allowed to have the same value. Given two membersA and B with the same value (and A defined first), B is an alias to A. By-valuelookup of the value of A and B will return A. By-name lookup of B will alsoreturn A:

>>>classShape(Enum):...SQUARE=2...DIAMOND=1...CIRCLE=3...ALIAS_FOR_SQUARE=2...>>>Shape.SQUARE<Shape.SQUARE: 2>>>>Shape.ALIAS_FOR_SQUARE<Shape.SQUARE: 2>>>>Shape(2)<Shape.SQUARE: 2>

Ensuring unique enumeration values¶

By default, enumerations allow multiple names as aliases for the same value.When this behavior isn’t desired, the following decorator can be used toensure each value is used only once in the enumeration:

@enum.unique¶

Aclass decorator specifically for enumerations. It searches anenumeration’s__members__ gathering any aliases it finds; if any arefoundValueError is raised with the details:

>>>fromenumimportEnum,unique>>>@unique...classMistake(Enum):...ONE=1...TWO=2...THREE=3...FOUR=3...Traceback (most recent call last):...ValueError:duplicate values found in <enum 'Mistake'>: FOUR -> THREE

Using automatic values¶

If the exact value is unimportant you can useauto:

>>>fromenumimportEnum,auto>>>classColor(Enum):...RED=auto()...BLUE=auto()...GREEN=auto()...>>>list(Color)[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

The values are chosen by_generate_next_value_(), which can beoverridden:

>>>classAutoName(Enum):...def_generate_next_value_(name,start,count,last_values):...returnname...>>>classOrdinal(AutoName):...NORTH=auto()...SOUTH=auto()...EAST=auto()...WEST=auto()...>>>list(Ordinal)[<Ordinal.NORTH: 'NORTH'>, <Ordinal.SOUTH: 'SOUTH'>, <Ordinal.EAST: 'EAST'>, <Ordinal.WEST: 'WEST'>]

Iteration¶

Iterating over the members of an enum does not provide the aliases:

>>>list(Shape)[<Shape.SQUARE: 2>, <Shape.DIAMOND: 1>, <Shape.CIRCLE: 3>]

The special attribute__members__ is a read-only ordered mapping of namesto members. It includes all names defined in the enumeration, including thealiases:

>>>forname,memberinShape.__members__.items():...name,member...('SQUARE', <Shape.SQUARE: 2>)('DIAMOND', <Shape.DIAMOND: 1>)('CIRCLE', <Shape.CIRCLE: 3>)('ALIAS_FOR_SQUARE', <Shape.SQUARE: 2>)

The__members__ attribute can be used for detailed programmatic access tothe enumeration members. For example, finding all the aliases:

>>>[nameforname,memberinShape.__members__.items()ifmember.name!=name]['ALIAS_FOR_SQUARE']

Comparisons¶

Enumeration members are compared by identity:

>>>Color.REDisColor.REDTrue>>>Color.REDisColor.BLUEFalse>>>Color.REDisnotColor.BLUETrue

Ordered comparisons between enumeration values arenot supported. Enummembers are not integers (but seeIntEnum below):

>>>Color.RED<Color.BLUETraceback (most recent call last):  File"<stdin>", line1, in<module>TypeError:'<' not supported between instances of 'Color' and 'Color'

Equality comparisons are defined though:

>>>Color.BLUE==Color.REDFalse>>>Color.BLUE!=Color.REDTrue>>>Color.BLUE==Color.BLUETrue

Comparisons against non-enumeration values will always compare not equal(again,IntEnum was explicitly designed to behave differently, seebelow):

>>>Color.BLUE==2False

Allowed members and attributes of enumerations¶

The examples above use integers for enumeration values. Using integers isshort and handy (and provided by default by theFunctional API), but notstrictly enforced. In the vast majority of use-cases, one doesn’t care whatthe actual value of an enumeration is. But if the valueis important,enumerations can have arbitrary values.

Enumerations are Python classes, and can have methods and special methods asusual. If we have this enumeration:

>>>classMood(Enum):...FUNKY=1...HAPPY=3......defdescribe(self):...# self is the member here...returnself.name,self.value......def__str__(self):...return'my custom str!{0}'.format(self.value)......@classmethod...deffavorite_mood(cls):...# cls here is the enumeration...returncls.HAPPY...

Then:

>>>Mood.favorite_mood()<Mood.HAPPY: 3>>>>Mood.HAPPY.describe()('HAPPY', 3)>>>str(Mood.FUNKY)'my custom str! 1'

The rules for what is allowed are as follows: names that start and end witha single underscore are reserved by enum and cannot be used; all otherattributes defined within an enumeration will become members of thisenumeration, with the exception of special methods (__str__(),__add__(), etc.), descriptors (methods are also descriptors), andvariable names listed in_ignore_.

Note: if your enumeration defines__new__() and/or__init__() thenwhatever value(s) were given to the enum member will be passed into thosemethods. SeePlanet for an example.

Restricted Enum subclassing¶

A newEnum class must have one base Enum class, up to one concretedata type, and as manyobject-based mixin classes as needed. Theorder of these base classes is:

classEnumName([mix-in,...,][data-type,]base-enum):pass

Also, subclassing an enumeration is allowed only if the enumeration does not defineany members. So this is forbidden:

>>>classMoreColor(Color):...PINK=17...Traceback (most recent call last):...TypeError:Cannot extend enumerations

But this is allowed:

>>>classFoo(Enum):...defsome_behavior(self):...pass...>>>classBar(Foo):...HAPPY=1...SAD=2...

Allowing subclassing of enums that define members would lead to a violation ofsome important invariants of types and instances. On the other hand, it makessense to allow sharing some common behavior between a group of enumerations.(SeeOrderedEnum for an example.)

Pickling¶

Enumerations can be pickled and unpickled:

>>>fromtest.test_enumimportFruit>>>frompickleimportdumps,loads>>>Fruit.TOMATOisloads(dumps(Fruit.TOMATO))True

The usual restrictions for pickling apply: picklable enums must be defined inthe top level of a module, since unpickling requires them to be importablefrom that module.

It is possible to modify how Enum members are pickled/unpickled by defining__reduce_ex__() in the enumeration class.

Functional API¶

TheEnum class is callable, providing the following functional API:

>>>Animal=Enum('Animal','ANT BEE CAT DOG')>>>Animal<enum 'Animal'>>>>Animal.ANT<Animal.ANT: 1>>>>Animal.ANT.value1>>>list(Animal)[<Animal.ANT: 1>, <Animal.BEE: 2>, <Animal.CAT: 3>, <Animal.DOG: 4>]

The semantics of this API resemblenamedtuple. The firstargument of the call toEnum is the name of the enumeration.

The second argument is thesource of enumeration member names. It can be awhitespace-separated string of names, a sequence of names, a sequence of2-tuples with key/value pairs, or a mapping (e.g. dictionary) of names tovalues. The last two options enable assigning arbitrary values toenumerations; the others auto-assign increasing integers starting with 1 (usethestart parameter to specify a different starting value). Anew class derived fromEnum is returned. In other words, the aboveassignment toAnimal is equivalent to:

>>>classAnimal(Enum):...ANT=1...BEE=2...CAT=3...DOG=4...

The reason for defaulting to1 as the starting number and not0 isthat0 isFalse in a boolean sense, but enum members all evaluatetoTrue.

Pickling enums created with the functional API can be tricky as frame stackimplementation details are used to try and figure out which module theenumeration is being created in (e.g. it will fail if you use a utilityfunction in separate module, and also may not work on IronPython or Jython).The solution is to specify the module name explicitly as follows:

>>>Animal=Enum('Animal','ANT BEE CAT DOG',module=__name__)

The new pickle protocol 4 also, in some circumstances, relies on__qualname__ being set to the location where pickle will be ableto find the class. For example, if the class was made available in classSomeData in the global scope:

>>>Animal=Enum('Animal','ANT BEE CAT DOG',qualname='SomeData.Animal')

The complete signature is:

Enum(value='NewEnumName',names=<...>,*,module='...',qualname='...',type=<mixed-inclass>,start=1)

value

What the new Enum class will record as its name.

names

The Enum members. This can be a whitespace or comma separated string(values will start at 1 unless otherwise specified):

'RED GREEN BLUE'|'RED,GREEN,BLUE'|'RED, GREEN, BLUE'

or an iterator of names:

['RED','GREEN','BLUE']

or an iterator of (name, value) pairs:

[('CYAN',4),('MAGENTA',5),('YELLOW',6)]

or a mapping:

{'CHARTREUSE':7,'SEA_GREEN':11,'ROSEMARY':42}

module

name of module where new Enum class can be found.

qualname

where in module new Enum class can be found.

type

type to mix in to new Enum class.

start

number to start counting at if only names are passed in.

Derived Enumerations¶

>>>fromenumimportIntEnum>>>classShape(IntEnum):...CIRCLE=1...SQUARE=2...>>>classRequest(IntEnum):...POST=1...GET=2...>>>Shape==1False>>>Shape.CIRCLE==1True>>>Shape.CIRCLE==Request.POSTTrue

>>>classShape(IntEnum):...CIRCLE=1...SQUARE=2...>>>classColor(Enum):...RED=1...GREEN=2...>>>Shape.CIRCLE==Color.REDFalse

>>>int(Shape.CIRCLE)1>>>['a','b','c'][Shape.CIRCLE]'b'>>>[iforiinrange(Shape.SQUARE)][0, 1]

>>>fromenumimportIntFlag>>>classPerm(IntFlag):...R=4...W=2...X=1...>>>Perm.R|Perm.W<Perm.R|W: 6>>>>Perm.R+Perm.W6>>>RW=Perm.R|Perm.W>>>Perm.RinRWTrue

>>>classPerm(IntFlag):...R=4...W=2...X=1...RWX=7>>>Perm.RWX<Perm.RWX: 7>>>>~Perm.RWX<Perm.-8: -8>

>>>Perm.R&Perm.X<Perm.0: 0>>>>bool(Perm.R&Perm.X)False

>>>Perm.X|8<Perm.8|X: 9>

>>>fromenumimportFlag,auto>>>classColor(Flag):...RED=auto()...BLUE=auto()...GREEN=auto()...>>>Color.RED&Color.GREEN<Color.0: 0>>>>bool(Color.RED&Color.GREEN)False

>>>classColor(Flag):...RED=auto()...BLUE=auto()...GREEN=auto()...WHITE=RED|BLUE|GREEN...>>>Color.WHITE<Color.WHITE: 7>

>>>classColor(Flag):...BLACK=0...RED=auto()...BLUE=auto()...GREEN=auto()...>>>Color.BLACK<Color.BLACK: 0>>>>bool(Color.BLACK)False

classIntEnum(int,Enum):pass

When to use__new__() vs.__init__()¶

__new__() must be used whenever you want to customize the actual value oftheEnum member. Any other modifications may go in either__new__() or__init__(), with__init__() being preferred.

For example, if you want to pass several items to the constructor, but onlywant one of them to be the value:

>>>classCoordinate(bytes,Enum):..."""...    Coordinate with binary codes that can be indexed by the int code....    """...def__new__(cls,value,label,unit):...obj=bytes.__new__(cls,[value])...obj._value_=value...obj.label=label...obj.unit=unit...returnobj...PX=(0,'P.X','km')...PY=(1,'P.Y','km')...VX=(2,'V.X','km/s')...VY=(3,'V.Y','km/s')...>>>print(Coordinate['PY'])Coordinate.PY>>>print(Coordinate(3))Coordinate.VY

Interesting examples¶

WhileEnum,IntEnum,IntFlag, andFlag areexpected to cover the majority of use-cases, they cannot cover them all. Hereare recipes for some different types of enumerations that can be used directly,or as examples for creating one’s own.

>>>classNoValue(Enum):...def__repr__(self):...return'<%s.%s>'%(self.__class__.__name__,self.name)...

>>>classColor(NoValue):...RED=auto()...BLUE=auto()...GREEN=auto()...>>>Color.GREEN<Color.GREEN>

>>>classColor(NoValue):...RED=object()...GREEN=object()...BLUE=object()...>>>Color.GREEN<Color.GREEN>

>>>classColor(NoValue):...RED='stop'...GREEN='go'...BLUE='too fast!'...>>>Color.GREEN<Color.GREEN>>>>Color.GREEN.value'go'

>>>classAutoNumber(NoValue):...def__new__(cls):...value=len(cls.__members__)+1...obj=object.__new__(cls)...obj._value_=value...returnobj...>>>classColor(AutoNumber):...RED=()...GREEN=()...BLUE=()...>>>Color.GREEN<Color.GREEN>>>>Color.GREEN.value2

>>>classAutoNumber(NoValue):...def__new__(cls,*args):# this is the only change from above...value=len(cls.__members__)+1...obj=object.__new__(cls)...obj._value_=value...returnobj...

>>>classSwatch(AutoNumber):...def__init__(self,pantone='unknown'):...self.pantone=pantone...AUBURN='3497'...SEA_GREEN='1246'...BLEACHED_CORAL=()# New color, no Pantone code yet!...>>>Swatch.SEA_GREEN<Swatch.SEA_GREEN: 2>>>>Swatch.SEA_GREEN.pantone'1246'>>>Swatch.BLEACHED_CORAL.pantone'unknown'

>>>classOrderedEnum(Enum):...def__ge__(self,other):...ifself.__class__isother.__class__:...returnself.value>=other.value...returnNotImplemented...def__gt__(self,other):...ifself.__class__isother.__class__:...returnself.value>other.value...returnNotImplemented...def__le__(self,other):...ifself.__class__isother.__class__:...returnself.value<=other.value...returnNotImplemented...def__lt__(self,other):...ifself.__class__isother.__class__:...returnself.value<other.value...returnNotImplemented...>>>classGrade(OrderedEnum):...A=5...B=4...C=3...D=2...F=1...>>>Grade.C<Grade.ATrue

>>>classDuplicateFreeEnum(Enum):...def__init__(self,*args):...cls=self.__class__...ifany(self.value==e.valueforeincls):...a=self.name...e=cls(self.value).name...raiseValueError(..."aliases not allowed in DuplicateFreeEnum:%r -->%r"...%(a,e))...>>>classColor(DuplicateFreeEnum):...RED=1...GREEN=2...BLUE=3...GRENE=2...Traceback (most recent call last):...ValueError:aliases not allowed in DuplicateFreeEnum:  'GRENE' --> 'GREEN'

>>>classPlanet(Enum):...MERCURY=(3.303e+23,2.4397e6)...VENUS=(4.869e+24,6.0518e6)...EARTH=(5.976e+24,6.37814e6)...MARS=(6.421e+23,3.3972e6)...JUPITER=(1.9e+27,7.1492e7)...SATURN=(5.688e+26,6.0268e7)...URANUS=(8.686e+25,2.5559e7)...NEPTUNE=(1.024e+26,2.4746e7)...def__init__(self,mass,radius):...self.mass=mass# in kilograms...self.radius=radius# in meters...@property...defsurface_gravity(self):...# universal gravitational constant  (m3 kg-1 s-2)...G=6.67300E-11...returnG*self.mass/(self.radius*self.radius)...>>>Planet.EARTH.value(5.976e+24, 6378140.0)>>>Planet.EARTH.surface_gravity9.802652743337129

>>>fromdatetimeimporttimedelta>>>classPeriod(timedelta,Enum):..."different lengths of time"..._ignore_='Period i'...Period=vars()...foriinrange(367):...Period['day_%d'%i]=i...>>>list(Period)[:2][<Period.day_0: datetime.timedelta(0)>, <Period.day_1: datetime.timedelta(days=1)>]>>>list(Period)[-2:][<Period.day_365: datetime.timedelta(days=365)>, <Period.day_366: datetime.timedelta(days=366)>]

How are Enums different?¶

Enums have a custom metaclass that affects many aspects of both derived Enumclasses and their instances (members).

>>>classColor(Enum):..._order_='RED GREEN BLUE'...RED=1...BLUE=3...GREEN=2...Traceback (most recent call last):...TypeError:member order does not match _order_

>>>classFieldTypes(Enum):...name=0...value=1...size=2...>>>FieldTypes.value.size<FieldTypes.size: 2>>>>FieldTypes.size.value2

def__bool__(self):returnbool(self.value)

>>>dir(Planet)['EARTH', 'JUPITER', 'MARS', 'MERCURY', 'NEPTUNE', 'SATURN', 'URANUS', 'VENUS', '__class__', '__doc__', '__members__', '__module__']>>>dir(Planet.EARTH)['__class__', '__doc__', '__module__', 'name', 'surface_gravity', 'value']

>>>classColor(Flag):...RED=auto()...GREEN=auto()...BLUE=auto()...MAGENTA=RED|BLUE...YELLOW=RED|GREEN...CYAN=GREEN|BLUE...>>>Color(3)# named combination<Color.YELLOW: 3>>>>Color(7)# not named combination<Color.CYAN|MAGENTA|BLUE|YELLOW|GREEN|RED: 7>