Metadata-Version: 2.1
Name: excode
Version: 0.1.4
Summary: 统一的异常与错误码管理包
Home-page: https://github.com/zhenzi0322-package/excode
Author: 
Author-email:  <>
License: MIT
Requires-Python: >=3.8
description-content-type: text/markdown
Description:
 <p align="center">
   <h1>excode</h1>
   <a href="https://pypi.org/project/excode/"><img src="https://img.shields.io/pypi/v/excode.svg" alt="PyPI version"></a>
   <a href="https://pypi.org/project/excode/"><img src="https://img.shields.io/badge/Python-3.8~3.14-3776AB?logo=python&logoColor=white" alt="Python"></a>
   <a href="https://github.com/zhenzi0322/excode/blob/main/LICENSE"><img src="https://img.shields.io/pypi/l/excode.svg" alt="License"></a>
   <a href="https://tool.long920.cn/excode"><img src="https://app.readthedocs.org/projects/zhenzi0322-tool/badge/?version=latest" alt="Documentation Status"></a>
 </p>
 
 > 统一的异常与错误码管理`Python`包，提供标准化的异常类、错误码枚举以及错误处理工具函数。
 
 ## 安装
 
 ```bash
 pip install excode
 ```
 
 ## 快速开始
 
 ```python
 from excode import ExCodeError, ErrorCode, raise_for_error
 
 # 根据错误码自动抛出对应异常
 try:
     raise_for_error(ErrorCode.AUTHENTICATION_ERROR)
 except ExCodeError as e:
     print(e)  # [1002] 认证失败，API Key 无效或过期
 ```
 
 ## 错误码一览
 
 | 错误码 | 枚举值 | 说明 |
 |--------|--------|------|
 | `0` | `ErrorCode.SUCCESS` | 成功 |
 | `1000` | `ErrorCode.UNKNOWN_ERROR` | 未知错误 |
 | `1001` | `ErrorCode.SERVICE_ERROR` | 服务错误 |
 | `1002` | `ErrorCode.AUTHENTICATION_ERROR` | 认证失败,API Key 无效或过期 |
 | `1003` | `ErrorCode.RATE_LIMIT` | 请求频率超限，请稍后重试 |
 | `1004` | `ErrorCode.QUOTA_EXCEEDED` | 配额/余额不足 |
 | `1005` | `ErrorCode.SERVICE_TIMEOUT` | 服务超时，请稍后重试 |
 | `1006` | `ErrorCode.SERVICE_BUSY` | 服务繁忙，请稍后再试！ |
 | `2001` | `ErrorCode.INVALID_PARAMS` | 请求参数无效 |
 | `3001` | `ErrorCode.PROMPT_BANNED` | 提示词包含违禁内容 |
 | `3002` | `ErrorCode.IMAGE_BANNED` | 图片包含违禁内容 |
 | `3003` | `ErrorCode.CONTENT_POLICY_VIOLATION` | 您的请求包含违反平台政策的内容,请调整图像或提示词后重试 |
 | `4001` | `ErrorCode.INVALID_IMAGE` | 图片无效或损坏 |
 | `4002` | `ErrorCode.IMAGE_GENERATE_FAIL` | 图片生成失败，请稍后重试 |
 | `4003` | `ErrorCode.NO_IMAGE_RESULT` | 模型未返回图片结果,请调整图像或提示词后重试 |
 
 ## 异常类层级
 
 所有异常均继承自 `ExCodeError`，可通过 `except ExCodeError` 统一捕获。
 
 ```
 ExCodeError
 ├── ServiceError                # 通用服务错误
 ├── AuthenticationError         # 认证失败
 ├── RateLimitError              # 请求频率超限
 ├── QuotaExceededError          # 配额/余额不足
 ├── ServiceTimeoutError         # 服务超时
 ├── ServiceBusyError            # 服务繁忙
 ├── InvalidParamsError          # 请求参数无效
 ├── PromptBanError              # 提示词违禁
 ├── ImageBanError               # 图片违禁
 ├── ContentPolicyViolationError # 违反平台政策
 ├── InvalidImageError           # 图片无效或损坏
 ├── ImageGenerateFailError      # 图片生成失败
 └── NoImageResultError          # 模型未返回图片结果
 ```
 
 ## 使用方式
 
 ### 1. 直接抛出异常
 
 ```python
 from excode import AuthenticationError
 
 raise AuthenticationError("API Key 已过期", extra_data={"key_id": "abc123"})
 # 输出: [1002] API Key 已过期 [{'key_id': 'abc123'}]
 ```
 
 ### 2. 根据错误码抛出（工厂函数）
 
 ```python
 from excode import ErrorCode, raise_for_error
 
 # 使用默认描述
 raise_for_error(ErrorCode.RATE_LIMIT)
 # 输出: [1003] 请求频率超限，请稍后重试
 
 # 使用自定义描述
 raise_for_error(ErrorCode.RATE_LIMIT, error_msg="当前接口调用次数已达上限")
 # 输出: [1003] 当前接口调用次数已达上限
 ```
 
 ### 3. 统一捕获并处理
 
 ```python
 from excode import ExCodeError, ErrorCode, raise_for_error
 
 try:
     raise_for_error(ErrorCode.QUOTA_EXCEEDED)
 except ExCodeError as e:
     print(e.error_code)       # ErrorCode.QUOTA_EXCEEDED
     print(e.error_code.value) # 1004
     print(e.error_msg)        # 配额/余额不足
     print(e.extra_data)       # {}
 ```
 
 ### 4. 分类捕获
 
 ```python
 from excode import AuthenticationError, RateLimitError, ExCodeError
 
 try:
     # 业务逻辑
     ...
 except AuthenticationError as e:
     # 处理认证失败
     refresh_api_key()
 except RateLimitError as e:
     # 处理限流
     wait_and_retry()
 except ExCodeError as e:
     # 兜底处理其他 excode 异常
     log_error(e)
 ```
 
 ### 5. 携带额外上下文
 
 ```python
 from excode import InvalidParamsError
 
 raise InvalidParamsError(
     "参数校验失败",
     extra_data={"field": "width", "value": -1, "reason": "必须为正整数"}
 )
 # 输出: [2001] 参数校验失败 [{'field': 'width', 'value': -1, 'reason': '必须为正整数'}]
 ```
 
 ### 6. 特殊异常的扩展属性
 
 ```python
 from excode import PromptBanError, InvalidImageError
 
 # PromptBanError 携带命中的违禁词列表
 raise PromptBanError("提示词违禁", data=["暴力", "色情"])
 
 # InvalidImageError 携带图片尺寸和原始异常
 raise InvalidImageError("图片无法解码", image_size=2048, original_error=decode_err)
 ```
 
 ### 7. 获取错误码描述
 
 ```python
 from excode import ErrorCode, get_error_message
 
 msg = get_error_message(ErrorCode.SERVICE_TIMEOUT)
 print(msg)  # 服务超时，请稍后重试
 ```
 
 ### 8. 注册自定义错误码映射
 
 ```python
 from enum import IntEnum
 from excode import ExCodeError, ErrorCode, raise_for_error, register_error_code
 
 # 定义自定义异常
 class NetworkError(ExCodeError):
     error_code = ErrorCode.UNKNOWN_ERROR  # 可复用或自行扩展
 
 # 注册映射
 register_error_code(ErrorCode.SERVICE_ERROR, NetworkError)
 
 # 之后 raise_for_error 会使用你注册的异常类
 raise_for_error(ErrorCode.SERVICE_ERROR, error_msg="网络连接失败")
 ```
 
 ### 9. 自定义错误码（CustomErrorCode）
 
 当内置 `ErrorCode` 枚举无法满足需求时，可使用 `CustomErrorCode` 定义字符串类型的错误码：
 
 ```python
 from excode import CustomErrorCode, ServiceResult, raise_for_error
 
 # 直接创建
 MY_ERROR = CustomErrorCode("MY_ERROR", "自定义错误消息")
 
 # 用于 ServiceResult
 result = ServiceResult.fail(MY_ERROR)
 print(result.code)  # CustomErrorCode('MY_ERROR', '自定义错误消息')
 print(result.msg)   # 自定义错误消息
 
 # 用于 raise_for_error（将抛出 ExCodeError）
 raise_for_error(MY_ERROR)
 ```
 
 ### 10. 错误码注册表（ErrorCodeRegistry）
 
 提供全局注册和查找自定义错误码的能力：
 
 ```python
 from excode import ErrorCodeRegistry
 
 # 注册自定义错误码
 MY_ERROR = ErrorCodeRegistry.register("MY_ERROR", "自定义错误消息")
 
 # 查找已注册的错误码
 found = ErrorCodeRegistry.get("MY_ERROR")
 print(found)  # CustomErrorCode('MY_ERROR', '自定义错误消息')
 
 # 列出所有已注册的错误码
 all_codes = ErrorCodeRegistry.list_all()
 
 # 清空注册表（主要用于测试）
 ErrorCodeRegistry.clear()
 ```
 
 ### 11. 服务结果封装（ServiceResult）
 
 使用 `ServiceResult` 以返回值代替异常，统一表示成功或失败：
 
 ```python
 from excode import ServiceResult, ErrorCode, CustomErrorCode
 
 # 成功
 result = ServiceResult.success(data={"id": 1, "name": "test"})
 print(result.is_success)  # True
 print(result.data)        # {'id': 1, 'name': 'test'}
 
 # 失败 - 使用内置错误码
 result = ServiceResult.fail(ErrorCode.AUTHENTICATION_ERROR)
 print(result.is_success)  # False
 print(result.code)        # ErrorCode.AUTHENTICATION_ERROR
 print(result.msg)         # 认证失败,API Key 无效或过期
 
 # 失败 - 使用自定义错误码
 my_error = CustomErrorCode("BIZ_ERROR", "业务错误")
 result = ServiceResult.fail(my_error)
 print(result.code)  # CustomErrorCode('BIZ_ERROR', '业务错误')
 
 # 布尔判断
 if result:
     print("成功")
 else:
     print("失败")
 
 # 转为字典
 d = result.to_dict()
 # {'is_success': False, 'code': 'BIZ_ERROR', 'msg': '业务错误', 'data': None}
 
 # 从异常创建
 try:
     ...
 except Exception as e:
     result = ServiceResult.from_exception(e)
 ```
 

