{"id":2927,"date":"2021-11-14T16:33:27","date_gmt":"2021-11-14T16:33:27","guid":{"rendered":"https:\/\/www.pythontutorial.net\/?page_id=2927"},"modified":"2025-03-28T02:50:11","modified_gmt":"2025-03-28T02:50:11","slug":"python-enum-unique","status":"publish","type":"page","link":"https:\/\/www.pythontutorial.net\/python-oop\/python-enum-unique\/","title":{"rendered":"Python Enum aliases & @enum.unique Decorator"},"content":{"rendered":"\n

Summary<\/strong>: in this tutorial, you’ll learn about enumeration member aliases and how to use the enum unique decorator to ensure the uniqueness of member values. <\/p>\n\n\n\n

Introduction to the enum aliases #<\/a><\/h2>\n\n\n\n

By definition, the enumeration <\/a>member values are unique. However, you can create different member names with the same values.<\/p>\n\n\n\n

For example, the following defines the Color<\/code> 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    CRIMSON = 1<\/span>\n    SALMON = 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
In this example, the Color<\/code> enumeration has the RED<\/code>, CRIMSON<\/code>, and SALMON<\/code> members with the same value 1. <\/p>\n\n\n\n
When you define multiple members in an enumeration with the same values, Python does not create different members but aliases. <\/p>\n\n\n\n
In this example, the RED<\/code> is the main member while the CRIMSON<\/code> and SALMON<\/code> members are the aliases of the RED<\/code> member<\/p>\n\n\n\n
The following statements return True<\/code> because CRIMSON<\/code> and SALMON<\/code> members are RED meber:<\/p>\n\n\n
print(Color.RED is<\/span> Color.CRIMSON)\nprint(Color.RED is<\/span> Color.SALMON)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Output:<\/p>\n\n\n
True<\/span>\nTrue<\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
When you look up a member by value, you’ll always get the main member, not aliases. For example, the following statement returns the RED<\/code> member:<\/p>\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
When you iterate the members of an enumeration with aliases, you’ll get only the main members, not the aliases. For example:<\/p>\n\n\n
for<\/span> color in<\/span> Color:\n    print(color)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
It returns only three members:<\/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
To get all the members including aliases, you need to use the __member__<\/code> property of the enumeration class. For example:<\/p>\n\n\n
from<\/span> enum import<\/span> Enum\nfrom<\/span> pprint import<\/span> pprint\n\n\nclass<\/span> Color<\/span>(Enum)<\/span>:<\/span>\n    RED = 1<\/span>\n    CRIMSON = 1<\/span>\n    SALMON = 1<\/span>\n    GREEN = 2<\/span>\n    BLUE = 3<\/span>\n\n\npprint(Color.__members__)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Output:<\/p>\n\n\n
mappingproxy({'BLUE'<\/span>: <Color.BLUE: 3<\/span>>,\n              'CRIMSON'<\/span>: <Color.RED: 1<\/span>>,\n              'GREEN'<\/span>: <Color.GREEN: 2<\/span>>,\n              'RED'<\/span>: <Color.RED: 1<\/span>>,\n              'SALMON'<\/span>: <Color.RED: 1<\/span>>})<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
The output indicates the CRIMSON<\/code> and SALMON<\/code> reference the same object which is referenced by the RED<\/code> member:<\/p>\n\n\n
<Color.RED: 1<\/span>><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
When to use enum aliases #<\/a><\/h2>\n\n\n\n
Enumeration aliases can be helpful in some situations. For example, suppose that you have to deal with API from two different systems. And each system has a different response status doe with the same meaning as shown in the following table:<\/p>\n\n\n\n
 System 1 <\/th>System 2<\/th>Meaning<\/th><\/tr><\/thead>
REQUESTING<\/td>PENDING<\/td>The request is in progress<\/td><\/tr>
OK<\/td>FULFILLED<\/td>The request was completed successfully<\/td><\/tr>
NOT_OK<\/td>REJECTED<\/td>The request was failed<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
To standardize the status codes from these systems, you can use enumeration aliases as follows:<\/p>\n\n\n\n
Your System<\/th> System 1 <\/th>System 2<\/th>Meaning<\/th><\/tr><\/thead>
IN_PROGRESS<\/td>REQUESTING<\/td>PENDING<\/td>The request is in progress<\/td><\/tr>
SUCCESS<\/td>OK<\/td>FULFILLED<\/td>The request was completed successfully<\/td><\/tr>
ERROR<\/td>NOT_OK<\/td>REJECTED<\/td>The request was failed<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
The following defines the ResponseStatus<\/code> enumeration with aliases:<\/p>\n\n\n
from<\/span> enum import<\/span> Enum\n\n\nclass<\/span> ResponseStatus<\/span>(Enum)<\/span>:<\/span>\n    # in progress<\/span>\n    IN_PROGRESS = 1<\/span>\n    REQUESTING = 1<\/span>\n    PENDING = 1<\/span>\n\n    # success<\/span>\n    SUCCESS = 2<\/span>\n    OK = 2<\/span>\n    FULFILLED = 2<\/span>\n\n    # error<\/span>\n    ERROR = 3<\/span>\n    NOT_OK = 3<\/span>\n    REJECTED = 3<\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
The following compares the response code from system 1 to check if the request was successful or not:<\/p>\n\n\n
code = 'OK'<\/span>\nif<\/span> ResponseStatus[code] is<\/span> ResponseStatus.SUCCESS:\n    print('The request completed successfully'<\/span>)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Output:<\/p>\n\n\n
The request completed successfully<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Likewise, you can check the response code from system 2 to see if the request was successful:<\/p>\n\n\n
code = 'FULFILLED'<\/span>\nif<\/span> ResponseStatus[code] is<\/span> ResponseStatus.SUCCESS:\n    print('The request completed successfully'<\/span>)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Output:<\/p>\n\n\n
print('The request completed successfully'<\/span>)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
@enum.unique decorator #<\/a><\/h2>\n\n\n\n
To define an enumeration with no aliases, you can carefully use unique values for the members. For example:<\/p>\n\n\n
from<\/span> enum import<\/span> Enum\n\n\nclass<\/span> Day<\/span>(Enum)<\/span>:<\/span>\n    MON = 'Monday'<\/span>\n    TUE = 'Tuesday'<\/span>\n    WED = 'Wednesday'<\/span>\n    THU = 'Thursday'<\/span>\n    FRI = 'Friday'<\/span>\n    SAT = 'Saturday'<\/span>\n    SUN = 'Sunday'<\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
But you can accidentally use the same values for two members like this:<\/p>\n\n\n
class<\/span> Day<\/span>(Enum)<\/span>:<\/span>\n    MON = 'Monday'<\/span>\n    TUE = 'Monday'<\/span>\n    WED = 'Wednesday'<\/span>\n    THU = 'Thursday'<\/span>\n    FRI = 'Friday'<\/span>\n    SAT = 'Saturday'<\/span>\n    SUN = 'Sunday'<\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
In this example, the TUE<\/code> member is the alias of the MON<\/code> member, which you may not expect.<\/p>\n\n\n\n
To ensure an enumeration has no alias, you can use the @enum.unique<\/code> decorator from the enum<\/code> module.<\/p>\n\n\n\n
When you decorate an enumeration with the @enum.unique<\/code> decorator, Python will throw an exception if the enumeration has aliases. <\/p>\n\n\n\n
For example, the following will raise a ValueError<\/code>:<\/p>\n\n\n
import<\/span> enum\n\nfrom<\/span> enum import<\/span> Enum\n\n\n@enum.unique<\/span>\nclass<\/span> Day<\/span>(Enum)<\/span>:<\/span>\n    MON = 'Monday'<\/span>\n    TUE = 'Monday'<\/span>\n    WED = 'Wednesday'<\/span>\n    THU = 'Thursday'<\/span>\n    FRI = 'Friday'<\/span>\n    SAT = 'Saturday'<\/span>\n    SUN = 'Sunday'<\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Error:<\/p>\n\n\n
ValueError: duplicate values found in<\/span> <enum 'Day'<\/span>>: TUE -> MON<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Summary #<\/a><\/h2>\n\n\n\n
    \n
  • When an enumeration has different members with the same values, the first member is the main member while others are aliases of the main member.<\/li>\n\n\n\n
  • Use the @enum.unique<\/code> decorator from the enum<\/code> module to enforce the uniqueness of the values of the members.<\/li>\n<\/ul>\n
    \n\t
    \n\t\t
    Was this tutorial helpful ?<\/div>\n\t\t
    \n\t\t\t\n\t\t\t\t\n\t\t\t\t\t<\/path>\n\t\t\t\t<\/svg>\n\t\t\t\t Yes <\/span>\n\t\t\t<\/button>\n\n\t\t\t\n\t\t\t\t\n\t\t\t\t\t<\/path>\n\t\t\t\t<\/svg>\n\t\t\t\t No <\/span>\n\t\t\t<\/button>\n\t\t<\/div>\n\t<\/header>\n\n\t
    \n\t\t
    \n\t\t\t
    <\/div>\n\t\t\t
Try it<\/a><\/p>\n\n\n\n