pywecomarchive 0.1.0__py3-none-win_amd64.whl

pywecomarchive/__init__.py

@@ -0,0 +1,48 @@
+"""企业微信会话存档同步 SDK，公开输入输出均为 Python 数据类型。"""
+
+from .client import WecomArchiveSdk
+from .errors import (
+    SdkCallError,
+    SdkClosedError,
+    SdkDataExpiredError,
+    SdkDataParseError,
+    SdkDecryptError,
+    SdkDecryptMsgError,
+    SdkDeprecated10004Error,
+    SdkDeprecated10007Error,
+    SdkError,
+    SdkFileIdError,
+    SdkInvalidIpError,
+    SdkLoadError,
+    SdkNetworkError,
+    SdkRequestParameterError,
+    SdkResponseError,
+    SdkSslCertificateError,
+    SdkSystemCallError,
+)
+from .models import ChatDataResponse, EncryptedChatData, MediaData, Response
+
+__all__ = [
+    "Response",
+    "ChatDataResponse",
+    "EncryptedChatData",
+    "SdkRequestParameterError",
+    "SdkNetworkError",
+    "SdkDataParseError",
+    "SdkSystemCallError",
+    "SdkDeprecated10004Error",
+    "SdkFileIdError",
+    "SdkDecryptError",
+    "SdkDeprecated10007Error",
+    "SdkDecryptMsgError",
+    "SdkInvalidIpError",
+    "SdkDataExpiredError",
+    "SdkSslCertificateError",
+    "WecomArchiveSdk",
+    "MediaData",
+    "SdkCallError",
+    "SdkClosedError",
+    "SdkError",
+    "SdkLoadError",
+    "SdkResponseError",
+]

pywecomarchive/_adapter.py

