Creating Enumerations by Subclassing Enum

The enum module defines a general-purpose enumeration type with iteration and comparison capabilities. You can use this type to create sets of named constants that you can use to replace literals of common data types, such as numbers and strings.

A classic example of when you should use an enumeration is when you need to create a set of enumerated constants representing the days of the week. Each day will have a symbolic name and a numeric value between 1 and 7 , inclusive.

Here’s how you can create this enumeration by using Enum as your superclass or parent class :

Your Day class is a subclass of Enum . So, you can call Day an enumeration , or just an enum . Day.MONDAY , Day.TUESDAY , and the like are enumeration members , also known as enum members , or just members . Each member must have a value , which needs to be constant.

Because enumeration members must be constants, Python doesn’t allow you to assign new values to enum members at runtime:

If you try to change the value of an enum member, then you get an AttributeError . Unlike member names, the name containing the enumeration itself isn’t a constant but a variable. So, it’s possible to rebind this name at any moment during your program’s execution, but you should avoid doing that.

In the example above, you’ve reassigned Day , which now holds a string rather than the original enumeration. By doing this, you’ve lost the reference to the enum itself.

Often, the values mapped to members are consecutive integer numbers. However, they can be of any type, including user-defined types. In this example, the value of Day.MONDAY is 1 , the value of Day.TUESDAY is 2 , and so on.

Note : You may have noticed that the members of Day are capitalized. Here’s why:

Because Enums are used to represent constants we recommend using UPPER_CASE names for enum members… ( Source )

You can think of enumerations as collections of constants. Like lists , tuples , or dictionaries , Python enumerations are also iterable. That’s why you can use list() to turn an enumeration into a list of enumeration members.

The members of a Python enumeration are instances of the container enumeration itself:

You shouldn’t confuse a custom enum class like Day with its members: Day.MONDAY , Day.TUESDAY , and so on. In this example, the Day enum type is a hub for enumeration members, which happen to be of type Day .

You can also use the idiom based on range() to build enumerations:

In this example, you use range() with the start and stop arguments. The start argument allows you to provide the number that starts the range, while the stop argument defines the number at which the range will stop generating numbers.

Even though you use the class syntax to create enumerations, they’re special classes that differ from normal Python classes. Unlike regular classes, enums:

You should keep in mind all these subtle differences when you start creating and working with your own enumerations in Python.

Often, the members of an enumeration take consecutive integer values. However, in Python, the values of members can be of any type, including user-defined types. For example, here’s an enumeration of school grades that uses non-consecutive numeric values in descending order:

This example shows that Python enums are pretty flexible and allow you to use any meaningful value for their members. You can set the member values according to the intent of your code.

You can also use string values for your enumeration members. Here’s an example of a Size enumeration that you can use in an online store:

In this example, the value associated with each size holds a description that can help you and other developers understand the meaning of your code.

You can also create enumerations of Boolean values. In this case, the members of your enumeration will have only two values:

These two examples show how you can use enumerations to add extra context to your code. In the first example, anyone reading your code will know that the code emulates a switch object with two possible states. This additional information highly improves your code’s readability.

You can also define an enumeration with heterogeneous values:

However, this practice makes your code inconsistent from a type safety perspective. Therefore, it’s not recommended practice. Ideally, it would help if you had values of the same data type, which is consistent with the idea of grouping similar, related constants in enumerations.

Finally, you can also create empty enumerations:

In this example, Empty represents an empty enumeration because it doesn’t define any member constants. Note that you can use the pass statement, the Ellipsis literal ( ... ), or a class-level docstring to create empty enumerations. This last approach can help you improve the readability of your code by providing extra context in the docstring.

Now, why would you need to define an empty enumeration anyway? Empty enumerations can come in handy when you need to build a hierarchy of enum classes to reuse functionality through inheritance .

Consider the following example:

In this example, you create BaseTextEnum as an enumeration with no members. You can only subclass a custom enumeration if it doesn’t have members, so BaseTextEnum qualifies. The Alphabet class inherits from your empty enumeration, which means that you can access the .as_list() method. This method converts the value of a given member into a list.

Creating Enumerations With the Functional API

