Creating Enumerations With the Functional API

00:00 Creating enumerations with a functional API. The Enum class provides a functional API that you can use to create enumerations without using the usual class syntax.

00:12 You’ll just need to call enum with appropriate arguments as you would do with a function or any other callable. This functional API resembles the way the namedtuple factory function works.

00:25 In the case of Enum, the function signature has the form seen on screen. From this signature, you can conclude that enum needs two positional arguments, value and names.

00:36 It can also take up to four optional and keyword-only arguments: module, qualname, type and start. On screen is a table that summarizes the content and meaning of each argument in the signature of enum.

00:54 To provide the names argument, you can use a string containing member names separated either with spaces or commas, an iterable of member names, or an iterable of name-value pairs.

01:08 The module and qualname arguments play an important role when you need to pickle and unpickle your enumerations. If module isn’t set, Python will attempt to find it.

01:18 If it fails, then the class will not be picklable. Similarly, if qualname isn’t set, Python will set it to the global scope, which may cause your enumerations to fail unpickling.

01:29 In some situations,

01:33 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 later on in the course.

01:48 Finally, the start argument provides a way to customize the initial value of your enumerations. This argument defaults to one rather than zero.

01:58 The reason for this default value is that zero is false in a Boolean sense, but Enum members evaluate to true. Therefore, starting from zero would be a little inconsistent and potentially confusing.

02:10 Most of the time, you’ll just use the first two arguments to enum when creating your enumerations. Onscreen is an example of creating an enumeration of common HTTP methods.

02:25 This call to enum returns a new enumeration called HTTPMethod. To provide the member names, you use a list of strings, each of which represents an HTTP method.

02:38 Note that the member values are automatically set to consecutive integer numbers. Starting from one, you can change this initial value using the start argument.

03:03 Note that defining these enumerations with a class syntax will produce the same result.

03:13 Here you use the class syntax to define HTTPMethod. This example is completely equivalent to the previous one. As you can conclude from the output of list,

03:25 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.

03:34 However, if you want to create enumerations dynamically, then the functional API may be your only option. Consider this example where you create an Enum with user-provided members.

04:10 Remember that this example is intended to show that the functional API is the way to go when you need to create enumerations dynamically. It’s not good programming practice because creating any object from user input is quite risky, considering that you can’t predict what they will input.

04:26 So doing so without measures to sanitize this input is a bad idea.

04:33 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.

04:43 In the example seen on screen, you use a list of name-value tuples to initialize all the enumeration members.

04:55 Providing a list of name-value tuples makes it possible to create the HTTPStatusCode enumeration with custom values for the members. 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.

05:18 In the next section of the course, you’ll look deeper at enumerations with automatic values, aliases, and unique values.