# py-enum
[](https://github.com/SkylerHu/py-enum)
[](https://github.com/SkylerHu/py-enum)
[](https://github.com/SkylerHu/py-enum)
[](https://github.com/SkylerHu/py-enum)
[](https://github.com/SkylerHu/py-enum)
[](https://github.com/SkylerHu/py-enum)
[](https://github.com/SkylerHu/py-enum)
[](https://github.com/SkylerHu/py-enum)
A python ChoiceEnum module for python3.
继承原生的 ·enum.Enum· 而来，扩展类`ChoiceEnum`用于以下场景：
- argparse使用 `add_argument` 的参数 `choices`
- Django中 `models.CharField` 的参数 `choices`
- Django REST framework `ChoiceField` 的参数 `choices`
## 1. 安装
pip install py-enum
可查看版本变更记录[ChangeLog](https://github.com/SkylerHu/py-enum/blob/master/docs/CHANGELOG-2.x.md)
## 2. 使用(Usage)
### 2.1 用ChoiceEnum定义枚举
```python
# 导入
from py_enum import ChoiceEnum
# 定义
class Color(ChoiceEnum):
RED = (1, '红色')
GREEN = (2, '绿色')
BLUE = (3, '蓝色', {'value': 'blue'})
class Status(ChoiceEnum):
PROCESSING = ('processing', '处理中')
APPROVED = ('approved', '已审批')
CANCELED = ('canceled', '已取消')
CLOSED = ('closed', '已关闭')
```
定义如上，按照`Key = (value, label, extra)`的形式进行定义，value定义的值；label是对值的描述；第三个参数是extra，额外信息，可以任意类型。
### 2.2 基础用法
```python
Color.RED # Color.RED
Color.RED.value # 1
type(Color.RED) # <enum 'Color'>
str(Color.RED) # (1, 红色)
len(colors) == 3 # true
Color.RED.value in Color # true
1 in Color # true
0 not in Color # true
# 以下是在原生基础上扩展的属性和方法
Color.values # [1, 2, 3]
Color.names # ['RED', 'GREEN', 'BLUE']
Color.labels # ['红色', '绿色', '蓝色']
Color.choices # [(1, '红色'), (2, '绿色'), (3, '蓝色')]
Color.get_label(Color.RED.value) # '红色'
Color.get_extra(Color.BLUE.value) # {'value': 'blue'}
for member in Color:
print(member.value, member.label) # 直接遍历value和label
# 1, '红色'
# 2, '绿色'
# 3, '蓝色'
Color.to_js_enum()
# 输出dict数据，可以通过接口序列化后给前端使用，结合js-enumerate前端枚举库
"""
[
{"key": "RED", "value": 1, "label": "红色"},
{"key": "GREEN", "value": 2, "label": "绿色"},
{"key": "BLUE", "value": 3, "label": "蓝色", "extra": {"value": "blue"}}
]
"""
```
### 2.3 枚举对象实例化
```python
member = Color(Color.RED.value) # 或者 Color(1)
member.value == 1 # true
member.name == 'RED' # true
member.label == '红色' # true
member.option == (1, '红色') # true
member.extra == None # true，因为没有定义
# 以上几个属性无法修改，直接赋值会抛出AttributeError异常
member.value in Color # true
```
### 2.4 在Python argparse中使用
```python
import argparse
parser = argparse.ArgumentParser(description='test ChoiceEnum use in argparse.')
parser.add_argument('--color', type=int, choices=Color, required=True)
args = parser.parse_args(['--color', str(Color.RED.value)])
# args.color == Color.RED.value
```
### 2.5 在Django中使用
```python
from django.db import models
class ColorModel(models.Model):
color = models.IntegerField(verbose_name='颜色', choices=Color.choices, default=Color.RED.value)
instance = ColorModel.objects.create()
assert instance.color == colors.RED.value
instance.color = colors.BLUE.value
instance.save()
```
### 2.6 在DRF中使用
```python
from rest_framework import serializers
class ColorSerializer(serializers.Serializer):
color = serializers.ChoiceField(help_text='选择颜色', choices=Color.choices, default=Color.RED.value)
s = ColorSerializer()
s = ColorSerializer(data={'status': status.CLOSED.value})
assert s.is_valid() is True
s = ColorSerializer(data={'status': 1})
assert s.is_valid() is True
s = ColorSerializer(data={'status': 0})
assert s.is_valid() is False # 值不在枚举定义范围内，校验不通过
```
## 3. 对比
- `ChoiceEnum`和Django的 models.Choices 的优势在于低版本Django也能使用，且普通Python项目脚本也能使用
- 新增了额外的特性
- 额外多出了`ChoiceEnum.extra`的用法，对不同枚举成员做映射配置相关场景可以使用
- 增加方法`ChoiceEnum.to_js_enum`返回数组数据，可以用于前端枚举库 [js-enumerate](https://github.com/SkylerHu/js-enum) 初始化使用
Raw data
{
"_id": null,
"home_page": "https://github.com/SkylerHu/py-enum.git",
"name": "py-enum",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "python, enum, ChoiceEnum, enumerate",
"author": "SkylerHu",
"author_email": "skylerhu@qq.com",
"download_url": "https://files.pythonhosted.org/packages/fd/5a/c76910499dfb2e093af427b41a84876db5c266421920a660f6e0638ce80c/py_enum-2.1.1.tar.gz",
"platform": "any",
"description": "# py-enum\n\n[](https://github.com/SkylerHu/py-enum)\n[](https://github.com/SkylerHu/py-enum)\n[](https://github.com/SkylerHu/py-enum)\n[](https://github.com/SkylerHu/py-enum)\n[](https://github.com/SkylerHu/py-enum)\n[](https://github.com/SkylerHu/py-enum)\n[](https://github.com/SkylerHu/py-enum)\n[](https://github.com/SkylerHu/py-enum)\n\nA python ChoiceEnum module for python3.\n\n\u7ee7\u627f\u539f\u751f\u7684 \u00b7enum.Enum\u00b7 \u800c\u6765\uff0c\u6269\u5c55\u7c7b`ChoiceEnum`\u7528\u4e8e\u4ee5\u4e0b\u573a\u666f\uff1a\n- argparse\u4f7f\u7528 `add_argument` \u7684\u53c2\u6570 `choices`\n- Django\u4e2d `models.CharField` \u7684\u53c2\u6570 `choices`\n- Django REST framework `ChoiceField` \u7684\u53c2\u6570 `choices`\n\n\n## 1. \u5b89\u88c5\n\n\tpip install py-enum\n\n\u53ef\u67e5\u770b\u7248\u672c\u53d8\u66f4\u8bb0\u5f55[ChangeLog](https://github.com/SkylerHu/py-enum/blob/master/docs/CHANGELOG-2.x.md)\n\n## 2. \u4f7f\u7528(Usage)\n\n### 2.1 \u7528ChoiceEnum\u5b9a\u4e49\u679a\u4e3e\n\n```python\n# \u5bfc\u5165\nfrom py_enum import ChoiceEnum\n\n# \u5b9a\u4e49\nclass Color(ChoiceEnum):\n RED = (1, '\u7ea2\u8272')\n GREEN = (2, '\u7eff\u8272')\n BLUE = (3, '\u84dd\u8272', {'value': 'blue'})\n\nclass Status(ChoiceEnum):\n PROCESSING = ('processing', '\u5904\u7406\u4e2d')\n APPROVED = ('approved', '\u5df2\u5ba1\u6279')\n CANCELED = ('canceled', '\u5df2\u53d6\u6d88')\n CLOSED = ('closed', '\u5df2\u5173\u95ed')\n```\n\u5b9a\u4e49\u5982\u4e0a\uff0c\u6309\u7167`Key = (value, label, extra)`\u7684\u5f62\u5f0f\u8fdb\u884c\u5b9a\u4e49\uff0cvalue\u5b9a\u4e49\u7684\u503c\uff1blabel\u662f\u5bf9\u503c\u7684\u63cf\u8ff0\uff1b\u7b2c\u4e09\u4e2a\u53c2\u6570\u662fextra\uff0c\u989d\u5916\u4fe1\u606f\uff0c\u53ef\u4ee5\u4efb\u610f\u7c7b\u578b\u3002\n\n### 2.2 \u57fa\u7840\u7528\u6cd5\n```python\nColor.RED # Color.RED\nColor.RED.value # 1\ntype(Color.RED) # <enum 'Color'>\nstr(Color.RED) # (1, \u7ea2\u8272)\nlen(colors) == 3 # true\nColor.RED.value in Color # true\n1 in Color # true\n0 not in Color # true\n\n# \u4ee5\u4e0b\u662f\u5728\u539f\u751f\u57fa\u7840\u4e0a\u6269\u5c55\u7684\u5c5e\u6027\u548c\u65b9\u6cd5\nColor.values # [1, 2, 3]\nColor.names # ['RED', 'GREEN', 'BLUE']\nColor.labels # ['\u7ea2\u8272', '\u7eff\u8272', '\u84dd\u8272']\nColor.choices # [(1, '\u7ea2\u8272'), (2, '\u7eff\u8272'), (3, '\u84dd\u8272')]\n\nColor.get_label(Color.RED.value) # '\u7ea2\u8272'\nColor.get_extra(Color.BLUE.value) # {'value': 'blue'}\n\nfor member in Color:\n print(member.value, member.label) # \u76f4\u63a5\u904d\u5386value\u548clabel\n# 1, '\u7ea2\u8272'\n# 2, '\u7eff\u8272'\n# 3, '\u84dd\u8272'\n\nColor.to_js_enum()\n# \u8f93\u51fadict\u6570\u636e\uff0c\u53ef\u4ee5\u901a\u8fc7\u63a5\u53e3\u5e8f\u5217\u5316\u540e\u7ed9\u524d\u7aef\u4f7f\u7528\uff0c\u7ed3\u5408js-enumerate\u524d\u7aef\u679a\u4e3e\u5e93\n\"\"\"\n[\n {\"key\": \"RED\", \"value\": 1, \"label\": \"\u7ea2\u8272\"},\n {\"key\": \"GREEN\", \"value\": 2, \"label\": \"\u7eff\u8272\"},\n {\"key\": \"BLUE\", \"value\": 3, \"label\": \"\u84dd\u8272\", \"extra\": {\"value\": \"blue\"}}\n]\n\"\"\"\n```\n\n### 2.3 \u679a\u4e3e\u5bf9\u8c61\u5b9e\u4f8b\u5316\n```python\nmember = Color(Color.RED.value) # \u6216\u8005 Color(1)\nmember.value == 1 # true\nmember.name == 'RED' # true\nmember.label == '\u7ea2\u8272' # true\nmember.option == (1, '\u7ea2\u8272') # true\nmember.extra == None # true\uff0c\u56e0\u4e3a\u6ca1\u6709\u5b9a\u4e49\n# \u4ee5\u4e0a\u51e0\u4e2a\u5c5e\u6027\u65e0\u6cd5\u4fee\u6539\uff0c\u76f4\u63a5\u8d4b\u503c\u4f1a\u629b\u51faAttributeError\u5f02\u5e38\nmember.value in Color # true\n```\n\n### 2.4 \u5728Python argparse\u4e2d\u4f7f\u7528\n```python\nimport argparse\n\nparser = argparse.ArgumentParser(description='test ChoiceEnum use in argparse.')\nparser.add_argument('--color', type=int, choices=Color, required=True)\nargs = parser.parse_args(['--color', str(Color.RED.value)])\n# args.color == Color.RED.value\n```\n\n### 2.5 \u5728Django\u4e2d\u4f7f\u7528\n```python\nfrom django.db import models\n\nclass ColorModel(models.Model):\n color = models.IntegerField(verbose_name='\u989c\u8272', choices=Color.choices, default=Color.RED.value)\n\ninstance = ColorModel.objects.create()\nassert instance.color == colors.RED.value\ninstance.color = colors.BLUE.value\ninstance.save()\n```\n\n### 2.6 \u5728DRF\u4e2d\u4f7f\u7528\n```python\nfrom rest_framework import serializers\n\nclass ColorSerializer(serializers.Serializer):\n color = serializers.ChoiceField(help_text='\u9009\u62e9\u989c\u8272', choices=Color.choices, default=Color.RED.value)\n\ns = ColorSerializer()\ns = ColorSerializer(data={'status': status.CLOSED.value})\nassert s.is_valid() is True\ns = ColorSerializer(data={'status': 1})\nassert s.is_valid() is True\ns = ColorSerializer(data={'status': 0})\nassert s.is_valid() is False # \u503c\u4e0d\u5728\u679a\u4e3e\u5b9a\u4e49\u8303\u56f4\u5185\uff0c\u6821\u9a8c\u4e0d\u901a\u8fc7\n```\n\n## 3. \u5bf9\u6bd4\n- `ChoiceEnum`\u548cDjango\u7684 models.Choices \u7684\u4f18\u52bf\u5728\u4e8e\u4f4e\u7248\u672cDjango\u4e5f\u80fd\u4f7f\u7528\uff0c\u4e14\u666e\u901aPython\u9879\u76ee\u811a\u672c\u4e5f\u80fd\u4f7f\u7528\n- \u65b0\u589e\u4e86\u989d\u5916\u7684\u7279\u6027\n - \u989d\u5916\u591a\u51fa\u4e86`ChoiceEnum.extra`\u7684\u7528\u6cd5\uff0c\u5bf9\u4e0d\u540c\u679a\u4e3e\u6210\u5458\u505a\u6620\u5c04\u914d\u7f6e\u76f8\u5173\u573a\u666f\u53ef\u4ee5\u4f7f\u7528\n - \u589e\u52a0\u65b9\u6cd5`ChoiceEnum.to_js_enum`\u8fd4\u56de\u6570\u7ec4\u6570\u636e\uff0c\u53ef\u4ee5\u7528\u4e8e\u524d\u7aef\u679a\u4e3e\u5e93 [js-enumerate](https://github.com/SkylerHu/js-enum) \u521d\u59cb\u5316\u4f7f\u7528\n",
"bugtrack_url": null,
"license": "MIT Licence",
"summary": "enums for choices fields",
"version": "2.1.1",
"project_urls": {
"Homepage": "https://github.com/SkylerHu/py-enum.git"
},
"split_keywords": [
"python",
" enum",
" choiceenum",
" enumerate"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2460d372bd6e6c118ccfa3d6dc64c6dfa4a92f17f2f7c6f210d9384022ec2763",
"md5": "c300935d9a8773fec2f77681edd17702",
"sha256": "fa89cf4b008bf869edd960d84e8178ae86d88a31a5c5e588a860b0d19b9471cc"
},
"downloads": -1,
"filename": "py_enum-2.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c300935d9a8773fec2f77681edd17702",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 6957,
"upload_time": "2025-09-02T16:22:56",
"upload_time_iso_8601": "2025-09-02T16:22:56.638177Z",
"url": "https://files.pythonhosted.org/packages/24/60/d372bd6e6c118ccfa3d6dc64c6dfa4a92f17f2f7c6f210d9384022ec2763/py_enum-2.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "fd5ac76910499dfb2e093af427b41a84876db5c266421920a660f6e0638ce80c",
"md5": "cf9067756a80f5468cf451b51f3662f9",
"sha256": "5eb2c16b77ef867f472fd8714480b0802c63fb466fd858b04efa0f3a816a2121"
},
"downloads": -1,
"filename": "py_enum-2.1.1.tar.gz",
"has_sig": false,
"md5_digest": "cf9067756a80f5468cf451b51f3662f9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 9759,
"upload_time": "2025-09-02T16:22:58",
"upload_time_iso_8601": "2025-09-02T16:22:58.095244Z",
"url": "https://files.pythonhosted.org/packages/fd/5a/c76910499dfb2e093af427b41a84876db5c266421920a660f6e0638ce80c/py_enum-2.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-02 16:22:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SkylerHu",
"github_project": "py-enum",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "py-enum"
}
JSON