The Enum class provides a functional API that you can use to create enumerations without using the usual class syntax. You’ll just need to call Enum with appropriate arguments like you’d do with a function or any other callable.

This functional API resembles the way in which the namedtuple() factory function works. In the case of Enum , the functional signature has the following form:

From this signature, you can conclude that Enum needs two positional arguments, value and names . It can also take up to four optional and keyword-only arguments. These arguments are module , qualname , type , and start .

Here’s a table that summarizes the content and meaning of each argument in the signature of Enum :

To provide the names argument, you can use the following objects:

The module and qualname arguments play an important role when you need to pickle and unpickle your enumerations. If module isn’t set, then Python will attempt to find the module. If it fails, then the class will not be picklable. Similarly, if qualname isn’t set, then Python will set it to the global scope , which may cause your enumerations to fail unpickling in some situations.

The type argument is required when you want to provide a mixin class for your enumeration. Using a mixin class can provide your custom enum with new functionality, such as extended comparison capabilities, as you’ll learn in the section about mixing enumerations with other data types .

Finally, the start argument provides a way to customize the initial value of your enumerations. This argument defaults to 1 rather than to 0 . The reason for this default value is that 0 is false in a Boolean sense, but enum members evaluate to True . Therefore, starting from 0 would seem surprising and confusing.

Most of the time, you’ll just use the first two arguments to Enum when creating your enumerations. Here’s an example of creating an enumeration of common HTTP methods :

This call to Enum returns a new enumeration called HTTPMethod . To provide the member names, you use a list of strings. Each string represents an HTTP method. Note that the member values are automatically set to consecutive integer numbers starting from 1 . You can change this initial value using the start argument.

Note that defining the above enumerations with the class syntax will produce the same result:

Here, you use the class syntax to define the HTTPMethod enum. This example is completely equivalent to the previous one, as you can conclude from the output of list() .

Using either the class syntax or the functional API to create your enumeration is your decision and will mostly depend on your taste and concrete conditions. However, if you want to create enumerations dynamically, then the functional API can be your only option.

Consider the following example, where you create an enum with user-provided members:

This example is a little bit extreme because creating any object from your user’s input is quite a risky practice, considering that you can’t predict what the user will input. However, the example is intended to show that the functional API is the way to go when you need to create enumerations dynamically.

Finally, if you need to set custom values for your enum members, then you can use an iterable of name-value pairs as your names argument. In the example below, you use a list of name-value tuples to initialize all the enumeration members:

Providing a list of name-value tuples like you did above makes it possible to create the HTTPStatusCode enumeration with custom values for the members. In this example, if you didn’t want to use a list of name-value tuples, then you could also use a dictionary that maps names to values.

Building Enumerations From Automatic Values

Python’s enum module provides a convenient function called auto() that allows you to set automatic values for your enum members. This function’s default behavior is to assign consecutive integer values to members.

Here’s how auto() works:

You need to call auto() once for each automatic value that you need. You can also combine auto() with concrete values, just like you did with Day.WEDNESDAY and Day.SUNDAY in this example.

By default, auto() assigns consecutive integer numbers to each target member starting from 1 . You can tweak this default behavior by overriding the ._generate_next_value_() method, which auto() uses under the hood to generate the automatic values.

Here’s an example of how to do this:

In this example, you create an enumeration of Earth’s cardinal directions in which values are automatically set to strings containing the first character of each member’s name. Note that you must provide your overridden version of ._generate_next_value_() before defining any members. That’s because the members will be built by calling the method.

Creating Enumerations With Aliases and Unique Values

Linux distributions are considered independent operating systems. So, Ubuntu and Debian are both independent systems with different goals and target audiences. However, they share a common kernel called Linux.

The above enumeration maps operating systems to their corresponding kernels. This relationship turns DEBIAN into an alias of UBUNTU , which may be useful when you have code that’s kernel-related along with code that’s specific to a given Linux distribution.

An important piece of behavior to note in the above example is that when you iterate over the enumeration directly, aliases aren’t considered. If you ever need to iterate over all the members, including aliases, then you need to use .__members__ . You’ll learn more about iteration and the .__members__ attribute in the section about iterating through enumerations .

