Metadata-Version: 2.4
Name: py-easy-wecom
Version: 3.0.2
Summary: 企业微信 Python SDK，提供简单易用的企业微信 API 封装，支持消息发送、媒体上传等功能。
Home-page: https://gitee.com/guolei19850528/py_easy_wecom
Author: guolei
Author-email: 174000902@qq.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx
Requires-Dist: jsonschema
Requires-Dist: diskcache
Requires-Dist: redis
Requires-Dist: jsonpath-ng
Requires-Dist: decorator
Requires-Dist: py-easy-httpx
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# py_easy_wecom

企业微信 Python SDK，提供简单易用的企业微信 API 封装，支持消息发送、媒体上传等功能。

## 功能特性

- **Webhook 机器人**：支持同步和异步发送消息，上传媒体文件
- **企业微信服务器**：支持获取和刷新 access_token，管理缓存（支持 diskcache 和 redis）
- **消息管理**：支持发送应用消息
- **媒体管理**：支持上传临时素材和图文消息内的图片
- **同步/异步支持**：同时支持同步和异步操作
- **灵活配置**：支持通过参数自定义客户端行为
- **响应处理**：提供 JSON 数据验证和提取功能
- **类型提示**：完整的类型注解，提供良好的 IDE 支持

## 安装

### 使用 pip 安装

```bash
pip install py_easy_wecom
```

### 从源码安装

```bash
git clone https://gitee.com/guolei19850528/py_easy_wecom.git
cd py_easy_wecom
pip install -e .
```

## 依赖

- httpx
- diskcache
- redis
- py_easy_httpx

## 快速开始

### Webhook 机器人

#### 同步发送消息

```python
from py_easy_wecom.webhook import Webhook

# 初始化机器人
robot = Webhook(key="YOUR_WEBHOOK_KEY")

# 发送文本消息
response = robot.send(
    json={
        "msgtype": "text",
        "text": {
            "content": "Hello, World!",
            "mentioned_list": ["@all"],
            "mentioned_mobile_list": []
        }
    }
)
print(response)
```

#### 异步发送消息

```python
import asyncio
from py_easy_wecom.webhook import Webhook

async def main():
    # 初始化机器人
    robot = Webhook(key="YOUR_WEBHOOK_KEY")
    
    # 发送文本消息
    response = await robot.async_send(
        json={
            "msgtype": "text",
            "text": {
                "content": "Hello, World!",
                "mentioned_list": ["@all"],
                "mentioned_mobile_list": []
            }
        }
    )
    print(response)

asyncio.run(main())
```

### 企业微信服务器

#### 初始化服务器

```python
from py_easy_wecom.server import Server

# 初始化服务器
server = Server(
    corpid="YOUR_CORPID",
    corpsecret="YOUR_CORPSECRET",
    agentid="YOUR_AGENTID"
)

# 刷新 access_token
server.refresh_access_token()
print(server.access_token)
```

#### 发送应用消息

```python
from py_easy_wecom.server.message import Message

# 初始化消息客户端
message_client = Message(
    corpid="YOUR_CORPID",
    corpsecret="YOUR_CORPSECRET",
    agentid="YOUR_AGENTID"
)

# 刷新 access_token
message_client.refresh_access_token()

# 发送文本消息
response = message_client.send(
    json={
        "touser": "UserID1|UserID2",
        "msgtype": "text",
        "text": {
            "content": "Hello, World!"
        }
    }
)
print(response)
```

#### 上传媒体文件

```python
from py_easy_wecom.server.media import Media

# 初始化媒体客户端
media_client = Media(
    corpid="YOUR_CORPID",
    corpsecret="YOUR_CORPSECRET",
    agentid="YOUR_AGENTID"
)

# 刷新 access_token
media_client.refresh_access_token()

# 上传临时素材
with open("example.jpg", "rb") as f:
    response = media_client.upload(
        file_type="image",
        files={"media": f}
    )
print(response)  # 返回 media_id
```

## API 文档

### Webhook 类

#### 初始化参数
- `base_url`：企业微信 API 基础 URL，默认为 "https://qyapi.weixin.qq.com/"
- `key`：机器人 Webhook 密钥
- `mentioned_list`：提及用户列表
- `mentioned_mobile_list`：提及手机号列表
- `client_kwargs`：传递给 httpx.Client 的额外参数

