{"id":24574061,"url":"https://github.com/zhiwei2017/named_enum","last_synced_at":"2025-04-23T12:55:40.078Z","repository":{"id":42197033,"uuid":"159143328","full_name":"zhiwei2017/named_enum","owner":"zhiwei2017","description":"Python named enumeration, which extends the built-in Enum class with extra features. ","archived":false,"fork":false,"pushed_at":"2024-01-11T21:40:47.000Z","size":6413,"stargazers_count":8,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"dev","last_synced_at":"2025-01-09T08:53:20.740Z","etag":null,"topics":["enum","enumeration","extended","metaclass","python3","python310","python311","python37","python38","python39"],"latest_commit_sha":null,"homepage":"https://zhiwei2017.github.io/named_enum/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zhiwei2017.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2018-11-26T09:26:53.000Z","updated_at":"2024-06-22T05:39:16.000Z","dependencies_parsed_at":"2022-08-12T09:10:46.101Z","dependency_job_id":"7ea56c64-a2d5-4055-84b6-2424ad267bd8","html_url":"https://github.com/zhiwei2017/named_enum","commit_stats":{"total_commits":44,"total_committers":2,"mean_commits":22.0,"dds":"0.15909090909090906","last_synced_commit":"f4e1429e7956e11683ff5669ed4485081fbd99c2"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhiwei2017%2Fnamed_enum","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhiwei2017%2Fnamed_enum/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhiwei2017%2Fnamed_enum/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhiwei2017%2Fnamed_enum/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zhiwei2017","download_url":"https://codeload.github.com/zhiwei2017/named_enum/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235350008,"owners_count":18975813,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["enum","enumeration","extended","metaclass","python3","python310","python311","python37","python38","python39"],"created_at":"2025-01-23T20:56:50.465Z","updated_at":"2025-01-23T20:56:51.101Z","avatar_url":"https://github.com/zhiwei2017.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"named-enum\n==========\n\n.. license badge\n.. image:: https://img.shields.io/pypi/l/named-enum.svg\n    :target: https://pypi.python.org/pypi/named-enum/\n\n.. readthedocs badge\n.. image:: https://readthedocs.org/projects/named-enum/badge/?version=latest\n    :target: https://named-enum.readthedocs.io/en/latest/?badge=latest\n    :alt: Documentation Status\n\n.. actions building badge\n.. image:: https://github.com/zhiwei2017/named_enum/workflows/Unit%20Test%20\u0026%20Build%20Test/badge.svg\n    :target: https://github.com/zhiwei2017/named_enum/actions\n\n.. pypi version badge\n.. image:: https://img.shields.io/pypi/v/named-enum.svg\n    :target: https://pypi.python.org/pypi/named-enum/\n\n.. development status from pypi\n.. image:: https://img.shields.io/pypi/status/named-enum.svg\n    :target: https://pypi.python.org/pypi/named-enum/\n\n.. python version badge from PyPI\n.. image:: https://img.shields.io/pypi/pyversions/named-enum.svg\n    :target: https://pypi.python.org/pypi/named-enum/\n    :alt: Python 3.7 | Python 3.8 | Python3.9 | Python3.10 | Python3.11 | 3.12\n\n.. pypi format\n.. image:: https://img.shields.io/pypi/format/named-enum.svg\n    :target: https://badge.fury.io/py/named-enum\n\n.. codecov badge\n.. image:: https://codecov.io/gh/zhiwei2017/named_enum/branch/master/graph/badge.svg\n    :target: https://codecov.io/gh/zhiwei2017/named_enum\n\n.. pyup badge\n.. image:: https://pyup.io/repos/github/zhiwei2017/named_enum/shield.svg\n    :target: https://pyup.io/repos/github/zhiwei2017/named_enum/\n    :alt: Updates\n\n.. download statistics badge\n.. image:: https://pepy.tech/badge/named-enum\n    :target: https://pepy.tech/project/named-enum\n\n.. Quality Gate Status\n.. image:: https://sonarcloud.io/api/project_badges/measure?project=KnightConan_named_enum\u0026metric=alert_status\n    :target: https://sonarcloud.io/dashboard?id=KnightConan_named_enum\n\n\nIntroduction\n------------\n\nThis package provides several enumeration classes, which extends the default\n**Enum** class with various functionalities. For each enumeration class, its\nenumeration item's value is a customised tuple type generated by\n**namedtuple** from **collections** package.\n\nInstallation\n------------\n\nStable release\n``````````````\n\nTo install Named Enum, run this command in your terminal:\n\n.. code-block:: console\n\n    $ pip install named_enum\n\nor\n\n.. code-block:: console\n\n    $ poetry self add named_enum\n\nThis is the preferred method to install Named Enum, as it will always install the most recent stable release.\n\n\nFrom sources\n````````````\n\nThe sources for Named Enum can be downloaded from the `Github repo \u003chttps://github.com/zhiwei2017/named_enum\u003e`_.\n\nYou can either clone the public repository:\n\n.. code-block:: console\n\n    $ git clone https://github.com/zhiwei2017/named_enum.git\n\nOnce you have a copy of the source, you can install it with:\n\n.. code-block:: console\n\n    $ pip install .\n\nor\n\n.. code-block:: console\n\n    $ poetry install\n\nQuick Start\n-----------\n\nEnumeration Creation\n````````````````````\n\nThere are two ways to create an enumeration.\n\n- Use the provided enumeration classes ``ExtendedEnum``, ``LabeledEnum``, ``PairEnum`` to declare your enumeration.\n\n  .. code-block:: python\n\n     from named_enum import ExtendedEnum, LabeledEnum, PairEnum\n\n     class TVCouple(ExtendedEnum):\n         GALLAGHERS = (\"FRANK\", \"MONICA\")\n         MIKE_AND_MOLLY = (\"Mike\", \"Molly\")\n\n     class NBALegendary(LabeledEnum):\n         JOHNSON = (\"Johnson\", \"Magic Johnson\")\n         JORDAN = (\"Jordan\", \"Air Jordan\")\n\n     class Pair(PairEnum):\n         TOM_AND_JERRY = (\"Tom\", \"Jerry\")\n         BULLS = (\"Micheal\", \"Pippen\")\n\n- Customise your own enumeration class and use it to define the enumeration.\n\n  1. Create a new enumeration class\n\n    + Inherit from class ``NamedEnum``\n\n      .. code-block:: python\n\n         from named_enum import NamedEnum\n\n         class TripleEnum(NamedEnum):\n             \"\"\"using a sequence of strings to define the field names\"\"\"\n             _field_names_ = (\"first\", \"second\", \"third\")\n\n    + Use function ``namedenum``\n\n      .. code-block:: python\n\n        from named_enum import namedenum\n\n        # using a sequence of strings to define the field names\n        TripleEnum = namedenum(\"TripleEnum\", (\"first\", \"second\", \"third\"))\n\n        # using a comma/space separated string to define the field names\n        TripleEnum = namedenum(\"LabelEnum\", \"key, label\")\n\n  2. Create enumeration using the customized enumeration class in last step.\n\n      .. code-block:: python\n\n         class AnimationFamily(TripleEnum):\n             SIMPSONS = (\"Homer\", \"Bart\", \"Marge\")\n             DUCKS = (\"Huey\", \"Dewey\", \"Louie\")\n\nUsages\n``````\n+ ``names(as_tuple=True)``\n    ``as_tuple=True``: returns the names of all enumeration items as a tuple.\n\n    .. code-block:: python\n\n      \u003e\u003e\u003e AnimationFamily.names()\n      ('SIMPSONS', 'DUCKS')\n\n    ``as_tuple=False``: returns a generator of the names of all enumeration items.\n\n    .. code-block:: python\n\n      \u003e\u003e\u003e from types import GeneratorType\n      \u003e\u003e\u003e isinstance(AnimationFamily.names(as_tuple=False), GeneratorType)\n      True\n\n+ ``values(as_tuple=True)``\n    ``as_tuple=True``: returns the values of all enumeration items as a tuple.\n\n    .. code-block:: python\n\n      # TripleEnum\n      \u003e\u003e\u003e AnimationFamily.values()\n      (NamedTuple(first='Homer', second='Bart', third='Marge'), NamedTuple(first='Huey', second='Dewey', third='Louie'))\n\n      # ExtendedEnum\n      \u003e\u003e\u003e TVCouple.values()\n      (('FRANK', 'MONICA'), ('Mike', 'Molly'))\n\n    ``as_tuple=False``: returns a generator of the values of all enumeration items.\n\n    .. code-block:: python\n\n      \u003e\u003e\u003e import types\n      \u003e\u003e\u003e isinstance(AnimationFamily.values(as_tuple=False), GeneratorType)\n      True\n\n+ ``describe()``\n    displays the enumeration as a table.\n\n    .. code-block:: python\n\n      # TripleEnum\n      \u003e\u003e\u003e AnimationFamily.describe()\n      Class: AnimationFamily\n          Name | First | Second | Third\n      ---------------------------------\n      SIMPSONS | Homer |   Bart | Marge\n         DUCKS |  Huey |  Dewey | Louie\n      \u003cBLANKLINE\u003e\n\n      # ExtendedEnum\n      \u003e\u003e\u003e TVCouple.describe()\n      Class: TVCouple\n                Name |               Value\n      ------------------------------------\n          GALLAGHERS | ('FRANK', 'MONICA')\n      MIKE_AND_MOLLY |   ('Mike', 'Molly')\n      \u003cBLANKLINE\u003e\n\n+ ``gen(name_value_pair=True)``\n    ``name_value_pair=True``: returns a generator comprised of name-value pair of each enumeration item\n\n    .. code-block:: python\n\n      # TripleEnum\n      \u003e\u003e\u003e tuple(AnimationFamily.gen())\n      (('SIMPSONS', NamedTuple(first='Homer', second='Bart', third='Marge')), ('DUCKS', NamedTuple(first='Huey', second='Dewey', third='Louie')))\n\n      # ExtendedEnum\n      \u003e\u003e\u003e tuple(TVCouple.gen())\n      (('GALLAGHERS', ('FRANK', 'MONICA')), ('MIKE_AND_MOLLY', ('Mike', 'Molly')))\n\n    ``name_value_pair=False``: returns a generator of enumeration items\n\n    .. code-block:: python\n\n      # TripleEnum\n      \u003e\u003e\u003e tuple(AnimationFamily.gen(name_value_pair=False))\n      (\u003cAnimationFamily.SIMPSONS: NamedTuple(first='Homer', second='Bart', third='Marge')\u003e, \u003cAnimationFamily.DUCKS: NamedTuple(first='Huey', second='Dewey', third='Louie')\u003e)\n\n      # ExtendedEnum\n      \u003e\u003e\u003e tuple(TVCouple.gen(name_value_pair=False))\n      (\u003cTVCouple.GALLAGHERS: ('FRANK', 'MONICA')\u003e, \u003cTVCouple.MIKE_AND_MOLLY: ('Mike', 'Molly')\u003e)\n\n+ ``as_dict()``\n    returns a dictionary, in which the key is the enumeration item's name and the value is the item's value\n\n    .. code-block:: python\n\n      # TripleEnum\n      \u003e\u003e\u003e AnimationFamily.as_dict()\n      {'SIMPSONS': NamedTuple(first='Homer', second='Bart', third='Marge'), 'DUCKS': NamedTuple(first='Huey', second='Dewey', third='Louie')}\n\n      # ExtendedEnum\n      \u003e\u003e\u003e TVCouple.as_dict()\n      {'GALLAGHERS': ('FRANK', 'MONICA'), 'MIKE_AND_MOLLY': ('Mike', 'Molly')}\n\n+ ``as_set()``\n    returns a set of tuples containing the enumeration item's name and value\n\n    .. code-block:: python\n\n      # TripleEnum\n      \u003e\u003e\u003e AnimationFamily.as_set()\n      {('SIMPSONS', NamedTuple(first='Homer', second='Bart', third='Marge')), ('DUCKS', NamedTuple(first='Huey', second='Dewey', third='Louie'))}\n\n      # ExtendedEnum\n      \u003e\u003e\u003e TVCouple.as_set()\n      {('GALLAGHERS', ('FRANK', 'MONICA')), ('MIKE_AND_MOLLY', ('Mike', 'Molly'))}\n\n+ ``as_tuple()``\n    returns a tuple of tuples containing the enumeration item's name and value\n\n    .. code-block:: python\n\n      # TripleEnum\n      \u003e\u003e\u003e AnimationFamily.as_tuple()\n      (('SIMPSONS', NamedTuple(first='Homer', second='Bart', third='Marge')), ('DUCKS', NamedTuple(first='Huey', second='Dewey', third='Louie')))\n\n      # ExtendedEnum\n      \u003e\u003e\u003e TVCouple.as_tuple()\n      (('GALLAGHERS', ('FRANK', 'MONICA')), ('MIKE_AND_MOLLY', ('Mike', 'Molly')))\n\n+ ``as_list()``\n    returns a list of tuples containing the enumeration item's name and value\n\n    .. code-block:: python\n\n      # TripleEnum\n      \u003e\u003e\u003e AnimationFamily.as_list()\n      [('SIMPSONS', NamedTuple(first='Homer', second='Bart', third='Marge')), ('DUCKS', NamedTuple(first='Huey', second='Dewey', third='Louie'))]\n\n      # ExtendedEnum\n      \u003e\u003e\u003e TVCouple.as_list()\n      [('GALLAGHERS', ('FRANK', 'MONICA')), ('MIKE_AND_MOLLY', ('Mike', 'Molly'))]\n\n+ ``as_ordereddict()``\n    returns an ordered dict, in which the key is the enumeration item's name and the value is the item's value\n\n    .. code-block:: python\n\n      # TripleEnum\n      \u003e\u003e\u003e AnimationFamily.as_ordereddict()\n      OrderedDict([('SIMPSONS', NamedTuple(first='Homer', second='Bart', third='Marge')), ('DUCKS', NamedTuple(first='Huey', second='Dewey', third='Louie'))])\n\n      # ExtendedEnum\n      \u003e\u003e\u003e TVCouple.as_ordereddict()\n      OrderedDict([('GALLAGHERS', ('FRANK', 'MONICA')), ('MIKE_AND_MOLLY', ('Mike', 'Molly'))])\n\nIf 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:\n\n- ``\u003cfield_name\u003es(as_tuple=True)``\n    ``as_tuple=True``: returns a tuple containing all corresponding values of the field in enumeration items\n\n    .. code-block:: python\n\n      # TripleEnum\n      \u003e\u003e\u003e AnimationFamily.firsts()\n      ('Homer', 'Huey')\n      \u003e\u003e\u003e AnimationFamily.seconds()\n      ('Bart', 'Dewey')\n      \u003e\u003e\u003e AnimationFamily.thirds()\n      ('Marge', 'Louie')\n\n      # LabeledEnum\n      \u003e\u003e\u003e NBALegendary.keys()\n      ('Johnson', 'Jordan')\n      \u003e\u003e\u003e NBALegendary.labels()\n      ('Magic Johnson', 'Air Jordan')\n\n    ``as_tuple=False``: returns a generator of all corresponding values of the field in enumeration items\n\n    .. code-block:: python\n\n      # TripleEnum\n      \u003e\u003e\u003e isinstance(AnimationFamily.firsts(as_tuple=False), GeneratorType)\n      True\n\n- ``from_\u003cfield_name\u003e(field_value, as_tuple=True)``\n    ``as_tuple=True``: returns a tuple containing **all enumeration items** which has the given ``field_value`` in corresponding field\n\n    .. code-block:: python\n\n      # TripleEnum\n      \u003e\u003e\u003e AnimationFamily.from_first('Homer')\n      (\u003cAnimationFamily.SIMPSONS: NamedTuple(first='Homer', second='Bart', third='Marge')\u003e,)\n\n      \u003e\u003e\u003e AnimationFamily.from_second('Dewey')\n      (\u003cAnimationFamily.DUCKS: NamedTuple(first='Huey', second='Dewey', third='Louie')\u003e,)\n\n      \u003e\u003e\u003e AnimationFamily.from_third('Marge')\n      (\u003cAnimationFamily.SIMPSONS: NamedTuple(first='Homer', second='Bart', third='Marge')\u003e,)\n\n      # LabeledEnum\n      \u003e\u003e\u003e NBALegendary.from_key('Johnson')\n      (\u003cNBALegendary.JOHNSON: NamedTuple(key='Johnson', label='Magic Johnson')\u003e,)\n\n      \u003e\u003e\u003e NBALegendary.from_label('Air Jordan')\n      (\u003cNBALegendary.Jordan: NamedTuple(key='Jordan', label='Air Jordan')\u003e,)\n\n    ``as_tuple=False``: returns a generator of **all enumeration items** which has the given ``field_value`` in corresponding field\n\n    .. code-block:: python\n\n      # TripleEnum\n      \u003e\u003e\u003e isinstance(AnimationFamily.from_first('Homer', as_tuple=False), GeneratorType)\n      True\n\n- ``has_\u003cfield_name\u003e(field_value)``\n    returns a boolean value to indicate whether there is at least one enumeration item has the given ``field_value`` in corresponding field\n\n    .. code-block:: python\n\n      # TripleEnum\n      \u003e\u003e\u003e AnimationFamily.has_first('Homer')\n      True\n      \u003e\u003e\u003e AnimationFamily.has_first('Holmes')\n      False\n\n      \u003e\u003e\u003e AnimationFamily.has_second('Dewey')\n      True\n      \u003e\u003e\u003e AnimationFamily.has_second('David')\n      False\n\n      \u003e\u003e\u003e AnimationFamily.has_third('Louie')\n      True\n      \u003e\u003e\u003e AnimationFamily.has_third('Louis')\n      False\n\n      # LabeledEnum\n      \u003e\u003e\u003e NBALegendary.has_key('Johnson')\n      True\n      \u003e\u003e\u003e NBALegendary.has_key('John')\n      False\n\n      \u003e\u003e\u003e NBALegendary.has_label('Air Jordan')\n      True\n      \u003e\u003e\u003e NBALegendary.has_label('The Black Mamba')\n      False\n\nDocumentation\n-------------\nThe documentation about this project is available in\n`Read the Docs \u003chttps://named-enum.readthedocs.io/en/latest/\u003e`_.\n\nAcknowledgement\n---------------\n- `Cristian Alfonso González Mora \u003chttps://github.com/cagonza6/\u003e`_ for the inspiration of this project.\n\nAuthor\n------\n\n* `Zhiwei Zhang \u003chttps://github.com/zhiwei2017\u003e`_ - *Maintainer* - `zhiwei2017@gmail.com \u003cmailto:zhiwei2017@gmail.com?subject=[GitHub]Named%20Enum\u003e`_\n* `Jianlan Shao \u003chttps://github.com/Lan314\u003e`_ - *Developer* - `jianlan.shao@gmail.com \u003cmailto:jianlan.shao@gmail.com?subject=[GitHub]Named%20Enum\u003e`_\n\n**[ ~ Dependencies scanned by** `PyUp.io \u003chttps://pyup.io\u003e`_ **~ ]**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhiwei2017%2Fnamed_enum","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzhiwei2017%2Fnamed_enum","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhiwei2017%2Fnamed_enum/lists"}