py-lmobile-toolkit 1.0.0__py3-none-any.whl

py_lmobile_toolkit/__init__.py

@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+"""
+py_lmobile - 微网通联短信服务 Python SDK
+
+本模块提供接入微网通联（51welink）短信服务的完整功能，包括：
+- 同步和异步短信发送能力
+- 请求签名认证机制
+- 响应数据模型
+- 工具函数支持
+
+主要组件：
+- Sms: 短信客户端核心类，提供同步和异步发送接口
+- utils: 工具函数模块，包含签名生成、时间戳等功能
+- responses: 响应数据模型，用于标准化API响应
+
+官方 API 文档：https://www.lmobile.cn/ApiPages/index.html
+
+使用示例：
+    from py_lmobile.sms import Sms
+    
+    sms = Sms(account_id="your_account", password="your_password", product_id="your_product")
+    response = sms.send(phone_nos="13800138000", content="您的验证码是：123456")
+"""

py_lmobile_toolkit/sms/__init__.py

@@ -0,0 +1,238 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+"""
+短信客户端模块
+
+本模块提供微网通联短信服务的客户端实现，支持同步和异步两种发送方式。
+
+核心功能：
+- 客户端配置与初始化
+- 同步/异步HTTP请求封装
+- 短信发送接口（支持批量发送）
+- 请求签名生成与认证
+
+官方 API 文档：https://www.lmobile.cn/ApiPages/index.html
+
+使用示例：
+    # 同步发送
+    sms = Sms(account_id="xxx", password="xxx", product_id="xxx")
+    response = sms.send(phone_nos="13800138000", content="测试短信")
+    
+    # 异步发送
+    response = await sms.async_send(phone_nos=["13800138000", "13900139000"], content="测试短信")
+"""
+
+from typing import Optional, Union
+
+import httpx
+from py_httpx_toolkit import Httpx
+
+from .utils import timestamp, random_digits, sha256_signature
+
+
+class Sms(Httpx):
+    """
+    微网通联短信客户端
+    
+    提供同步和异步两种方式发送短信，支持请求签名认证机制。
+    
+    设计架构：
+    - 配置层：初始化时配置账号信息、服务器地址等参数
+    - 客户端层：提供同步/异步HTTP客户端的创建与管理
+    - 请求层：封装底层HTTP请求，支持外部传入客户端实例
+    - 业务层：短信发送接口，处理签名生成和参数组装
+    """
+
+    def __init__(
+            self,
+            base_url: Optional[str] = "https://api.51welink.com/",
+            account_id: Optional[str] = None,
+            password: Optional[str] = None,
+            product_id: Optional[Union[str, int]] = None,
+            smms_encrypt_key: Optional[str] = "SMmsEncryptKey",
+            client_kwargs: Optional[dict] = None
+    ):
+        """
+        初始化短信客户端
+        
+        Args:
+            base_url: API服务器地址，默认为微网通联官方地址
+            account_id: 账号ID，从微网通联控制台获取
+            password: 账号密码，用于签名生成
+            product_id: 产品ID，标识具体的短信产品
+            smms_encrypt_key: 加密密钥，用于密码的MD5加密盐值
+            client_kwargs: 传递给httpx.Client的额外配置参数
+        
+        配置处理逻辑：
+            1. 处理base_url末尾斜杠，确保统一格式
+            2. 将None值转换为空字符串，避免后续处理异常
+            3. 合并默认客户端配置与用户传入配置
+            4. 默认禁用SSL验证（针对部分内部环境），超时60秒
+        """
+        # 处理base_url，确保末尾无斜杠
+        self.base_url = base_url or ""
+        self.base_url = self.base_url[:-1] if self.base_url.endswith("/") else self.base_url
+
+        # 存储账号信息，None值转换为空字符串
+        self.account_id = account_id or ""
+        self.password = password or ""
+        self.product_id = product_id or ""
+        self.smms_encrypt_key = smms_encrypt_key or ""
+
+        # 合并客户端配置，用户配置可覆盖默认配置
+        self.client_kwargs = client_kwargs or {}
+        self.client_kwargs = {
+            **{
+                "base_url": self.base_url,
+                "verify": False,  # 默认禁用SSL验证
+                "timeout": 60,  # 默认超时60秒
+            },
+            **self.client_kwargs,
+        }
+
+    def send(
+            self,
+            phone_nos: Optional[Union[str, list, tuple]] = None,
+            content: Optional[str] = None,
+            client: Optional[httpx.Client] = None,
+            client_kwargs: Optional[dict] = None,
+            **kwargs
+    ) -> httpx.Response:
+        """
+        同步发送短信
+        
+        组装短信发送请求参数，生成签名，调用底层HTTP请求发送短信。
+        
+        Args:
+            client: 可选的HTTP客户端实例，若不传则自动创建
+            phone_nos: 接收短信的手机号码，支持单个字符串或列表/元组
+            content: 短信内容
+            **kwargs: 传递给httpx.Client.request的额外参数
+            
+        Returns:
+            httpx.Response: HTTP响应对象
+            
+        Raises:
+            Exception: 发送过程中可能抛出的异常（网络错误、超时等）
+        
+        请求组装逻辑：
+            1. 处理手机号格式：列表/元组转换为逗号分隔的字符串
+            2. 生成时间戳（毫秒级）用于请求时效性验证
+            3. 生成随机数用于签名唯一性
+            4. 使用SHA256算法生成请求签名
+            5. 组装完整的请求参数并发送
+        
+        签名生成规则：
+            1. 密码先进行MD5加密（带盐值smms_encrypt_key）
+            2. 按顺序拼接：AccountId、PhoneNos（第一个）、Password（MD5后）、Random、Timestamp
+            3. 使用&连接所有参数
+            4. 对拼接结果进行SHA256加密
+        """
+        # 处理手机号格式：列表/元组转换为逗号分隔的字符串
+        if isinstance(phone_nos, (list, tuple)):
+            phone_nos = ",".join(phone_nos)
+
+        # 生成时间戳和随机数
+        ts = timestamp()
+        digits = random_digits()
+        client = client or None
+        client_kwargs = client_kwargs or {}
+        # 处理None值，确保kwargs是字典类型
+        kwargs = kwargs or {}
+
+        # 组装请求参数
+        kwargs = {
+            **{
+                "method": "POST",
+                "url": "/EncryptionSubmit/SendSms.ashx",
+                "data": {
+                    "AccountID": self.account_id,
+                    "ProductID": self.product_id,
+                    "PhoneNos": phone_nos,
+                    "Timestamp": ts,
+                    "Random": digits,
+                    "Content": content,
+                    "AccessKey": sha256_signature(
+                        account_id=self.account_id,
+                        password=self.password,
+                        phone_nos=phone_nos,
+                        random_digits=digits,
+                        timestamp=ts,
+                        smms_encrypt_key=self.smms_encrypt_key,
+                    )
+                },
+            },
+            **kwargs
+        }
+
+        # 调用同步请求方法发送短信
+        return self.request(client=client, client_kwargs=client_kwargs, **kwargs)
+
+    async def async_send(
+            self,
+            phone_nos: Optional[Union[str, list, tuple]] = None,
+            content: Optional[str] = None,
+            client: Optional[httpx.AsyncClient] = None,
+            client_kwargs: Optional[dict] = None,
+            **kwargs
+    ) -> httpx.Response:
+        """
+        异步发送短信
+        
+        组装短信发送请求参数，生成签名，调用底层异步HTTP请求发送短信。
+        
+        Args:
+            client: 可选的异步HTTP客户端实例，若不传则自动创建
+            phone_nos: 接收短信的手机号码，支持单个字符串或列表/元组
+            content: 短信内容
+            **kwargs: 传递给httpx.AsyncClient.request的额外参数
+            
+        Returns:
+            httpx.Response: HTTP响应对象
+            
+        Raises:
+            Exception: 发送过程中可能抛出的异常（网络错误、超时等）
+        
+        请求组装逻辑：
+            与同步版本相同，详见send()方法的注释
+        """
+        # 处理手机号格式：列表/元组转换为逗号分隔的字符串
+        if isinstance(phone_nos, (list, tuple)):
+            phone_nos = ",".join(phone_nos)
+
+        # 生成时间戳和随机数
+        ts = timestamp()
+        digits = random_digits()
+        client = client or None
+        client_kwargs = client_kwargs or {}
+
+        # 处理None值，确保kwargs是字典类型
+        kwargs = kwargs or {}
+
+        # 组装请求参数
+        kwargs = {
+            **{
+                "method": "POST",
+                "url": "/EncryptionSubmit/SendSms.ashx",
+                "data": {
+                    "AccountID": self.account_id,
+                    "ProductID": self.product_id,
+                    "PhoneNos": phone_nos,
+                    "Timestamp": ts,
+                    "Random": digits,
+                    "Content": content,
+                    "AccessKey": sha256_signature(
+                        account_id=self.account_id,
+                        password=self.password,
+                        phone_nos=phone_nos,
+                        random_digits=digits,
+                        timestamp=ts,
+                        smms_encrypt_key=self.smms_encrypt_key,
+                    )
+                },
+            },
+            **kwargs
+        }
+
+        # 调用异步请求方法发送短信
+        return await self.async_request(client=client, client_kwargs=client_kwargs, **kwargs)

