Module Contents¶

EnumType

Thetype for Enum and its subclasses.

Enum

Base class for creating enumerated constants.

IntEnum

Base class for creating enumerated constants that are alsosubclasses ofint. (Notes)

StrEnum

Base class for creating enumerated constants that are alsosubclasses ofstr. (Notes)

Flag

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

IntFlag

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

ReprEnum

Used byIntEnum,StrEnum, andIntFlagto keep thestr() of the mixed-in type.

EnumCheck

An enumeration with the valuesCONTINUOUS,NAMED_FLAGS, andUNIQUE, for use withverify() to ensure various constraintsare met by a given enumeration.

FlagBoundary

An enumeration with the valuesSTRICT,CONFORM,EJECT, andKEEP which allows for more fine-grained control over how invalid valuesare dealt with in an enumeration.

EnumDict

A subclass ofdict for use when subclassingEnumType.

auto

Instances are replaced with an appropriate value for Enum members.StrEnum defaults to the lower-cased version of the member name,while other Enums default to 1 and increase from there.

property()

AllowsEnum members to have attributes without conflicting withmember names. Thevalue andname attributes are implemented thisway.

unique()

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

verify()

Enum class decorator that checks user-selectable constraints on anenumeration.

member()

Makeobj a member. Can be used as a decorator.

nonmember()

Do not makeobj a member. Can be used as a decorator.

global_enum()

Modify thestr() andrepr() of an enumto show its members as belonging to the module instead of its class,and export the enum members to the global namespace.

show_flag_values()

Return a list of all power-of-two integers contained in a flag.

Data Types¶

classenum.EnumType¶

EnumType is themetaclass forenum enumerations. It is possibleto subclassEnumType – seeSubclassing EnumTypefor details.

EnumType is responsible for setting the correct__repr__(),__str__(),__format__(), and__reduce__() methods on thefinalenum, as well as creating the enum members, properly handlingduplicates, providing iteration over the enum class, etc.

__call__(cls,value,names=None,*,module=None,qualname=None,type=None,start=1,boundary=None)¶

This method is called in two different ways:

• to look up an existing member:

  cls:

  The enum class being called.

  value:

  The value to lookup.

• to use thecls enum to create a new enum (only if the existing enumdoes not have any members):

  cls:

  The enum class being called.

  value:

  The name of the new Enum to create.

  names:

  The names/values of the members for the new Enum.

  module:

  The name of the module the new Enum is created in.

  qualname:

  The actual location in the module where this Enum can be found.

  type:

  A mix-in type for the new Enum.

  start:

  The first integer value for the Enum (used byauto).

  boundary:

  How to handle out-of-range values from bit operations (Flag only).

__contains__(cls,member)¶

ReturnsTrue if member belongs to thecls:

>>>some_var=Color.RED>>>some_varinColorTrue>>>Color.RED.valueinColorTrue

Changed in version 3.12:Before Python 3.12, aTypeError is raised if anon-Enum-member is used in a containment check.

__dir__(cls)¶

Returns['__class__','__doc__','__members__','__module__'] and thenames of the members incls:

>>>dir(Color)['BLUE', 'GREEN', 'RED', '__class__', '__contains__', '__doc__', '__getitem__', '__init_subclass__', '__iter__', '__len__', '__members__', '__module__', '__name__', '__qualname__']

__getitem__(cls,name)¶

Returns the Enum member incls matchingname, or raises aKeyError:

>>>Color['BLUE']<Color.BLUE: 3>

__iter__(cls)¶

Returns each member incls in definition order:

>>>list(Color)[<Color.RED: 1>, <Color.GREEN: 2>, <Color.BLUE: 3>]

__len__(cls)¶

Returns the number of member incls:

>>>len(Color)3

__members__¶

Returns a mapping of every enum name to its member, including aliases

__reversed__(cls)¶

Returns each member incls in reverse definition order:

>>>list(reversed(Color))[<Color.BLUE: 3>, <Color.GREEN: 2>, <Color.RED: 1>]

_add_alias_()¶

Adds a new name as an alias to an existing member. Raises aNameError if the name is already assigned to a different member.

_add_value_alias_()¶

Adds a new value as an alias to an existing member. Raises aValueError if the value is already linked with a different member.