#### 方法
- `send(client=None, **kwargs)`：同步发送消息
- `async_send(client=None, **kwargs)`：异步发送消息
- `upload_media(client=None, file_type="file", **kwargs)`：同步上传媒体文件
- `async_upload_media(client=None, file_type="file", **kwargs)`：异步上传媒体文件

### Server 类

#### 初始化参数
- `base_url`：企业微信 API 基础 URL，默认为 "https://qyapi.weixin.qq.com"
- `corpid`：企业 ID
- `corpsecret`：应用的凭证密钥
- `agentid`：应用 ID
- `cache_config`：缓存配置，支持 diskcache 或 redis
- `client_kwargs`：传递给 httpx.Client 的额外参数

#### 方法
- `request(client=None, **kwargs)`：同步发送请求
- `async_request(client=None, **kwargs)`：异步发送请求
- `get_access_token(client=None, **kwargs)`：获取 access_token
- `async_get_access_token(client=None, **kwargs)`：异步获取 access_token
- `get_api_domain_ip(client=None, **kwargs)`：获取企业微信 API 域名 IP 段
- `async_get_api_domain_ip(client=None, **kwargs)`：异步获取企业微信 API 域名 IP 段
- `get_callback_ip(client=None, **kwargs)`：获取企业微信回调 IP 段
- `async_get_callback_ip(client=None, **kwargs)`：异步获取企业微信回调 IP 段
- `refresh_access_token(client=None, get_access_token_kwargs=None, get_api_domain_ip_kwargs=None)`：刷新 access_token
- `async_refresh_access_token(client=None, get_access_token_kwargs=None, get_api_domain_ip_kwargs=None)`：异步刷新 access_token

### Message 类

#### 方法
- `send(client=None, **kwargs)`：同步发送应用消息
- `async_send(client=None, **kwargs)`：异步发送应用消息

### Media 类

#### 方法
- `upload(client=None, file_type=None, **kwargs)`：同步上传临时素材
- `async_upload(client=None, file_type=None, **kwargs)`：异步上传临时素材
- `upload_img(client=None, **kwargs)`：同步上传图文消息内的图片
- `async_upload_img(client=None, **kwargs)`：异步上传图文消息内的图片

## 高级用法

### 缓存配置

#### 使用 diskcache

```python
import diskcache
from py_easy_wecom.server import Server

# 创建缓存实例
cache = diskcache.Cache("./cache")

# 初始化服务器
server = Server(
    corpid="YOUR_CORPID",
    corpsecret="YOUR_CORPSECRET",
    agentid="YOUR_AGENTID",
    cache_config={
        "instance": cache,
        "expire": 7100  # 缓存过期时间（秒）
    }
)
```

#### 使用 redis

```python
import redis
from py_easy_wecom.server import Server

# 创建 redis 实例
redis_client = redis.Redis(host="localhost", port=6379, db=0)

# 初始化服务器
server = Server(
    corpid="YOUR_CORPID",
    corpsecret="YOUR_CORPSECRET",
    agentid="YOUR_AGENTID",
    cache_config={
        "instance": redis_client,
        "expire": 7100  # 缓存过期时间（秒）
    }
)
```

## 项目结构

```
py_easy_wecom/
├── py_easy_wecom/              # 主包目录
│   ├── __init__.py            # 包初始化文件
│   ├── webhook/               # Webhook 模块
│   │   └── __init__.py        # Webhook 初始化文件
│   └── server/                # 服务器模块
│       ├── __init__.py        # 服务器初始化文件
│       ├── message.py         # 消息管理模块
│       └── media.py           # 媒体管理模块
├── README.md                  # 项目文档
├── setup.py                   # 安装配置
├── requirements.txt           # 依赖列表
├── LICENSE                    # 许可证文件
└── .gitignore                 # Git 忽略文件
```

## 测试

运行测试：

```bash
# 运行测试
python -m pytest
```

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！

## 联系方式

- 作者：guolei
- 邮箱：174000902@qq.com
- 项目地址：https://gitee.com/guolei19850528/py_easy_wecom

## 致谢

- [httpx](https://www.python-httpx.org/) - 高性能的异步 HTTP 客户端库
- [diskcache](https://github.com/grantjenkins/diskcache) - 简单易用的本地缓存库
- [redis](https://redis.io/) - 高性能的键值存储
- [py_easy_httpx](https://gitee.com/guolei19850528/py_easy_httpx) - 简化 HTTP 请求的工具包
