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

py_wecom_toolkit-3.0.2/PKG-INFO

@@ -0,0 +1,492 @@
+Metadata-Version: 2.1
+Name: py-wecom-toolkit
+Version: 3.0.2
+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
+Author-email: 郭磊 <174000902@qq.com>
+License: MIT License
+        
+        Copyright (c) 2024 py-wecom-toolkit
+        
+        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.
+License-File: LICENSE
+Keywords: enterprise,webhook,wechat,wecom,work
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: twine>=4.0.0; extra == 'dev'
+Provides-Extra: server
+Requires-Dist: diskcache>=5.6.0; extra == 'server'
+Requires-Dist: redis>=5.0.0; extra == 'server'
+Description-Content-Type: text/markdown
+
+# py-wecom-toolkit
+
+企业微信 Python 扩展包 - 支持 Webhook 与 Server 端 API.
+
+- **版本**: 3.0.2
+- **作者**: 郭磊
+- **邮箱**: 174000902@qq.com
+- **项目主页**: https://gitee.com/guolei19850528/py_wecom_toolkit
+- **PyPI**: https://pypi.org/project/py-wecom-toolkit/
+
+## 项目结构
+
+```
+py-wecom-toolkit/
+├── pyproject.toml              # 项目构建配置
+├── README.md                   # 项目说明文档
+├── LICENSE                     # MIT 许可证
+├── src/
+│   └── py_wecom_toolkit/       # 源代码包
+│       ├── __init__.py         # 包入口，导出所有公共类
+│       ├── webhook/            # Webhook 消息发送模块（原“群机器人”）
+│       │   ├── __init__.py
+│       │   ├── client.py       # WebhookClient / AsyncWebhookClient
+│       │   ├── 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
+│           ├── models.py       # Server API 响应模型
+│           ├── exceptions.py   # Server 异常定义
+│           ├── message.py      # 应用消息发送（MessageSendMixin）
+│           └── media.py        # 素材上传/下载（MediaMixin）
+├── tests/                      # 测试用例
+│   ├── __init__.py
+│   ├── webhook/                # Webhook 测试
+│   │   ├── __init__.py
+│   │   ├── test_client.py      # 同步客户端测试
+│   │   ├── test_async_client.py # 异步客户端测试
+│   │   ├── test_models.py      # 消息模型测试
+│   │   └── test_integration.py # 真实集成测试
+│   └── server/                 # Server 端测试
+│       ├── __init__.py
+│       ├── test_client.py      # 同步客户端测试
+│       ├── test_async_client.py # 异步客户端测试
+│       ├── test_token.py       # AccessToken 管理器测试
+│       ├── test_cache.py       # 缓存测试
+│       ├── test_integration_real.py # 真实集成测试
+│       └── test_upload_readme_to_guolei.py # 上传README并发送测试
+└── examples/                   # 演示代码
+    ├── webhook/                # Webhook 示例
+    │   ├── README.md
+    │   ├── .env.example        # 环境变量模板
+    │   ├── config.py           # 配置读取
+    │   ├── basic.py            # 基础用法（上下文管理器、手动连接、自定义配置、原始dict）
+    │   ├── text.py             # 文本消息示例
+    │   ├── markdown.py         # Markdown 消息示例
+    │   ├── markdown_v2.py      # Markdown V2 消息示例
+    │   ├── image.py            # 图片消息示例
+    │   ├── news.py             # 图文消息示例
+    │   ├── file.py             # 文件消息示例
+    │   ├── voice.py            # 语音消息示例
+    │   ├── template_card.py    # 模版卡片消息示例
+    │   ├── async_basic.py      # 异步基础示例
+    │   ├── async_text.py       # 异步文本消息示例
+    │   └── async_file.py       # 异步文件消息示例
+    └── server/                 # Server 端示例
+        ├── README.md
+        ├── .env.example        # 环境变量模板
+        ├── config.py           # 配置读取
+        ├── basic_sync.py       # 同步基础示例
+        ├── basic_async.py      # 异步基础示例
+        ├── send_message.py     # 发送应用消息示例
+        └── upload_file.py      # 上传文件并发送示例
+```
+
+## 安装
+
+```bash
+pip install py-wecom-toolkit
+```
+
+安装包含 Server 端支持 (diskcache / redis 缓存):
+
+```bash
+pip install py-wecom-toolkit[server]
+```
+
+开发环境（包含测试、代码检查、打包、上传工具）:
+
+```bash
+pip install py-wecom-toolkit[dev]
+```
+
+## 功能特性
+
+### Webhook 模块
+- 支持全部 8 种 Webhook 消息类型: text, markdown, markdown_v2, image, news, file, voice, template_card
+- 基于 pydantic v2 的消息模型验证
+- 基于 httpx 的异步 HTTP 客户端
+- 同步与异步客户端双模式支持 (`WebhookClient` / `AsyncWebhookClient`)
+- 消息发送支持 @ 成员列表合并与去重
+- 文件上传接口 (base64 编码 + md5 校验)
+
+### Server 端模块
+- **access_token 管理**: 自动获取与缓存 (支持 memory/diskcache/redis 三种后端)
+- **接口 IP 段**: 获取企业微信服务器 IP 段
+- **回调 IP 段**: 获取企业微信回调服务器 IP 段
+- **应用消息发送**: 文本、Markdown、图片、文件、语音、图文、模版卡片等
+- **素材管理**: 上传临时素材、下载临时素材
+- 同步与异步客户端双模式支持 (`WeComServerClient` / `AsyncWeComServerClient`)
+- agentid 支持：可在客户端初始化时指定，发送消息时未传则自动使用客户端 agentid
+
+## 快速开始
+
+### 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
+
+# 创建同步客户端，支持上下文管理器自动管理连接池
+with WebhookClient(key="你的webhook_key") as client:
+
+    # 发送文本消息
+    resp = client.send_text("Hello, World!")
+    print(f"发送结果: {resp.errmsg}")
+
+    # 发送文本消息并 @某人
+    resp = client.send_text(
+        "你好, 请查看",
+        mentioned_list=["zhangsan"],
+        mentioned_mobile_list=["13800001111"],
+    )
+    print(f"发送结果: {resp.errmsg}")
+
+    # 发送 Markdown 消息
+    resp = client.send_markdown(
+        '实时新增用户反馈<font color="warning">132例</font>'
+    )
+    print(f"发送结果: {resp.errmsg}")
+
+    # 发送图文消息
+    resp = client.send_news([{
+        "title": "中秋节礼品领取",
+        "description": "今年中秋节公司有豪礼相送",
+        "url": "https://work.weixin.qq.com",
+        "picurl": "https://example.com/pic.png",
+    }])
+    print(f"发送结果: {resp.errmsg}")
+
+    # 发送图片
+    resp = client.send_image("/path/to/image.png")
+    print(f"发送结果: {resp.errmsg}")
+
+    # 上传文件并发送
+    media_id = client.upload_media("/path/to/file.pdf")
+    resp = client.send_file(media_id)
+    print(f"发送结果: {resp.errmsg}")
+```
+
+### Server 端 API (同步)
+
+```python
+from py_wecom_toolkit import WeComServerClient
+
+# 关键配置请通过环境变量或配置文件读取，不要硬编码在代码中
+client = WeComServerClient(
+    corpid="你的CorpID",
+    corpsecret="你的CorpSecret",
+    agentid="你的AgentID",
+)
+
+# 获取 access_token (自动缓存)
+token = client.get_access_token()
+print(f"access_token: {token}")
+
+# 获取企业微信接口 IP 段
+iplist = client.get_iplist()
+print(f"接口 IP 段: {iplist.ip_list}")
+
+# 获取企业微信回调 IP 段
+callback_ip = client.get_callback_ip()
+print(f"回调 IP 段: {callback_ip.ip_list}")
+
+# 发送文本应用消息
+resp = client.send_text(
+    content="Hello, WeCom!",
+    touser="Guolei",
+)
+print(f"发送结果: {resp.errmsg}")
+
+# 上传素材并发送文件消息
+media = client.upload_media("/path/to/README.md", media_type="file")
+resp = client.send_file(media.media_id, touser="Guolei")
+print(f"发送文件结果: {resp.errmsg}")
+
+client.close()
+```
+
+### Server 端 API (异步)
+
+```python
+import asyncio
+from py_wecom_toolkit import AsyncWeComServerClient
+
+async def main():
+    client = AsyncWeComServerClient(
+        corpid="你的CorpID",
+        corpsecret="你的CorpSecret",
+        agentid="你的AgentID",
+    )
+
+    # 获取 access_token (自动缓存)
+    token = await client.async_get_access_token()
+    print(f"access_token: {token}")
+
+    # 获取接口 IP 段
+    iplist = await client.async_get_iplist()
+    print(f"接口 IP 段: {iplist.ip_list}")
+
+    # 发送文本应用消息
+    resp = await client.async_send_text(
+        content="Hello, WeCom Async!",
+        touser="Guolei",
+    )
+    print(f"发送结果: {resp.errmsg}")
+
+    # 上传素材并发送文件消息
+    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}")
+
+    await client.close()
+
+asyncio.run(main())
+```
+
+### 高级用法
+
+```python
+import httpx
+from py_wecom_toolkit import WebhookClient
+
+# 使用自定义 httpx 客户端
+async with httpx.AsyncClient(timeout=30.0) as http_client:
+    client = WebhookClient(key="xxx", client=http_client)
+    await client.send_text("使用自定义客户端")
+
+# 使用上下文管理器
+async with WebhookClient(key="xxx") as client:
+    await 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"),
+)
+
+# 使用 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),
+)
+```
+
+## API 参考
+
+### WebhookClient / AsyncWebhookClient
+
+| 方法 | 说明 |
+|------|------|
+| `send(message)` / `async_send(message)` | 发送任意类型的消息 |
+| `send_text(content, ...)` / `async_send_text(...)` | 发送文本消息 |
+| `send_markdown(content)` / `async_send_markdown(content)` | 发送 Markdown 消息 |
+| `send_markdown_v2(content)` / `async_send_markdown_v2(content)` | 发送 Markdown V2 消息 |
+| `send_image(path)` / `async_send_image(path)` | 发送图片消息 |
+| `send_news(articles)` / `async_send_news(articles)` | 发送图文消息 |
+| `send_file(media_id)` / `async_send_file(media_id)` | 发送文件消息 |
+| `send_voice(media_id)` / `async_send_voice(media_id)` | 发送语音消息 |
+| `send_template_card(card)` / `async_send_template_card(card)` | 发送模版卡片消息 |
+| `upload_media(path, type)` / `async_upload_media(path, type)` | 上传媒体文件 |
+
+### WeComServerClient / AsyncWeComServerClient
+
+| 方法 | 说明 |
+|------|------|
+| `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(...)` | 发送文本应用消息 |
+| `send_message(request)` / `async_send_message(request)` | 发送任意类型应用消息 |
+| `send_file(media_id, touser, ...)` / `async_send_file(...)` | 发送文件应用消息 |
+| `upload_media(path, type)` / `async_upload_media(path, type)` | 上传临时素材 |
+| `download_media(media_id)` / `async_download_media(media_id)` | 下载临时素材 |
+
+## 测试用例
+
+项目包含完整的单元测试和集成测试：
+
+```bash
+# 运行所有测试
+pytest tests/
+
+# 仅运行 Webhook 测试
+pytest tests/webhook/
+
+# 仅运行 Server 端测试
+pytest tests/server/
+
+# 运行真实集成测试（需要配置有效的 Webhook Key / CorpID/CorpSecret/AgentID）
+pytest tests/webhook/test_integration.py
+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 消息模型测试
+- `tests/webhook/test_integration.py` - Webhook 真实集成测试
+- `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_integration_real.py` - Server 端真实集成测试
+- `tests/server/test_upload_readme_to_guolei.py` - 上传 README 并发送测试
+
+## 演示代码
+
+### Webhook 示例 (`examples/webhook/`)
+
+| 文件 | 说明 |
+|------|------|
+| `basic.py` | 基础用法（上下文管理器、手动连接、自定义配置、原始dict） |
+| `text.py` | 文本消息示例 |
+| `markdown.py` | Markdown 消息示例 |
+| `markdown_v2.py` | Markdown V2 消息示例 |
+| `image.py` | 图片消息示例 |
+| `news.py` | 图文消息示例 |
+| `file.py` | 文件消息示例 |
+| `voice.py` | 语音消息示例 |
+| `template_card.py` | 模版卡片消息示例 |
+| `async_basic.py` | 异步基础示例 |
+| `async_text.py` | 异步文本消息示例 |
+| `async_file.py` | 异步文件消息示例 |
+| `config.py` | 配置读取 |
+| `.env.example` | 环境变量模板 |
+
+### Server 端示例 (`examples/server/`)
+
+| 文件 | 说明 |
+|------|------|
+| `basic_sync.py` | 同步基础示例（access_token / IP 段） |
+| `basic_async.py` | 异步基础示例（access_token / IP 段） |
+| `send_message.py` | 发送文本/Markdown 应用消息示例 |
+| `upload_file.py` | 上传文件并发送文件应用消息示例 |
+| `config.py` | 配置读取 |
+| `.env.example` | 环境变量模板 |
+
+使用前请先配置环境变量或 `.env` 文件：
+
+```bash
+cp examples/webhook/.env.example examples/webhook/.env
+# 或
+cp examples/server/.env.example examples/server/.env
+```
+
+## 构建与发布
+
+```bash
+# 安装开发依赖
+pip install py-wecom-toolkit[dev]
+
+# 构建分发包
+python -m build
+
+# 上传到 PyPI
+python -m twine upload dist/*
+```
+
+## 消息类型参考
+
+参考 [企业微信文档](https://developer.work.weixin.qq.com/document/path/91770) 获取 Webhook 消息格式说明.
+
+参考 [企业微信服务端API](https://developer.work.weixin.qq.com/document/path/90664) 获取 Server 端 API 说明.
+
+## License
+
+MIT