聊天对象

通过机器人对象 Botchats(), friends()groups(), mps() 方法, 可分别获取到当前机器人的 所有聊天对象、好友、群聊,以及公众号列表。

而获得到的聊天对象合集 ChatsGroups 具有一些合集方法,例如:Chats.search() 可用于按条件搜索聊天对象:

from wxpy import *
bot = Bot()
my_friend = bot.friends().search('游否', sex=MALE, city='深圳')[0]
# <Friend: 游否>

在找到好友(或其他聊天对象)后,还可使用该聊天对象的 send 系列方法,对其发送消息:

# 发送文本
my_friend.send('Hello, WeChat!')
# 发送图片
my_friend.send_image('my_picture.png')
# 发送视频
my_friend.send_video('my_video.mov')
# 发送文件
my_friend.send_file('my_file.zip')
# 以动态的方式发送图片
my_friend.send('@img@my_picture.png')

各类型的继承关系

在继续了解各个聊天对象之前,我们需要首先 理解各种不同类型聊天对象的继承关系

基础类

所有聊天对象,均继承于以下两种基础类,并拥有相应的属性和方法。

基本聊天对象 Chat
  • 所有的聊天对象均继承于此类型
  • 拥有 微信ID、昵称 等属性
  • 拥有 发送消息 Chat.send(), 获取头像 Chat.get_avatar() 等方法
单个聊天对象 User
  • 继承于 Chat,表示个体聊天对象 (而非群聊)。
  • 被以下聊天对象所继承
  • 拥有 性别、省份、城市、是否为好友 等属性
  • 拥有 加为好友 User.add(), 接受为好友 User.accept() 等方法

实际类

在实际使用过程中,我们会更多的用到以下实际聊天对象类型。

小技巧

请牢记,除了自身私有的属性和方法外,它们还拥有对应基础类的属性和方法 (未重复列出)。

注解

阅读以下内容,你将了解:

  • 如何获取他们的各种属性 (ID、昵称、性别、地区、是否为好友关系等)
  • 如何对他们进行发送消息、加为好友、加入群聊、下载头像 等操作

基本聊天对象

所有聊天对象都继承于"基本聊天对象",并拥有相应的属性和方法。

class wxpy.Chat(core, _chat)[源代码]
基本聊天对象
单个用户 (User) 和群聊 (Group) 的基础类
参数:
  • core -- 关联的内核对象
  • _chat -- username 或 原始数据 dict
bot

所属的 机器人对象

raw

原始数据

puid

持续有效,且稳定唯一的聊天对象/用户ID,适用于持久保存

请使用 Bot.enable_puid() 来启用 puid 属性

小技巧

puidwxpy 特有的聊天对象/用户ID
不同于其他 ID 属性,puid 可始终被获取到,且具有稳定的唯一性

注意

puid 映射数据 不可跨机器人使用

nickname

该聊天对象的昵称 (好友、群员的昵称,或群名称)

name
该聊天对象的友好名称
即: 从 备注名称、群聊显示名称、昵称(或群名称),username 中按序选取第一个可用的
send(content, msg_type=None, media_id=None)[源代码]

发送消息。默认为发送文本消息,也可指定其他消息类型

参数:
  • content -- 消息类型为 TEXT 时为消息的文本内容,其他类型时为文件路径
  • msg_type -- 消息类型,支持 TEXT, IMAGE, STICKER, VIDEO, FILE (默认为 TEXT)
  • media_id -- 文件在服务器中的唯一 ID,填写后可省略上传步骤
返回:

已发送的消息

返回类型:

SentMessage

send_image(path, media_id=None)[源代码]

发送图片

参数:
  • path -- 图片的文件路径
  • media_id -- 文件在服务器中的唯一 ID,填写后可省略上传步骤
返回:

已发送的消息

返回类型:

SentMessage

send_sticker(path, media_id=None)[源代码]

发送表情 (类似于手机端中发送收藏的表情)

参数:
  • path -- 表情图片的文件路径
  • media_id -- 文件在服务器中的唯一 ID,填写后可省略上传步骤
返回:

已发送的消息

返回类型:

SentMessage

send_video(path, media_id=None)[源代码]

发送视频

参数:
  • path -- 视频的文件路径 (通常为 mp4 格式)
  • media_id -- 文件在服务器中的唯一 ID,填写后可省略上传步骤
返回:

已发送的消息

返回类型:

SentMessage

send_file(path, media_id=None)[源代码]

发送文件

参数:
  • path -- 文件路径
  • media_id -- 文件在服务器中的唯一 ID,填写后可省略上传步骤
返回:

已发送的消息

返回类型:

SentMessage

send_card(wxid, friend_or_mp)[源代码]

发送好友名片或公众号名片 (被发送的名片必须为好友关系或已关注的公众号)

参数:
  • wxid -- 好友或公众号的微信ID (无法直接获取,需要手动填写)
  • friend_or_mp -- 好友对象或公众号对象
mark_as_read()[源代码]

消除当前聊天对象的未读提示小红点

pin()[源代码]

将聊天对象置顶

unpin()[源代码]

取消聊天对象的置顶状态

get_avatar(save_path=None)[源代码]

获取头像

参数:save_path -- 保存路径(后缀通常为.jpg),若空则直接返回字节数据
raw

原始数据

username

该聊天对象的内部 ID,会随着登陆会话而改变,通常不需要用到

注意

此 ID 在机器人重新登录后 会被改变 !

update()[源代码]

更新聊天对象的详细信息

小技巧

