跳转至

快手小店 Python SDK

基础模块

kuaishou/kwaixiaodian-python-sdk

基础模块

SDK的核心基础组件和通用模块，提供异常处理机制、基础数据模型定义、通用数据结构等核心功能。这些模块为整个SDK的稳定运行提供基础支撑，确保API调用的可靠性和数据的一致性。

异常处理

`kwaixiaodian.exceptions`

快手SDK异常定义

定义了SDK中使用的所有异常类型，提供详细的错误信息和处理建议。

类：

名称	描述
`KwaixiaodianSDKError`	快手SDK基础异常
`KwaixiaodianAPIError`	快手API调用异常
`KwaixiaodianAuthError`	认证相关异常
`KwaixiaodianSignatureError`	签名验证异常
`KwaixiaodianNetworkError`	网络连接异常
`KwaixiaodianConfigError`	配置错误异常
`KwaixiaodianValidationError`	数据验证异常
`KwaixiaodianRateLimitError`	API限流异常

Classes

`KwaixiaodianSDKError(message: str, details: Optional[Dict[str, Any]] = None)`

Bases: Exception

快手SDK基础异常

Source code in src/kwaixiaodian/exceptions.py

def __init__(self, message: str, details: Optional[Dict[str, Any]] = None):
    super().__init__(message)
    self.message = message
    self.details = details or {}

`KwaixiaodianAPIError(message: str, error_code: Optional[str] = None, sub_code: Optional[str] = None, http_status: Optional[int] = None, request_id: Optional[str] = None, details: Optional[Dict[str, Any]] = None)`

Bases: KwaixiaodianSDKError

快手API调用异常

当API返回错误状态或错误码时抛出此异常。

Source code in src/kwaixiaodian/exceptions.py

def __init__(
    self,
    message: str,
    error_code: Optional[str] = None,
    sub_code: Optional[str] = None,
    http_status: Optional[int] = None,
    request_id: Optional[str] = None,
    details: Optional[Dict[str, Any]] = None,
):
    super().__init__(message, details)
    self.error_code = error_code
    self.sub_code = sub_code
    self.http_status = http_status
    self.request_id = request_id

`KwaixiaodianAuthError(message: str, auth_type: Optional[str] = None, details: Optional[Dict[str, Any]] = None)`

Bases: KwaixiaodianSDKError

认证相关异常

包括OAuth认证失败、token过期、签名验证失败等。

Source code in src/kwaixiaodian/exceptions.py

def __init__(
    self,
    message: str,
    auth_type: Optional[str] = None,
    details: Optional[Dict[str, Any]] = None,
):
    super().__init__(message, details)
    self.auth_type = auth_type

`KwaixiaodianSignatureError(message: str, details: Optional[Dict[str, Any]] = None)`

Bases: KwaixiaodianAuthError

签名验证异常

Source code in src/kwaixiaodian/exceptions.py

def __init__(self, message: str, details: Optional[Dict[str, Any]] = None):
    super().__init__(message, "signature", details)

`KwaixiaodianNetworkError(message: str, details: Optional[Dict[str, Any]] = None)`

Bases: KwaixiaodianSDKError

网络连接异常

包括超时、连接失败、DNS解析失败等网络问题。

Source code in src/kwaixiaodian/exceptions.py

def __init__(self, message: str, details: Optional[Dict[str, Any]] = None):
    super().__init__(message)
    self.message = message
    self.details = details or {}

`KwaixiaodianConfigError(message: str, details: Optional[Dict[str, Any]] = None)`

Bases: KwaixiaodianSDKError

配置错误异常

包括参数配置错误、必要参数缺失等。

Source code in src/kwaixiaodian/exceptions.py

def __init__(self, message: str, details: Optional[Dict[str, Any]] = None):
    super().__init__(message)
    self.message = message
    self.details = details or {}

`KwaixiaodianValidationError(message: str, field: Optional[str] = None, value: Optional[Any] = None, details: Optional[Dict[str, Any]] = None)`

Bases: KwaixiaodianSDKError

数据验证异常

包括请求参数验证失败、响应数据格式错误等。

Source code in src/kwaixiaodian/exceptions.py

def __init__(
    self,
    message: str,
    field: Optional[str] = None,
    value: Optional[Any] = None,
    details: Optional[Dict[str, Any]] = None,
):
    super().__init__(message, details)
    self.field = field
    self.value = value

`KwaixiaodianRateLimitError(message: str, retry_after: Optional[int] = None, details: Optional[Dict[str, Any]] = None)`

Bases: KwaixiaodianAPIError

API限流异常

Source code in src/kwaixiaodian/exceptions.py

def __init__(
    self,
    message: str,
    retry_after: Optional[int] = None,
    details: Optional[Dict[str, Any]] = None,
):
    super().__init__(message, "RATE_LIMIT_EXCEEDED", details=details)
    self.retry_after = retry_after

基础数据模型

`kwaixiaodian.models.base`