@@ -0,0 +1,206 @@
+"""接口适配：校验参数、转换编码、处理错误并管理原生资源。"""
+
+import json
+from types import TracebackType
+from typing import Any
+
+from pydantic import TypeAdapter, ValidationError
+
+from ._buffers import NativeBuffers
+from ._native import NativeBinding
+from ._validation import (
+    CString,
+    Limit,
+    Pointer,
+    RequiredString,
+    SdkConfig,
+    Sequence,
+    checked,
+)
+from .errors import (
+    SDK_ERROR_TYPES,
+    SdkCallError,
+    SdkClosedError,
+    SdkError,
+    SdkResponseError,
+)
+from .models import ChatDataResponse, MediaData
+
+_POINTER_ADAPTER = TypeAdapter(Pointer)
+
+
+class SdkAdapter:
+    """返回 Python 数据，并在内部管理 SDK 句柄和原生缓冲区。"""
+
+    def __init__(
+        self,
+        corpid: str,
+        secret: str,
+        *,
+        proxy: str = "",
+        passwd: str = "",
+        timeout: int = 5,
+        library_path: str | None = None,
+    ) -> None:
+        config = SdkConfig(
+            corpid=corpid,
+            secret=secret,
+            proxy=proxy,
+            passwd=passwd,
+            timeout=timeout,
+            library_path=library_path,
+        )
+        self._config = config
+        self._binding = NativeBinding(config.library_path)
+        self._lib = self._binding.lib
+        self._utils = NativeBuffers(self._binding)
+        self._closed = False
+        self._handle = None
+        try:
+            self._handle = _POINTER_ADAPTER.validate_python(
+                self._lib.NewSdk(), strict=True
+            )
+            self._check(
+                "Init", self._lib.Init(self._handle, config.corpid, config.secret)
+            )
+        except ValidationError:
+            self.close()
+            raise SdkError("SDK 句柄分配失败") from None
+        except BaseException:
+            self.close()
+            raise
+
+    def _ensure_open(self) -> None:
+        if self._closed:
+            raise SdkClosedError("SDK 已经关闭")
+
+    @staticmethod
+    def _check(operation: str, code: int | None) -> None:
+        if type(code) is not int:
+            raise SdkResponseError(f"{operation} 返回无效的业务错误码")
+        if code == 0:
+            return
+        error_type = SDK_ERROR_TYPES.get(code)
+        if error_type is not None:
+            raise error_type(operation)
+        raise SdkCallError(operation, code)
+
+    @staticmethod
+    def _parse_json(raw: bytes, operation: str) -> dict[str, Any]:
+        try:
+            result = json.loads(raw)
+        except (ValueError, UnicodeError):
+            raise SdkResponseError(f"{operation} 返回无效的 JSON 数据") from None
+        if not isinstance(result, dict):
+            raise SdkResponseError(f"{operation} 返回的 JSON 必须是对象")
+        return result
+
+    @checked
+    def get_chat_data(self, seq: Sequence = 0, limit: Limit = 1000) -> ChatDataResponse:
+        """拉取一批加密消息，校验后返回响应模型。"""
+        self._ensure_open()
+        buffer = self._utils.new_slice()
+        try:
+            self._check(
+                "GetChatData",
+                self._lib.GetChatData(
+                    self._handle,
+                    seq,
+                    limit,
+                    self._config.proxy,
+                    self._config.passwd,
+                    self._config.timeout,
+                    buffer,
+                ),
+            )
+            result = self._parse_json(
+                self._utils.get_content_from_slice(buffer), "GetChatData"
+            )
+            code = result.get("errcode", None)
+            self._check("GetChatData", code)
+            try:
+                return ChatDataResponse.model_validate(result)
+            except ValidationError:
+                raise SdkResponseError("GetChatData 返回数据校验失败") from None
+        finally:
+            self._utils.free_slice(buffer)
+
+    @checked
+    def decrypt_data(
+        self, encrypt_key: RequiredString, encrypt_msg: RequiredString
+    ) -> dict[str, Any]:
+        """使用已解开的消息密钥解密，直接返回消息 JSON 对象。"""
+        self._ensure_open()
+        buffer = self._utils.new_slice()
+        try:
+            self._check(
+                "DecryptData",
+                self._lib.DecryptData(
+                    encrypt_key.encode(), encrypt_msg.encode(), buffer
+                ),
+            )
+            return self._parse_json(
+                self._utils.get_content_from_slice(buffer), "DecryptData"
+            )
+        finally:
+            self._utils.free_slice(buffer)
+
+    @checked
+    def get_media_data(
+        self, sdkfileid: RequiredString, indexbuf: CString = ""
+    ) -> MediaData:
+        """拉取一块媒体，返回内容、下一块索引和完成状态。"""
+        self._ensure_open()
+        buffer = self._utils.new_media_data()
+        try:
+            self._check(
+                "GetMediaData",
+                self._lib.GetMediaData(
+                    self._handle,
+                    indexbuf.encode(),
+                    sdkfileid.encode(),
+                    self._config.proxy,
+                    self._config.passwd,
+                    self._config.timeout,
+                    buffer,
+                ),
+            )
+            return MediaData(
+                data=self._utils.get_data(buffer),
+                indexbuf=self._utils.get_out_index_buf(buffer),
+                is_finish=self._utils.is_media_data_finish(buffer),
+            )
+        finally:
+            self._utils.free_media_data(buffer)
+
+    def __enter__(self) -> "SdkAdapter":
+        """进入上下文，在退出时释放 SDK 句柄。"""
+        self._ensure_open()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """退出时关闭封装，保留代码块内抛出的异常。"""
+        self.close()
+
+    def close(self) -> None:
+        """销毁 SDK 句柄并关闭库搜索目录。"""
+        if getattr(self, "_closed", False):
+            return
+        self._closed = True
+        handle = getattr(self, "_handle", None)
+        self._handle = None
+        try:
+            if handle is not None:
+                self._utils.destroy_sdk(handle)
+        finally:
+            binding = getattr(self, "_binding", None)
+            if binding is not None:
+                binding.close()
+
+    def __del__(self) -> None:
+        self.close()

pywecomarchive/_buffers.py

