named-enum 1.0.2

Named Enumeration

Introduction

This package provides several enumeration classes, which extends the default Enum class with various functionalities. For each enumeration class, its enumeration item’s value is a customised tuple type generated by namedtuple from collections package.

If you like it, please it in .

Installation

pip install named-enum

running test

python setup.py test

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")

  2. 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

Documentation

The documentation about this project is available in Read the Docs.

License

MIT

Acknowledgement

• Cristian Alfonso González Mora for the inspiration of this project.

[ ~ Dependencies scanned by PyUp.io ~ ]