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