aenum --- support for advanced enumerations, namedtuples, and constants

Advanced Enumerations (compatible with Python's stdlib Enum), NamedTuples, and NamedConstants

aenum includes a Python stdlib Enum-compatible data type, as well as a metaclass-based NamedTuple implementation and a NamedConstant class.

An Enum is a set of symbolic names (members) bound to unique, constant values. Within an enumeration, the members can be compared by identity, and the enumeration itself can be iterated over. If using Python 3 there is built-in support for unique values, multiple values, auto-numbering, and suspension of aliasing (members with the same value are not identical), plus the ability to have values automatically bound to attributes.

A NamedTuple is a class-based, fixed-length tuple with a name for each possible position accessible using attribute-access notation as well as the standard index notation.

A NamedConstant is a class whose members cannot be rebound; it lacks all other Enum capabilities, however; consequently, it can have duplicate values.

Module Contents

NamedTuple

Base class for creating NamedTuples, either by subclassing or via it's functional API.

Constant

Constant class for creating groups of constants. These names cannot be rebound to other values.

Enum

Base class for creating enumerated constants. See section Enum Functional API for an alternate construction syntax.

IntEnum

Base class for creating enumerated constants that are also subclasses of int.

StrEnum

Base class for creating enumerated constants that are also subclasses of str.

AutoNumberEnum

Derived class that automatically assigns an int value to each member.

OrderedEnum

Derived class that adds <, <=, >=, and > methods to an Enum.

UniqueEnum

Derived class that ensures only one name is bound to any one value.

Flag

Base class for creating enumerated constants that can be combined using the bitwise operations without losing their Flag membership.

IntFlag

Base class for creating enumerated constants that can be combined using the bitwise operators without losing their IntFlag membership. IntFlag members are also subclasses of int.

unique

Enum class decorator that ensures only one name is bound to any one value.

constant

Descriptor to add constant values to an Enum

convert

Helper to transform target global variables into an Enum.

enum

Helper for specifying keyword arguments when creating Enum members.

export

Helper for inserting Enum members into a namespace (usually globals()).

extend_enum

Helper for adding new Enum members after creation.

module

Function to take a Constant or Enum class and insert it into sys.modules with the effect of a module whose top-level constant and member names cannot be rebound.

member

Decorator to force a member in an Enum or Constant.

nonmember

Decorator to force a normal (non-Enum member) attribute in an Enum or Constant.

Creating an Enum

Enumerations can be created using the class syntax, which makes them easy to read and write. To define an enumeration, subclass Enum as follows:

>>> from aenum import Enum
>>> class Color(Enum):
...     RED = 1
...     GREEN = 2
...     BLUE = 3

The Enum class is also callable, providing the following functional API:

>>> Animal = Enum('Animal', 'ANT BEE CAT DOG')
>>> Animal
<enum 'Animal'>
>>> Animal.ANT
<Animal.ANT: 1>
>>> Animal.ANT.value
1
>>> list(Animal)
[<Animal.ANT: 1>, <Animal.BEE: 2>, <Animal.CAT: 3>, <Animal.DOG: 4>]

Note that Enum members are boolean True unless the __nonzero__ (Python 2) or __bool__ (Python 3) method is overridden to provide different semantics.

Creating a Flag

Flag (and IntFlag) has members that can be combined with each other using the bitwise operators (&, |, ^, ~). IntFlag members can be combined with int and other IntFlag members. While it is possible to specify the values directly it is recommended to use auto as the value and let (Int)Flag select an appropriate value:

>>> from enum import Flag
>>> class Color(Flag):
...     RED = auto()
...     BLUE = auto()
...     GREEN = auto()
...
>>> Color.RED & Color.GREEN
<Color.0: 0>
>>> bool(Color.RED & Color.GREEN)
False
>>> Color.RED | Color.BLUE
<Color.RED|BLUE: 3>

If you want to name the empty flag, or various combinations of flags, you may:

>>> class Color(Flag):
...     BLACK = 0
...     RED = auto()
...     BLUE = auto()
...     GREEN = auto()
...     WHITE = RED | BLUE | GREEN
...
>>> Color.BLACK
<Color.BLACK: 0>
>>> Color.WHITE
<Color.WHITE: 7>

Note that (Int)Flag zero-value members have the usual boolean value of False.

Creating NamedTuples

Simple

The most common way to create a new NamedTuple will be via the functional API:

>>> from aenum import NamedTuple
>>> Book = NamedTuple('Book', 'title author genre', module=__name__)

Advanced

The simple method of creating NamedTuples requires always specifying all possible arguments when creating instances; failure to do so will raise exceptions.

However, it is possible to specify both docstrings and default values when creating a NamedTuple using the class method:

>>> class Point(NamedTuple):
...     x = 0, 'horizontal coordinate', 0
...     y = 1, 'vertical coordinate', 0
...
>>> Point()
Point(x=0, y=0)

Creating Constants

Constant is similar to Enum, but does not support the Enum protocols, and have no restrictions on duplications:

>>> class K(Constant):
...     PI = 3.141596
...     TAU = 2 * PI
...
>>> K.TAU
6.283192

More Information

Detailed documentation can be found at <aenum/doc/aenum.rst>_

ethanfurman/aenum