Metadata-Version: 2.1
Name: named_enum
Version: 1.0.1
Summary: Named Enumeration
Home-page: https://github.com/KnightConan/named_enum
Author: Zhiwei Zhang
Author-email: zhiwei2017@gmail.com
License: MIT License
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/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
        
        .. send message to the author
        .. image:: https://img.shields.io/badge/saythanks.io-☼-1EAEDB.svg
            :target: https://saythanks.io/to/KnightConan
        
        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>`_ **~ ]**
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
