py-wecom-sdk 0.1.0__py3-none-any.whl

py_wecom_sdk/__init__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+from .provider import APIProvider as WeComAPIProvider
+
+__all__ = [
+    "WeComAPIProvider",
+]

py_wecom_sdk/core/group_robot/__init__.py

@@ -0,0 +1,17 @@
+"""群机器人公共接口，提供同步/异步客户端及响应模型。
+
+官方文档：https://developer.work.weixin.qq.com/document/path/91770
+"""
+
+from __future__ import annotations
+
+from ._api import API as GroupRobotAPI, AsyncAPI as GroupRobotAsyncAPI
+from ._models import SendResponse as GroupRobotSendResponse, UploadMediaResponse as GroupRobotUploadMediaResponse
+
+# 公共导出名称；官方文档：https://developer.work.weixin.qq.com/document/path/91770
+__all__ = [
+    "GroupRobotAPI",
+    "GroupRobotAsyncAPI",
+    "GroupRobotSendResponse",
+    "GroupRobotUploadMediaResponse",
+]

py_wecom_sdk/core/group_robot/_api.py

@@ -0,0 +1,488 @@
+"""群机器人同步与异步接口。
+
+官方文档：https://developer.work.weixin.qq.com/document/path/91770
+"""
+
+from __future__ import annotations
+
+import warnings
+from pathlib import Path
+from typing import Any, BinaryIO, Literal
+
+import httpx
+
+from ._models import SendResponse as GroupRobotSendResponse
+from ._models import UploadMediaResponse as GroupRobotUploadMediaResponse
+
+__all__ = ["API", "AsyncAPI"]
+
+# 企业微信 API 根地址；官方文档：https://developer.work.weixin.qq.com/document/path/91770
+DEFAULT_BASE_URL = "https://qyapi.weixin.qq.com/"
+# 消息发送地址；官方文档：https://developer.work.weixin.qq.com/document/path/91770#消息类型及数据格式
+DEFAULT_SEND_URL = "/cgi-bin/webhook/send"
+# 素材上传地址；官方文档：https://developer.work.weixin.qq.com/document/path/91770#文件上传接口
+DEFAULT_UPLOAD_MEDIA_URL = "/cgi-bin/webhook/upload_media"
+
+
+def _extract_media(
+    media: bytes | bytearray | str | Path | BinaryIO,
+    *,
+    filename: str | None = None,
+) -> tuple[str, bytes]:
+    """将素材转换为 multipart 上传所需的文件名和二进制内容。
+
+    Args:
+        media: 原始字节、文件路径或已打开的二进制文件对象。
+        filename: 显式文件名；未指定时从路径或文件对象推断，最后使用 media。
+
+    Returns:
+        文件名与原始字节。文件对象从当前位置读取，不负责关闭或重置游标。
+
+    Raises:
+        OSError: 路径不存在、指向目录或无法读取。
+        TypeError: 文件对象未返回二进制内容。
+
+    官方文档：https://developer.work.weixin.qq.com/document/path/91770#文件上传接口
+    """
+    if isinstance(media, (bytes, bytearray)):
+        return filename or "media", bytes(media)
+
+    if isinstance(media, (str, Path)):
+        path = Path(media)
+        return filename or path.name, path.read_bytes()
+
+    name = getattr(media, "name", None)
+    filename = filename or (Path(name).name if isinstance(name, (str, Path)) else "media")
+    content = media.read()
+    if not isinstance(content, (bytes, bytearray)):
+        raise TypeError("media 必须是二进制文件对象，请使用 rb 模式打开文件")
+    return filename or "media", bytes(content)
+
+
+class _BaseAPI:
+    """群机器人 API 公共基类，封装初始化和资源管理。"""
+
+    def __init__(
+        self,
+        key: str | None,
+        mentioned_list: list[str] | None,
+        mentioned_mobile_list: list[str] | None,
+        base_url: str | None,
+        timeout: float | tuple[float, float, float, float],
+        client_kwargs: dict[str, Any] | None,
+    ):
+        self.key = key or ""
+        if not self.key:
+            warnings.warn("未提供群机器人 key，消息发送将会失败", stacklevel=3)
+        self.mentioned_list = mentioned_list or []
+        self.mentioned_mobile_list = mentioned_mobile_list or []
+        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self.client_kwargs = client_kwargs or {}
+        self.client_kwargs.setdefault("base_url", self.base_url)
+        self.client_kwargs.setdefault("timeout", timeout)
+
+
+class API(_BaseAPI):
+    """企业微信群机器人同步 API。
+
+    官方文档：https://developer.work.weixin.qq.com/document/path/91770
+    """
+
+    def __init__(
+        self,
+        key: str | None = None,
+        mentioned_list: list[str] | None = None,
+        mentioned_mobile_list: list[str] | None = None,
+        base_url: str | None = None,
+        timeout: float | tuple[float, float, float, float] = 60.0,
+        client: httpx.Client | None = None,
+        client_kwargs: dict[str, Any] | None = None,
+    ):
+        """初始化同步客户端。
+
+        Args:
+            key: 群机器人的 Webhook key。
+            mentioned_list: 默认 @ 的成员 userid 列表。
+            mentioned_mobile_list: 默认 @ 的成员手机号列表。
+            base_url: API 根地址。
+            timeout: HTTP 请求超时时间。
+            client: 可选的已配置 httpx.Client。
+            client_kwargs: 未传入 client 时创建客户端的配置。
+
+        官方文档：https://developer.work.weixin.qq.com/document/path/91770
+        """
+        super().__init__(key, mentioned_list, mentioned_mobile_list, base_url, timeout, client_kwargs)
+        self.client = client or httpx.Client(**self.client_kwargs)
+
+    # --- 资源管理 ---
+
+    def close(self) -> None:
+        """关闭底层 HTTP 客户端，释放连接池。"""
+        self.client.close()
+
+    def __enter__(self) -> "API":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    # --- 发送接口 ---
+
+    def send(self, payload: dict[str, Any] | None = None) -> GroupRobotSendResponse:
+        """发送消息。
+
+        Args:
+            payload: 符合企业微信机器人消息格式的请求体。
+
+        Returns:
+            经过模型校验的发送响应，包含业务错误码和错误信息。
+
+        Raises:
+            httpx.HTTPStatusError: HTTP 状态码表示请求失败时抛出；业务错误需查看返回模型。
+
+        官方文档：https://developer.work.weixin.qq.com/document/path/91770#消息类型及数据格式
+        """
+        response = self.client.post(
+            url=DEFAULT_SEND_URL,
+            json=payload or {},
+            params={"key": self.key},
+        )
+        response.raise_for_status()
+        return GroupRobotSendResponse.model_validate(response.json())
+
+    def send_text(
+        self,
+        content: str = "",
+        mentioned_list: list[str] | None = None,
+        mentioned_mobile_list: list[str] | None = None,
+    ) -> GroupRobotSendResponse:
+        """发送文本消息。
+
+        Args:
+            content: 文本内容。
+            mentioned_list: 本次额外 @ 的成员 userid 列表。
+            mentioned_mobile_list: 本次额外 @ 的成员手机号列表。
+
+        Returns:
+            包含业务错误码和错误信息的发送响应模型。
+
+        官方文档：https://developer.work.weixin.qq.com/document/path/91770#文本类型
+        """
+        return self.send(
+            {
+                "msgtype": "text",
+                "text": {
+                    "content": content,
+                    "mentioned_list": self.mentioned_list + (mentioned_list or []),
+                    "mentioned_mobile_list": self.mentioned_mobile_list + (mentioned_mobile_list or []),
+                },
+            }
+        )
+
+    def send_markdown(self, content: str = "") -> GroupRobotSendResponse:
+        """发送 Markdown 消息。
+
+        Args:
+            content: Markdown 内容，最长 4096 个 UTF-8 字节。
+        Returns:
+            发送响应模型，业务错误通过错误码和错误信息表示。
+        官方文档：https://developer.work.weixin.qq.com/document/path/91770#markdown类型
+        """
+        return self.send({"msgtype": "markdown", "markdown": {"content": content}})
+
+    def send_markdown_v2(self, content: str = "") -> GroupRobotSendResponse:
+        """发送 Markdown V2 消息。
+
+        Args:
+            content: Markdown V2 内容，最长 4096 个 UTF-8 字节，不支持字体颜色和 @成员。
+        Returns:
+            发送响应模型，业务错误通过错误码和错误信息表示。
+        官方文档：https://developer.work.weixin.qq.com/document/path/91770#markdown-v2类型
+        """
+        return self.send({"msgtype": "markdown_v2", "markdown_v2": {"content": content}})
+
+    def send_image(self, base64: str, md5: str) -> GroupRobotSendResponse:
+        """发送图片消息。
+
+        Args:
+            base64: 图片二进制内容的 Base64 编码。
+            md5: 原始图片内容的 MD5；图片限 2MB，支持 JPG、PNG。
+        Returns:
+            发送响应模型，业务错误通过错误码和错误信息表示。
+        官方文档：https://developer.work.weixin.qq.com/document/path/91770#图片类型
+        """
+        return self.send({"msgtype": "image", "image": {"base64": base64, "md5": md5}})
+
+    def send_news(self, articles: list[dict[str, Any]]) -> GroupRobotSendResponse:
+        """发送 1 到 8 条图文，每条需包含 title、url，可选 description、picurl。
+
+        Args:
+            articles: 1 到 8 条图文文章数据。
+        Returns:
+            发送响应模型，业务错误通过错误码和错误信息表示。
+        官方文档：https://developer.work.weixin.qq.com/document/path/91770#图文类型
+        """
+        return self.send({"msgtype": "news", "news": {"articles": articles}})
+
+    def send_file(self, media_id: str) -> GroupRobotSendResponse:
+        """发送文件，media_id 由文件上传接口获取。
+
+        Args:
+            media_id: 文件上传接口返回的素材 ID。
+        Returns:
+            发送响应模型，业务错误通过错误码和错误信息表示。
+        官方文档：https://developer.work.weixin.qq.com/document/path/91770#文件类型
+        """
+        return self.send({"msgtype": "file", "file": {"media_id": media_id}})
+
+    def send_voice(self, media_id: str) -> GroupRobotSendResponse:
+        """发送语音，media_id 由语音上传接口获取。
+
+        Args:
+            media_id: 语音上传接口返回的素材 ID。
+        Returns:
+            发送响应模型，业务错误通过错误码和错误信息表示。
+        官方文档：https://developer.work.weixin.qq.com/document/path/91770#语音类型
+        """
+        return self.send({"msgtype": "voice", "voice": {"media_id": media_id}})
+
+    def send_template_card(self, template_card: dict[str, Any]) -> GroupRobotSendResponse:
+        """发送模板卡片，card_type 支持 text_notice 和 news_notice。
+
+        Args:
+            template_card: 模板卡片请求数据。
+        Returns:
+            发送响应模型，业务错误通过错误码和错误信息表示。
+        官方文档：https://developer.work.weixin.qq.com/document/path/91770#模版卡片类型
+        """
+        return self.send({"msgtype": "template_card", "template_card": template_card})
+
+    # --- 素材上传 ---
+
+    def upload_media(
+        self,
+        media: bytes | bytearray | str | Path | BinaryIO,
+        filename: str | None = None,
+        media_type: Literal["file", "voice"] = "file",
+    ) -> GroupRobotUploadMediaResponse:
+        """上传文件或语音素材。
+
+        Args:
+            media: 文件路径、字节内容或已打开的二进制文件对象。
+            filename: 可选文件名。
+            media_type: 上传类型，仅支持 file 或 voice。
+        Returns:
+            包含 media_id 的上传响应模型；media_id 用于发送对应素材。
+        注意：原图消息不通过此接口上传；文件对象从当前位置读取且不会被关闭。
+        官方文档：https://developer.work.weixin.qq.com/document/path/91770#文件上传接口
+        """
+        response = self.client.post(
+            url=DEFAULT_UPLOAD_MEDIA_URL,
+            params={"key": self.key, "type": media_type},
+            files={"media": _extract_media(media, filename=filename)},
+        )
+        response.raise_for_status()
+        return GroupRobotUploadMediaResponse.model_validate(response.json())
+
+
+class AsyncAPI(_BaseAPI):
+    """企业微信群机器人异步 API。
+
+    官方文档：https://developer.work.weixin.qq.com/document/path/91770
+    """
+
+    def __init__(
+        self,
+        key: str | None = None,
+        mentioned_list: list[str] | None = None,
+        mentioned_mobile_list: list[str] | None = None,
+        base_url: str | None = None,
+        timeout: float | tuple[float, float, float, float] = 60.0,
+        client: httpx.AsyncClient | None = None,
+        client_kwargs: dict[str, Any] | None = None,
+    ):
+        """初始化异步客户端。
+
+        Args:
+            key: 群机器人的 Webhook key。
+            mentioned_list: 默认 @ 的成员 userid 列表。
+            mentioned_mobile_list: 默认 @ 的成员手机号列表。
+            base_url: API 根地址。
+            timeout: HTTP 请求超时时间。
+            client: 可选的已配置 httpx.AsyncClient。
+            client_kwargs: 未传入 client 时创建客户端的配置。
+
+        官方文档：https://developer.work.weixin.qq.com/document/path/91770
+        """
+        super().__init__(key, mentioned_list, mentioned_mobile_list, base_url, timeout, client_kwargs)
+        self.client = client or httpx.AsyncClient(**self.client_kwargs)
+
+    # --- 资源管理 ---
+
+    async def close(self) -> None:
+        """关闭底层 HTTP 客户端，释放连接池。"""
+        await self.client.aclose()
+
+    async def __aenter__(self) -> "AsyncAPI":
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()
+
+    # --- 发送接口 ---
+
+    async def send(self, payload: dict[str, Any] | None = None) -> GroupRobotSendResponse:
+        """发送消息。
+
+        Args:
+            payload: 符合企业微信机器人消息格式的请求体。
+
+        Returns:
+            经过模型校验的发送响应，包含业务错误码和错误信息。
+
+        Raises:
+            httpx.HTTPStatusError: HTTP 状态码表示请求失败时抛出；业务错误需查看返回模型。
+
+        官方文档：https://developer.work.weixin.qq.com/document/path/91770#消息类型及数据格式
+        """
+        response = await self.client.post(
+            url=DEFAULT_SEND_URL,
+            json=payload or {},
+            params={"key": self.key},
+        )
+        response.raise_for_status()
+        return GroupRobotSendResponse.model_validate(response.json())
+
+    async def send_text(
+        self,
+        content: str = "",
+        mentioned_list: list[str] | None = None,
+        mentioned_mobile_list: list[str] | None = None,
+    ) -> GroupRobotSendResponse:
+        """异步发送文本消息。
+
+        Args:
+            content: 文本内容。
+            mentioned_list: 本次额外 @ 的成员 userid 列表。
+            mentioned_mobile_list: 本次额外 @ 的成员手机号列表。
+
+        Returns:
+            包含业务错误码和错误信息的发送响应模型。
+
+        官方文档：https://developer.work.weixin.qq.com/document/path/91770#文本类型
+        """
+        return await self.send(
+            {
+                "msgtype": "text",
+                "text": {
+                    "content": content,
+                    "mentioned_list": self.mentioned_list + (mentioned_list or []),
+                    "mentioned_mobile_list": self.mentioned_mobile_list + (mentioned_mobile_list or []),
+                },
+            }
+        )
+
+    async def send_markdown(self, content: str = "") -> GroupRobotSendResponse:
+        """异步发送 Markdown 消息。
+
+        Args:
+            content: Markdown 内容，最长 4096 个 UTF-8 字节。
+        Returns:
+            发送响应模型，业务错误通过错误码和错误信息表示。
+        官方文档：https://developer.work.weixin.qq.com/document/path/91770#markdown类型
+        """
+        return await self.send({"msgtype": "markdown", "markdown": {"content": content}})
+
+    async def send_markdown_v2(self, content: str = "") -> GroupRobotSendResponse:
+        """异步发送 Markdown V2 消息。
+
+        Args:
+            content: Markdown V2 内容，最长 4096 个 UTF-8 字节，不支持字体颜色和 @成员。
+        Returns:
+            发送响应模型，业务错误通过错误码和错误信息表示。
+        官方文档：https://developer.work.weixin.qq.com/document/path/91770#markdown-v2类型
+        """
+        return await self.send({"msgtype": "markdown_v2", "markdown_v2": {"content": content}})
+
+    async def send_image(self, base64: str, md5: str) -> GroupRobotSendResponse:
+        """异步发送图片消息。
+
+        Args:
+            base64: 图片二进制内容的 Base64 编码。
+            md5: 原始图片内容的 MD5；图片限 2MB，支持 JPG、PNG。
+        Returns:
+            发送响应模型，业务错误通过错误码和错误信息表示。
+        官方文档：https://developer.work.weixin.qq.com/document/path/91770#图片类型
+        """
+        return await self.send({"msgtype": "image", "image": {"base64": base64, "md5": md5}})
+
+    async def send_news(self, articles: list[dict[str, Any]]) -> GroupRobotSendResponse:
+        """异步发送 1 到 8 条图文，每条需包含 title、url，可选 description、picurl。
+
+        Args:
+            articles: 1 到 8 条图文文章数据。
+        Returns:
+            发送响应模型，业务错误通过错误码和错误信息表示。
+        官方文档：https://developer.work.weixin.qq.com/document/path/91770#图文类型
+        """
+        return await self.send({"msgtype": "news", "news": {"articles": articles}})
+
+    async def send_file(self, media_id: str) -> GroupRobotSendResponse:
+        """异步发送文件，media_id 由文件上传接口获取。
+
+        Args:
+            media_id: 文件上传接口返回的素材 ID。
+        Returns:
+            发送响应模型，业务错误通过错误码和错误信息表示。
+        官方文档：https://developer.work.weixin.qq.com/document/path/91770#文件类型
+        """
+        return await self.send({"msgtype": "file", "file": {"media_id": media_id}})
+
+    async def send_voice(self, media_id: str) -> GroupRobotSendResponse:
+        """异步发送语音，media_id 由语音上传接口获取。
+
+        Args:
+            media_id: 语音上传接口返回的素材 ID。
+        Returns:
+            发送响应模型，业务错误通过错误码和错误信息表示。
+        官方文档：https://developer.work.weixin.qq.com/document/path/91770#语音类型
+        """
+        return await self.send({"msgtype": "voice", "voice": {"media_id": media_id}})
+
+    async def send_template_card(self, template_card: dict[str, Any]) -> GroupRobotSendResponse:
+        """异步发送模板卡片，card_type 支持 text_notice 和 news_notice。
+
+        Args:
+            template_card: 模板卡片请求数据。
+        Returns:
+            发送响应模型，业务错误通过错误码和错误信息表示。
+        官方文档：https://developer.work.weixin.qq.com/document/path/91770#模版卡片类型
+        """
+        return await self.send({"msgtype": "template_card", "template_card": template_card})
+
+    # --- 素材上传 ---
+
+    async def upload_media(
+        self,
+        media: bytes | bytearray | str | Path | BinaryIO,
+        filename: str | None = None,
+        media_type: Literal["file", "voice"] = "file",
+    ) -> GroupRobotUploadMediaResponse:
+        """上传文件或语音素材。
+
+        Args:
+            media: 文件路径、字节内容或已打开的二进制文件对象。
+            filename: 可选文件名。
+            media_type: 上传类型，仅支持 file 或 voice。
+        Returns:
+            包含 media_id 的上传响应模型；media_id 用于发送对应素材。
+        注意：原图消息不通过此接口上传；文件对象从当前位置读取且不会被关闭。
+        官方文档：https://developer.work.weixin.qq.com/document/path/91770#文件上传接口
+        """
+        response = await self.client.post(
+            url=DEFAULT_UPLOAD_MEDIA_URL,
+            params={"key": self.key, "type": media_type},
+            files={"media": _extract_media(media, filename=filename)},
+        )
+        response.raise_for_status()
+        return GroupRobotUploadMediaResponse.model_validate(response.json())

