excode 0.1.0__cp313-cp313-win_amd64.whl

excode/__init__.py

@@ -0,0 +1,51 @@
+"""
+excode - 统一的异常与错误码管理包。
+
+提供标准化的异常类、错误码枚举以及错误处理工具函数。
+
+Usage:
+    from excode import ExCodeError, ErrorCode, raise_for_error
+
+    try:
+        raise_for_error(ErrorCode.AUTHENTICATION_ERROR)
+    except ExCodeError as e:
+        print(e)  # [1002] 认证失败，API Key 无效或过期
+"""
+
+from .codes import ErrorCode, get_error_message, ERROR_CODE_MESSAGES
+from .exceptions import (
+    ExCodeError,
+    ServiceError,
+    AuthenticationError,
+    RateLimitError,
+    QuotaExceededError,
+    ServiceTimeoutError,
+    InvalidParamsError,
+    PromptBanError,
+    ImageBanError,
+    InvalidImageError,
+)
+from .handler import raise_for_error, register_error_code
+
+__all__ = [
+    # 错误码
+    "ErrorCode",
+    "get_error_message",
+    "ERROR_CODE_MESSAGES",
+    # 异常类
+    "ExCodeError",
+    "ServiceError",
+    "AuthenticationError",
+    "RateLimitError",
+    "QuotaExceededError",
+    "ServiceTimeoutError",
+    "InvalidParamsError",
+    "PromptBanError",
+    "ImageBanError",
+    "InvalidImageError",
+    # 工具函数
+    "raise_for_error",
+    "register_error_code",
+]
+
+__version__ = "0.1.0"

excode/__init__.pyi

@@ -0,0 +1,5 @@
+from .codes import ERROR_CODE_MESSAGES as ERROR_CODE_MESSAGES, ErrorCode as ErrorCode, get_error_message as get_error_message
+from .exceptions import AuthenticationError as AuthenticationError, ExCodeError as ExCodeError, ImageBanError as ImageBanError, InvalidImageError as InvalidImageError, InvalidParamsError as InvalidParamsError, PromptBanError as PromptBanError, QuotaExceededError as QuotaExceededError, RateLimitError as RateLimitError, ServiceError as ServiceError, ServiceTimeoutError as ServiceTimeoutError
+from .handler import raise_for_error as raise_for_error, register_error_code as register_error_code
+
+__all__ = ['ErrorCode', 'get_error_message', 'ERROR_CODE_MESSAGES', 'ExCodeError', 'ServiceError', 'AuthenticationError', 'RateLimitError', 'QuotaExceededError', 'ServiceTimeoutError', 'InvalidParamsError', 'PromptBanError', 'ImageBanError', 'InvalidImageError', 'raise_for_error', 'register_error_code']

excode/codes.pyi

@@ -0,0 +1,28 @@
+from enum import IntEnum
+
+class ErrorCode(IntEnum):
+    """
+    excode 错误码枚举。
+
+    错误码规则：
+        - 1xxx: 通用/服务相关错误
+        - 2xxx: 参数相关错误
+        - 3xxx: 内容安全相关错误
+        - 4xxx: 图片相关错误
+    """
+    SUCCESS = 0
+    UNKNOWN_ERROR = 1000
+    SERVICE_ERROR = 1001
+    AUTHENTICATION_ERROR = 1002
+    RATE_LIMIT = 1003
+    QUOTA_EXCEEDED = 1004
+    SERVICE_TIMEOUT = 1005
+    INVALID_PARAMS = 2001
+    PROMPT_BANNED = 3001
+    IMAGE_BANNED = 3002
+    INVALID_IMAGE = 4001
+
+ERROR_CODE_MESSAGES: dict[ErrorCode, str]
+
+def get_error_message(code: ErrorCode) -> str:
+    """根据错误码获取对应的错误描述"""

excode/exceptions.pyi

