Update docstrings and comments
This commit is contained in:
Changhua
parent
c331ff6443
commit
5a4cb7fb85
@ -1,5 +1,4 @@
|
||||
# WeChatFerry Python 客户端
|
||||
⚠️ **只支持 Windows** ⚠️
|
||||
|
||||
🤖示例机器人框架：[WeChatRobot](https://github.com/lich0821/WeChatRobot)。
|
||||
|
||||
@ -8,29 +7,6 @@
|
||||
pip install --upgrade wcferry
|
||||
```
|
||||
|
||||
### 接口清单
|
||||
* 检查登录状态：`is_login`
|
||||
* 获取登录账号的 wxid：`get_self_wxid`
|
||||
* 获取消息类型：`get_msg_types`
|
||||
* 获取所有联系人：`get_contacts`
|
||||
* 获取所有好友：`get_friends`
|
||||
* 获取数据库：`get_dbs`
|
||||
* 获取某数据库下的表：`get_tables`
|
||||
* 获取用户信息：`get_user_info`
|
||||
* 发送文本消息（可 @）：`send_text`
|
||||
* 发送图片：`send_image`
|
||||
* 发送文件：`send_file`
|
||||
* 发送 XML：`send_xml`
|
||||
* 发送表情：`send_emotion`
|
||||
* 允许接收消息：`enable_receiving_msg` 和 `enable_recv_msg（旧接口）`
|
||||
* 停止接收消息：`disable_recv_msg`
|
||||
* 执行 SQL 查询：`query_sql`
|
||||
* 接受好友申请：`accept_new_friend`
|
||||
* 添加群成员：`add_chatroom_members`
|
||||
* 解密图片：`decrypt_image`
|
||||
|
||||
详情查看 [client.py](wcferry/client.py)。
|
||||
|
||||
### Demo：
|
||||
```py
|
||||
#! /usr/bin/env python3
|
||||
|
||||
@ -47,7 +47,17 @@ def _retry():
|
||||
|
||||
|
||||
class Wcf():
|
||||
"""WeChatFerry, 一个玩微信的工具。"""
|
||||
"""WeChatFerry, 一个玩微信的工具。
|
||||
|
||||
Args:
|
||||
host (str): `wcferry` RPC 服务器地址，默认本地启动；也可以指定地址连接远程服务
|
||||
port (int): `wcferry` RPC 服务器端口，默认为 10086，接收消息会占用 `port+1` 端口
|
||||
debug (bool): 是否开启调试模式（仅本地启动有效）
|
||||
|
||||
Attributes:
|
||||
contacts (list): 联系人缓存，调用 `get_contacts` 后更新
|
||||
self_wxid (str): 登录账号 wxid
|
||||
"""
|
||||
|
||||
def __init__(self, host: str = None, port: int = 10086, debug: bool = True) -> None:
|
||||
self._local_host = False
|
||||
@ -128,6 +138,7 @@ class Wcf():
|
||||
return rsp
|
||||
|
||||
def is_receiving_msg(self) -> bool:
|
||||
"""是否已启动接收消息功能"""
|
||||
return self._is_receiving_msg
|
||||
|
||||
def is_login(self) -> bool:
|
||||
@ -191,7 +202,14 @@ class Wcf():
|
||||
return dbs
|
||||
|
||||
def get_tables(self, db: str) -> List[dict]:
|
||||
"""获取 db 中所有表"""
|
||||
"""获取 db 中所有表
|
||||
|
||||
Args:
|
||||
db (str): 数据库名（可通过 `get_dbs` 查询）
|
||||
|
||||
Returns:
|
||||
List[dict]: `db` 下的所有表名及对应建表语句
|
||||
"""
|
||||
req = wcf_pb2.Request()
|
||||
req.func = wcf_pb2.FUNC_GET_DB_TABLES # FUNC_GET_DB_TABLES
|
||||
req.str = db
|
||||
@ -201,7 +219,7 @@ class Wcf():
|
||||
return tables
|
||||
|
||||
def get_user_info(self) -> dict:
|
||||
"""获取个人信息"""
|
||||
"""获取登录账号个人信息"""
|
||||
req = wcf_pb2.Request()
|
||||
req.func = wcf_pb2.FUNC_GET_USER_INFO # FUNC_GET_USER_INFO
|
||||
rsp = self._send_request(req)
|
||||
@ -210,7 +228,16 @@ class Wcf():
|
||||
return ui
|
||||
|
||||
def send_text(self, msg: str, receiver: str, aters: Optional[str] = "") -> int:
|
||||
"""发送文本消息"""
|
||||
"""发送文本消息
|
||||
|
||||
Args:
|
||||
msg (str): 要发送的消息，换行使用 `\\n`；如果 @ 人的话，需要带上跟 `aters` 里数量相同的 @
|
||||
receiver (str): 消息接收人，wxid 或者 roomid
|
||||
aters (str): 要 @ 的 wxid，多个用逗号分隔；`@所有人` 只需要 `nofity@all`
|
||||
|
||||
Returns:
|
||||
int: 0 为成功，其他失败
|
||||
"""
|
||||
req = wcf_pb2.Request()
|
||||
req.func = wcf_pb2.FUNC_SEND_TXT # FUNC_SEND_TXT
|
||||
req.txt.msg = msg
|
||||
@ -221,7 +248,15 @@ class Wcf():
|
||||
return rsp.status
|
||||
|
||||
def send_image(self, path: str, receiver: str) -> int:
|
||||
"""发送图片"""
|
||||
"""发送图片
|
||||
|
||||
Args:
|
||||
path (str): 本地图片路径，如：`C:/Projs/WeChatRobot/TEQuant.jpeg`
|
||||
receiver (str): 消息接收人，wxid 或者 roomid
|
||||
|
||||
Returns:
|
||||
int: 0 为成功，其他失败
|
||||
"""
|
||||
req = wcf_pb2.Request()
|
||||
req.func = wcf_pb2.FUNC_SEND_IMG # FUNC_SEND_IMG
|
||||
req.file.path = path
|
||||
@ -230,7 +265,15 @@ class Wcf():
|
||||
return rsp.status
|
||||
|
||||
def send_file(self, path: str, receiver: str) -> int:
|
||||
"""发送文件"""
|
||||
"""发送文件
|
||||
|
||||
Args:
|
||||
path (str): 本地文件路径，如：`C:/Projs/WeChatRobot/README.MD`
|
||||
receiver (str): 消息接收人，wxid 或者 roomid
|
||||
|
||||
Returns:
|
||||
int: 0 为成功，其他失败
|
||||
"""
|
||||
req = wcf_pb2.Request()
|
||||
req.func = wcf_pb2.FUNC_SEND_FILE # FUNC_SEND_FILE
|
||||
req.file.path = path
|
||||
@ -239,7 +282,17 @@ class Wcf():
|
||||
return rsp.status
|
||||
|
||||
def send_xml(self, receiver: str, xml: str, type: int, path: str = None) -> int:
|
||||
"""发送文件"""
|
||||
"""发送 XML
|
||||
|
||||
Args:
|
||||
receiver (str): 消息接收人，wxid 或者 roomid
|
||||
xml (str): xml 内容
|
||||
type (int): xml 类型，如：0x21 为小程序
|
||||
path (str): 封面图片路径
|
||||
|
||||
Returns:
|
||||
int: 0 为成功，其他失败
|
||||
"""
|
||||
req = wcf_pb2.Request()
|
||||
req.func = wcf_pb2.FUNC_SEND_XML # FUNC_SEND_XML
|
||||
req.xml.receiver = receiver
|
||||
@ -251,7 +304,15 @@ class Wcf():
|
||||
return rsp.status
|
||||
|
||||
def send_emotion(self, path: str, receiver: str) -> int:
|
||||
"""发送表情"""
|
||||
"""发送表情
|
||||
|
||||
Args:
|
||||
path (str): 本地表情路径，如：`C:/Projs/WeChatRobot/emo.gif`
|
||||
receiver (str): 消息接收人，wxid 或者 roomid
|
||||
|
||||
Returns:
|
||||
int: 0 为成功，其他失败
|
||||
"""
|
||||
req = wcf_pb2.Request()
|
||||
req.func = wcf_pb2.FUNC_SEND_EMOTION # FUNC_SEND_EMOTION
|
||||
req.file.path = path
|
||||
@ -260,10 +321,21 @@ class Wcf():
|
||||
return rsp.status
|
||||
|
||||
def get_msg(self, block=True) -> WxMsg:
|
||||
"""从消息队列中获取消息
|
||||
|
||||
Args:
|
||||
block (bool): 是否阻塞，默认阻塞
|
||||
|
||||
Returns:
|
||||
WxMsg: 微信消息
|
||||
|
||||
Raises:
|
||||
Empty: 如果阻塞并且超时，抛出空异常，需要用户自行捕获
|
||||
"""
|
||||
return self.msgQ.get(block, timeout=1)
|
||||
|
||||
def enable_receiving_msg(self) -> bool:
|
||||
"""允许接收消息"""
|
||||
"""允许接收消息，成功后通过 `get_msg` 读取消息"""
|
||||
def listening_msg():
|
||||
rsp = wcf_pb2.Response()
|
||||
self.msg_socket.dial(self.msg_url, block=True)
|
||||
@ -297,7 +369,10 @@ class Wcf():
|
||||
return True
|
||||
|
||||
def enable_recv_msg(self, callback: Callable[[WxMsg], None] = None) -> bool:
|
||||
"""设置接收消息回调"""
|
||||
"""（不建议使用）设置接收消息回调，消息量大时可能会丢失消息
|
||||
|
||||
.. deprecated:: 3.7.0.30.13
|
||||
"""
|
||||
def listening_msg():
|
||||
rsp = wcf_pb2.Response()
|
||||
self.msg_socket.dial(self.msg_url, block=True)
|
||||
@ -345,7 +420,15 @@ class Wcf():
|
||||
return rsp.status
|
||||
|
||||
def query_sql(self, db: str, sql: str) -> List[dict]:
|
||||
"""执行 SQL"""
|
||||
"""执行 SQL，如果数据量大注意分页，以免 OOM
|
||||
|
||||
Args:
|
||||
db (str): 要查询的数据库
|
||||
sql (str): 要执行的 SQL
|
||||
|
||||
Returns:
|
||||
List[dict]: 查询结果
|
||||
"""
|
||||
result = []
|
||||
req = wcf_pb2.Request()
|
||||
req.func = wcf_pb2.FUNC_EXEC_DB_QUERY # FUNC_EXEC_DB_QUERY
|
||||
@ -363,6 +446,7 @@ class Wcf():
|
||||
|
||||
def accept_new_friend(self, v3: str, v4: str, scene: int = 30) -> int:
|
||||
"""通过好友申请
|
||||
|
||||
Args:
|
||||
v3 (str): 加密用户名 (好友申请消息里 v3 开头的字符串)
|
||||
v4 (str): Ticket (好友申请消息里 v4 开头的字符串)
|
||||
@ -400,7 +484,15 @@ class Wcf():
|
||||
return friends
|
||||
|
||||
def add_chatroom_members(self, roomid: str, wxids: str) -> int:
|
||||
"""添加群成员"""
|
||||
"""添加群成员
|
||||
|
||||
Args:
|
||||
roomid (str): 待加群的 id
|
||||
wxids (str): 要加到群里的 wxid，多个用逗号分隔
|
||||
|
||||
Returns:
|
||||
int: 1 为成功，其他失败
|
||||
"""
|
||||
req = wcf_pb2.Request()
|
||||
req.func = wcf_pb2.FUNC_ADD_ROOM_MEMBERS # FUNC_ADD_ROOM_MEMBERS
|
||||
req.m.roomid = roomid
|
||||
@ -410,6 +502,7 @@ class Wcf():
|
||||
|
||||
def receive_transfer(self, wxid: str, transferid: str) -> int:
|
||||
"""接收转账
|
||||
|
||||
Args:
|
||||
wxid (str): 转账消息里的发送人 wxid
|
||||
transferid (str): 转账消息里的 transferid
|
||||
@ -426,6 +519,7 @@ class Wcf():
|
||||
|
||||
def decrypt_image(self, src: str, dst: str) -> bool:
|
||||
"""解密图片:
|
||||
|
||||
Args:
|
||||
src (str): 加密的图片路径
|
||||
dst (str): 解密的图片路径
|
||||
|
||||
@ -1,9 +1,23 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
|
||||
import re
|
||||
|
||||
from wcferry import wcf_pb2
|
||||
|
||||
|
||||
class WxMsg():
|
||||
"""微信消息"""
|
||||
"""微信消息
|
||||
|
||||
Attributes:
|
||||
type (int): 消息类型，可通过 `get_msg_types` 获取
|
||||
id (str): 消息 id
|
||||
xml (str): 消息 xml 部分
|
||||
sender (str): 消息发送人
|
||||
roomid (str): （仅群消息有）群 id
|
||||
content (str): 消息内容
|
||||
thumb (str): 视频或图片消息的缩略图路径
|
||||
extra (str): 视频或图片消息的路径
|
||||
"""
|
||||
|
||||
def __init__(self, msg: wcf_pb2.WxMsg) -> None:
|
||||
self._is_self = msg.is_self
|
||||
|
||||
Loading…
Reference in New Issue
Block a user