@@ -0,0 +1,86 @@
+"""接口适配层的缓冲区管理，所有指针仅供内部使用。"""
+
+from ._native import NativeBinding
+from ._validation import Length, Pointer, checked
+from .errors import SdkError, SdkResponseError
+
+
+class NativeBuffers:
+    """分配、读取并释放绑定层产生的缓冲区。"""
+
+    def __init__(self, binding: NativeBinding) -> None:
+        self._lib = binding.lib
+
+    @checked
+    def destroy_sdk(self, sdk: Pointer) -> None:
+        """释放 NewSdk 创建的句柄，调用后不得再次使用或释放。"""
+        self._lib.DestroySdk(sdk)
+
+    @checked
+    def new_slice(self) -> Pointer:
+        buffer = self._lib.NewSlice()
+        if not buffer:
+            raise SdkError("SDK 消息缓冲区分配失败")
+        return buffer
+
+    @checked
+    def free_slice(self, buffer: Pointer) -> None:
+        self._lib.FreeSlice(buffer)
+
+    @checked
+    def get_content_from_slice(self, buffer: Pointer) -> bytes:
+        return self._read(
+            self._lib.GetContentFromSlice(buffer), self._get_slice_len(buffer)
+        )
+
+    @checked
+    def new_media_data(self) -> Pointer:
+        buffer = self._lib.NewMediaData()
+        if not buffer:
+            raise SdkError("SDK 媒体缓冲区分配失败")
+        return buffer
+
+    @checked
+    def free_media_data(self, buffer: Pointer) -> None:
+        self._lib.FreeMediaData(buffer)
+
+    @checked
+    def get_out_index_buf(self, buffer: Pointer) -> str:
+        raw = self._read(self._lib.GetOutIndexBuf(buffer), self._get_index_len(buffer))
+        try:
+            return raw.decode("utf-8")
+        except UnicodeError:
+            raise SdkResponseError("GetOutIndexBuf 返回无效的 UTF-8 数据") from None
+
+    @checked
+    def get_data(self, buffer: Pointer) -> bytes:
+        return self._read(self._lib.GetData(buffer), self._get_data_len(buffer))
+
+    @checked
+    def is_media_data_finish(self, buffer: Pointer) -> bool:
+        finish = self._lib.IsMediaDataFinish(buffer)
+        if finish not in (0, 1):
+            raise SdkResponseError("IsMediaDataFinish 返回无效的完成标志")
+        return bool(finish)
+
+    @checked
+    def _get_slice_len(self, buffer: Pointer) -> Length:
+        return self._lib.GetSliceLen(buffer)
+
+    @checked
+    def _get_index_len(self, buffer: Pointer) -> Length:
+        return self._lib.GetIndexLen(buffer)
+
+    @checked
+    def _get_data_len(self, buffer: Pointer) -> Length:
+        return self._lib.GetDataLen(buffer)
+
+    @staticmethod
+    @checked
+    def _read(pointer: Pointer | None, length: Length) -> bytes:
+        if length < 0 or (length and not pointer):
+            raise SdkResponseError("SDK 返回无效的缓冲区")
+        if not length:
+            return b""
+        assert pointer is not None
+        return NativeBinding.read(pointer, length)

pywecomarchive/_native.py

