named-enum 1.4.0
Python named enumeration, which extends the built-in Enum class with extra features.
License: MIT
Requires Python: >=3.8.1,<4.0.0
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,Programming Language :: Python :: 3.9,Programming Language :: Python :: 3.10,Programming Language :: Python :: 3.11,Programming Language :: Python :: 3.12,Programming Language :: Python :: Implementation,Topic :: Utilities,Natural Language :: English,Intended Audience :: Developers

named-enum
==========

.. license badge
.. image:: https://img.shields.io/pypi/l/named-enum.svg
    :target: https://pypi.python.org/pypi/named-enum/

.. readthedocs badge
.. image:: https://readthedocs.org/projects/named-enum/badge/?version=latest
    :target: https://named-enum.readthedocs.io/en/latest/?badge=latest
    :alt: Documentation Status

.. actions building badge
.. image:: https://github.com/zhiwei2017/named_enum/workflows/Unit%20Test%20&%20Build%20Test/badge.svg
    :target: https://github.com/zhiwei2017/named_enum/actions

.. pypi version badge
.. image:: https://img.shields.io/pypi/v/named-enum.svg
    :target: https://pypi.python.org/pypi/named-enum/

.. development status from pypi
.. image:: https://img.shields.io/pypi/status/named-enum.svg
    :target: https://pypi.python.org/pypi/named-enum/

.. python version badge from PyPI
.. image:: https://img.shields.io/pypi/pyversions/named-enum.svg
    :target: https://pypi.python.org/pypi/named-enum/
    :alt: Python 3.7 | Python 3.8 | Python3.9 | Python3.10 | Python3.11 | 3.12

.. pypi format
.. image:: https://img.shields.io/pypi/format/named-enum.svg
    :target: https://badge.fury.io/py/named-enum

.. codecov badge
.. image:: https://codecov.io/gh/zhiwei2017/named_enum/branch/master/graph/badge.svg
    :target: https://codecov.io/gh/zhiwei2017/named_enum

.. pyup badge
.. image:: https://pyup.io/repos/github/zhiwei2017/named_enum/shield.svg
    :target: https://pyup.io/repos/github/zhiwei2017/named_enum/
    :alt: Updates

.. download statistics badge
.. image:: https://pepy.tech/badge/named-enum
    :target: https://pepy.tech/project/named-enum

.. Quality Gate Status
.. image:: https://sonarcloud.io/api/project_badges/measure?project=KnightConan_named_enum&metric=alert_status
    :target: https://sonarcloud.io/dashboard?id=KnightConan_named_enum


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:

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

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

  2. 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>`_ **~ ]**