py-wecom-toolkit 3.0.2__tar.gz → 3.0.4__tar.gz

{py_wecom_toolkit-3.0.2 → py_wecom_toolkit-3.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: py-wecom-toolkit
-Version: 3.0.2
+Version: 3.0.4
 Summary: 企业微信 Python 扩展包 - 支持 Webhook 与 Server 端 API
 Project-URL: Homepage, https://gitee.com/guolei19850528/py_wecom_toolkit
 Project-URL: Documentation, https://gitee.com/guolei19850528/py_wecom_toolkit#readme
@@ -52,9 +52,8 @@ Description-Content-Type: text/markdown
 
 # py-wecom-toolkit
 
-企业微信 Python 扩展包 - 支持 Webhook 与 Server 端 API.
+企业微信 Python 扩展包 - 支持 Webhook 与 Server 端 API。
 
-- **版本**: 3.0.2
 - **作者**: 郭磊
 - **邮箱**: 174000902@qq.com
 - **项目主页**: https://gitee.com/guolei19850528/py_wecom_toolkit
@@ -72,19 +71,19 @@ py-wecom-toolkit/
 │       ├── __init__.py         # 包入口，导出所有公共类
 │       ├── webhook/            # Webhook 消息发送模块（原“群机器人”）
 │       │   ├── __init__.py
-│       │   ├── client.py       # WebhookClient / AsyncWebhookClient
+│       │   ├── client.py       # WeComWebhookClient / AsyncWeComWebhookClient
 │       │   ├── exceptions.py   # Webhook 异常定义
 │       │   ├── models.py       # pydantic v2 消息模型（8种消息类型）
 │       │   └── types.py        # 类型别名
 │       └── server/             # Server 端 API 模块（企业微信服务端接口）
 │           ├── __init__.py
 │           ├── client.py       # WeComServerClient / AsyncWeComServerClient
-│           ├── token.py        # AccessToken 管理（支持缓存）
-│           ├── cache.py        # MemoryCache / DiskCache / RedisCache
+│           ├── token.py        # WeComServerAccessTokenManager
+│           ├── cache.py        # WeComServerMemoryCache / WeComServerDiskCache / WeComServerRedisCache
 │           ├── models.py       # Server API 响应模型
 │           ├── exceptions.py   # Server 异常定义
-│           ├── message.py      # 应用消息发送（MessageSendMixin）
-│           └── media.py        # 素材上传/下载（MediaMixin）
+│           ├── message.py      # 应用消息发送（WeComServerMessageSendMixin）
+│           └── media.py        # 素材上传/下载（WeComServerMediaMixin）
 ├── tests/                      # 测试用例
 │   ├── __init__.py
 │   ├── webhook/                # Webhook 测试
@@ -100,13 +99,13 @@ py-wecom-toolkit/
 │       ├── test_token.py       # AccessToken 管理器测试
 │       ├── test_cache.py       # 缓存测试
 │       ├── test_integration_real.py # 真实集成测试
-│       └── test_upload_readme_to_guolei.py # 上传README并发送测试
+│       └── test_upload_readme_to_guolei.py # 上传 README 并发送测试
 └── examples/                   # 演示代码
     ├── webhook/                # Webhook 示例
     │   ├── README.md
     │   ├── .env.example        # 环境变量模板
     │   ├── config.py           # 配置读取
-    │   ├── basic.py            # 基础用法（上下文管理器、手动连接、自定义配置、原始dict）
+    │   ├── basic.py            # 基础用法（上下文管理器、手动连接、自定义配置、原始 dict）
     │   ├── text.py             # 文本消息示例
     │   ├── markdown.py         # Markdown 消息示例
     │   ├── markdown_v2.py      # Markdown V2 消息示例
@@ -130,17 +129,19 @@ py-wecom-toolkit/
 
 ## 安装
 
+### 基础安装
+
 ```bash
 pip install py-wecom-toolkit
 ```
 
-安装包含 Server 端支持 (diskcache / redis 缓存):
+### 包含 Server 端支持（diskcache / redis 缓存）
 
 ```bash
 pip install py-wecom-toolkit[server]
 ```
 
-开发环境（包含测试、代码检查、打包、上传工具）:
+### 开发环境（包含测试、代码检查、打包、上传工具）
 
 ```bash
 pip install py-wecom-toolkit[dev]
@@ -148,76 +149,34 @@ pip install py-wecom-toolkit[dev]
 
 ## 功能特性
 
-### Webhook 模块
+### Webhook 消息发送模块
+
 - 支持全部 8 种 Webhook 消息类型: text, markdown, markdown_v2, image, news, file, voice, template_card
 - 基于 pydantic v2 的消息模型验证
 - 基于 httpx 的异步 HTTP 客户端
-- 同步与异步客户端双模式支持 (`WebhookClient` / `AsyncWebhookClient`)
+- 同步与异步客户端双模式支持 (`WeComWebhookClient` / `AsyncWeComWebhookClient`)
 - 消息发送支持 @ 成员列表合并与去重
 - 文件上传接口 (base64 编码 + md5 校验)
 
-### Server 端模块
-- **access_token 管理**: 自动获取与缓存 (支持 memory/diskcache/redis 三种后端)
+### Server 端 API 模块
+
+- **access_token 管理**: 自动获取与缓存（支持 memory/diskcache/redis 三种后端）
 - **接口 IP 段**: 获取企业微信服务器 IP 段
 - **回调 IP 段**: 获取企业微信回调服务器 IP 段
-- **应用消息发送**: 文本、Markdown、图片、文件、语音、图文、模版卡片等
+- **应用消息发送**: 文本、markdown、图片、文件、语音、图文、模版卡片等
 - **素材管理**: 上传临时素材、下载临时素材
 - 同步与异步客户端双模式支持 (`WeComServerClient` / `AsyncWeComServerClient`)
 - agentid 支持：可在客户端初始化时指定，发送消息时未传则自动使用客户端 agentid
 
 ## 快速开始
 
-### Webhook 消息发送
+### Webhook 消息发送（同步）
 
 ```python
-import asyncio
-from py_wecom_toolkit import WebhookClient
-
-async def main():
-    client = WebhookClient(key="你的webhook_key")
-
-    # 发送文本消息
-    await client.send_text("Hello, World!")
-
-    # 发送文本消息并 @某人
-    await client.send_text(
-        "你好, 请查看",
-        mentioned_list=["zhangsan"],
-        mentioned_mobile_list=["13800001111"],
-    )
-
-    # 发送 Markdown 消息
-    await client.send_markdown(
-        '实时新增用户反馈<font color="warning">132例</font>'
-    )
-
-    # 发送图文消息
-    await client.send_news([{
-        "title": "中秋节礼品领取",
-        "description": "今年中秋节公司有豪礼相送",
-        "url": "https://work.weixin.qq.com",
-        "picurl": "https://example.com/pic.png",
-    }])
-
-    # 发送图片
-    await client.send_image("/path/to/image.png")
-
-    # 上传文件并发送
-    media_id = await client.upload_media("/path/to/file.pdf")
-    await client.send_file(media_id)
-
-    await client.close()
-
-asyncio.run(main())
-```
-
-### Webhook 消息发送 (同步)
-
-```python
-from py_wecom_toolkit import WebhookClient
+from py_wecom_toolkit import WeComWebhookClient
 
 # 创建同步客户端，支持上下文管理器自动管理连接池
-with WebhookClient(key="你的webhook_key") as client:
+with WeComWebhookClient(key="你的webhook_key") as client:
 
     # 发送文本消息
     resp = client.send_text("Hello, World!")
@@ -256,7 +215,34 @@ with WebhookClient(key="你的webhook_key") as client:
     print(f"发送结果: {resp.errmsg}")
 ```
 
-### Server 端 API (同步)
+### Webhook 消息发送（异步）
+
+```python
+import asyncio
+from py_wecom_toolkit import AsyncWeComWebhookClient
+
+async def main():
+    async with AsyncWeComWebhookClient(key="你的webhook_key") as client:
+
+        # 发送文本消息
+        resp = await client.send_text("Hello, World!")
+        print(f"发送结果: {resp.errmsg}")
+
+        # 发送 Markdown 消息
+        resp = await client.send_markdown(
+            '实时新增用户反馈<font color="warning">132例</font>'
+        )
+        print(f"发送结果: {resp.errmsg}")
+
+        # 上传文件并发送
+        media_id = await client.upload_media("/path/to/file.pdf")
+        resp = await client.send_file(media_id)
+        print(f"发送结果: {resp.errmsg}")
+
+asyncio.run(main())
+```
+
+### Server 端 API（同步）
 
 ```python
 from py_wecom_toolkit import WeComServerClient
@@ -268,7 +254,7 @@ client = WeComServerClient(
     agentid="你的AgentID",
 )
 
-# 获取 access_token (自动缓存)
+# 获取 access_token（自动缓存）
 token = client.get_access_token()
 print(f"access_token: {token}")
 
@@ -295,40 +281,38 @@ print(f"发送文件结果: {resp.errmsg}")
 client.close()
 ```
 
-### Server 端 API (异步)
+### Server 端 API（异步）
 
 ```python
 import asyncio
 from py_wecom_toolkit import AsyncWeComServerClient
 
 async def main():
-    client = AsyncWeComServerClient(
+    async with AsyncWeComServerClient(
         corpid="你的CorpID",
         corpsecret="你的CorpSecret",
         agentid="你的AgentID",
-    )
-
-    # 获取 access_token (自动缓存)
-    token = await client.async_get_access_token()
-    print(f"access_token: {token}")
+    ) as client:
 
-    # 获取接口 IP 段
-    iplist = await client.async_get_iplist()
-    print(f"接口 IP 段: {iplist.ip_list}")
+        # 获取 access_token（自动缓存）
+        token = await client.async_get_access_token()
+        print(f"access_token: {token}")
 
-    # 发送文本应用消息
-    resp = await client.async_send_text(
-        content="Hello, WeCom Async!",
-        touser="Guolei",
-    )
-    print(f"发送结果: {resp.errmsg}")
+        # 获取接口 IP 段
+        iplist = await client.async_get_iplist()
+        print(f"接口 IP 段: {iplist.ip_list}")
 
-    # 上传素材并发送文件消息
-    media = await client.async_upload_media("/path/to/README.md", media_type="file")
-    resp = await client.async_send_file(media.media_id, touser="Guolei")
-    print(f"发送文件结果: {resp.errmsg}")
+        # 发送文本应用消息
+        resp = await client.async_send_text(
+            content="Hello, WeCom Async!",
+            touser="Guolei",
+        )
+        print(f"发送结果: {resp.errmsg}")
 
-    await client.close()
+        # 上传素材并发送文件消息
+        media = await client.async_upload_media("/path/to/README.md", media_type="file")
+        resp = await client.async_send_file(media.media_id, touser="Guolei")
+        print(f"发送文件结果: {resp.errmsg}")
 
 asyncio.run(main())
 ```
@@ -337,39 +321,38 @@ asyncio.run(main())
 
 ```python
 import httpx
-from py_wecom_toolkit import WebhookClient
+from py_wecom_toolkit import WeComWebhookClient, AsyncWeComWebhookClient
+from py_wecom_toolkit.server.cache import WeComServerDiskCache, WeComServerRedisCache
 
-# 使用自定义 httpx 客户端
+# 使用自定义 httpx 客户端（Webhook 异步客户端）
 async with httpx.AsyncClient(timeout=30.0) as http_client:
-    client = WebhookClient(key="xxx", client=http_client)
+    client = AsyncWeComWebhookClient(key="xxx", client=http_client)
     await client.send_text("使用自定义客户端")
 
-# 使用上下文管理器
-async with WebhookClient(key="xxx") as client:
-    await client.send_text("自动管理连接池")
+# 使用上下文管理器（Webhook 同步客户端）
+with WeComWebhookClient(key="xxx") as client:
+    client.send_text("自动管理连接池")
 
 # 使用 diskcache 缓存 access_token
-from py_wecom_toolkit.server.cache import DiskCache
 client = WeComServerClient(
     corpid="xxx",
     corpsecret="yyy",
     agentid="zzz",
-    cache=DiskCache(directory=".wecom_cache"),
+    cache=WeComServerDiskCache(directory=".wecom_cache"),
 )
 
 # 使用 redis 缓存 access_token
-from py_wecom_toolkit.server.cache import RedisCache
 client = WeComServerClient(
     corpid="xxx",
     corpsecret="yyy",
     agentid="zzz",
-    cache=RedisCache(host="localhost", port=6379),
+    cache=WeComServerRedisCache(host="localhost", port=6379),
 )
 ```
 
 ## API 参考
 
-### WebhookClient / AsyncWebhookClient
+### WeComWebhookClient / AsyncWeComWebhookClient
 
 | 方法 | 说明 |
 |------|------|
@@ -388,7 +371,7 @@ client = WeComServerClient(
 
 | 方法 | 说明 |
 |------|------|
-| `get_access_token()` / `async_get_access_token()` | 获取 access_token (自动缓存) |
+| `get_access_token()` / `async_get_access_token()` | 获取 access_token（自动缓存） |
 | `get_iplist()` / `async_get_iplist()` | 获取企业微信接口 IP 段 |
 | `get_callback_ip()` / `async_get_callback_ip()` | 获取企业微信回调 IP 段 |
 | `send_text(content, touser, ...)` / `async_send_text(...)` | 发送文本应用消息 |
@@ -417,6 +400,7 @@ pytest tests/server/test_integration_real.py
 ```
 
 测试覆盖：
+
 - `tests/webhook/test_client.py` - 同步 Webhook 客户端测试
 - `tests/webhook/test_async_client.py` - 异步 Webhook 客户端测试
 - `tests/webhook/test_models.py` - Webhook 消息模型测试
@@ -424,7 +408,7 @@ pytest tests/server/test_integration_real.py
 - `tests/server/test_client.py` - 同步 Server 客户端测试
 - `tests/server/test_async_client.py` - 异步 Server 客户端测试
 - `tests/server/test_token.py` - AccessToken 管理器测试
-- `tests/server/test_cache.py` - 缓存测试 (memory/diskcache/redis)
+- `tests/server/test_cache.py` - 缓存测试（memory/diskcache/redis）
 - `tests/server/test_integration_real.py` - Server 端真实集成测试
 - `tests/server/test_upload_readme_to_guolei.py` - 上传 README 并发送测试
 
@@ -434,7 +418,7 @@ pytest tests/server/test_integration_real.py
 
 | 文件 | 说明 |
 |------|------|
-| `basic.py` | 基础用法（上下文管理器、手动连接、自定义配置、原始dict） |
+| `basic.py` | 基础用法（上下文管理器、手动连接、自定义配置、原始 dict） |
 | `text.py` | 文本消息示例 |
 | `markdown.py` | Markdown 消息示例 |
 | `markdown_v2.py` | Markdown V2 消息示例 |
@@ -483,10 +467,10 @@ python -m twine upload dist/*
 
 ## 消息类型参考
 
-参考 [企业微信文档](https://developer.work.weixin.qq.com/document/path/91770) 获取 Webhook 消息格式说明.
+参考 [企业微信文档](https://developer.work.weixin.qq.com/document/path/91770) 获取 Webhook 消息格式说明。
 
-参考 [企业微信服务端API](https://developer.work.weixin.qq.com/document/path/90664) 获取 Server 端 API 说明.
+参考 [企业微信服务端 API](https://developer.work.weixin.qq.com/document/path/90664) 获取 Server 端 API 说明。
 
 ## License
 
-MIT
+MIT