对于群聊对象,group.update() 仅更新群本身,而不会更新群成员的详细信息
若要更新群员信息,可使用 group.members.update()

单个聊天对象

class wxpy.User(core, _chat)[源代码]

好友(Friend)、群聊成员(Member),和公众号(MP) 的基础类

基本聊天对象
单个用户 (User) 和群聊 (Group) 的基础类
参数:
  • core -- 关联的内核对象
  • _chat -- username 或 原始数据 dict
remark_name

备注名称

set_remark_name(remark_name)[源代码]

设置或修改好友的备注名称

参数:remark_name -- 新的备注名称
sex

性别,目前有:

# 男性
MALE = 1
# 女性
FEMALE = 2

未设置时为 None

province

省份

city

城市

signature

个性签名

is_friend

判断当前用户是否为好友关系

返回:若为好友关系,返回对应的好友,否则返回 False
add(verify_content=None)[源代码]

添加当前用户为好友

参数:verify_content -- 验证信息(文本)
accept()[源代码]

接受当前用户为好友

返回:新的好友对象
返回类型:wxpy.Friend

好友

class wxpy.Friend(core, _chat)[源代码]

好友对象

基本聊天对象
单个用户 (User) 和群聊 (Group) 的基础类
参数:
  • core -- 关联的内核对象
  • _chat -- username 或 原始数据 dict

群聊

class wxpy.Group(core, _chat)[源代码]

群聊对象

members

群聊的成员列表

返回类型:class:Chats:
nickname

该群聊对象的名称

get(keywords=None, **attributes)[源代码]

在群聊中查找群成员,等同于 Group.members.get(...)

find(keywords=None, **attributes)[源代码]

在群聊中查找群成员,等同于 Group.members.find(...)

search(keywords=None, **attributes)[源代码]

在群聊中查找群成员,等同于 Group.members.search(...)

owner

返回群主对象

is_owner

判断所属 bot 是否为群管理员

self

机器人自身 (作为群成员)

add(members, use_invitation=False)[源代码]

向群聊中加入用户

参数:
  • members -- 待加入的用户列表或单个用户
  • use_invitation -- 使用发送邀请的方式
remove(members)[源代码]

从群聊中移除用户

参数:members -- 待移除的用户列表或单个用户
rename(topic)[源代码]

修改群聊名称

参数:topic -- 新的名称,超长部分会被截断 (最长32字节)

群成员

class wxpy.Member(core, _raw, group_username)[源代码]

群聊成员对象

display_name

在群聊中的显示昵称

remove()[源代码]

从群聊中移除该成员

实用技巧

判断一位用户是否在群中只需用 in 语句:

friend = bot.friends().search('游否')[0]
group = bot.groups().search('wxpy 交流群')[0]

if friend in group:
    print('是的,{}{} 中!'.format(friend.name, group.name))
    # 是的,游否 在 wxpy 交流群 中!

若要遍历群成员,可直接对群对象使用 for 语句:

# 打印所有群成员
for member in group:
    print(member)

若需查看群成员数量,直接使用 len() 即可:

len(group) # 这个群的成员数量

若需判断一位群成员是否就是某个好友,使用 == 即可:

member = group.search('游否')[0]
if member == friend:
    print('{} is {}'.format(member, friend))
    # <Member: 游否> is <Friend: 游否>

公众号

class wxpy.MP(core, _chat)[源代码]

公众号对象

基本聊天对象
单个用户 (User) 和群聊 (Group) 的基础类
参数:
  • core -- 关联的内核对象
  • _chat -- username 或 原始数据 dict

聊天对象合集

好友、公众号、群聊成员的合集

Chats 对象中,除了最常用到的 search() 外,还有两个特别的方法,stats()stats_text(),可用来统计好友或群成员的性别和地区分布:

bot.friends().stats_text()
# 游否 共有 100 位微信好友\n\n男性: 67 (67.0%)\n女性: 23 (23.0%) ...
class wxpy.Chats(chat_list=None, source=None)[源代码]

多个聊天对象的列表,可用于搜索、更新、统计等功能

get(keywords=None, **attributes)[源代码]
找到匹配所设条件的唯一聊天对象
若结果不唯一,或没有找到,会抛出 ValueError 异常
参数:
  • keywords --
    聊天对象的名称关键词 (空格分隔, 不区分大小写)
    用于在 remark_name, display_name, nickname, wxid 中进行搜索
  • attributes --

    属性键值对,键可以是 sex(性别), province(省份), city(城市) 等,例如:

    bot.chats.get(nickname='游否', city='深圳', sex=MALE)
    
返回类型:

Chat

find(keywords=None, **attributes)[源代码]
类似于 any:Chats.get,不同之处在于仅返回 首个匹配的 聊天对象
也就是说: 即便列表内有多个匹配,也不会抛出异常; 若没有匹配的,则返回 None
返回类型:Chat
search(keywords=None, **attributes)[源代码]

类似于 any:Chats.get,不同之处在于会返回 所有匹配的 聊天对象

返回类型:Chats
update()[源代码]

更新列表中的所有聊天对象

stats(attribs=('sex', 'province', 'city'))[源代码]

统计各属性的分布情况

参数:attribs -- 需统计的属性列表或元组
返回:统计结果
stats_text(total=True, sex=True, top_provinces=10, top_cities=10)[源代码]

简单的统计结果的文本

参数:
  • total -- 总体数量
  • sex -- 性别分布
  • top_provinces -- 省份分布
  • top_cities -- 城市分布
返回:

统计结果文本

群聊的合集