@@ -0,0 +1,118 @@
+"""底层绑定：加载动态库并声明官方 C ABI，不处理业务数据。"""
+
+import ctypes as ct
+import os
+import platform
+from pathlib import Path
+
+from .errors import SdkLoadError
+
+
+def default_library() -> Path:
+    root = Path(__file__).resolve().parent / "lib"
+    machine = platform.machine().lower()
+    if platform.system() == "Windows" and machine in {"amd64", "x86_64"}:
+        return root / "windows/WeWorkFinanceSdk.dll"
+    if platform.system() == "Linux" and machine in {
+        "amd64",
+        "x86_64",
+        "aarch64",
+        "arm64",
+    }:
+        arch = "arm64" if machine in {"aarch64", "arm64"} else "x86_64"
+        return root / f"linux/{arch}/libWeWorkFinanceSdk_C.so"
+    raise SdkLoadError("当前系统或架构不受本地 SDK 支持")
+
+
+class NativeBinding:
+    """持有动态库与依赖搜索目录，供内部适配层使用。"""
+
+    def __init__(self, library_path: str | None = None) -> None:
+        self._directory = None
+        try:
+            path = (Path(library_path) if library_path else default_library()).resolve()
+            if os.name == "nt":
+                self._directory = os.add_dll_directory(str(path.parent))
+            self.lib = ct.CDLL(str(path))
+            self._configure_functions()
+        except (OSError, AttributeError):
+            self.close()
+            raise SdkLoadError("原生 SDK 加载失败，请检查库文件、架构及依赖") from None
+
+    def close(self) -> None:
+        if self._directory is not None:
+            self._directory.close()
+            self._directory = None
+
+    @staticmethod
+    def read(pointer: int, length: int) -> bytes:
+        return ct.string_at(pointer, length)
+
+    def _configure_functions(self) -> None:
+        """显式配置原生函数的参数类型和返回类型。"""
+        self.lib.NewSdk.argtypes = []
+        self.lib.NewSdk.restype = ct.c_void_p
+
+        self.lib.Init.argtypes = [ct.c_void_p, ct.c_char_p, ct.c_char_p]
+        self.lib.Init.restype = ct.c_int
+
+        self.lib.GetChatData.argtypes = [
+            ct.c_void_p,
+            ct.c_ulonglong,
+            ct.c_uint,
+            ct.c_char_p,
+            ct.c_char_p,
+            ct.c_int,
+            ct.c_void_p,
+        ]
+        self.lib.GetChatData.restype = ct.c_int
+
+        self.lib.DecryptData.argtypes = [ct.c_char_p, ct.c_char_p, ct.c_void_p]
+        self.lib.DecryptData.restype = ct.c_int
+
+        self.lib.GetMediaData.argtypes = [
+            ct.c_void_p,
+            ct.c_char_p,
+            ct.c_char_p,
+            ct.c_char_p,
+            ct.c_char_p,
+            ct.c_int,
+            ct.c_void_p,
+        ]
+        self.lib.GetMediaData.restype = ct.c_int
+
+        self.lib.DestroySdk.argtypes = [ct.c_void_p]
+        self.lib.DestroySdk.restype = None
+
+        self.lib.NewSlice.argtypes = []
+        self.lib.NewSlice.restype = ct.c_void_p
+
+        self.lib.FreeSlice.argtypes = [ct.c_void_p]
+        self.lib.FreeSlice.restype = None
+
+        self.lib.GetContentFromSlice.argtypes = [ct.c_void_p]
+        self.lib.GetContentFromSlice.restype = ct.c_void_p
+
+        self.lib.GetSliceLen.argtypes = [ct.c_void_p]
+        self.lib.GetSliceLen.restype = ct.c_int
+
+        self.lib.NewMediaData.argtypes = []
+        self.lib.NewMediaData.restype = ct.c_void_p
+
+        self.lib.FreeMediaData.argtypes = [ct.c_void_p]
+        self.lib.FreeMediaData.restype = None
+
+        self.lib.GetOutIndexBuf.argtypes = [ct.c_void_p]
+        self.lib.GetOutIndexBuf.restype = ct.c_void_p
+
+        self.lib.GetData.argtypes = [ct.c_void_p]
+        self.lib.GetData.restype = ct.c_void_p
+
+        self.lib.GetIndexLen.argtypes = [ct.c_void_p]
+        self.lib.GetIndexLen.restype = ct.c_int
+
+        self.lib.GetDataLen.argtypes = [ct.c_void_p]
+        self.lib.GetDataLen.restype = ct.c_int
+
+        self.lib.IsMediaDataFinish.argtypes = [ct.c_void_p]
+        self.lib.IsMediaDataFinish.restype = ct.c_int

