Quick Start

Enumeration Creation

There are two ways to create an enumeration.

  • Use the provided enumeration classes ExtendedEnum, LabeledEnum, PairEnum to declare your enumeration.

    from named_enum import ExtendedEnum, LabeledEnum, PairEnum
    
    class TVCouple(ExtendedEnum):
        GALLAGHERS = ("FRANK", "MONICA")
        MIKE_AND_MOLLY = ("Mike", "Molly")
    
    class NBALegendary(LabeledEnum):
        JOHNSON = ("Johnson", "Magic Johnson")
        JORDAN = ("Jordan", "Air Jordan")
    
    class Pair(PairEnum):
        TOM_AND_JERRY = ("Tom", "Jerry")
        BULLS = ("Micheal", "Pippen")
    
  • customise your own enumeration class and use it to define the enumeration.

    1. create a new enumeration class
    • inherit from class NamedEnum

      from named_enum import NamedEnum
      
      class TripleEnum(NamedEnum):
          """using a sequence of strings to define the field names"""
          _field_names_ = ("first", "second", "third")
      
    • use function namedenum

      from named_enum import namedenum
      
      # using a sequence of strings to define the field names
      TripleEnum = namedenum("TripleEnum", ("first", "second", "third"))
      
      # using a comma/space separated string to define the field names
      TripleEnum = namedenum("LabelEnum", "key, label")
      
    1. create enumeration using the customized enumeration class in last step.

      class AnimationFamily(TripleEnum):
          SIMPSONS = ("Homer", "Bart", "Marge")
          DUCKS = ("Huey", "Dewey", "Louie")
      

Usages

  • names(as_tuple=True)

    as_tuple=True: returns the names of all enumeration items as a tuple.

    >>> AnimationFamily.names()
    ('SIMPSONS', 'DUCKS')
    

    as_tuple=False: returns a generator of the names of all enumeration items.

    >>> from types import GeneratorType
    >>> isinstance(AnimationFamily.names(as_tuple=False), GeneratorType)
    True
    
  • values(as_tuple=True)

    as_tuple=True: returns the values of all enumeration items as a tuple.

    # TripleEnum
    >>> AnimationFamily.values()
    (NamedTuple(first='Homer', second='Bart', third='Marge'), NamedTuple(first='Huey', second='Dewey', third='Louie'))
    
    # ExtendedEnum
    >>> TVCouple.values()
    (('FRANK', 'MONICA'), ('Mike', 'Molly'))
    

    as_tuple=False: returns a generator of the values of all enumeration items.

    >>> import types
    >>> isinstance(AnimationFamily.values(as_tuple=False), GeneratorType)
    True
    
  • describe()

    displays the enumeration as a table.

    # TripleEnum
    >>> AnimationFamily.describe()
    Class: AnimationFamily
        Name | First | Second | Third
    ---------------------------------
    SIMPSONS | Homer |   Bart | Marge
       DUCKS |  Huey |  Dewey | Louie
    <BLANKLINE>
    
    # ExtendedEnum
    >>> TVCouple.describe()
    Class: TVCouple
              Name |               Value
    ------------------------------------
        GALLAGHERS | ('FRANK', 'MONICA')
    MIKE_AND_MOLLY |   ('Mike', 'Molly')
    <BLANKLINE>
    
  • gen(name_value_pair=True)

    name_value_pair=True: returns a generator comprised of name-value pair of each enumeration item

    # TripleEnum
    >>> tuple(AnimationFamily.gen())
    (('SIMPSONS', NamedTuple(first='Homer', second='Bart', third='Marge')), ('DUCKS', NamedTuple(first='Huey', second='Dewey', third='Louie')))
    
    # ExtendedEnum
    >>> tuple(TVCouple.gen())
    (('GALLAGHERS', ('FRANK', 'MONICA')), ('MIKE_AND_MOLLY', ('Mike', 'Molly')))
    

    name_value_pair=False: returns a generator of enumeration items

    # TripleEnum
    >>> tuple(AnimationFamily.gen(name_value_pair=False))
    (<AnimationFamily.SIMPSONS: NamedTuple(first='Homer', second='Bart', third='Marge')>, <AnimationFamily.DUCKS: NamedTuple(first='Huey', second='Dewey', third='Louie')>)
    
    # ExtendedEnum
    >>> tuple(TVCouple.gen(name_value_pair=False))
    (<TVCouple.GALLAGHERS: ('FRANK', 'MONICA')>, <TVCouple.MIKE_AND_MOLLY: ('Mike', 'Molly')>)
    
  • as_dict()

    returns a dictionary, in which the key is the enumeration item’s name and the value is the item’s value

    # TripleEnum
    >>> AnimationFamily.as_dict()
    {'SIMPSONS': NamedTuple(first='Homer', second='Bart', third='Marge'), 'DUCKS': NamedTuple(first='Huey', second='Dewey', third='Louie')}
    
    # ExtendedEnum
    >>> TVCouple.as_dict()
    {'GALLAGHERS': ('FRANK', 'MONICA'), 'MIKE_AND_MOLLY': ('Mike', 'Molly')}
    
  • as_set()

    returns a set of tuples containing the enumeration item’s name and value

    # TripleEnum
    >>> AnimationFamily.as_set()
    {('SIMPSONS', NamedTuple(first='Homer', second='Bart', third='Marge')), ('DUCKS', NamedTuple(first='Huey', second='Dewey', third='Louie'))}
    
    # ExtendedEnum
    >>> TVCouple.as_set()
    {('GALLAGHERS', ('FRANK', 'MONICA')), ('MIKE_AND_MOLLY', ('Mike', 'Molly'))}
    
  • as_tuple()

    returns a tuple of tuples containing the enumeration item’s name and value

    # TripleEnum
    >>> AnimationFamily.as_tuple()
    (('SIMPSONS', NamedTuple(first='Homer', second='Bart', third='Marge')), ('DUCKS', NamedTuple(first='Huey', second='Dewey', third='Louie')))
    
    # ExtendedEnum
    >>> TVCouple.as_tuple()
    (('GALLAGHERS', ('FRANK', 'MONICA')), ('MIKE_AND_MOLLY', ('Mike', 'Molly')))
    
  • as_list()

    returns a list of tuples containing the enumeration item’s name and value

    # TripleEnum
    >>> AnimationFamily.as_list()
    [('SIMPSONS', NamedTuple(first='Homer', second='Bart', third='Marge')), ('DUCKS', NamedTuple(first='Huey', second='Dewey', third='Louie'))]
    
    # ExtendedEnum
    >>> TVCouple.as_list()
    [('GALLAGHERS', ('FRANK', 'MONICA')), ('MIKE_AND_MOLLY', ('Mike', 'Molly'))]
    
  • as_ordereddict()

    returns an ordered dict, in which the key is the enumeration item’s name and the value is the item’s value

    # TripleEnum
    >>> AnimationFamily.as_ordereddict()
    OrderedDict([('SIMPSONS', NamedTuple(first='Homer', second='Bart', third='Marge')), ('DUCKS', NamedTuple(first='Huey', second='Dewey', third='Louie'))])
    
    # ExtendedEnum
    >>> TVCouple.as_ordereddict()
    OrderedDict([('GALLAGHERS', ('FRANK', 'MONICA')), ('MIKE_AND_MOLLY', ('Mike', 'Molly'))])
    

