py-wecom-toolkit

企业微信 Python 扩展包 - 支持 Webhook 与 Server 端 API.

版本: 3.0.0
作者: 郭磊
邮箱: 174000902@qq.com
项目主页: https://gitee.com/guolei19850528/py_wecom_toolkit

安装

pip install py-wecom-toolkit

安装包含 Server 端支持 (diskcache / redis 缓存):

pip install py-wecom-toolkit[server]

功能特性

支持全部 8 种 Webhook 消息类型: text, markdown, markdown_v2, image, news, file, voice, template_card
基于 pydantic v2 的消息模型验证
基于 httpx 的异步 HTTP 客户端
独立的 Webhook Server 模块 (FastAPI)
文件上传接口
完整的类型注解
Server 端 API: access_token 管理 (支持 memory/diskcache/redis 缓存)、接口 IP 段、回调 IP 段、应用消息发送、素材上传/下载
同步与异步客户端双模式支持

快速开始

Webhook 消息发送

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())

Server 端 API (同步)

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 (异步)

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())

高级用法

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("自动管理连接池")

API 参考

WebhookClient

方法	说明
`send(message)`	发送任意类型的消息
`send_text(content, ...)`	发送文本消息
`send_markdown(content)`	发送 Markdown 消息
`send_markdown_v2(content)`	发送 Markdown V2 消息
`send_image(path)`	发送图片消息
`send_news(articles)`	发送图文消息
`send_file(media_id)`	发送文件消息
`send_voice(media_id)`	发送语音消息
`send_template_card(card)`	发送模版卡片消息
`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)`	下载临时素材

示例代码

查看 examples/server/ 目录下的完整示例代码.

消息类型参考

参考企业微信文档获取 Webhook 消息格式说明.

参考企业微信服务端API 获取 Server 端 API 说明.

License

MIT

Metadata

Release files for py-wecom-toolkit 3.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for py-wecom-toolkit 3.0.0
File	Size	Uploaded	Provenance
py_wecom_toolkit-3.0.0.tar.gz	24.2 kB	Oct 16, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for py-wecom-toolkit 3.0.0
File	Interpreter	ABI	Platform	Reset
py_wecom_toolkit-3.0.0-py3-none-any.whl 24.8 kB Oct 16, 2026 Without provenance	Python 3	none	any	Details

Total release size: 49.0 kB

Release files / py_wecom_toolkit-3.0.0.tar.gz

Download URL	py_wecom_toolkit-3.0.0.tar.gz
Size	24.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`f5c0c71c7b04d35c71b805b1d5deec9220d4573051f9c46e764aa6d9fb5568d1`
BLAKE2b-256 checksum How to use checksums	`2216539ab798065052f06c9ec2833f512348abfb751da9b44d5fa8a220429f33`
Upload date	Oct 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.6`

Release files / py_wecom_toolkit-3.0.0-py3-none-any.whl

Download URL	py_wecom_toolkit-3.0.0-py3-none-any.whl
Size	24.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`f09a2bd3661e131c9da5d3205eaba16f1b70d19eb5b9b20cb6dc890d4af6c0e6`
BLAKE2b-256 checksum How to use checksums	`37d3c384a405337d0a725eb7e0d66ef3beef222edae68e0990f3b9036f899a92`
Upload date	Oct 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.6`

Security for py-wecom-toolkit 3.0.0

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.