extended-enum 完整使用文档一、extended-enum 概述与核心功能1. 基础介绍extended-enum是 Python 第三方枚举增强库基于标准库enum.Enum做功能扩展解决原生枚举短板原生 Enum 仅支持名称、值映射缺少多字段存储、序列化、数据库映射、快速检索、自动生成标签/描述、字典互转、校验、批量操作等能力。项目核心定位带附加属性的增强枚举兼容标准 Enum 所有语法无缝迁移原生枚举代码。2. 核心功能清单多附属字段绑定单个枚举项可存储 name、value、label、desc、code、sort、status 等任意自定义字段无需额外字典映射多维度反向查找支持按 value、label、自定义字段快速查询枚举实例原生 Enum 仅能按 value/name 查找序列化与反序列化一键转字典、JSON、元组列表支持数据库 ORM 直接存储/读取内置校验工具判断值是否合法、批量校验输入数组、获取所有合法取值集合排序与过滤按自定义 sort 字段排序、按状态/标签筛选子集枚举别名与兼容兼容原生 Enum__members__、Enum(value)构造方式支持自定义别名自动属性访问通过.label.desc直接读取附加字段无需封装类批量工具获取全部选项、下拉框数据源、前端枚举常量导出空值/默认值兼容支持设置默认枚举项、空输入兜底。二、安装方式1. pip 标准安装pipinstallextended-enum2. 指定版本安装pipinstallextended-enum0.4.03. 源码安装开发版gitclone https://github.com/yourname/extended-enum.gitcdextended-enum python setup.pyinstall4. 依赖说明仅依赖 Python 内置库enum、json无第三方额外依赖支持 Python3.7~3.12。三、基础语法、核心类与参数说明3.1 核心导入fromextended_enumimportExtendedEnum,EnumFieldExtendedEnum增强枚举基类继承它定义业务枚举EnumField枚举字段构造器用于定义多属性枚举项。3.2 EnumField 构造参数核心EnumField(value, labelNone, descNone, sort0, **kwargs)参数类型说明value任意可哈希类型(int/str)枚举唯一主键等价原生 Enum 的 value查询核心键labelstr展示标签前端下拉、页面展示用descstr详细描述日志、文档、注释展示sortint排序权重list()输出时按 sort 升序排列**kwargs任意键值自定义扩展字段如status1、is_validTrue、db_codeA013.3 ExtendedEnum 内置方法与属性实例属性单个枚举项假设枚举实例Status.ENABLE.name枚举常量名如ENABLE.value主键值.label标签.desc描述.sort排序值自定义字段直接访问.is_valid、.db_code类方法全局枚举操作get_by_value(val, defaultNone)按 value 查找枚举找不到返回 defaultget_by_label(label, defaultNone)按 label 反向查找get_by_field(field_name, field_val, defaultNone)按任意自定义字段查找values()返回所有 value 列表labels()返回所有 label 列表items()返回[(value, label), ...]下拉框数据源to_dict()全枚举转为字典{value: 完整字段dict}to_json()输出 JSON 字符串is_valid(val)判断传入 value 是否属于合法枚举filter_by(field, target_val)筛选指定字段匹配的枚举子集sorted_list()按 sort 字段升序返回枚举实例列表__members__兼容原生枚举返回常量名-实例映射3.4 基础定义语法模板fromextended_enumimportExtendedEnum,EnumFieldclassOrderStatus(ExtendedEnum):# 格式常量名 EnumField(主键值, 标签, 描述, 排序, 自定义参数)PENDINGEnumField(0,待支付,用户已下单未付款,sort1,is_endFalse)PAIDEnumField(1,已支付,付款完成待发货,sort2,is_endFalse)DELIVEREDEnumField(2,已发货,商品出库配送,sort3,is_endFalse)FINISHEnumField(3,已完成,订单签收结束,sort4,is_endTrue)CANCELEnumField(9,已取消,用户主动取消,sort5,is_endTrue)四、8 个完整实战应用案例案例1后端接口下拉框数据源最常用场景后端返回前端下拉选择列表需要 valuelabel 二元组fromextended_enumimportExtendedEnum,EnumFieldclassOrderStatus(ExtendedEnum):PENDINGEnumField(0,待支付,未付款订单,sort1)PAIDEnumField(1,已支付,待发货,sort2)FINISHEnumField(3,已完成,sort3)# 获取前端下拉数据源dropdownOrderStatus.items()print(dropdown)# 输出[(0, 待支付), (1, 已支付), (3, 已完成)]# FastAPI/Flask 接口直接返回# return {options: OrderStatus.items()}案例2按 value/自定义字段反向查询枚举场景数据库存储数字值业务代码转换为带标签的枚举对象# 数据库取出状态值 db_status 1db_status1statusOrderStatus.get_by_value(db_status)print(status.label)# 已支付# 按自定义字段查询筛选已结束订单end_statusOrderStatus.get_by_field(is_end,True,defaultNone)案例3参数合法性校验接口入参校验场景校验前端传入状态码是否合法防止非法参数defcheck_order_status(input_status):ifnotOrderStatus.is_valid(input_status):raiseValueError(f非法订单状态{input_status})returnOrderStatus.get_by_value(input_status)check_order_status(0)# 正常# check_order_status(99) # 抛出异常案例4枚举转JSON前后端全量常量下发场景前端需要全量枚举常量做本地判断一次性序列化所有属性json_strOrderStatus.to_json()print(json_str)# {0: {value:0,label:待支付,desc:未付款订单,sort:1}, 1: {...}}案例5业务状态过滤筛选完结/进行中订单场景报表统计只需要已完成、已取消的完结订单# 筛选所有 is_endTrue 的枚举end_status_listOrderStatus.filter_by(is_end,True)print([item.labelforiteminend_status_list])# [已完成, 已取消]案例6ORM 数据库映射存储与读取场景SQLAlchemy/ Django ORM 存数字读取自动转枚举对象# 存入数据库直接取 .valuestatus_valOrderStatus.PENDING.value# 0# 从数据库读取后还原枚举db_val3order_statusOrderStatus.get_by_value(db_val)print(f状态名称{order_status.name}, 展示名{order_status.label})案例7按 sort 自定义排序输出枚举场景页面下拉需要自定义展示顺序不按 value 数字排序# 定义时 sort 打乱classUserLevel(ExtendedEnum):VIP3EnumField(3,VIP3,sort1)VIP1EnumField(1,VIP1,sort2)VIP2EnumField(2,VIP2,sort3)# 按sort升序输出sorted_levelsUserLevel.sorted_list()print([item.labelforiteminsorted_levels])# [VIP3, VIP1, VIP2]案例8批量日志打印、异常文案统一管理场景错误码枚举统一管理错误码、错误文案、日志描述classErrorCode(ExtendedEnum):PARAM_ERREnumField(1001,参数非法,接口请求参数缺失或格式错误,sort1)AUTH_FAILEnumField(2001,登录失效,token过期请重新登录,sort2)ORDER_NOT_EXISTEnumField(3001,订单不存在,查询的订单ID未找到,sort3)# 全局异常捕获统一返回defget_err_msg(code:int):errErrorCode.get_by_value(code)return{code:err.value,msg:err.label,log_desc:err.desc}print(get_err_msg(1001))# {code: 1001, msg: 参数非法, log_desc: 接口请求参数缺失或格式错误}五、常见错误、报错原因与解决方案错误1LookupError: No matching enum found触发代码OrderStatus.get_by_value(99)且未传 default原因传入的 value 在枚举中不存在无兜底默认值解决传入 default 参数捕获空值statusOrderStatus.get_by_value(99,defaultNone)ifstatusisNone:print(状态不存在)错误2AttributeError: ‘ExtendedEnum’ object has no attribute ‘xxx’原因1未在 EnumField 定义自定义字段直接访问.xxx解决定义时补充xxxxxx_value原因2常量名拼写错误如.PAID写成.PAIDED解决核对枚举常量名称错误3TypeError: unhashable type: ‘list’原因EnumField 的 value 使用列表、字典等不可哈希类型value 必须 int/str/tuple解决value 改用字符串或数字主键错误4多个枚举项 value 重复报错ValueError: duplicate enum value原因不同常量设置了相同 valuevalue 是唯一索引解决保证每个枚举项 value 全局唯一错误5filter_by 返回空列表原因筛选字段名/字段值不匹配大小写、类型不一致如数字1和字符串1解决统一字段值数据类型核对字段名拼写错误6to_json 序列化报错自定义对象无法序列化原因EnumField 传入了无法 json 序列化的自定义字段datetime、自定义类实例解决存储基础类型int/str/bool复杂对象转字符串存储错误7继承普通 Enum 混用 ExtendedEnum 方法fromenumimportEnumclassDemo(Enum):A0Demo.items()# 报错原因仅ExtendedEnum拥有扩展方法原生 Enum 无 items/get_by_value 等解决基类改为ExtendedEnum六、使用注意事项与最佳实践1. 定义规范枚举常量名统一大写下划线ORDER_PAID遵循常量命名规范value 优先使用 int数据库存储更节省空间前端展示文字统一放入 label业务区分字段全部通过EnumField关键字参数传入不要使用外部字典映射sort 统一规划避免后期下拉顺序混乱。2. 查询与容错规范所有外部输入接口参数、数据库读取查询枚举必须加defaultNone兜底参数校验统一使用.is_valid()不要手动判断 value 是否在列表多业务区分使用独立枚举类订单状态、用户等级、错误码分开定义。3. 序列化与前后端交互前端下拉框固定使用.items()轻量化仅返回 value-label前端需要完整常量配置使用.to_json()禁止直接将枚举实例对象返回接口必须转字典/元组。4. 性能注意枚举类加载后全局缓存无需重复实例化百万次循环查询.get_by_value()性能优于字典底层做了哈希缓存超大枚举100项不建议一次性 to_json按需 filter 子集下发。5. 兼容性完全兼容原生 Enum 写法原有Enum(1)、OrderStatus.PAID.name均可正常使用可与 Pydantic、FastAPI 搭配做类型校验直接作为模型字段类型不支持运行时动态新增枚举项枚举为静态常量如需动态配置请使用数据库字典表。6. 避坑要点不要把业务逻辑写在枚举类内枚举仅存储静态属性自定义字段避免使用保留关键字value、label、desc、sort、name布尔类筛选字段统一命名is_xxxis_end、is_valid便于过滤不要使用浮点数作为 value浮点精度会导致查找匹配失败。《动手学PyTorch建模与应用:从深度学习到大模型》是一本从零基础上手深度学习和大模型的PyTorch实战指南。全书共11章前6章涵盖深度学习基础包括张量运算、神经网络原理、数据预处理及卷积神经网络等后5章进阶探讨图像、文本、音频建模技术并结合Transformer架构解析大语言模型的开发实践。书中通过房价预测、图像分类等案例讲解模型构建方法每章附有动手练习题帮助读者巩固实战能力。内容兼顾数学原理与工程实现适配PyTorch框架最新技术发展趋势。