Added in version 3.11:Before 3.11EnumType was calledEnumMeta, which is still available as an alias.

classenum.Enum¶

Enum is the base class for allenum enumerations.

name¶

The name used to define theEnum member:

>>>Color.BLUE.name'BLUE'

value¶

The value given to theEnum member:

>>>Color.RED.value1

Value of the member, can be set in__new__().

Note

Enum member values

Member values can be anything:int,str, etc. Ifthe exact value is unimportant you may useauto instances and anappropriate value will be chosen for you. Seeauto for thedetails.

While mutable/unhashable values, such asdict,list ora mutabledataclass, can be used, they will have aquadratic performance impact during creation relative to thetotal number of mutable/unhashable values in the enum.

_name_¶

Name of the member.

_value_¶

Value of the member, can be set in__new__().

_order_¶

No longer used, kept for backward compatibility.(class attribute, removed during class creation).

_ignore_¶

_ignore_ is only used during creation and is removed from theenumeration once creation is complete.

_ignore_ is a list of names that will not become members, and whosenames will also be removed from the completed enumeration. SeeTimePeriod for an example.

__dir__(self)¶

Returns['__class__','__doc__','__module__','name','value'] andany public methods defined onself.__class__:

>>>fromdatetimeimportdate>>>classWeekday(Enum):...MONDAY=1...TUESDAY=2...WEDNESDAY=3...THURSDAY=4...FRIDAY=5...SATURDAY=6...SUNDAY=7...@classmethod...deftoday(cls):...print('today is%s'%cls(date.today().isoweekday()).name)...>>>dir(Weekday.SATURDAY)['__class__', '__doc__', '__eq__', '__hash__', '__module__', 'name', 'today', 'value']

_generate_next_value_(name,start,count,last_values)¶

name:

The name of the member being defined (e.g. ‘RED’).

start:

The start value for the Enum; the default is 1.

count:

The number of members currently defined, not including this one.

last_values:

A list of the previous values.

Astaticmethod that is used to determine the next value returned byauto:

>>>fromenumimportauto>>>classPowersOfThree(Enum):...@staticmethod...def_generate_next_value_(name,start,count,last_values):...return3**(count+1)...FIRST=auto()...SECOND=auto()...>>>PowersOfThree.SECOND.value9

__init__(self,*args,**kwds)¶

By default, does nothing. If multiple values are given in the memberassignment, those values become separate arguments to__init__; e.g.

>>>fromenumimportEnum>>>classWeekday(Enum):...MONDAY=1,'Mon'

Weekday.__init__() would be called asWeekday.__init__(self,1,'Mon')

__init_subclass__(cls,**kwds)¶

Aclassmethod that is used to further configure subsequent subclasses.By default, does nothing.

_missing_(cls,value)¶

Aclassmethod for looking up values not found incls. By default itdoes nothing, but can be overridden to implement custom search behavior:

>>>fromenumimportStrEnum>>>classBuild(StrEnum):...DEBUG=auto()...OPTIMIZED=auto()...@classmethod...def_missing_(cls,value):...value=value.lower()...formemberincls:...ifmember.value==value:...returnmember...returnNone...>>>Build.DEBUG.value'debug'>>>Build('deBUG')<Build.DEBUG: 'debug'>

__new__(cls,*args,**kwds)¶

By default, doesn’t exist. If specified, either in the enum classdefinition or in a mixin class (such asint), all values givenin the member assignment will be passed; e.g.

>>>fromenumimportEnum>>>classMyIntEnum(int,Enum):...TWENTYSIX='1a',16

results in the callint('1a',16) and a value of26 for the member.

Note

When writing a custom__new__, do not usesuper().__new__ –call the appropriate__new__ instead.

__repr__(self)¶

Returns the string used forrepr() calls. By default, returns theEnum name, member name, and value, but can be overridden:

>>>classOtherStyle(Enum):...ALTERNATE=auto()...OTHER=auto()...SOMETHING_ELSE=auto()...def__repr__(self):...cls_name=self.__class__.__name__...returnf'{cls_name}.{self.name}'...>>>OtherStyle.ALTERNATE,str(OtherStyle.ALTERNATE),f"{OtherStyle.ALTERNATE}"(OtherStyle.ALTERNATE, 'OtherStyle.ALTERNATE', 'OtherStyle.ALTERNATE')

