Skip to main content

Named Enumeration

Project description

https://img.shields.io/pypi/l/named-enum.svg Documentation Status https://github.com/KnightConan/named_enum/workflows/Unit%20Test%20&%20Build%20Test/badge.svg https://img.shields.io/pypi/v/named-enum.svg https://img.shields.io/pypi/status/named-enum.svg Python 3.6 | Python 3.7 | Python 3.8 https://img.shields.io/pypi/format/named-enum.svg https://codecov.io/gh/KnightConan/named_enum/branch/master/graph/badge.svg Updates https://pepy.tech/badge/named-enum https://img.shields.io/badge/saythanks.io-☼-1EAEDB.svg

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 star it in github.

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

Documentation

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

License

MIT

Acknowledgement

[ ~ Dependencies scanned by PyUp.io ~ ]

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for named-enum, version 1.0.1
Filename, size File type Python version Upload date Hashes
Filename, size named_enum-1.0.1-py3-none-any.whl (13.1 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size named_enum-1.0.1.tar.gz (16.2 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page