You also have the option to completely forbid aliases in your enumerations. To do this, you can use the @unique decorator from the enum module:

In this example, you decorate OperatingSystem with @unique . If any member value is duplicated, then you get a ValueError . Here, the exception message points out that DEBIAN and UBUNTU share the same value, which isn’t allowed.

Adding and Tweaking Member Methods

You can provide your enumerations with new functionality by adding new methods to your enumeration classes as you’d do with any regular Python class. Enumerations are classes with special features. Like regular classes, enumerations can have methods and special methods .

Consider the following example, adapted from the Python documentation :

In this example, you have a Mood enumeration with three members. Regular methods like .describe_mood() are bound to instances of their containing enum, which are the enum members. So, you must call regular methods on enum members rather than on the enum class itself.

Note: Remember that Python’s enumerations can’t be instantiated. The members of an enumeration are the enumeration’s allowed instances. So, the self parameter represents the current member.

Similarly, the .__str__() special method operates on members, providing a nicely printable representation of each member.

Finally, the .favorite_mood() method is a class method , which operates on the class or enumeration itself. Class methods like this one provide access to all the enum members from inside the class.

You can also take advantage of this ability to contain additional behavior when you need to implement the strategy pattern . For example, say you need a class that allows you to use two strategies for sorting a list of numbers in ascending and descending order. In this case, you can use an enumeration like the following:

Each member of Sort represents a sorting strategy. The .__call__() method makes the members of Sort callable . Inside .__call__() , you use the built-in sorted() function to sort the input values in ascending or descending order, depending on the called member.

Note: The above example is intended to be a demonstrative example of using an enum to implement the strategy design pattern . In practice, it’s unnecessary to create this Sort enum with the sole purpose of wrapping the sorted() function. Instead, you may use sorted() and its reverse argument directly and avoid overengineering your solution.

When you call Sort.ASCENDING , the input numbers are sorted in ascending order. In contrast, when you call Sort.DESCENDING , the numbers get sorted in descending order. That’s it! You’ve used an enumeration to quickly implement the strategy design pattern.

Mixing Enumerations With Other Types

Python supports multiple inheritance as part of its object-oriented features. This means that in Python, you can inherit multiple classes when creating class hierarchies. Multiple inheritance comes in handy when you want to reuse functionality from several classes at the same time.

A common practice in object-oriented programming is to use what’s known as mixin classes . These classes provide functionality that other classes can use. In Python, you can add mixin classes to the list of parents of a given class to automatically get the mixin functionality.

For example, say that you want an enumeration that supports integer comparison. In this case, you can use the built-in int type as a mixin when defining your enum:

In this example, your Size class inherits from int and Enum . Inheriting from the int type enables direct comparison between members through the > , < , >= , and <= comparison operators. It also enables comparisons between Size members and integer numbers.

Finally, note that when you use a data type as a mixin, the member’s .value attribute isn’t the same as the member itself, although it’s equivalent and will compare as such. That’s why you can compare the members of Size with integer numbers directly.

Note: Using integer enum member values is a pretty common practice. That’s why the enum module provides an IntEnum to create enumerations with integer values directly. You’ll learn more about this class in the section called Exploring Other Enumeration Classes .

The above example shows that creating enumerations with mixin classes is often of great help when you need to reuse a given piece of functionality. If you decide to use this technique in some of your enums, then you’ll have to stick to the following signature:

This signature implies that you can have one or more mixin classes, at most one data type class, and the parent enum class, in that order.

Consider the following examples:

The ValidEnum class shows that in the sequence of bases, you must place as many mixin classes as you need—but only one data type—before Enum .

WrongMixinOrderEnum shows that if you put Enum in any position other than the last, then you’ll get a TypeError with information about the correct signature to use. Meanwhile, TooManyDataTypesEnum confirms that your list of mixin classes must have at most one concrete data type, such as int or str .

Keep in mind that if you use a concrete data type in your list of mixin classes, then the member values have to match the type of this specific data type.

Building Integer Enumerations: IntEnum

