| 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``. |
| |
| ``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. |
| |
| ``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 affect of a module whose top-level constant and |
| member names cannot be rebound. |
| |
| ``skip`` |
| ~~~~~~ |
| Descriptor to add a normal (non-``Enum`` member) attribute to 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>] |
| |
| |
| 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 do not support the ``Enum`` |
| protocols, and have no restrictions on duplications:: |
| |
| >>> class K(Constant): |
| ... PI = 3.141596 |
| ... TAU = 2 * PI |
| ... |
| >>> K.TAU |
| 6.283192 |
| |