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:

.. code-block:: console

    $ pip install named_enum

or

.. code-block:: console

    $ 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 <https://github.com/zhiwei2017/named_enum>`_.

You can either clone the public repository:

.. code-block:: console

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

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

.. code-block:: console

    $ pip install .

or

.. code-block:: console

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

.. code-block:: python

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
  
  .. code-block:: python
  
  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
  
  .. code-block:: python
  
  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.
  
  .. code-block:: python
```
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.

    .. code-block:: python

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

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

    .. code-block:: python

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

    .. code-block:: python

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

    .. code-block:: python

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

+ ``describe()``
    displays the enumeration as a table.

    .. code-block:: python

      # 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

    .. code-block:: python

      # 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

    .. code-block:: python

      # 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

    .. code-block:: python

      # 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

    .. code-block:: python

      # 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

    .. code-block:: python

      # 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

    .. code-block:: python

      # 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

    .. code-block:: python

      # 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

    .. code-block:: python

      # 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

    .. code-block:: python

      # 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

    .. code-block:: python

      # 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

    .. code-block:: python

      # 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

    .. code-block:: python

      # 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 <https://named-enum.readthedocs.io/en/latest/>`_.

Acknowledgement
---------------
- `Cristian Alfonso González Mora <https://github.com/cagonza6/>`_ for the inspiration of this project.

Author
------

* `Zhiwei Zhang <https://github.com/zhiwei2017>`_ - *Maintainer* - `zhiwei2017@gmail.com <mailto:zhiwei2017@gmail.com?subject=[GitHub]Named%20Enum>`_
* `Jianlan Shao <https://github.com/Lan314>`_ - *Developer* - `jianlan.shao@gmail.com <mailto:jianlan.shao@gmail.com?subject=[GitHub]Named%20Enum>`_

**[ ~ Dependencies scanned by** `PyUp.io <https://pyup.io>`_ **~ ]**

Keywords

Operating System :: OS Independent

License :: OSI Approved :: MIT License

Development Status :: 5 - Production/Stable

Programming Language :: Python

Programming Language :: Python :: 3

Programming Language :: Python :: 3.8

FAQs

What is named-enum?

Is named-enum well maintained?

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install