@@ -0,0 +1,77 @@
+from .codes import ErrorCode as ErrorCode
+from _typeshed import Incomplete
+from typing import Any
+
+class ExCodeError(Exception):
+    """
+    excode 包的基础异常类。
+
+    所有 excode 异常都继承自此类，可通过 `except ExCodeError` 统一捕获。
+
+    Attributes:
+        error_code: 错误码枚举值
+        error_msg: 错误描述
+        extra_data: 额外上下文数据
+    """
+    error_code: ErrorCode
+    error_msg: Incomplete
+    extra_data: Incomplete
+    def __init__(self, error_msg: str, extra_data: dict[str, Any] | None = None, **kwargs: Any) -> None: ...
+
+class ServiceError(ExCodeError):
+    """通用服务错误"""
+    error_code: Incomplete
+
+class AuthenticationError(ExCodeError):
+    """认证失败，API Key 无效或过期"""
+    error_code: Incomplete
+
+class RateLimitError(ExCodeError):
+    """请求频率超限"""
+    error_code: Incomplete
+
+class QuotaExceededError(ExCodeError):
+    """配额/余额不足"""
+    error_code: Incomplete
+
+class ServiceTimeoutError(ExCodeError):
+    """服务超时"""
+    error_code: Incomplete
+
+class InvalidParamsError(ExCodeError):
+    """请求参数无效"""
+    error_code: Incomplete
+
+class PromptBanError(ExCodeError):
+    """
+    提示词违禁异常。
+
+    Attributes:
+        error_msg: 错误描述
+        extend_data: 命中的违禁词列表
+        extra_data: 额外上下文数据
+    """
+    error_code: Incomplete
+    extend_data: Incomplete
+    def __init__(self, error_msg: str, data: Any = None, extra_data: dict[str, Any] | None = None, **kwargs: Any) -> None: ...
+
+class ImageBanError(ExCodeError):
+    """图片包含违禁内容"""
+    error_code: Incomplete
+
+class InvalidImageError(ExCodeError):
+    """
+    图片无效异常。
+
+    当图片损坏、格式错误或无法解码时抛出。
+
+    Attributes:
+        error_msg: 错误描述
+        image_size: 图片数据大小（字节数）
+        original_error: 原始异常
+        extra_data: 额外上下文数据
+    """
+    error_code: Incomplete
+    image_size: Incomplete
+    original_error: Incomplete
+    def __init__(self, error_msg: str, image_size: int | None = None, original_error: Exception | None = None, extra_data: dict[str, Any] | None = None, **kwargs: Any) -> None: ...

excode/handler.pyi

@@ -0,0 +1,25 @@
+from .codes import ErrorCode as ErrorCode, get_error_message as get_error_message
+from .exceptions import AuthenticationError as AuthenticationError, ExCodeError as ExCodeError, ImageBanError as ImageBanError, InvalidImageError as InvalidImageError, InvalidParamsError as InvalidParamsError, PromptBanError as PromptBanError, QuotaExceededError as QuotaExceededError, RateLimitError as RateLimitError, ServiceError as ServiceError, ServiceTimeoutError as ServiceTimeoutError
+from typing import Any
+
+def raise_for_error(error_code: ErrorCode, error_msg: str | None = None, extra_data: dict[str, Any] | None = None, **kwargs: Any) -> None:
+    """
+    根据错误码抛出对应的异常。
+
+    Args:
+        error_code: 错误码
+        error_msg: 错误描述，为 None 时使用默认描述
+        extra_data: 额外上下文数据
+        **kwargs: 其他关键字参数
+
+    Raises:
+        ExCodeError: 对应错误码的异常
+    """
+def register_error_code(error_code: ErrorCode, exc_class: type[ExCodeError]) -> None:
+    """
+    注册自定义的错误码到异常类的映射。
+
+    Args:
+        error_code: 错误码
+        exc_class: 对应的异常类
+    """

excode-0.1.0.dist-info/METADATA

