Metadata-Version: 2.1
Name: named_enum
Version: 1.1.0
Summary: Python named enumeration, which extends the built-in Enum class with extra features.
Home-page: https://github.com/zhiwei2017/named_enum
Author: Zhiwei Zhang
Author-email: zhiwei2017@gmail.com
License: MIT
Description: 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.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/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
        
        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
        
            $ python setup.py install
        
        or
        
        .. code-block:: console
        
            $ pip 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>`_
        
        **[ ~ Dependencies scanned by** `PyUp.io <https://pyup.io>`_ **~ ]**
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
Provides-Extra: docs
