Enumerations
************

Basic enumeration, providing ordered types for collections. These can
be constructed as simple type listings…

   >>> from stem.util import enum
   >>> insects = enum.Enum('ANT', 'WASP', 'LADYBUG', 'FIREFLY')
   >>> insects.ANT
   'Ant'
   >>> tuple(insects)
   ('Ant', 'Wasp', 'Ladybug', 'Firefly')

… or with overwritten string counterparts…

   >>> from stem.util import enum
   >>> pets = enum.Enum(('DOG', 'Skippy'), 'CAT', ('FISH', 'Nemo'))
   >>> pets.DOG
   'Skippy'
   >>> pets.CAT
   'Cat'

**Module Overview:**

   UppercaseEnum - Provides an enum instance with capitalized values

   Enum - Provides a basic, ordered  enumeration
     |- keys - string representation of our enum keys
     |- index_of - index of an enum value
     |- next - provides the enum after a given enum value
     |- previous - provides the enum before a given value
     |- __getitem__ - provides the value for an enum key
     +- __iter__ - iterator over our enum keys

stem.util.enum.UppercaseEnum(*args)

   Provides an "Enum" instance where the values are identical to the
   keys. Since the keys are uppercase by convention this means the
   values are too. For instance…

      >>> from stem.util import enum
      >>> runlevels = enum.UppercaseEnum('DEBUG', 'INFO', 'NOTICE', 'WARN', 'ERROR')
      >>> runlevels.DEBUG
      'DEBUG'

   Parameters:
      **args** (*list*) – enum keys to initialize with

   Returns:
      "Enum" instance with the given keys

class stem.util.enum.Enum(*args)

   Bases: "object"

   Basic enumeration.

   keys()

      Provides an ordered listing of the enumeration keys in this set.

      Returns:
         **list** with our enum keys

   index_of(value)

      Provides the index of the given value in the collection.

      Parameters:
         **value** (*str*) – entry to be looked up

      Returns:
         **int** index of the given entry

      Raises:
         **ValueError** if no such element exists

   next(value)

      Provides the next enumeration after the given value.

      Parameters:
         **value** (*str*) – enumeration for which to get the next
         entry

      Returns:
         enum value following the given entry

      Raises:
         **ValueError** if no such element exists

   previous(value)

      Provides the previous enumeration before the given value.

      Parameters:
         **value** (*str*) – enumeration for which to get the previous
         entry

      Returns:
         enum value proceeding the given entry

      Raises:
         **ValueError** if no such element exists