__str__(self)¶

Returns the string used forstr() calls. By default, returns theEnum name and member name, but can be overridden:

>>>classOtherStyle(Enum):...ALTERNATE=auto()...OTHER=auto()...SOMETHING_ELSE=auto()...def__str__(self):...returnf'{self.name}'...>>>OtherStyle.ALTERNATE,str(OtherStyle.ALTERNATE),f"{OtherStyle.ALTERNATE}"(<OtherStyle.ALTERNATE: 1>, 'ALTERNATE', 'ALTERNATE')

__format__(self)¶

Returns the string used forformat() andf-string calls. By default,returns__str__() return value, but can be overridden:

>>>classOtherStyle(Enum):...ALTERNATE=auto()...OTHER=auto()...SOMETHING_ELSE=auto()...def__format__(self,spec):...returnf'{self.name}'...>>>OtherStyle.ALTERNATE,str(OtherStyle.ALTERNATE),f"{OtherStyle.ALTERNATE}"(<OtherStyle.ALTERNATE: 1>, 'OtherStyle.ALTERNATE', 'ALTERNATE')

Note

Usingauto withEnum results in integers of increasing value,starting with1.

Changed in version 3.12:AddedDataclass support

classenum.IntEnum¶

IntEnum is the same asEnum, but its members are also integers and can beused anywhere that an integer can be used. If any integer operation is performedwith anIntEnum member, the resulting value loses its enumeration status.

>>>fromenumimportIntEnum>>>classNumber(IntEnum):...ONE=1...TWO=2...THREE=3...>>>Number.THREE<Number.THREE: 3>>>>Number.ONE+Number.TWO3>>>Number.THREE+58>>>Number.THREE==3True

Note

Usingauto withIntEnum results in integers of increasingvalue, starting with1.

Changed in version 3.11:__str__() is nowint.__str__() tobetter support thereplacement of existing constants use-case.__format__() was alreadyint.__format__() for that same reason.

classenum.StrEnum¶

StrEnum is the same asEnum, but its members are also strings and can be usedin most of the same places that a string can be used. The result of any stringoperation performed on or with aStrEnum member is not part of the enumeration.

Note

There are places in the stdlib that check for an exactstrinstead of astr subclass (i.e.type(unknown)==strinstead ofisinstance(unknown,str)), and in those locations youwill need to usestr(StrEnum.member).

Note

Usingauto withStrEnum results in the lower-cased membername as the value.

Note

__str__() isstr.__str__() to better support thereplacement of existing constants use-case.__format__() is likewisestr.__format__() for that same reason.

Added in version 3.11.

classenum.Flag¶

Flag is the same asEnum, but its members support the bitwiseoperators& (AND),| (OR),^ (XOR), and~ (INVERT);the results of those operations are (aliases of) members of the enumeration.

__contains__(self,value)¶

ReturnsTrue if value is in self:

>>>fromenumimportFlag,auto>>>classColor(Flag):...RED=auto()...GREEN=auto()...BLUE=auto()...>>>purple=Color.RED|Color.BLUE>>>white=Color.RED|Color.GREEN|Color.BLUE>>>Color.GREENinpurpleFalse>>>Color.GREENinwhiteTrue>>>purpleinwhiteTrue>>>whiteinpurpleFalse

__iter__(self):

Returns all contained non-alias members:

>>>list(Color.RED)[<Color.RED: 1>]>>>list(purple)[<Color.RED: 1>, <Color.BLUE: 4>]

Added in version 3.11.

__len__(self):

Returns number of members in flag:

>>>len(Color.GREEN)1>>>len(white)3

Added in version 3.11.

__bool__(self):

ReturnsTrue if any members in flag,False otherwise:

>>>bool(Color.GREEN)True>>>bool(white)True>>>black=Color(0)>>>bool(black)False

__or__(self,other)¶

Returns current flag binary or’ed with other:

>>>Color.RED|Color.GREEN<Color.RED|GREEN: 3>

__and__(self,other)¶

Returns current flag binary and’ed with other:

>>>purple&white<Color.RED|BLUE: 5>>>>purple&Color.GREEN<Color: 0>

__xor__(self,other)¶

Returns current flag binary xor’ed with other:

