Metadata-Version: 2.4
Name: py-wecom-toolkit
Version: 3.0.13
Summary: 企业微信 Python 扩展包 - 支持 Webhook 与 Server 端 API
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.
        
Project-URL: Homepage, https://gitee.com/guolei19850528/py_wecom_toolkit
Project-URL: Documentation, https://gitee.com/guolei19850528/py_wecom_toolkit#readme
Keywords: wecom,wechat,work,webhook,enterprise
Classifier: Development Status :: 4 - Beta
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.8
Classifier: Programming Language :: Python :: 3.9
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: cache
Requires-Dist: diskcache>=5.0.0; extra == "cache"
Requires-Dist: redis>=5.0.0; extra == "cache"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: python-dotenv>=1.0.0; extra == "dev"
Dynamic: license-file

# py-wecom-toolkit

#### 介绍
企业微信 Python 扩展包，支持 Webhook（群机器人）与 Server 端 API。提供同步/异步双模客户端、基于 Pydantic v2 的消息模型，以及自动缓存的 access_token 管理。

py-wecom-toolkit 让你极其简单地与企业微信 API 交互。无需手动拼接 URL，无需手动构建 JSON 负载，自动缓存 access_token，支持同步和异步客户端。

#### 软件架构
```
py-wecom-toolkit/
├── pyproject.toml              # 项目构建配置
├── README.md                   # 项目说明文档
├── README.en.md                # 项目说明文档（英文）
├── LICENSE                     # MIT 许可证
├── uv.lock                     # 锁定依赖版本
├── src/
│   └── py_wecom_toolkit/       # 源代码包
│       ├── __init__.py         # 包入口
│       ├── py.typed            # PEP 561 类型标记
│       ├── webhook/            # Webhook 消息发送模块（群机器人）
│       │   ├── __init__.py
│       │   ├── client.py       # WeComWebhookClient / AsyncWeComWebhookClient / WeComWebhookClientConfig
│       │   ├── models.py       # pydantic v2 消息模型与异常定义
│       │   └── types.py        # 类型别名
│       └── server/             # Server 端 API 模块（企业微信服务端接口）
│           ├── __init__.py
│           ├── client.py       # WeComServerClient / AsyncWeComServerClient / WeComServerClientConfig
│           ├── token.py        # WeComServerAccessTokenManager / AsyncWeComServerAccessTokenManager
│           ├── cache.py        # WeComServerMemoryCache / WeComServerDiskCache / WeComServerRedisCache
│           ├── models.py       # Server API 响应模型与异常定义
│           ├── message.py      # 应用消息发送（WeComServerMessageSendMixin / AsyncWeComServerMessageSendMixin）
│           └── media.py        # 素材上传/下载（WeComServerMediaMixin / AsyncWeComServerMediaMixin）
├── tests/                      # 测试用例
│   ├── webhook/                # Webhook 测试（按消息类型组织）
│   └── server/                 # Server 端测试（按功能模块组织）
└── examples/                   # 演示代码
    ├── webhook/                # Webhook 示例
    └── server/                 # Server 端示例
```

#### 安装教程

1.  基础安装（推荐 uv）：`uv pip install py-wecom-toolkit`
2.  带缓存依赖安装（diskcache / redis）：`uv pip install py-wecom-toolkit[cache]`
3.  开发环境安装（包含测试、代码检查工具）：`uv pip install py-wecom-toolkit[dev]`

#### 使用说明

1.  Webhook 消息发送（同步）：
```python
from py_wecom_toolkit.webhook.client import WeComWebhookClient

with WeComWebhookClient(key="你的webhook_key") as client:
    resp = client.send_text("Hello, World!")
    print(f"发送结果: {resp.errmsg}")
```

2.  Webhook 消息发送（异步）：
```python
import asyncio
from py_wecom_toolkit.webhook.client import AsyncWeComWebhookClient

async def main():
    async with AsyncWeComWebhookClient(key="你的webhook_key") as client:
        resp = await client.send_text("Hello, World!")
        print(f"发送结果: {resp.errmsg}")

asyncio.run(main())
```

3.  Server 端 API（同步）：
```python
from py_wecom_toolkit.server.client import WeComServerClient
from py_wecom_toolkit.server.cache import WeComServerDiskCache

client = WeComServerClient(
    corpid="你的CorpID",
    corpsecret="你的CorpSecret",
    agentid="你的AgentID",
    cache=WeComServerDiskCache(directory=".runtime.cache.diskcache"),
)

token = client.get_access_token()
print(f"access_token: {token}")

resp = client.send_text(content="Hello, WeCom!", touser="Guolei")
print(f"发送结果: {resp.errmsg}")

client.close()
```

#### 参与贡献

1.  Fork 本仓库
2.  新建 Feat_xxx 分支
3.  提交代码
4.  新建 Pull Request


#### 特技

1.  同步与异步双模客户端，方法名完全一致
2.  基于 Pydantic v2 的消息模型，字段自动校验
3.  自动缓存 access_token，支持内存、diskcache、Redis 三种后端
