Python's Enumeration Class

What is an Enumerator?

Enumerating something adds values (numerical) to the items. In Python, when iterating over an array, it's sometimes beneficial to get the item with the index. Take for example the iterations below.

>>> ex_list = ["cat", "dog", "Jim"]
>>> for i in ex_list:
	print(i)

	
## cat
## dog
## Jim

>>> for i in enumerate(ex_list):
	print(i)

	
## (0, 'cat')
## (1, 'dog')
## (2, 'Jim')

The second iteration provides a numerical value to identify the different items. It's important that the numerical values are unique. If not, they would lose their significance as identifiers.

enum module

The enum module opens up a few enumeration classes and helper methods that allow us to more easily work with enumerations.

A couple of the most commons classes are Enum (base class) and IntEnum. These help us create enumerated constants. Additionally, one of the helpful classes is the auto class that replaces the instances in the enumerated class with values automatically (starting at 1).

The class keyword that is used to create enumerated classes doesn't create your typical Python class. Instead, it creates an enumeration class. The differences are beyond the scope of this article, but if you're interested you can read more about it in the docs.

Basic Example

First, let's start by importing the Enum and auto classes from the enum module. Then we can define a new class named Roles, pass in the Enum class, and define some values.

>>> from enum import Enum, auto
>>> class Roles(Enum):
	ADMIN = 1
	SUBADMIN = 2
	USER = 3

	
>>> Roles
## <enum 'Roles'>
>>> for role in Roles:
	print(role)

	
## Roles.ADMIN
## Roles.SUBADMIN
## Roles.USER
>>> Roles["ADMIN"]
## <Roles.ADMIN: 1>

We can get similar values by using the auto class.

>>> class Roles(Enum):
	ADMIN = auto()
	SUBADMIN = auto()
	USER = auto()

	
>>> Roles["ADMIN"]
## <Roles.ADMIN: 1>

More Complex Example

I came across the numerator class because the Bureau of Economic Analysis (BEA) has a situation where this class applies. The BEA provides a free API to retrieve economic data.

One of the parameters that some endpoints accept is a GeoFips. As written in the BEA API developer guide:

GeoFips specifies geography. It can be all states (STATE), all counties (COUNTY), all Metropolitan Statistical Areas (MSA), all Micropolitan Statistical Areas (MIC), all Metropolitan Divisions (DIV), all Combined Statistical Areas (CSA), all metropolitan/nonmetropolitan portions (PORT), or state post office abbreviation for all counties in one state (e.g. NY). It can also be a list of ANSI state-county codes or metropolitan area codes.

For example, the GeoFips for Jasper, GA is 13159. Georgia has a GeoFips of 13, but it's hard to remember every state's GeoFips!

Therefore, an enumerator class can be used in this situation.

>>> class StateFIPS(Enum):
	ALABAMA=1
	ALASKA=2
	Arizona=4

	
>>> StateFIPS.ALABAMA
## <StateFIPS.ALABAMA: 1>
>>> StateFIPS.ALABAMA.value
## 1

Conclusion

Truthfully, it took me a while to hear about the enum module. However, it might be just the thing for your situation.

On another note, the reason the values are capitalized is that they are considered constants. And it's common practice to put constants in all caps.