>>>purple^white<Color.GREEN: 2>>>>purple^Color.GREEN<Color.RED|GREEN|BLUE: 7>

__invert__(self):

Returns all the flags intype(self) that are not inself:

>>>~white<Color: 0>>>>~purple<Color.GREEN: 2>>>>~Color.RED<Color.GREEN|BLUE: 6>

_numeric_repr_()¶

Function used to format any remaining unnamed numeric values. Default isthe value’s repr; common choices arehex() andoct().

Note

Usingauto withFlag results in integers that are powersof two, starting with1.

Changed in version 3.11:Therepr() of zero-valued flags has changed. Itis now::

>>>Color(0)<Color: 0>

classenum.IntFlag¶

IntFlag is the same asFlag, but its members are also integers and can beused anywhere that an integer can be used.

>>>fromenumimportIntFlag,auto>>>classColor(IntFlag):...RED=auto()...GREEN=auto()...BLUE=auto()...>>>Color.RED&2<Color: 0>>>>Color.RED|2<Color.RED|GREEN: 3>

If any integer operation is performed with anIntFlag member, the result isnot anIntFlag:

>>>Color.RED+23

If aFlag operation is performed with anIntFlag member and:

• the result is a validIntFlag: anIntFlag is returned

• the result is not a validIntFlag: the result depends on theFlagBoundary setting

Therepr() of unnamed zero-valued flags has changed. It is now:

>>>Color(0)<Color: 0>

Note

Usingauto withIntFlag results in integers that are powersof two, starting with1.

Changed in version 3.11:__str__() is nowint.__str__() to better support thereplacement of existing constants use-case.__format__() wasalreadyint.__format__() for that same reason.

Inversion of anIntFlag now returns a positive value that is theunion of all flags not in the given flag, rather than a negative value.This matches the existingFlag behavior.

classenum.ReprEnum¶

ReprEnum uses therepr() ofEnum,but thestr() of the mixed-in data type:

• int.__str__() forIntEnum andIntFlag

• str.__str__() forStrEnum

Inherit fromReprEnum to keep thestr() /format()of the mixed-in data type instead of using theEnum-defaultstr().

Added in version 3.11.

classenum.EnumCheck¶

EnumCheck contains the options used by theverify() decorator to ensurevarious constraints; failed constraints result in aValueError.

UNIQUE¶

Ensure that each value has only one name:

>>>fromenumimportEnum,verify,UNIQUE>>>@verify(UNIQUE)...classColor(Enum):...RED=1...GREEN=2...BLUE=3...CRIMSON=1Traceback (most recent call last):...ValueError:aliases found in <enum 'Color'>: CRIMSON -> RED

CONTINUOUS¶

Ensure that there are no missing values between the lowest-valued memberand the highest-valued member:

>>>fromenumimportEnum,verify,CONTINUOUS>>>@verify(CONTINUOUS)...classColor(Enum):...RED=1...GREEN=2...BLUE=5Traceback (most recent call last):...ValueError:invalid enum 'Color': missing values 3, 4

NAMED_FLAGS¶

Ensure that any flag groups/masks contain only named flags – useful whenvalues are specified instead of being generated byauto():

>>>fromenumimportFlag,verify,NAMED_FLAGS>>>@verify(NAMED_FLAGS)...classColor(Flag):...RED=1...GREEN=2...BLUE=4...WHITE=15...NEON=31Traceback (most recent call last):...ValueError:invalid Flag 'Color': aliases WHITE and NEON are missing combined values of 0x18 [use enum.show_flag_values(value) for details]

Note

CONTINUOUS and NAMED_FLAGS are designed to work with integer-valued members.

Added in version 3.11.

classenum.FlagBoundary¶

FlagBoundary controls how out-of-range values are handled inFlag and itssubclasses.

STRICT¶

Out-of-range values cause aValueError to be raised. This is thedefault forFlag:

>>>fromenumimportFlag,STRICT,auto>>>classStrictFlag(Flag,boundary=STRICT):...RED=auto()...GREEN=auto()...BLUE=auto()...>>>StrictFlag(2**2+2**4)Traceback (most recent call last):...ValueError:<flag 'StrictFlag'> invalid value 20    given 0b0 10100  allowed 0b0 00111

CONFORM¶

Out-of-range values have invalid values removed, leaving a validFlagvalue:

