https://github.com/zhiwei2017/named_enum
Python named enumeration, which extends the built-in Enum class with extra features.
https://github.com/zhiwei2017/named_enum
enum enumeration extended metaclass python3 python310 python311 python37 python38 python39
Last synced: 9 months ago
JSON representation
Python named enumeration, which extends the built-in Enum class with extra features.
- Host: GitHub
- URL: https://github.com/zhiwei2017/named_enum
- Owner: zhiwei2017
- License: mit
- Created: 2018-11-26T09:26:53.000Z (about 7 years ago)
- Default Branch: dev
- Last Pushed: 2024-01-11T21:40:47.000Z (almost 2 years ago)
- Last Synced: 2025-01-09T08:53:20.740Z (12 months ago)
- Topics: enum, enumeration, extended, metaclass, python3, python310, python311, python37, python38, python39
- Language: Python
- Homepage: https://zhiwei2017.github.io/named_enum/
- Size: 6.12 MB
- Stars: 8
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.rst
- Contributing: CONTRIBUTING.rst
- License: LICENSE
Awesome Lists containing this project
README
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 `_.
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
# ExtendedEnum
>>> TVCouple.describe()
Class: TVCouple
Name | Value
------------------------------------
GALLAGHERS | ('FRANK', 'MONICA')
MIKE_AND_MOLLY | ('Mike', 'Molly')
+ ``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))
(, )
# ExtendedEnum
>>> tuple(TVCouple.gen(name_value_pair=False))
(, )
+ ``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:
- ``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_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.from_second('Dewey')
(,)
>>> AnimationFamily.from_third('Marge')
(,)
# LabeledEnum
>>> NBALegendary.from_key('Johnson')
(,)
>>> NBALegendary.from_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_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 `_.
Acknowledgement
---------------
- `Cristian Alfonso González Mora `_ for the inspiration of this project.
Author
------
* `Zhiwei Zhang `_ - *Maintainer* - `zhiwei2017@gmail.com `_
* `Jianlan Shao `_ - *Developer* - `jianlan.shao@gmail.com `_
**[ ~ Dependencies scanned by** `PyUp.io `_ **~ ]**