{"id":182,"date":"2024-01-25T15:03:01","date_gmt":"2024-01-25T15:03:01","guid":{"rendered":"https:\/\/learnpython.elegantwallp.com\/?p=182"},"modified":"2024-01-25T15:03:02","modified_gmt":"2024-01-25T15:03:02","slug":"python-enumeration","status":"publish","type":"post","link":"https:\/\/learnpython.elegantwallp.com\/2024\/01\/25\/python-enumeration\/","title":{"rendered":"Python Enumeration"},"content":{"rendered":"\n

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

Introduction to the Python Enumeration<\/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\u00a0enum<\/code>\u00a0module that contains the\u00a0Enum<\/code>\u00a0type for defining new enumerations. And you define a new enumeration type by\u00a0subclassing\u00a0the\u00a0Enum<\/code>\u00a0class.<\/p>\n\n\n\n

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

from enum import Enum class Color(Enum): RED = 1 GREEN = 2 BLUE = 3<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
How it works.<\/p>\n\n\n\n
First, import the\u00a0Enum<\/code>\u00a0type from the\u00a0enum<\/code>\u00a0module:<\/p>\n\n\n\n
from enum import Enum<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
Second, define the\u00a0Color<\/code>\u00a0class that inherits from the\u00a0Enum<\/code>\u00a0type:<\/p>\n\n\n\n
class Color(Enum):<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
Third, define the members of the\u00a0Color<\/code>\u00a0enumeration:<\/p>\n\n\n\n
RED = 1 GREEN = 2 BLUE = 3<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
Note that the enumeration\u2019s 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\u00a0Color.RED<\/code>\u00a0is the\u00a0Color<\/code>\u00a0enumeration:<\/p>\n\n\n\n
print(type(Color.RED))<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
Output:<\/p>\n\n\n\n
<enum 'Color'><\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
The\u00a0Color.RED<\/code>\u00a0is also an instance of the\u00a0Color<\/code>\u00a0enumeration:<\/p>\n\n\n\n
print(isinstance(Color.RED, Color))<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
Output:<\/p>\n\n\n\n
True<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
And it has the name and value attributes:<\/p>\n\n\n\n
print(Color.RED.name) print(Color.RED.value)<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
Output:<\/p>\n\n\n\n
RED 1<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
Membership and equality<\/h2>\n\n\n\n
To check if a member is in an enumeration, you use the\u00a0in<\/code>\u00a0operator. For example:<\/p>\n\n\n\n
if Color.RED in Color: print('Yes')<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
Output:<\/p>\n\n\n\n
Yes<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
To compare two members, you can use either\u00a0is<\/code>\u00a0or\u00a0==<\/code>\u00a0operator. For example:<\/p>\n\n\n\n
if Color.RED is Color.BLUE: print('red is blue') else: print('red is not blue')<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
Output:<\/p>\n\n\n\n
red is not blue<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
Note that a member and its associated value are not equal. The following example returns\u00a0False<\/code>:<\/p>\n\n\n\n
if Color.RED == 1: print('Color.RED == 1') else: print('Color.RED != 1')<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
Output:<\/p>\n\n\n\n
Color.RED != 1<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
Enumeration members are hashable<\/h2>\n\n\n\n
Enumeration members are always\u00a0hashable. It means that you can use the enumeration members as keys in a\u00a0dictionary\u00a0or as elements of a\u00a0Set.<\/p>\n\n\n\n
The following example uses the members of the\u00a0Color<\/code>\u00a0enumeration in a dictionary:<\/p>\n\n\n\n
rgb = { Color.RED: '#ff0000', Color.GREEN: '#00ff00', Color.BLUE: '#0000ff' }<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
Access an enumeration member by name and value<\/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:Color.RED<\/code>Code language: Python (python)<\/small><\/p>\n\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\u00a0[]<\/code>\u00a0syntax to get the\u00a0RED<\/code>\u00a0member of the\u00a0Color<\/code>\u00a0enumeration by its name:<\/p>\n\n\n\n
print(Color['RED'])<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
Output:<\/p>\n\n\n\n
Color.RED<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
Since an enumeration is\u00a0callable, you can get a member by its value. For example, the following return the\u00a0RED<\/code>\u00a0member of the\u00a0Color<\/code>\u00a0enumeration by its value:<\/p>\n\n\n\n
print(Color(1))<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
Output:<\/p>\n\n\n\n
Color.RED<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
The following expression returns\u00a0True<\/code>\u00a0because it accesses the same enumeration member using name and value:<\/p>\n\n\n\n
print(Color['RED'] == Color(1))<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
Output:<\/p>\n\n\n\n
True<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
Iterate enumeration members<\/h2>\n\n\n\n
Enumerations are iterables so you can iterate them using a\u00a0for<\/code>\u00a0loop. For example:<\/p>\n\n\n\n
for color in Color: print(color)<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
Output:<\/p>\n\n\n\n
Color.RED Color.GREEN Color.BLUE<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\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\u00a0list()<\/code>\u00a0function to return a list of members from an enumeration:<\/p>\n\n\n\n
print(list(Color))<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
Output:<\/p>\n\n\n\n
[<Color.RED: 1>, <Color.GREEN: 2>, <Color.BLUE: 3>]<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
Enumerations are immutable<\/h2>\n\n\n\n
Enumerations are\u00a0immutable. 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\u00a0Color<\/code>\u00a0enumeration and causes a\u00a0TypeError<\/code>:<\/p>\n\n\n\n
Color['YELLOW'] = 4<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
Error:<\/p>\n\n\n\n
TypeError: 'EnumMeta' object does not support item assignment<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
The following example attempts the change the value of the\u00a0RED<\/code>\u00a0member of the\u00a0Color<\/code>\u00a0enumeration and causes an\u00a0AttributeError<\/code>:<\/p>\n\n\n\n
Color.RED.value = 100<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
Output:<\/p>\n\n\n\n
AttributeError: can't set attribute<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
Inherits from an enumeration<\/h2>\n\n\n\n
An enumeration cannot be inherited unless it contains no members. The following example works fine because the\u00a0Color<\/code>\u00a0enumeration contains no members:<\/p>\n\n\n\n
class Color(Enum): pass class RGB(Color): RED = 1 GREEN = 2 BLUE = 3<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
However, the following example won\u2019t work because the\u00a0RGB<\/code>\u00a0enumeration has members:<\/p>\n\n\n\n
class RGBA(RGB): ALPHA = 4<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
Error:<\/p>\n\n\n\n
TypeError: Cannot extend enumerations<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
Python enumeration example<\/h2>\n\n\n\n
The following example defines an enumeration called\u00a0ResponseStatus<\/code>:<\/p>\n\n\n\n
class ResponseStatus(Enum): PENDING = 'pending' FULFILLED = 'fulfilled' REJECTED = 'rejected'<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
Suppose you receive a response from an HTTP request with the following string:<\/p>\n\n\n\n
response = '''{ \"status\":\"fulfilled\" }'''<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
And you want to look up the\u00a0ResponseStatus<\/code>\u00a0enumeration by the\u00a0status<\/code>. To do that, you need to convert the response\u2019s string to a dictionary and get the value of the status:<\/p>\n\n\n\n
import json data = json.loads(response) status = data['status']<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
And then you look up the member of the\u00a0ResponseStatus<\/code>\u00a0enumeration by the status\u2019 value:<\/p>\n\n\n\n
print(ResponseStatus(status))<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
Output:<\/p>\n\n\n\n
PromiseStatus.FULFILLED<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
Here\u2019s the complete program:<\/p>\n\n\n\n
from enum import Enum import json class ResponseStatus(Enum): PENDING = 'pending' FULFILLED = 'fulfilled' REJECTED = 'rejected' response = '''{ \"status\":\"fulfilled\" }''' data = json.loads(response) status = data['status'] print(ResponseStatus(status))<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
What if the\u00a0status<\/code>\u00a0is not one of the values of the\u00a0ResponseStatus<\/code>\u00a0members? then you\u2019ll get an error. For example:<\/p>\n\n\n\n
from enum import Enum import json class ResponseStatus(Enum): PENDING = 'pending' FULFILLED = 'fulfilled' REJECTED = 'rejected' response = '''{ \"status\":\"ok\" }''' data = json.loads(response) status = data['status'] print(ResponseStatus(status))<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
Error:<\/p>\n\n\n\n
ValueError: 'ok' is not a valid ResponseStatus<\/code>Code language: Python (python)<\/small><\/code><\/pre>\n\n\n\n
To catch the exception, you can use the\u00a0try\u2026except<\/a>\u00a0statement like the following:<\/p>\n\n\n\n
from enum import Enum import json class ResponseStatus(Enum): PENDING = 'pending' FULFILLED = 'fulfilled' REJECTED = 'rejected' response = '''{ \"status\":\"ok\" }''' data = json.loads(response) status = data['status'] try: if ResponseStatus(status) is ResponseStatus.FULFILLED: print('The request completed successfully') except ValueError as error: print(error)<\/code><\/code><\/pre>\n","protected":false},"excerpt":{"rendered":"
Summary: in this tutorial, you\u2019ll learn about Python enumeration and how to use it effectively. Introduction to the Python Enumeration By definition, an enumeration is a set of members that have associated unique constant values. Enumeration is often called enum. Python provides you with the\u00a0enum\u00a0module that contains the\u00a0Enum\u00a0type for defining new enumerations. And you define […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[29],"tags":[],"class_list":["post-182","post","type-post","status-publish","format-standard","hentry","category-5-enumeration"],"_links":{"self":[{"href":"https:\/\/learnpython.elegantwallp.com\/wp-json\/wp\/v2\/posts\/182","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/learnpython.elegantwallp.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/learnpython.elegantwallp.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/learnpython.elegantwallp.com\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/learnpython.elegantwallp.com\/wp-json\/wp\/v2\/comments?post=182"}],"version-history":[{"count":1,"href":"https:\/\/learnpython.elegantwallp.com\/wp-json\/wp\/v2\/posts\/182\/revisions"}],"predecessor-version":[{"id":183,"href":"https:\/\/learnpython.elegantwallp.com\/wp-json\/wp\/v2\/posts\/182\/revisions\/183"}],"wp:attachment":[{"href":"https:\/\/learnpython.elegantwallp.com\/wp-json\/wp\/v2\/media?parent=182"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/learnpython.elegantwallp.com\/wp-json\/wp\/v2\/categories?post=182"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/learnpython.elegantwallp.com\/wp-json\/wp\/v2\/tags?post=182"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}