py_lmobile_toolkit/sms/responses.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+"""
+响应模型模块
+
+本模块定义了微网通联API响应的数据模型，使用Pydantic进行数据验证和序列化。
+
+核心模型：
+- Base: 所有响应的基类，包含Result字段
+- Success: 成功响应模型，Result字段值固定为"succ"
+
+设计说明：
+- 使用Pydantic BaseModel作为基类，提供自动数据验证
+- 支持额外字段（extra="allow"），兼容API返回的未知字段
+- 使用Field描述字段的标题和说明，便于生成文档
+
+官方 API 文档：https://www.lmobile.cn/ApiPages/index.html
+"""
+
+from pydantic import BaseModel, Field
+from typing import Literal, Union, Any, Optional
+
+
+class Base(BaseModel):
+    """
+    微网通联API响应基类
+    
+    所有API响应都继承自此基类，包含统一的错误码字段。
+    
+    字段说明：
+        Result: 错误码字段，用于标识请求处理结果
+                - "succ" 表示成功
+                - 其他值表示失败，具体含义参考API文档
+    
+    配置说明：
+        extra: "allow" - 允许响应中包含模型未定义的额外字段
+               这是因为API可能返回一些未在文档中明确说明的字段
+    """
+    Result: str = Field(..., title="错误码", description="错误码，succ表示成功，其他表示失败")
+
+    model_config = {
+        "extra": "allow"  # 允许额外动态字段，兼容API返回的扩展字段
+    }
+
+
+class Success(Base):
+    """
+    成功响应模型
+    
+    继承自Base，专门用于表示API请求成功的响应。
+    
+    字段约束：
+        Result: 固定为"succ"，使用Literal类型进行严格类型约束
+    
+    使用场景：
+        - 验证响应是否为成功状态
+        - 作为响应数据的标准化容器
+        - 与utils中的build_success_instance函数配合使用
+    
+    代码演示：
+        >>> from py_lmobile_toolkit.sms.responses import Success
+        >>> result = Success(Result="succ")
+        >>> print(result.Result)
+        'succ'
+        >>> result.model_dump()
+        {'Result': 'succ'}
+    """
+    Result: Literal["succ"] = Field(..., title="错误码", description="成功，值为succ")

