snowland-qyweixin-python

Description

Unofficial open-source SDK for WeCom (Enterprise WeChat), built on top of snowland-http.

This SDK provides a unified, rate-limited HTTP transport layer via snowland-http. Every client exposes both synchronous and asynchronous (asyncio) APIs, backed by requests / httpx respectively.

Installation

Core dependencies (no concrete HTTP library — only the snowland-http transport abstraction):

pip install -r requirements.txt

HTTP backends are all optional: you can import and use the SDK without any backend installed, but calling the corresponding sync/async request methods will raise a clear message at runtime. Install only one of them as needed (do not install all at once):

pip install snowland-qyweixin[requests]   # sync only
pip install snowland-qyweixin[httpx]      # sync + async (recommended, one library covers both)
pip install snowland-qyweixin[aiohttp]    # async only
# or install a single one manually:
pip install requests / httpx / aiohttp

Quick Start

Synchronous client:

from qywechat import MessageClient

client = MessageClient(corpid="xxx", corpsecret="yyy", agentid=1000001)
client.send_text("hello", touser=["zhangsan", "lisi"])

Asynchronous client:

import asyncio
from qywechat import MessageClient

async def main():
    client = MessageClient(corpid="xxx", corpsecret="yyy", agentid=1000001)
    await client.send_text_async("hello", touser="zhangsan")

asyncio.run(main())

Group robot (Webhook):

from qywechat import Robot

robot = Robot("https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxx")
robot.send_markdown("**hello**")

Modules

Each client class provides both synchronous and asynchronous methods: the synchronous method uses the feature name (e.g. send_text), and the corresponding async method appends the _async suffix (e.g. send_text_async).

Tests

python -m unittest discover -s qywechat/tests -p "test_*.py"

Notes

• BaseClient holds both a synchronous and an asynchronous HttpClient, and access_token is reused within its validity period.
• Synchronous methods only require any one synchronous library (candidates: requests, httpx); async methods only require any one asynchronous library (candidates: httpx, aiohttp). A missing library raises a clear message only when the corresponding method is actually used.
• Global token-bucket rate limiting can be enabled via rate_limit=RateLimitConfig(...).