pywecomarchive/_validation.py

@@ -0,0 +1,127 @@
+"""SDK 内部配置、参数约束与调用校验。"""
+
+import ctypes
+from collections.abc import Callable
+from functools import wraps
+from typing import Annotated, ParamSpec, TypeVar, get_type_hints
+
+from pydantic import (
+    AfterValidator,
+    BaseModel,
+    ConfigDict,
+    Field,
+    TypeAdapter,
+    ValidationError,
+    field_validator,
+    validate_call,
+)
+
+from .errors import SdkResponseError
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+
+def check_c_string(value: str) -> str:
+    if "\x00" in value:
+        raise ValueError("字符串不能包含空字符")
+    try:
+        value.encode("utf-8")
+    except UnicodeError:
+        raise ValueError("字符串不能编码为 UTF-8") from None
+    return value
+
+
+CString = Annotated[str, AfterValidator(check_c_string)]
+RequiredString = Annotated[CString, Field(min_length=1)]
+Pointer = Annotated[int, Field(gt=0, le=2 ** (ctypes.sizeof(ctypes.c_void_p) * 8) - 1)]
+Sequence = Annotated[int, Field(ge=0, le=2**64 - 1)]
+Limit = Annotated[int, Field(ge=1, le=1000)]
+Length = Annotated[int, Field(ge=0, le=2**31 - 1)]
+
+
+class SdkConfig(BaseModel):
+    """SDK 初始化配置，在加载原生库前严格校验。"""
+
+    model_config = ConfigDict(
+        strict=True, extra="forbid", frozen=True, hide_input_in_errors=True
+    )
+
+    corpid: bytes = Field(min_length=1, strict=False)
+    secret: bytes = Field(min_length=1, strict=False, repr=False)
+    proxy: bytes = Field(default=b"", strict=False)
+    passwd: bytes = Field(default=b"", strict=False, repr=False)
+    timeout: int = Field(default=5, ge=1, le=2**31 - 1)
+    library_path: str | None = Field(default=None, min_length=1)
+
+    def __init__(
+        self,
+        *,
+        corpid: str | bytes,
+        secret: str | bytes,
+        proxy: str | bytes = b"",
+        passwd: str | bytes = b"",
+        timeout: int = 5,
+        library_path: str | None = None,
+    ) -> None:
+        super().__init__(
+            corpid=corpid,
+            secret=secret,
+            proxy=proxy,
+            passwd=passwd,
+            timeout=timeout,
+            library_path=library_path,
+        )
+
+    @field_validator("corpid", "secret", "proxy", "passwd", mode="before")
+    @classmethod
+    def validate_string_input(cls, value: object) -> str | bytes:
+        """仅接受字符串或字节串，由 Pydantic 完成编码转换。"""
+        if not isinstance(value, (str, bytes)):
+            raise ValueError("参数必须是字符串或字节串")
+        return value
+
+    @field_validator("corpid", "secret", "proxy", "passwd")
+    @classmethod
+    def validate_c_bytes(cls, value: bytes) -> bytes:
+        """避免 C 字符串被空字符截断，并确保内容为 UTF-8。"""
+        if b"\x00" in value:
+            raise ValueError("字符串不能包含空字符")
+        try:
+            value.decode("utf-8")
+        except UnicodeError:
+            raise ValueError("字节串必须是有效的 UTF-8") from None
+        return value
+
+    @field_validator("library_path")
+    @classmethod
+    def validate_library_path(cls, value: str | None) -> str | None:
+        """库路径保留字符串类型，供 pathlib 使用。"""
+        if value is None:
+            return None
+        return check_c_string(value)
+
+
+def checked(function: Callable[P, T]) -> Callable[P, T]:
+    """严格校验方法输入输出，参数错误直接抛出 Pydantic 验证异常。"""
+    config = ConfigDict(
+        strict=True, arbitrary_types_allowed=True, hide_input_in_errors=True
+    )
+    validated = validate_call(config=config)(function)
+    return_type = get_type_hints(function, include_extras=True)["return"]
+    output = TypeAdapter(
+        return_type,
+        config=None
+        if isinstance(return_type, type) and issubclass(return_type, BaseModel)
+        else config,
+    )
+
+    @wraps(function)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+        result = validated(*args, **kwargs)
+        try:
+            return output.validate_python(result, strict=True)
+        except ValidationError:
+            raise SdkResponseError(f"{function.__name__} 返回数据校验失败") from None
+
+    return wrapper