>>>fromenumimportFlag,CONFORM,auto>>>classConformFlag(Flag,boundary=CONFORM):...RED=auto()...GREEN=auto()...BLUE=auto()...>>>ConformFlag(2**2+2**4)<ConformFlag.BLUE: 4>

EJECT¶

Out-of-range values lose theirFlag membership and revert toint.

>>>fromenumimportFlag,EJECT,auto>>>classEjectFlag(Flag,boundary=EJECT):...RED=auto()...GREEN=auto()...BLUE=auto()...>>>EjectFlag(2**2+2**4)20

KEEP¶

Out-of-range values are kept, and theFlag membership is kept.This is the default forIntFlag:

>>>fromenumimportFlag,KEEP,auto>>>classKeepFlag(Flag,boundary=KEEP):...RED=auto()...GREEN=auto()...BLUE=auto()...>>>KeepFlag(2**2+2**4)<KeepFlag.BLUE|16: 20>

Added in version 3.11.

classenum.EnumDict¶

EnumDict is a subclass ofdict that is used as the namespacefor defining enum classes (seePreparing the class namespace).It is exposed to allow subclasses ofEnumType with advancedbehavior like having multiple values per member.It should be called with the name of the enum class being created, otherwiseprivate names and internal classes will not be handled correctly.

Note that only theMutableMapping interface(__setitem__() andupdate()) is overridden.It may be possible to bypass the checks using otherdictoperations like|=.

member_names¶

A list of member names.

Added in version 3.13.

Utilities and Decorators¶

classenum.auto¶

auto can be used in place of a value. If used, theEnum machinery willcall anEnum’s_generate_next_value_() to get an appropriate value.ForEnum andIntEnum that appropriate value will be the last value plusone; forFlag andIntFlag it will be the first power-of-two greaterthan the highest value; forStrEnum it will be the lower-cased version ofthe member’s name. Care must be taken if mixingauto() with manuallyspecified values.

auto instances are only resolved when at the top level of an assignment:

• FIRST=auto() will work (auto() is replaced with1);

• SECOND=auto(),-2 will work (auto is replaced with2, so2,-2 isused to create theSECOND enum member;

• THREE=[auto(),-3] willnot work (<autoinstance>,-3 is used tocreate theTHREE enum member)

Changed in version 3.11.1:In prior versions,auto() had to be the only thingon the assignment line to work properly.

_generate_next_value_ can be overridden to customize the values used byauto.

Note

in 3.13 the default_generate_next_value_ will always returnthe highest member value incremented by 1, and will fail if anymember is an incompatible type.

@enum.property¶

A decorator similar to the built-inproperty, but specifically forenumerations. It allows member attributes to have the same names as membersthemselves.

Note

theproperty and the member must be defined in separate classes;for example, thevalue andname attributes are defined in theEnum class, andEnum subclasses can define members with thenamesvalue andname.

Added in version 3.11.

@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

@enum.verify¶

Aclass decorator specifically for enumerations. Members fromEnumCheck are used to specify which constraints should be checkedon the decorated enumeration.

Added in version 3.11.

@enum.member¶

A decorator for use in enums: its target will become a member.

Added in version 3.11.

@enum.nonmember¶

A decorator for use in enums: its target will not become a member.

Added in version 3.11.

@enum.global_enum¶

A decorator to change thestr() andrepr() of an enumto show its members as belonging to the module instead of its class.Should only be used when the enum members are exportedto the module global namespace (seere.RegexFlag for an example).

Added in version 3.11.

enum.show_flag_values(value)¶

Return a list of all power-of-two integers contained in a flagvalue.

Added in version 3.11.

Notes¶

IntEnum,StrEnum, andIntFlag

These three enum types are designed to be drop-in replacements for existinginteger- and string-based values; as such, they have extra limitations:

• __str__ uses the value and not the name of the enum member

• __format__, because it uses__str__, will also use the value ofthe enum member instead of its name

If you do not need/want those limitations, you can either create your ownbase class by mixing in theint orstr type yourself:

>>>fromenumimportEnum>>>classMyIntEnum(int,Enum):...pass

or you can reassign the appropriatestr(), etc., in your enum:

>>>fromenumimportEnum,IntEnum>>>classMyIntEnum(IntEnum):...__str__=Enum.__str__