In the current stable Python version, 3.10 , the enum module doesn’t include a StrEnum class. However, this class is another example of a popular use case of enumerations. For this reason, Python 3.11 will include a StrEnum type with direct support for common string operations. In the meantime, you can simulate the behavior of a StrEnum class by creating a mixin class with str and Enum as parent classes.

Creating Integer Flags: IntFlag and Flag

You can use IntFlag as the base class for enumerations that should support the bitwise operators. Performing bitwise operations on members of an IntFlag subclass will return an object that’s also a member of the underlying enum.

Here’s an example of a Role enumeration that lets you manage different user roles in a single combined object:

In this code snippet, you create an enumeration that holds a set of user roles in a given application. The members of this enumeration hold integer values that you can combine using the bitwise OR operator ( | ). For example, the user named John has both USER and SUPERVISOR roles. Note that the object stored in john_roles is a member of your Role enumeration.

Note: You should keep in mind that individual members of enums based on IntFlag , also known as flags , should take values that are powers of two (1, 2, 4, 8, …). However, this isn’t a requirement for combinations of flags, like Role.ADMIN .

In the above example, you defined Role.ADMIN as a combination of roles. Its value results from applying the bitwise OR operator to the complete list of previous roles in the enumeration.

IntFlag also supports integer operations, such as arithmetic and comparison operations. However, these types of operations return integers rather than member objects:

IntFlag members are also subclasses of int . That’s why you can use them in expressions that involve integer numbers. In these situations, the resulting value will be an integer rather than an enum member.

Finally, you’ll also find the Flag class available in enum . This class works similarly to IntFlag and has some additional restrictions:

The main difference between IntFlag and Flag is that the latter doesn’t inherit from int . Therefore, integer operations aren’t supported. When you try to use a member of Role in an integer operation, you get a TypeError .

Just like members of IntFlag enums, the members of Flag enums should have values that are powers of two. Again, this doesn’t apply to combinations of flags, like Role.ADMIN in the example above.

Replacing Magic Numbers

The rest of the code connects to a sample web page, performs a GET request, retrieves the response object, and processes it using your process_response() function. The finally clause closes the active connection to avoid resource leaks.

Even though this code works, it can be challenging to read and understand for people unfamiliar with HTTP status codes and their corresponding meanings. To fix these issues and make your code more readable and maintainable, you can use an enumeration to group the HTTP status codes and give them descriptive names:

This code adds a new enumeration called HTTPStatusCode to your application. This enum groups the target HTTP status codes and gives them readable names. It also makes them strictly constant, which makes your app more reliable.

Inside process_response() , you use human-readable and descriptive names that provide context and content information. Now anyone reading your code will immediately know that the match criteria are HTTP status codes. They’ll also spot the meaning of each target code quickly.

Creating a State Machine

Another interesting use case of enumerations is when you use them for re-creating the different possible states of a given system. If your system can be in exactly one of a finite number of states at any given time, then your system works as a state machine . Enumerations are useful when you need to implement this common design pattern.

As an example of how to use an enum to implement the state machine pattern, you create a minimal disk player simulator. To start, go ahead and create a disk_player.py file with the following content:

Here, you define the State class. This class groups all the possible states of your disk player: EMPTY , STOPPED , PAUSED , and PLAYING . Now you can code the DiskPlayer player class, which would look something like this:

The DiskPlayer class implements all the possible actions that your player can execute, including inserting and ejecting the disk, playing, pausing, and stopping the player. Note how each method in DiskPlayer checks and updates the player’s current state by taking advantage of your State enumeration.

To complete your example, you’ll use the traditional if __name__ == "__main__": idiom to wrap up a few lines of code that’ll allow you to try out the DiskPlayer class:

In this code snippet, you first define an actions variable , which holds the sequence of methods that you’ll call from DiskPlayer in order to try out the class. Then you create an instance of your disk player class. Finally, you start a for loop to iterate over the list of actions and run every action through the player instance.

That’s it! Your disk player simulator is ready for a test. To run it, go ahead and execute the following command at your command line:

This command’s output shows that your app has gone through all the possible states. Of course, this example is minimal and doesn’t consider all the potential scenarios. It’s a demonstrative example of how you could use an enumeration to implement the state machine pattern in your code.