@@ -0,0 +1,186 @@
+Metadata-Version: 2.1
+Name: excode
+Version: 0.1.0
+Summary: 统一的异常与错误码管理包
+Home-page: https://github.com/zhenzi0322/excode
+Author: 
+Author-email:  <>
+License: MIT
+Requires-Python: >=3.8
+description-content-type: text/markdown
+Description:
+ # excode
+ 
+ 统一的异常与错误码管理 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` | 认证失败 |
+ | `1003` | `ErrorCode.RATE_LIMIT` | 请求频率超限 |
+ | `1004` | `ErrorCode.QUOTA_EXCEEDED` | 配额/余额不足 |
+ | `1005` | `ErrorCode.SERVICE_TIMEOUT` | 服务超时 |
+ | `2001` | `ErrorCode.INVALID_PARAMS` | 请求参数无效 |
+ | `3001` | `ErrorCode.PROMPT_BANNED` | 提示词违禁 |
+ | `3002` | `ErrorCode.IMAGE_BANNED` | 图片违禁 |
+ | `4001` | `ErrorCode.INVALID_IMAGE` | 图片无效或损坏 |
+ 
+ ## 异常类层级
+ 
+ 所有异常均继承自 `ExCodeError`，可通过 `except ExCodeError` 统一捕获。
+ 
+ ```
+ ExCodeError
+ ├── ServiceError            # 通用服务错误
+ ├── AuthenticationError     # 认证失败
+ ├── RateLimitError          # 请求频率超限
+ ├── QuotaExceededError      # 配额/余额不足
+ ├── ServiceTimeoutError     # 服务超时
+ ├── InvalidParamsError      # 请求参数无效
+ ├── PromptBanError          # 提示词违禁
+ ├── ImageBanError           # 图片违禁
+ └── InvalidImageError       # 图片无效或损坏
+ ```
+ 
+ ## 使用方式
+ 
+ ### 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="网络连接失败")
+ ```
+ 
+ ## 技术架构
+ 
+ ```
+ excode/
+ ├── __init__.py       # 包入口，统一导出所有公开 API
+ ├── codes.py          # ErrorCode 枚举、错误码描述映射
+ ├── exceptions.py     # 异常类定义（继承体系）
+ └── handler.py        # raise_for_error 工厂函数、register_error_code 注册函数
+ ```
+ 
+ 
+

excode-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+excode/codes.cp313-win_amd64.pyd,sha256=LmL5bPcLWCTEbFnqX-ha4uSMacOx6px7IG4WZDdu3h8,41472
+excode/codes.pyi,sha256=51WD0qCG3oxdNnEo6PM0OjxBM2-esk2DY5_WdX562ic,720
+excode/exceptions.cp313-win_amd64.pyd,sha256=_oo0QtrzBvMau74_Dfqpytkh54W95Dm2qBjF7GZtW-Y,66560
+excode/exceptions.pyi,sha256=iolGjsSLZsz0ZHnQALVQF1uW2vpf3zc5AgDiURdeph0,2341
+excode/handler.cp313-win_amd64.pyd,sha256=wDUoWONAYIFH2SWsROSKYIaGxfpJUjXE5JBGXpkEaH4,49152
+excode/handler.pyi,sha256=4ZPUHut89cBWW-IDM_liY0NAewNWv1-tsnK7kyeG7vo,1207
+excode/__init__.py,sha256=vsrn-Bn28ACuGSyWnbV1gB13135s6uyxdLwSslnQOqg,1234
+excode/__init__.pyi,sha256=VA4i2N4qpUduIQcJSRtqfyT-6sHKGXxyqtwuWAxU_m4,930
+excode/__pycache__/__init__.cpython-313.pyc,sha256=zubGyQmjrcMeO7ULkHIyR4hSRDYYYkRyIqml5z6fRjg,1144
+excode-0.1.0.dist-info/METADATA,sha256=S5No4QFWXdVsDvXpkgDoSOGTvqZkpNXq6549oLL0fkc,5442
+excode-0.1.0.dist-info/WHEEL,sha256=DTvG4vLPSiwqQf5tyjRQz7wlFnL8feDr0AeF_828au8,109
+excode-0.1.0.dist-info/RECORD,,

excode-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: excode-protected-builder
+Root-Is-Purelib: false
+Tag: cp313-cp313-win_amd64