py_wecom_sdk/core/group_robot/_models.py

@@ -0,0 +1,50 @@
+"""群机器人消息发送与素材上传响应模型。
+
+官方文档：https://developer.work.weixin.qq.com/document/path/91770
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+__all__ = ["BaseResponse", "SendResponse", "UploadMediaResponse"]
+
+
+class BaseResponse(BaseModel):
+    """企业微信业务响应，errcode 为 0 表示成功，errmsg 为结果说明。
+
+    官方文档：https://developer.work.weixin.qq.com/document/path/91770
+    """
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+    errcode: int
+    errmsg: str
+
+    @property
+    def ok(self) -> bool:
+        """判断 errcode 是否为 0。"""
+        return self.errcode == 0
+
+
+class SendResponse(BaseResponse):
+    """消息发送响应，通过 ok 判断企业微信业务请求是否成功。
+
+    官方文档：https://developer.work.weixin.qq.com/document/path/91770#消息类型及数据格式
+    """
+
+
+class UploadMediaResponse(BaseResponse):
+    """素材上传响应，包含素材 ID、类型和创建时间。
+
+    media_id 用于后续文件或语音消息发送；素材仅供对应机器人使用，有效期为 3 天。
+    官方文档：https://developer.work.weixin.qq.com/document/path/91770#文件上传接口
+    """
+
+    media_id: str
+    type: str
+    created_at: int
+
+    @property
+    def ok(self) -> bool:
+        """判断业务请求是否成功且 media_id 非空。"""
+        return super().ok and bool(self.media_id)

py_wecom_sdk/core/token/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

py_wecom_sdk/core/token/_client.py

@@ -0,0 +1 @@
+from __future__ import annotations

py_wecom_sdk/core/token/_models.py

@@ -0,0 +1 @@
+from __future__ import annotations

py_wecom_sdk/provider.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .core.group_robot import GroupRobotAPI, GroupRobotAsyncAPI
+
+
+class APIProvider:
+    """企业微信提供器."""
+
+    def __init__(self):
+        pass
+
+    @staticmethod
+    def group_robot_api(*args, **kwargs) -> GroupRobotAPI:
+        return GroupRobotAPI(*args, **kwargs)
+
+    @staticmethod
+    def group_robot_async_api(*args, **kwargs) -> GroupRobotAsyncAPI:
+        return GroupRobotAsyncAPI(*args, **kwargs)

py_wecom_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,323 @@
+Metadata-Version: 2.3
+Name: py-wecom-sdk
+Version: 0.1.0
+Summary: 企业微信（WeCom）开放接口的 Python SDK，基于 httpx + pydantic，同步与异步统一封装。
+Keywords: wecom,wechat-work,企业微信,sdk,httpx,pydantic,群机器人
+Author: guolei
+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.
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: anyio>=4.16.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.14.3
+Requires-Dist: diskcache>=5.6.0 ; extra == 'all'
+Requires-Dist: redis>=5.0.0 ; extra == 'all'
+Requires-Dist: diskcache>=5.6.0 ; extra == 'diskcache'
+Requires-Dist: redis>=5.0.0 ; extra == 'redis'
+Maintainer: guolei
+Maintainer-email: guolei <174000902@qq.com>
+Requires-Python: >=3.10
+Project-URL: Homepage, https://gitee.com/guolei19850528/py_wecom_sdk
+Project-URL: Repository, https://gitee.com/guolei19850528/py_wecom_sdk.git
+Project-URL: Issues, https://gitee.com/guolei19850528/py_wecom_sdk/issues
+Provides-Extra: all
+Provides-Extra: diskcache
+Provides-Extra: redis
+Description-Content-Type: text/markdown
+
+# py_wecom_sdk
+
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green)](https://opensource.org/licenses/MIT)
+[![httpx](https://img.shields.io/badge/httpx-0.28%2B-orange)](https://github.com/encode/httpx)
+[![pydantic](https://img.shields.io/badge/pydantic-2.14%2B-emerald)](https://github.com/pydantic/pydantic)
+
+企业微信（WeCom）开放接口的 Python SDK，基于 **httpx + pydantic v2**，**同步 / 异步统一封装**。
+
+> 官方文档：<https://developer.work.weixin.qq.com/document/path/91770>
+
+---
+
+## ✨ 特性
+
+- **同步 / 异步统一 API** — `GroupRobotAPI` 与 `GroupRobotAsyncAPI` 接口完全一致，只需替换 import
+- **类型安全** — pydantic v2 自动校验所有请求 / 响应，Mypy strict 模式 100% 通过
+- **零魔法基类** — 同步 / 异步共享 `_BaseAPI`，初始化和资源管理逻辑一次实现
+- **丰富的消息类型** — 文本、Markdown、Markdown V2、图片、图文、文件、语音、模板卡片
+- **素材上传支持** — `upload_media()` 统一处理文件 / 语音上传并返回 `media_id`
+- **HTTP 连接池管理** — `close()` / `with` / `async with` 三种方式释放连接
+- **企业级依赖** — httpx（encode 维护）+ pydantic v2（比 v1 快 5-50 倍）
+
+## 📦 安装
+
+### 使用 pip
+
+```bash
+pip install py-wecom-sdk
+```
+
+### 使用 uv（推荐）
+
+```bash
+uv add py-wecom-sdk
+```
+
+### 安装可选依赖
+
+```bash
+# DiskCache 本地缓存后端
+uv add "py-wecom-sdk[diskcache]"
+
+# Redis 分布式缓存后端
+uv add "py-wecom-sdk[redis]"
+
+# 全部可选依赖
+uv add "py-wecom-sdk[all]"
+```
+
+## 🚀 快速开始
+
+### 同步客户端
+
+```python
+from py_wecom_sdk import WeComAPIProvider
+
+api = WeComAPIProvider.group_robot_api(key="YOUR_WEBHOOK_KEY")
+
+# 发送文本
+resp = api.send_text("Hello, WeCom!")
+assert resp.ok
+
+# 发送 Markdown
+api.send_markdown("## 标题\n> <font color='info'>重要通知</font>")
+
+# 发送图文
+api.send_news([{"title": "标题", "url": "https://example.com"}])
+
+# 发送文件（需先上传）
+uploaded = api.upload_media("/path/to/file.pdf", media_type="file")
+api.send_file(uploaded.media_id)
+
+# 释放连接池
+api.close()
+# 或使用上下文管理器：
+# with WeComAPIProvider.group_robot_api(key="YOUR_KEY") as api: ...
+```
+
+### 异步客户端
+
+```python
+import asyncio
+from py_wecom_sdk import WeComAPIProvider
+
+async def main():
+    async with WeComAPIProvider.group_robot_async_api(key="YOUR_WEBHOOK_KEY") as api:
+        resp = await api.send_text("Hello from async!")
+        assert resp.ok
+        await api.send_markdown_v2("**Markdown V2** 也很好用")
+        uploaded = await api.upload_media(b"fake data", filename="demo.txt", media_type="file")
+        await api.send_file(uploaded.media_id)
+
+asyncio.run(main())
+```
+
+### 通过原始 dict 发送任意消息类型
+
+所有便捷方法底层都调用 `send(payload)`，你可以直接传入符合企业微信协议的字典：
+
+```python
+api.send({"msgtype": "text", "text": {"content": "原始 dict", "mentioned_list": ["userid1"]}})
+```
+
+## 📖 功能清单
+
+### `GroupRobotAPI` / `GroupRobotAsyncAPI`
+
+| 方法 | 功能 | 官方文档 |
+|------|------|----------|
+| `send(payload)` | 发送任意类型消息（原始 dict） | — |
+| `send_text(content, mentioned_list, mentioned_mobile_list)` | 文本消息，支持 @ 指定成员 | [文本类型](https://developer.work.weixin.qq.com/document/path/91770#文本类型) |
+| `send_markdown(content)` | Markdown 消息 | [Markdown 类型](https://developer.work.weixin.qq.com/document/path/91770#markdown类型) |
+| `send_markdown_v2(content)` | Markdown V2 消息 | [Markdown V2](https://developer.work.weixin.qq.com/document/path/91770#markdown-v2类型) |
+| `send_image(base64, md5)` | 图片消息（限 2MB，JPG / PNG） | [图片类型](https://developer.work.weixin.qq.com/document/path/91770#图片类型) |
+| `send_news(articles)` | 图文消息（1-8 条） | [图文类型](https://developer.work.weixin.qq.com/document/path/91770#图文类型) |
+| `send_file(media_id)` | 文件消息（需先上传） | [文件类型](https://developer.work.weixin.qq.com/document/path/91770#文件类型) |
+| `send_voice(media_id)` | 语音消息（需先上传） | [语音类型](https://developer.work.weixin.qq.com/document/path/91770#语音类型) |
+| `send_template_card(card)` | 模板卡片（text_notice / news_notice） | [模板卡片](https://developer.work.weixin.qq.com/document/path/91770#模版卡片类型) |
+| `upload_media(media, filename, media_type)` | 上传文件 / 语音素材，返回 `media_id` | [文件上传接口](https://developer.work.weixin.qq.com/document/path/91770#文件上传接口) |
+
+### `send_text` 默认 @ 配置
+
+实例化时可传入默认 @ 列表，每次 `send_text` 会自动合并：
+
+```python
+api = WeComAPIProvider.group_robot_api(
+    key="YOUR_KEY",
+    mentioned_list=["userid1"],       # 每次自动 @ userid1
+    mentioned_mobile_list=["13800138000"],
+)
+api.send_text("重要通知", mentioned_list=["userid2"])  # 合并 @ userid1 + userid2
+```
+
+### `UploadMediaResponse.ok` 多一层校验
+
+上传响应除了业务成功（`errcode == 0`），还额外校验 `media_id` 非空：
+
+```python
+uploaded = api.upload_media("/path/to/file.pdf", media_type="file")
+if not uploaded.ok:
+    print(f"上传失败：errcode={uploaded.errcode}, errmsg={uploaded.errmsg}")
+```
+
+## 🏗️ 项目结构
+
+```
+py_wecom_sdk/
+├── pyproject.toml                  # 项目配置（PEP 621 + Ruff + Mypy + Pytest）
+├── LICENSE                         # MIT License
+├── README.md                       # 中文文档
+├── README.en.md                    # 英文文档
+├── .python-version                 # 锁定 Python 版本（3.10）
+├── .gitignore
+├── .env.example                    # 示例 .env 文件
+│
+├── src/
+│   └── py_wecom_sdk/               # 包根目录（src-layout）
+│       ├── __init__.py             # 导出 WeComAPIProvider
+│       ├── provider.py             # APIProvider 统一入口
+│       └── core/
+│           ├── group_robot/        # 群机器人模块 ✅ 已实现
+│           │   ├── __init__.py     # 公共导出
+│           │   ├── _api.py         # GroupRobotAPI + GroupRobotAsyncAPI + _BaseAPI
+│           │   └── _models.py      # SendResponse / UploadMediaResponse / BaseResponse
+│           └── token/              # access_token 模块 🚧 预留
+│               ├── __init__.py
+│               ├── _client.py
+│               └── _models.py
+│
+├── examples/
+│   └── group_robot.py              # 群机器人完整示例（同步 + 异步 + 多消息类型）
+│
+└── tests/
+    ├── conftest.py
+    └── test_group_robot.py         # 单元测试（respx mock）
+```
+
+## 🛠️ 开发
+
+### 环境准备
+
+```bash
+# 克隆仓库
+git clone https://gitee.com/guolei19850528/py_wecom_sdk.git
+cd py_wecom_sdk
+
+# 安装 uv（包管理器）
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# 创建虚拟环境 + 安装全部依赖（含 dev）
+uv sync --group dev
+```
+
+### 代码质量
+
+```bash
+# Ruff：lint（修复） + format
+uv run ruff check --fix src tests
+uv run ruff format src tests
+
+# Mypy（strict 模式）
+uv run mypy src
+```
+
+### 测试
+
+```bash
+# 运行全部测试（离线，使用 respx mock）
+uv run pytest
+
+# 运行需要真实网络的集成测试
+cp .env.example .env
+# 编辑 .env 填入 WECOM_GROUP_ROBOT_API_KEY
+uv run pytest -m real_network
+```
+
+### 示例运行
+
+```bash
+# 编辑 .env 填入机器人 key
+cp .env.example .env
+vim .env
+
+# 同步发送
+uv run python examples/group_robot.py
+
+# 异步发送 + 图片 / 文件 / 语音
+uv run python examples/group_robot.py --async --image ./test.png --file ./report.pdf
+```
+
+### 构建发布
+
+```bash
+# 构建 wheel + sdist
+uv build
+
+# 发布到 PyPI / Gitee
+uv publish --repository gitee
+```
+
+## 📋 路线图
+
+- [x] 群机器人模块（group_robot）
+  - [x] 同步 / 异步统一 API
+  - [x] 全部 9 种消息类型
+  - [x] 素材上传接口
+  - [x] pydantic 数据模型校验
+- [ ] access_token 模块（token）
+  - [ ] 缓存后端：内存 / DiskCache / Redis
+  - [ ] 自动刷新 + 并发去重
+- [ ] 通讯录模块（contact）
+- [ ] 消息推送模块（message）
+
+## 📄 许可证
+
+本项目基于 **MIT License** 开源，详见 [LICENSE](LICENSE)。
+
+## 📎 相关链接
+
+- [企业微信开发者中心](https://developer.work.weixin.qq.com/)
+- [群机器人接口文档](https://developer.work.weixin.qq.com/document/path/91770)
+- [httpx 官方仓库](https://github.com/encode/httpx)
+- [pydantic v2 文档](https://docs.pydantic.dev/)
+- [uv 官方仓库](https://github.com/astral-sh/uv)

py_wecom_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+py_wecom_sdk/__init__.py,sha256=yS7F1ZeXNvkvpUwFDf17W8seCsIsF_r4ZDRTlb5gpeo,128
+py_wecom_sdk/core/group_robot/__init__.py,sha256=g6-6HRst5jqsX1GeK09eYnai0UCEQlSGZwVuFiJwqUY,600
+py_wecom_sdk/core/group_robot/_api.py,sha256=kMwVVokC12VBKpOaVU-o3qezcdAIEAs8gk0JDpM9Dlo,19796
+py_wecom_sdk/core/group_robot/_models.py,sha256=NO03LpuN6UajbE8KBTQ-f9EOfgQ0nAmXtw4moebSW3o,1484
+py_wecom_sdk/core/token/__init__.py,sha256=U4S_2y3zgLZVfMenHRaJFBW8yqh2mUBuI291LGQVOJ8,35
+py_wecom_sdk/core/token/_client.py,sha256=U4S_2y3zgLZVfMenHRaJFBW8yqh2mUBuI291LGQVOJ8,35
+py_wecom_sdk/core/token/_models.py,sha256=U4S_2y3zgLZVfMenHRaJFBW8yqh2mUBuI291LGQVOJ8,35
+py_wecom_sdk/provider.py,sha256=wwJ9t0MbRtiA4PUrWl16H7bgpBZ4U6w9V89iKxorcq4,480
+py_wecom_sdk-0.1.0.dist-info/WHEEL,sha256=MWx7psoF7KNST9G72pGtiBYuaXRXQXBk9pw5R6FzYko,80
+py_wecom_sdk-0.1.0.dist-info/METADATA,sha256=3Tm95H1-f7n-5QrHPV7m9tZtcfIH7MUc3KJe9-uUUjU,11755
+py_wecom_sdk-0.1.0.dist-info/RECORD,,

py_wecom_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.13.7
+Root-Is-Purelib: true
+Tag: py3-none-any