{"id":2908,"date":"2021-11-14T07:55:40","date_gmt":"2021-11-14T07:55:40","guid":{"rendered":"https:\/\/www.pythontutorial.net\/?page_id=2908"},"modified":"2025-03-28T02:48:49","modified_gmt":"2025-03-28T02:48:49","slug":"python-enumeration","status":"publish","type":"page","link":"https:\/\/www.pythontutorial.net\/python-oop\/python-enumeration\/","title":{"rendered":"Python Enumeration"},"content":{"rendered":"\n

Summary<\/strong>: in this tutorial, you’ll learn about Python enumeration and how to use it effectively.<\/p>\n\n\n\n

Introduction to the Python Enumeration #<\/a><\/h2>\n\n\n\n

By definition, an enumeration is a set of members that have associated unique constant values. Enumeration is often called enum.<\/p>\n\n\n\n

Python provides you with the enum<\/code> module that contains the Enum<\/code> type for defining new enumerations. And you define a new enumeration type by subclassing<\/a> the Enum<\/code> class.<\/p>\n\n\n\n

The following example shows how to create an enumeration called Color<\/code>:<\/p>\n\n\n

from<\/span> enum import<\/span> Enum\n\n\nclass<\/span> Color<\/span>(Enum)<\/span>:<\/span>\n    RED = 1<\/span>\n    GREEN = 2<\/span>\n    BLUE = 3<\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
How it works.<\/p>\n\n\n\n
First, import the Enum<\/code> type from the enum<\/code> module:<\/p>\n\n\n
from<\/span> enum import<\/span> Enum<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Second, define the Color<\/code> class that inherits from the Enum<\/code> type:<\/p>\n\n\n
class<\/span> Color<\/span>(Enum)<\/span>:<\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Third, define the members of the Color<\/code> enumeration:<\/p>\n\n\n
RED = 1<\/span>\nGREEN = 2<\/span>\nBLUE = 3<\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Note that the enumeration’s members are constants. Therefore, their names are in uppercase letters by convention.<\/p>\n\n\n\n
In this example, the Color<\/code> is an enumeration. The RED<\/code>, GREEN<\/code>, and BLUE<\/code> are members of the Color<\/code> enumeration. They have associated values 1, 2, and 3. <\/p>\n\n\n\n
The type of a member is the enumeration to which it belongs. <\/p>\n\n\n\n
The following illustrates that the type of Color.RED<\/code> is the Color<\/code> enumeration:<\/p>\n\n\n
print(type(Color.RED))<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Output:<\/p>\n\n\n
<enum 'Color'<\/span>><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
The Color.RED<\/code> is also an instance of the Color<\/code> enumeration:<\/p>\n\n\n
print(isinstance(Color.RED, Color))<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Output:<\/p>\n\n\n
True<\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
And it has the name and value attributes:<\/p>\n\n\n
print(Color.RED.name)\nprint(Color.RED.value)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Output:<\/p>\n\n\n
RED\n1<\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Here’s the complete script:<\/p>\n\n\n
from enum import Enum\n\n\nclass Color(Enum):\n    RED = 1\n    GREEN = 2\n    BLUE = 3\n    \nprint(type(Color.RED))    \nprint(isinstance(Color.RED, Color))\n\nprint(Color.RED.name)\nprint(Color.RED.value)<\/code><\/span><\/pre>\n\n\n
Try it<\/a><\/p>\n\n\n\n
Membership and equality #<\/a><\/h2>\n\n\n\n
To check if a member is in an enumeration, you use the in<\/code> operator. For example:<\/p>\n\n\n
if<\/span> Color.RED in<\/span> Color:\n    print('Yes'<\/span>)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Output:<\/p>\n\n\n
Yes<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
To compare two members, you can use either is<\/code> or ==<\/code> operator. For example:<\/p>\n\n\n
if<\/span> Color.RED is<\/span> Color.BLUE:\n    print('red is blue'<\/span>)\nelse<\/span>:\n    print('red is not blue'<\/span>)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Output:<\/p>\n\n\n
red is<\/span> not<\/span> blue<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Note that a member and its associated value are not equal. The following example returns False<\/code>:<\/p>\n\n\n
if<\/span> Color.RED == 1<\/span>:\n    print('Color.RED == 1'<\/span>)\nelse<\/span>:\n    print('Color.RED != 1'<\/span>)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Output:<\/p>\n\n\n
Color.RED != 1<\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Here’s the complete script:<\/p>\n\n\n
from enum import Enum\n\n\nclass Color(Enum):\n    RED = 1\n    GREEN = 2\n    BLUE = 3\n    \nif Color.RED in Color:\n    print('Yes')\n    \nif Color.RED is Color.BLUE:\n    print('red is blue')\nelse:\n    print('red is not blue')    \n    \nif Color.RED == 1:\n    print('Color.RED == 1')\nelse:\n    print('Color.RED != 1')    <\/code><\/span><\/pre>\n\n\n
Enumeration members are hashable #<\/a><\/h2>\n\n\n\n
Enumeration members are always hashable<\/a>. It means that you can use the enumeration members as keys in a dictionary<\/a> or as elements of a Set<\/a>. <\/p>\n\n\n\n
The following example uses the members of the Color<\/code> enumeration in a dictionary:<\/p>\n\n\n
rgb = {\n    Color.RED: '#ff0000'<\/span>,\n    Color.GREEN: '#00ff00'<\/span>,\n    Color.BLUE: '#0000ff'<\/span>\n}<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Access an enumeration member by name and value #<\/a><\/h2>\n\n\n\n
The typical way to access an enumeration member is to use the dot notation (.) syntax as you have seen so far:<\/p>\n\n\n
Color.RED<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Because the Enum<\/code> implements the __getitem__<\/code> method, you can also use a square brackets []<\/code> syntax to get a member by its name.<\/p>\n\n\n\n
For example, the following uses the square brackets []<\/code> syntax to get the RED<\/code> member of the Color<\/code> enumeration by its name:<\/p>\n\n\n
print(Color['RED'<\/span>])<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Output:<\/p>\n\n\n
Color.RED<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
print(Color(1<\/span>))<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Output:<\/p>\n\n\n
Color.RED<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
The following expression returns True<\/code> because it accesses the same enumeration member using name and value:<\/p>\n\n\n
print(Color['RED'<\/span>] == Color(1<\/span>))<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Output:<\/p>\n\n\n
True<\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Iterate enumeration members #<\/a><\/h2>\n\n\n\n
Enumerations are iterables so you can iterate them using a for<\/code> loop. For example:<\/p>\n\n\n
from<\/span> enum import<\/span> Enum\n\n\nclass<\/span> Color<\/span>(Enum)<\/span>:<\/span>\n    RED = 1<\/span>\n    GREEN = 2<\/span>\n    BLUE = 3<\/span>\n    \nfor<\/span> color in<\/span> Color:\n    print(color) <\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Output:<\/p>\n\n\n
Color.RED\nColor.GREEN\nColor.BLUE<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Notice that the order of the members is the same as in the enumeration definition.<\/p>\n\n\n\n
Also, you can use the list()<\/code> function to return a list of members from an enumeration:<\/p>\n\n\n
from<\/span> enum import<\/span> Enum\n\n\nclass<\/span> Color<\/span>(Enum)<\/span>:<\/span>\n    RED = 1<\/span>\n    GREEN = 2<\/span>\n    BLUE = 3<\/span>\n    \nprint(list(Color))<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Output:<\/p>\n\n\n
[<Color.RED: 1<\/span>>, <Color.GREEN: 2<\/span>>, <Color.BLUE: 3<\/span>>]<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Enumerations are immutable #<\/a><\/h2>\n\n\n\n
Enumerations are immutable<\/a>. It means you cannot add or remove members once an enumeration is defined. And you also cannot change the member values.<\/p>\n\n\n\n
The following example attempts to assign a new member to the Color<\/code> enumeration and causes a TypeError<\/code>:<\/p>\n\n\n
Color['YELLOW'<\/span>] = 4<\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Error:<\/p>\n\n\n
TypeError: 'EnumMeta'<\/span> object does not<\/span> support item assignment<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
The following example attempts the change the value of the RED<\/code> member of the Color<\/code> enumeration and causes an AttributeError<\/code>:<\/p>\n\n\n
Color.RED.value = 100<\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Output:<\/p>\n\n\n
AttributeError: can't set attribute<\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Inherits from an enumeration #<\/a><\/h2>\n\n\n\n
An enumeration cannot be inherited unless it contains no members. The following example works fine because the Color<\/code> enumeration contains no members:<\/p>\n\n\n
class<\/span> Color<\/span>(Enum)<\/span>:<\/span>\n    pass<\/span>\n\n\nclass<\/span> RGB<\/span>(Color)<\/span>:<\/span>\n    RED = 1<\/span>\n    GREEN = 2<\/span>\n    BLUE = 3<\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
However, the following example won’t work because the RGB<\/code> enumeration has members:<\/p>\n\n\n
class<\/span> RGBA<\/span>(RGB)<\/span>:<\/span>\n    ALPHA = 4<\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Error:<\/p>\n\n\n
TypeError: Cannot extend enumerations<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Python enumeration example #<\/a><\/h2>\n\n\n\n
The following example defines an enumeration called ResponseStatus<\/code>:<\/p>\n\n\n
class<\/span> ResponseStatus<\/span>(Enum)<\/span>:<\/span>\n    PENDING = 'pending'<\/span>\n    FULFILLED = 'fulfilled'<\/span>\n    REJECTED = 'rejected'<\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Suppose you receive a response from an HTTP request with the following string:<\/p>\n\n\n
response = '''{\n    \"status\":\"fulfilled\"\n}'''<\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
And you want to look up the ResponseStatus<\/code> enumeration by the status<\/code>. To do that, you need to convert the response’s string to a dictionary and get the value of the status:<\/p>\n\n\n
import<\/span> json\n\ndata = json.loads(response)\nstatus = data['status'<\/span>]<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
And then you look up the member of the ResponseStatus<\/code> enumeration by the status’ value:<\/p>\n\n\n
print(ResponseStatus(status))<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Output:<\/p>\n\n\n
PromiseStatus.FULFILLED<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Here’s the complete program:<\/p>\n\n\n
from<\/span> enum import<\/span> Enum\nimport<\/span> json\n\n\nclass<\/span> ResponseStatus<\/span>(Enum)<\/span>:<\/span>\n    PENDING = 'pending'<\/span>\n    FULFILLED = 'fulfilled'<\/span>\n    REJECTED = 'rejected'<\/span>\n\n\nresponse = '''{\n    \"status\":\"fulfilled\"\n}'''<\/span>\n\ndata = json.loads(response)\nstatus = data['status'<\/span>]\n\nprint(ResponseStatus(status))<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
What if the status<\/code> is not one of the values of the ResponseStatus<\/code> members? then you’ll get an error. For example:<\/p>\n\n\n
from<\/span> enum import<\/span> Enum\nimport<\/span> json\n\n\nclass<\/span> ResponseStatus<\/span>(Enum)<\/span>:<\/span>\n    PENDING = 'pending'<\/span>\n    FULFILLED = 'fulfilled'<\/span>\n    REJECTED = 'rejected'<\/span>\n\n\nresponse = '''{\n    \"status\":\"ok\"\n}'''<\/span>\n\ndata = json.loads(response)\nstatus = data['status'<\/span>]\n\nprint(ResponseStatus(status))<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Error:<\/p>\n\n\n
ValueError: 'ok'<\/span> is<\/span> not<\/span> a valid ResponseStatus<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
from<\/span> enum import<\/span> Enum\nimport<\/span> json\n\n\nclass<\/span> ResponseStatus<\/span>(Enum)<\/span>:<\/span>\n    PENDING = 'pending'<\/span>\n    FULFILLED = 'fulfilled'<\/span>\n    REJECTED = 'rejected'<\/span>\n\n\nresponse = '''{\n    \"status\":\"ok\"\n}'''<\/span>\n\ndata = json.loads(response)\nstatus = data['status'<\/span>]\n\ntry<\/span>:\n    if<\/span> ResponseStatus(status) is<\/span> ResponseStatus.FULFILLED:\n        print('The request completed successfully'<\/span>)\nexcept<\/span> ValueError as<\/span> error:\n    print(error)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
'ok' is not a valid ResponseStatus<\/code><\/span>Code language:<\/span> plaintext<\/span> (<\/span>plaintext<\/span>)<\/span><\/small><\/pre>\n\n\n
Summary #<\/a><\/h2>\n\n\n\n
Try it<\/a><\/p>\n\n\n
To catch the exception, you can use the try…except<\/a> statement like the following:<\/p>\n\n\n
Try it<\/a><\/p>\n\n\n\n
Try it<\/a><\/p>\n\n\n\n
Try it<\/a><\/p>\n\n\n\n
Try it<\/a><\/p>\n\n\n\n
Since an enumeration is callable<\/a>, you can get a member by its value. For example, the following return the RED<\/code> member of the Color<\/code> enumeration by its value:<\/p>\n\n\n