py_lmobile_toolkit/sms/utils.py

@@ -0,0 +1,273 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+"""
+工具函数模块
+
+本模块提供短信服务所需的辅助工具函数，包括：
+- JSON数据处理工具
+- 时间戳生成
+- 随机数生成
+- SHA256签名生成
+- 响应模型转换
+- JSON Schema校验
+
+这些工具函数被Sms客户端内部使用，也可单独导出供外部使用。
+
+官方 API 文档：https://www.lmobile.cn/ApiPages/index.html
+"""
+
+import hashlib
+import random
+import string
+from datetime import datetime
+from typing import Any, Optional, Union
+
+import httpx
+from jsonpath_ng import parse
+from jsonschema.validators import Draft202012Validator
+
+from .responses import Success
+
+
+def json_find_first(expression: str, data: Any) -> Any:
+    """
+    使用 JSONPath 表达式从数据中查找第一个匹配项
+    
+    JSONPath是一种用于在JSON数据中定位和提取信息的查询语言，
+    类似于XPath用于XML文档的查询。
+    
+    Args:
+        expression: JSONPath表达式，用于指定要查找的数据路径
+        data: 待查询的JSON数据（字典或列表）
+    
+    Returns:
+        Any: 第一个匹配的值，如果没有匹配项则返回None
+    
+    支持的JSONPath语法示例：
+        - $.key: 获取根节点下的key字段
+        - $..key: 递归查找所有名为key的字段
+        - $.list[0]: 获取列表的第一个元素
+        - $.list[*].name: 获取列表所有元素的name字段
+    
+    代码演示：
+        >>> data = {"store": {"books": [{"title": "Python"}, {"title": "Java"}]}}
+        >>> json_find_first("$.store.books[0].title", data)
+        'Python'
+    """
+    # 使用jsonpath_ng解析表达式并查找匹配项
+    results = [i.value for i in parse(expression).find(data)]
+    
+    # 返回第一个匹配结果，若无匹配则返回None
+    if isinstance(results, list) and len(results) > 0:
+        return results[0]
+    return None
+
+
+def json_is_valid(schema: Optional[dict], data: Any) -> bool:
+    """
+    校验 JSON 数据是否符合指定的 JSON Schema
+    
+    JSON Schema是一种用于定义JSON数据结构的规范，可用于数据验证、
+    文档生成和代码生成等场景。本函数使用Draft2020-12版本的规范。
+    
+    Args:
+        schema: JSON Schema字典，定义了数据的结构约束
+        data: 待校验的JSON数据
+    
+    Returns:
+        bool: 校验是否成功，True表示符合Schema，False表示不符合
+    
+    代码演示：
+        >>> schema = {"type": "object", "properties": {"name": {"type": "string"}}, "required": ["name"]}
+        >>> json_is_valid(schema, {"name": "test"})
+        True
+        >>> json_is_valid(schema, {"age": 18})
+        False
+    """
+    # 使用Draft2020-12版本的Validator进行校验
+    return Draft202012Validator(schema).is_valid(data)
+
+
+def timestamp() -> int:
+    """
+    生成当前时间戳（毫秒）
+    
+    返回当前时间距离1970年1月1日00:00:00 UTC的毫秒数，
+    用于请求的时效性验证和签名生成。
+    
+    Returns:
+        int: 当前时间戳（毫秒）
+    
+    设计说明：
+        - 使用datetime.now().timestamp()获取秒级时间戳
+        - 乘以1000转换为毫秒
+        - 使用int()取整，确保返回整数类型
+    
+    代码演示：
+        >>> ts = timestamp()
+        >>> print(ts)  # 输出示例: 1630000000000
+        >>> isinstance(ts, int)
+        True
+    """
+    return int((datetime.now().timestamp() * 1000))
+
+
+def random_digits(length: int = 10) -> int:
+    """
+    生成指定长度的随机数字
+    
+    从数字字符集'0123456789'中随机选取指定长度的字符，
+    拼接后转换为整数返回。
+    
+    Args:
+        length: 随机数的长度，默认为10位
+    
+    Returns:
+        int: 指定长度的随机数字
+    
+    实现细节：
+        - 使用random.sample()确保不会出现重复字符
+        - 使用string.digits获取数字字符集
+        - 转换为整数而非字符串，便于后续计算和比较
+    
+    代码演示：
+        >>> digits = random_digits(6)
+        >>> print(digits)  # 输出示例: 123456
+        >>> len(str(digits))
+        6
+    """
+    # 从数字字符集中随机选取length个字符，拼接后转换为整数
+    return int("".join(random.sample(string.digits, length)))
+
+
+def sha256_signature(
+        account_id: str = "",
+        password: str = "",
+        phone_nos: str = "",
+        random_digits: Optional[Union[int, str]] = "",
+        timestamp: Optional[Union[int, str]] = "",
+        smms_encrypt_key: str = ""
+) -> str:
+    """
+    生成SHA256签名
+    
+    按照微网通联API要求的格式生成签名，用于短信发送请求的认证。
+    
+    签名生成算法（严格按照API要求的顺序）：
+        1. 密码MD5加密：password + smms_encrypt_key -> MD5 -> 转大写
+        2. 参数拼接：AccountId={account_id}&PhoneNos={first_phone}&Password={md5_password}&Random={random}&Timestamp={timestamp}
+        3. SHA256加密：对拼接后的字符串进行SHA256哈希
+    
+    Args:
+        account_id: 账号ID
+        password: 原始密码
+        phone_nos: 手机号，多个手机号用逗号分隔（签名时只取第一个）
+        random_digits: 随机数字（由random_digits()生成）
+        timestamp: 时间戳（由timestamp()生成）
+        smms_encrypt_key: 加密密钥，作为MD5加密的盐值
+    
+    Returns:
+        str: SHA256签名结果（64位十六进制字符串）
+    
+    代码演示：
+        >>> signature = sha256_signature(
+        ...     account_id="dljtwy00",
+        ...     password="g07KjuLN1",
+        ...     phone_nos="13800138000",
+        ...     random_digits="1234567890",
+        ...     timestamp="1630000000000",
+        ...     smms_encrypt_key="SMmsEncryptKey"
+        ... )
+        >>> len(signature)
+        64
+    """
+    # 步骤1：对密码进行MD5加密，使用加密密钥作为盐值
+    # 格式：MD5(password + smms_encrypt_key)，结果转大写
+    password_md5 = hashlib.md5(f"{password}{smms_encrypt_key}".encode('utf-8')).hexdigest()
+
+    # 步骤2：按照API要求的顺序拼接参数
+    # 注意：PhoneNos只取第一个手机号用于签名
+    temp_string = "&".join([
+        f"AccountId={account_id}",
+        f"PhoneNos={phone_nos.split(',')[0]}",  # 只取第一个手机号
+        f"Password={password_md5.upper()}",      # MD5结果转大写
+        f"Random={random_digits}",
+        f"Timestamp={timestamp}",
+    ])
+
+    # 步骤3：对拼接后的字符串进行SHA256加密
+    return hashlib.sha256(temp_string.encode("utf-8")).hexdigest()
+
+
+def build_success_instance(response: Union[httpx.Response, dict]) -> Success:
+    """
+    将 HTTP 响应或字典转换为 Success 模型对象
+    
+    统一处理httpx.Response对象和字典，将其转换为标准化的Success响应模型，
+    便于后续的响应数据处理和校验。
+    
+    Args:
+        response: HTTP响应对象或字典数据
+    
+    Returns:
+        Success: 标准化的响应模型对象，包含Result字段
+    
+    处理逻辑：
+        - 如果输入是httpx.Response对象，先调用json()方法解析响应体
+        - 如果输入是字典，直接传入Success构造函数
+    
+    代码演示：
+        >>> response = httpx.Response(200, json={"Result": "succ"})
+        >>> result = build_success_instance(response)
+        >>> print(result.Result)
+        'succ'
+        >>> isinstance(result, Success)
+        True
+    """
+    if isinstance(response, httpx.Response):
+        return Success(**response.json())
+    return Success(**response)
+
+
+def success__is_valid(
+        response: Union[httpx.Response, dict] = None,
+        schema: dict = {
+            "type": "object",
+            "properties": {
+                "Result": {
+                    "oneOf": [
+                        {"type": "string", "const": "succ"}
+                    ]
+                },
+            },
+            "required": ["Result"]
+        }
+):
+    """
+    校验 HTTP 响应或字典是否符合成功响应的 JSON Schema
+    
+    用于验证API响应是否为预期的成功格式，确保响应数据的正确性。
+    
+    Args:
+        response: HTTP响应对象或字典数据
+        schema: JSON Schema字典，默认为成功响应的Schema
+    
+    Returns:
+        bool: 校验是否成功，True表示符合Schema，False表示不符合
+    
+    默认Schema说明：
+        - 必须是对象类型
+        - 必须包含Result字段
+        - Result字段的值必须是字符串"succ"
+    
+    代码演示：
+        >>> response = httpx.Response(200, json={"Result": "succ"})
+        >>> success__is_valid(response)
+        True
+        >>> success__is_valid({"Result": "fail"})
+        False
+    """
+    # 根据输入类型选择不同的处理方式
+    if isinstance(response, httpx.Response):
+        return json_is_valid(schema, response.json())
+    return json_is_valid(schema, response)