If you define the enumeration class with _field_names_ variable, then for each field name in it 3 corresponding functions are generated and assigned to the enumeration class:

  • <field_name>s(as_tuple=True)

    as_tuple=True: returns a tuple containing all corresponding values of the field in enumeration items

    # TripleEnum
    >>> AnimationFamily.firsts()
    ('Homer', 'Huey')
    >>> AnimationFamily.seconds()
    ('Bart', 'Dewey')
    >>> AnimationFamily.thirds()
    ('Marge', 'Louie')
    
    # LabeledEnum
    >>> NBALegendary.keys()
    ('Johnson', 'Jordan')
    >>> NBALegendary.labels()
    ('Magic Johnson', 'Air Jordan')
    

    as_tuple=False: returns a generator of all corresponding values of the field in enumeration items

    # TripleEnum
    >>> isinstance(AnimationFamily.firsts(as_tuple=False), GeneratorType)
    True
    
  • from_<field_name>(field_value, as_tuple=True)

    as_tuple=True: returns a tuple containing all enumeration items which has the given field_value in corresponding field

    # TripleEnum
    >>> AnimationFamily.from_first('Homer')
    (<AnimationFamily.SIMPSONS: NamedTuple(first='Homer', second='Bart', third='Marge')>,)
    
    >>> AnimationFamily.from_second('Dewey')
    (<AnimationFamily.DUCKS: NamedTuple(first='Huey', second='Dewey', third='Louie')>,)
    
    >>> AnimationFamily.from_third('Marge')
    (<AnimationFamily.SIMPSONS: NamedTuple(first='Homer', second='Bart', third='Marge')>,)
    
    # LabeledEnum
    >>> NBALegendary.from_key('Johnson')
    (<NBALegendary.JOHNSON: NamedTuple(key='Johnson', label='Magic Johnson')>,)
    
    >>> NBALegendary.from_label('Air Jordan')
    (<NBALegendary.Jordan: NamedTuple(key='Jordan', label='Air Jordan')>,)
    

    as_tuple=False: returns a generator of all enumeration items which has the given field_value in corresponding field

    # TripleEnum
    >>> isinstance(AnimationFamily.from_first('Homer', as_tuple=False), GeneratorType)
    True
    
  • has_<field_name>(field_value)

    returns a boolean value to indicate whether there is at least one enumeration item has the given field_value in corresponding field

    # TripleEnum
    >>> AnimationFamily.has_first('Homer')
    True
    >>> AnimationFamily.has_first('Holmes')
    False
    
    >>> AnimationFamily.has_second('Dewey')
    True
    >>> AnimationFamily.has_second('David')
    False
    
    >>> AnimationFamily.has_third('Louie')
    True
    >>> AnimationFamily.has_third('Louis')
    False
    
    # LabeledEnum
    >>> NBALegendary.has_key('Johnson')
    True
    >>> NBALegendary.has_key('John')
    False
    
    >>> NBALegendary.has_label('Air Jordan')
    True
    >>> NBALegendary.has_label('The Black Mamba')
    False