基础数据模型定义

类：

名称	描述
`BaseModel`	基础数据模型
`HttpMethod`	HTTP方法枚举
`BaseRequest`	基础请求模型
`BaseResponse`	基础响应模型
`PagedData`	分页数据模型
`PagedResponse`	分页响应模型

Classes

`BaseModel`

Bases: BaseModel

基础数据模型

使用Pydantic v2作为基础，提供数据验证和序列化功能。

方法：

名称	描述
`to_dict`	转换为字典
`to_json`	转换为JSON字符串
`from_dict`	从字典创建实例
`from_json`	从JSON字符串创建实例

Functions

to_dict(exclude_none: bool = True) -> Dict[str, Any]

转换为字典

参数：

名称	类型	描述	默认
`exclude_none`	`bool`	是否排除None值	`True`

返回：

类型	描述
`Dict[str, Any]`	字典表示

to_json(exclude_none: bool = True) -> str

转换为JSON字符串

参数：

名称	类型	描述	默认
`exclude_none`	`bool`	是否排除None值	`True`

返回：

类型	描述
`str`	JSON字符串

from_dict(data: Dict[str, Any]) -> BaseModel classmethod

从字典创建实例

参数：

名称	类型	描述	默认
`data`	`Dict[str, Any]`	字典数据	必需

返回：

类型	描述
`BaseModel`	模型实例

from_json(json_str: str) -> BaseModel classmethod

从JSON字符串创建实例

参数：

名称	类型	描述	默认
`json_str`	`str`	JSON字符串	必需

返回：

类型	描述
`BaseModel`	模型实例

`HttpMethod`

Bases: str, Enum

HTTP方法枚举

`BaseRequest`

Bases: BaseModel, ABC

基础请求模型

方法：

名称	描述
`get_business_params`	获取业务参数

属性：

名称	类型	描述
`api_method`	`str`	API方法名
`http_method`	`HttpMethod`	HTTP方法，默认为POST

Attributes

api_method: str property

API方法名

优先从实例字段或子类类属性中读取，兼容部分子类以字段方式声明 api_method 的写法。子类也可以显式覆写为 @property 以返回常量字符串。

http_method: HttpMethod property

HTTP方法，默认为POST

兼容子类以字段方式声明 http_method 的写法。

Functions

get_business_params() -> Dict[str, Any]

获取业务参数

返回排除公共参数后的业务参数字典

`BaseResponse`

Bases: BaseModel, Generic[T]

基础响应模型

属性：

名称	类型	描述
`is_success`	`bool`	请求是否成功
`error_message`	`str`	完整错误信息

Attributes

is_success: bool property

请求是否成功

error_message: str property

完整错误信息

`PagedData`

Bases: BaseModel, Generic[T]

分页数据模型

属性：

名称	类型	描述
`total_pages`	`Optional[int]`	总页数

Attributes

total_pages: Optional[int] property

总页数

`PagedResponse(**data)`

Bases: BaseResponse[PagedData[T]]

分页响应模型

通用数据模型

`kwaixiaodian.models.common`

通用数据模型

类：

名称	描述
`OrderStatus`	订单状态
`ItemStatus`	商品状态
`RefundStatus`	退款状态
`PaymentStatus`	支付状态
`PaymentType`	支付方式
`Address`	地址信息
`LogisticsInfo`	物流信息
`PriceInfo`	价格信息（单位：分）
`Image`	图片信息
`UserInfo`	用户信息
`ShopInfo`	店铺信息
`TimeRange`	时间范围
`PageInfo`	分页信息
`SortInfo`	排序信息
`ApiError`	API错误信息

Classes

`OrderStatus`

Bases: int, Enum

订单状态

`ItemStatus`

Bases: int, Enum

商品状态

`RefundStatus`

Bases: int, Enum

退款状态

`PaymentStatus`

Bases: int, Enum

支付状态

`PaymentType`

Bases: int, Enum

支付方式

`Address`

Bases: BaseModel

地址信息

`LogisticsInfo`

Bases: BaseModel

物流信息

`PriceInfo`

Bases: BaseModel

价格信息（单位：分）

属性：

名称	类型	描述
`original_yuan`	`float`	原价（元）
`sell_yuan`	`float`	售价（元）
`discount_yuan`	`Optional[float]`	优惠金额（元）

Attributes

original_yuan: float property

原价（元）

sell_yuan: float property

售价（元）

discount_yuan: Optional[float] property

优惠金额（元）

`Image`

Bases: BaseModel

图片信息

`UserInfo`

Bases: BaseModel

用户信息

`ShopInfo`

Bases: BaseModel

店铺信息

`TimeRange`

Bases: BaseModel

时间范围

`PageInfo`

Bases: BaseModel

分页信息

属性：

名称	类型	描述
`offset`	`int`	偏移量

Attributes

offset: int property

偏移量

`SortInfo`

Bases: BaseModel

排序信息

`ApiError`

Bases: BaseModel

API错误信息