py_lmobile_toolkit-1.0.0.dist-info/METADATA

@@ -0,0 +1,326 @@
+Metadata-Version: 2.4
+Name: py-lmobile-toolkit
+Version: 1.0.0
+Summary: 微网通联（51welink）短信服务 Python SDK，提供同步和异步两种发送方式，支持请求签名认证
+Author-email: Guolei <174000902@qq.com>
+License: MIT License
+        
+        Copyright (c) 2026 郭磊
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://gitee.com/guolei19850528/py_lmobile_toolkit
+Project-URL: Repository, https://gitee.com/guolei19850528/py_lmobile_toolkit.git
+Project-URL: Documentation, https://www.lmobile.cn/ApiPages/index.html
+Keywords: lmobile,python,client,api,微网通联,短信,sms,51welink
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Communications
+Classifier: Topic :: Communications :: Telephony
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: jsonpath-ng>=1.5.3
+Requires-Dist: jsonschema>=4.21.0
+Requires-Dist: py-httpx-toolkit>=1.0.1
+Dynamic: license-file
+
+# py-lmobile-toolkit
+
+微网通联（51welink）短信服务 Python SDK，提供同步和异步两种发送方式，支持请求签名认证机制。
+
+## 作者
+
+**Guolei**
+
+- 邮箱：174000902@qq.com
+
+## 项目主页
+
+- **Gitee**: https://gitee.com/guolei19850528/py_lmobile_toolkit
+- **官方 API 文档**: https://www.lmobile.cn/ApiPages/index.html
+
+## 功能特性
+
+- ✅ 同步短信发送接口
+- ✅ 异步短信发送接口
+- ✅ 请求签名认证机制（SHA256）
+- ✅ 响应数据模型验证（Pydantic）
+- ✅ 完整的工具函数支持
+
+## 安装
+
+使用 `uv` 安装：
+
+```bash
+uv add py-lmobile-toolkit
+```
+
+或从pip安装：
+
+```bash
+pip install py-lmobile-toolkit
+```
+
+## 依赖包
+
+| 依赖 | 版本要求 | 说明 |
+|------|----------|------|
+| httpx | >=0.27.0 | HTTP 客户端 |
+| pydantic | >=2.0 | 数据验证 |
+| jsonpath-ng | >=1.5.3 | JSONPath 查询 |
+| jsonschema | >=4.21.0 | JSON Schema 校验 |
+| py-httpx-toolkit | >=1.0.1 | HTTP 工具封装 |
+
+## API 接口
+
+### Sms 类
+
+短信客户端核心类，提供同步和异步发送接口。
+
+#### 初始化
+
+```python
+from py_lmobile_toolkit.sms import Sms
+
+sms = Sms(
+    account_id="your_account",
+    password="your_password",
+    product_id="your_product"
+)
+```
+
+**参数说明**:
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| base_url | str | https://api.51welink.com/ | API 服务器地址 |
+| account_id | str | None | 账号 ID |
+| password | str | None | 账号密码 |
+| product_id | str/int | None | 产品 ID |
+| smms_encrypt_key | str | SMmsEncryptKey | 加密密钥 |
+| client_kwargs | dict | None | httpx.Client 配置 |
+
+#### 同步发送
+
+```python
+response = sms.send(
+    phone_nos="13800138000",
+    content="您的验证码是：123456"
+)
+```
+
+#### 异步发送
+
+```python
+response = await sms.async_send(
+    phone_nos=["13800138000", "13900139000"],
+    content="测试短信"
+)
+```
+
+**参数说明**:
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| phone_nos | str/list/tuple | 手机号码，支持单个或多个 |
+| content | str | 短信内容 |
+| client | httpx.Client/AsyncClient | 可选的客户端实例 |
+| client_kwargs | dict | 客户端配置 |
+
+## Utils 工具函数
+
+### 时间戳生成
+
+```python
+from py_lmobile_toolkit.sms.utils import timestamp
+
+ts = timestamp()  # 返回毫秒级时间戳
+```
+
+### 随机数生成
+
+```python
+from py_lmobile_toolkit.sms.utils import random_digits
+
+digits = random_digits(length=10)  # 生成10位随机数
+```
+
+### SHA256 签名生成
+
+```python
+from py_lmobile_toolkit.sms.utils import sha256_signature
+
+signature = sha256_signature(
+    account_id="dljtwy00",
+    password="g07KjuLN1",
+    phone_nos="13800138000",
+    random_digits="1234567890",
+    timestamp="1630000000000",
+    smms_encrypt_key="SMmsEncryptKey"
+)
+```
+
+### JSONPath 查询
+
+```python
+from py_lmobile_toolkit.sms.utils import json_find_first
+
+data = {"store": {"books": [{"title": "Python"}, {"title": "Java"}]}}
+title = json_find_first("$.store.books[0].title", data)  # 返回 "Python"
+```
+
+### JSON Schema 校验
+
+```python
+from py_lmobile_toolkit.sms.utils import json_is_valid
+
+schema = {"type": "object", "properties": {"name": {"type": "string"}}}
+valid = json_is_valid(schema, {"name": "test"})  # 返回 True
+```
+
+### 响应模型转换
+
+```python
+from py_lmobile_toolkit.sms.utils import build_success_instance
+
+result = build_success_instance(response)  # 转换为 Success 模型
+```
+
+## 响应模型
+
+### Base
+
+所有响应的基类：
+
+```python
+from py_lmobile_toolkit.sms.responses import Base
+
+class Base(BaseModel):
+    Result: str  # 错误码，succ 表示成功
+```
+
+### Success
+
+成功响应模型：
+
+```python
+from py_lmobile_toolkit.sms.responses import Success
+
+result = Success(Result="succ")
+```
+
+## 使用示例
+
+### 同步发送示例
+
+```python
+from py_lmobile_toolkit.sms import Sms
+
+# 初始化客户端
+sms = Sms(
+    account_id="your_account",
+    password="your_password",
+    product_id="your_product"
+)
+
+# 发送单条短信
+response = sms.send(
+    phone_nos="13800138000",
+    content="您的验证码是：123456"
+)
+
+# 解析响应
+data = response.json()
+print(f"发送结果: {data.get('Result')}")
+```
+
+### 异步发送示例
+
+```python
+import asyncio
+from py_lmobile_toolkit.sms import Sms
+
+async def main():
+    # 初始化客户端
+    sms = Sms(
+        account_id="your_account",
+        password="your_password",
+        product_id="your_product"
+    )
+
+    # 批量发送短信
+    response = await sms.async_send(
+        phone_nos=["13800138000", "13900139000", "13700137000"],
+        content="【通知】您的订单已发货"
+    )
+
+    # 解析响应
+    data = response.json()
+    print(f"发送结果: {data.get('Result')}")
+
+asyncio.run(main())
+```
+
+### 签名验证示例
+
+```python
+from py_lmobile_toolkit.sms.utils import sha256_signature, timestamp, random_digits
+
+# 生成签名所需参数
+ts = timestamp()
+digits = random_digits()
+
+# 生成签名
+signature = sha256_signature(
+    account_id="your_account",
+    password="your_password",
+    phone_nos="13800138000",
+    random_digits=digits,
+    timestamp=ts,
+    smms_encrypt_key="SMmsEncryptKey"
+)
+
+print(f"生成的签名: {signature}")
+```
+
+## 签名生成算法
+
+签名生成遵循以下步骤：
+
+1. **密码 MD5 加密**：`MD5(password + smms_encrypt_key)`，结果转大写
+2. **参数拼接**（按顺序）：
+   ```
+   AccountId={account_id}&PhoneNos={first_phone}&Password={md5_password}&Random={random}&Timestamp={timestamp}
+   ```
+3. **SHA256 加密**：对拼接后的字符串进行 SHA256 哈希
+
+## 许可证
+
+MIT License