pywecomarchive/client.py

@@ -0,0 +1,103 @@
+"""业务 API：调用方只需传入和接收 Python 数据。"""
+
+from collections.abc import Iterator
+from types import TracebackType
+from typing import TypeVar, overload
+
+from pydantic import TypeAdapter, ValidationError
+
+from ._adapter import SdkAdapter
+from .errors import SdkResponseError
+from .models import ArchiveMessage, ChatDataResponse, MediaData, message_adapter
+
+T = TypeVar("T")
+
+
+class WecomArchiveSdk:
+    """同步会话存档客户端；支持显式关闭与上下文管理。"""
+
+    def __init__(
+        self,
+        corpid: str,
+        secret: str,
+        *,
+        proxy: str = "",
+        passwd: str = "",
+        timeout: int = 5,
+        library_path: str | None = None,
+    ) -> None:
+        self._adapter = SdkAdapter(
+            corpid,
+            secret,
+            proxy=proxy,
+            passwd=passwd,
+            timeout=timeout,
+            library_path=library_path,
+        )
+
+    def get_chat_data(self, seq: int = 0, limit: int = 1000) -> ChatDataResponse:
+        """拉取一批加密消息，返回支持属性访问的响应模型。"""
+        return self._adapter.get_chat_data(seq, limit)
+
+    @overload
+    def decrypt_data(self, encrypt_key: str, encrypt_msg: str) -> ArchiveMessage: ...
+
+    @overload
+    def decrypt_data(
+        self, encrypt_key: str, encrypt_msg: str, *, adapter: TypeAdapter[T]
+    ) -> T: ...
+
+    def decrypt_data(
+        self,
+        encrypt_key: str,
+        encrypt_msg: str,
+        *,
+        adapter: TypeAdapter[T] | None = None,
+    ) -> ArchiveMessage | T:
+        """解密并校验消息；默认使用内置模型，也可传入自定义 TypeAdapter。"""
+        value = self._adapter.decrypt_data(encrypt_key, encrypt_msg)
+        try:
+            if adapter is None:
+                return message_adapter.validate_python(value, strict=True)
+            return adapter.validate_python(value, strict=True)
+        except ValidationError:
+            raise SdkResponseError("解密后的消息格式校验失败") from None
+
+    def get_media_data(self, sdkfileid: str, indexbuf: str = "") -> MediaData:
+        """拉取媒体分块，用返回的 indexbuf 继续获取后续内容。"""
+        return self._adapter.get_media_data(sdkfileid, indexbuf)
+
+    def iter_media_data(
+        self, sdkfileid: str, indexbuf: str = ""
+    ) -> Iterator[MediaData]:
+        """从指定索引逐块下载，首次迭代时校验参数并发起请求。
+
+        每次返回完整的 MediaData，包含可用于断点续传的下一块索引。
+        调用失败直接抛出异常；停止迭代不会关闭客户端。
+        """
+        while True:
+            chunk = self.get_media_data(sdkfileid, indexbuf)
+            if not chunk.is_finish and (
+                not chunk.indexbuf or chunk.indexbuf == indexbuf
+            ):
+                raise SdkResponseError("GetMediaData 未完成但续传索引为空或未前进")
+            yield chunk
+            if chunk.is_finish:
+                return
+            indexbuf = chunk.indexbuf
+
+    def close(self) -> None:
+        """释放原生资源，可重复调用。"""
+        self._adapter.close()
+
+    def __enter__(self) -> "WecomArchiveSdk":
+        self._adapter.__enter__()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()