named-enum 1.4.0

Python named enumeration, which extends the built-in Enum class with extra features.

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.

Installation

Stable release

To install Named Enum, run this command in your terminal:

$ pip install named_enum

or

$ poetry self add named_enum

This is the preferred method to install Named Enum, as it will always install the most recent stable release.

From sources

The sources for Named Enum can be downloaded from the Github repo.

You can either clone the public repository:

$ git clone https://github.com/zhiwei2017/named_enum.git

Once you have a copy of the source, you can install it with:

$ pip install .

or

$ poetry install

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.

Acknowledgement

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

Author

• Zhiwei Zhang - Maintainer - [e-mail]

• Jianlan Shao - Developer - [e-mail]

[ ~ Dependencies scanned by PyUp.io ~ ]