py_lmobile_toolkit-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+py_lmobile_toolkit/__init__.py,sha256=BMXppKx35yJaI1CLgvFtEotzOEheeZmTAwSNTTIpOfE,813
+py_lmobile_toolkit/sms/__init__.py,sha256=ObWMMFmjMcXjuhlxR-jB5SZ9fTf4FCWWc2U4WucZS18,8845
+py_lmobile_toolkit/sms/responses.py,sha256=3FR5JuJcq7KGZ3074P3BgZYO14TfPXYfkjsXHgJqask,2203
+py_lmobile_toolkit/sms/utils.py,sha256=-tYocYe_AUH-hdg2cuDHGDnC-kaXCZboPx4lsgrdHFI,8975
+py_lmobile_toolkit-1.0.0.dist-info/licenses/LICENSE,sha256=HazFJNaQP3rbY1dvg3hAmO-FZ6v7DwM0YHwXvWsGG3A,1063
+py_lmobile_toolkit-1.0.0.dist-info/METADATA,sha256=QyPZFtNTBH2QnAmoC83CNN3gf4KBl1oEDFqySG7UAp0,8268
+py_lmobile_toolkit-1.0.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+py_lmobile_toolkit-1.0.0.dist-info/top_level.txt,sha256=cOZV6kg2o6nx4OrH7Qs3zP_Svy1zijgBt0xN9RuBb3A,19
+py_lmobile_toolkit-1.0.0.dist-info/RECORD,,

py_lmobile_toolkit-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

py_lmobile_toolkit-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 郭磊
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

py_lmobile_toolkit-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+py_lmobile_toolkit