Metadata-Version: 2.1
Name: named-enum
Version: 1.0.2
Summary: Named Enumeration
Home-page: https://github.com/KnightConan/named_enum
Author: Zhiwei Zhang
Author-email: zhiwei2017@gmail.com
License: MIT License
Platform: UNKNOWN
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: MIT License
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: Implementation
Classifier: Topic :: Utilities
Classifier: Natural Language :: English
Classifier: Intended Audience :: Developers
Description-Content-Type: text/x-rst

==========
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/KnightConan/named_enum/workflows/Unit%20Test%20&%20Build%20Test/badge.svg
    :target: https://github.com/KnightConan/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.6 | Python 3.7 | Python 3.8

.. 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/KnightConan/named_enum/branch/master/graph/badge.svg
    :target: https://codecov.io/gh/KnightConan/named_enum

.. pyup badge
.. image:: https://pyup.io/repos/github/KnightConan/named_enum/shield.svg
    :target: https://pyup.io/repos/github/KnightConan/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.

If you like it, please |start|_ it in |github|_.

.. |start| image:: https://img.icons8.com/material-rounded/26/000000/star.png
    :alt: star

.. |github| image:: https://img.icons8.com/small/26/000000/github.png
    :alt: github

.. _github: https://github.com/KnightConan/named_enum

.. _start: https://github.com/KnightConan/named_enum

Installation
------------

    .. code-block:: console

        pip install named-enum

running test
````````````

    .. code-block:: console

        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.

  .. 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/>`_.

License
-------
`MIT <https://github.com/KnightConan/named_enum/blob/master/LICENSE>`_

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


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

