Real Python: Build Enumerations of Constants With Python's Enum

Some programming languages, like Java and C++, include syntax that supports a data type known as enumerations, or just enums. This data type allows you to create sets of semantically related constants that you can access through the enumeration itself. Python doesn’t have a dedicated syntax for enums. However, the Python standard library has an enum module that supports enumerations through the Enum class.

If you come from a language with enumerations, and you’re used to working with them, or if you just want to learn how to use enumerations in Python, then this tutorial is for you.

In this tutorial, you’ll learn how to:

• Create enumerations of constants using Python’s Enum class
• Work with enumerations and their members in Python
• Customize enumeration classes with new functionalities
• Code practical examples to understand why you would use enumerations

Additionally, you’ll explore other specific enumeration types that live in enum, including IntEnum, IntFlag, and Flag. They’ll help you create specialized enums.

To follow along with this tutorial, you should be familiar with object-oriented programming and inheritance in Python.

Getting to Know Enumerations in Python

Several programming languages, including Java and C++, have a native enumeration or enum data type as part of their syntax. This data type allows you to create sets of named constants, which are considered members of the containing enum. You can access the members through the enumeration itself.

Enumerations come in handy when you need to define an immutable and discrete set of similar or related constant values that may or may not have semantic meaning in your code.

Days of the week, months and seasons of the year, Earth’s cardinal directions, a program’s status codes, HTTP status codes, colors in a traffic light, and pricing plans of a web service are all great examples of enumerations in programming. In general, you can use an enum whenever you have a variable that can take one of a limited set of possible values.

Python doesn’t have an enum data type as part of its syntax. Fortunately, Python 3.4 added the enum module to the standard library. This module provides the Enum class for supporting general-purpose enumerations in Python.

Enumerations were introduced by PEP 435, which defines them as follows:

An enumeration is a set of symbolic names bound to unique, constant values. Within an enumeration, the values can be compared by identity, and the enumeration itself can be iterated over. (Source)

Before this addition to the standard library, you could create something similar to an enumeration by defining a sequence of similar or related constants. To this end, Python developers often used the following idiom:

>>> RED,GREEN,YELLOW=range(3)>>> RED0>>> GREEN1

Even though this idiom works, it doesn’t scale well when you’re trying to group a large number of related constants. Another inconvenience is that the first constant will have a value of 0, which is falsy in Python. This can be an issue in certain situations, especially those involving Boolean tests.

In most cases, enumerations can help you avoid the drawbacks of the above idiom. They’ll also help you produce more organized, readable, and robust code. Enumerations have several benefits, some of which relate to ease of coding:

• Allowing for conveniently grouping related constants in a sort of namespace
• Allowing for additional behavior with custom methods that operate on either enum members or the enum itself
• Providing quick and flexible access to enum members
• Enabling direct iteration over members, including their names and values
• Facilitating code completion within IDEs and editors
• Enabling type and error checking with static checkers
• Providing a hub of searchable names
• Mitigating spelling mistakes when using the members of an enumeration

They also make your code robust by providing the following benefits:

• Ensuring constant values that can’t be changed during the code’s execution
• Guaranteeing type safety by differentiating the same value shared across several enums
• Improving readability and maintainability by using descriptive names instead of mysterious values or magic numbers
• Facilitating debugging by taking advantage of readable names instead of values with no explicit meaning
• Providing a single source of truth and consistency throughout the code

Now that you know the basics of enumerations in programming and in Python, you can start creating your own enum types by using Python’s Enum class.

Creating Enumerations With Python’s Enum

Python’s enum module provides the Enum class, which allows you to create enumeration types. To create your own enumerations, you can either subclass Enum or use its functional API. Both options will let you define a set of related constants as enum members.