数据对象模型¶

消息对象Message¶

class yawxt.Message(to_id, from_id, msg_type, content, msg_id=None, create_time=None)¶

微信消息类，包括接收消息和发送消息，事件也属于消息

变量:

to_id -- 如果是接收的用户消息，则为公众号appid，如果是发送给用户的消息，则为用户openid
from_id -- 如果是接收的用户消息，则为用户openid，如果是发送给用户的消息，则为公众号appid
create_time -- 消息的创建时间，整型unix时间戳
msg_type -- 消息的类型，如 text, voice, 事件消息类型为event_加事件类型，如 event_LOCATION, event_VIEW

content --

消息除去头部自动构成的xml字符串，例如：

<Location_X>39.915119</Location_X>
<Location_Y>116.403963</Location_Y>
<Scale>16</Scale>
<Label><![CDATA[北京市东城区东长安街]]></Label>

classmethod from_string(xml_str)¶

从文本字符串构造 Message 对象

参数:	xml_str -- xml文本字符串
返回类型:	Message

build_xml()¶

生成此消息的xml字符

返回:	此消息对应的微信xml格式消息字符串
返回类型:	str

用户对象User¶

class yawxt.User(_d=None, **kwargs)¶

公众号用户类

变量:

subscribe -- 是否订阅该公众号
openid -- 用户的标识
nickname -- 用户的昵称
sex -- 用户的性别，值为1时是男性，值为2时是女性，值为0时是未知
city -- 用户所在城市
country -- 用户所在国家
province -- 用户所在省份
language -- 用户的语言，简体中文为zh_CN
headimgurl -- 用户头像，最后一个数值代表正方形头像大小（有0、46、64、 96、132数值可选，0代表640*640正方形头像），用户没有头像时该项为空。若用户更换头像，原有头像URL将失效。
subscribe_time -- 用户关注时间，为时间戳
union -- 只有在用户将公众号绑定到微信开放平台帐号后，才会出现该字段
remark -- 公众号运营者对粉丝的备注
groupid -- 用户所在的分组ID
tagid_list -- 用户被打上的标签ID列表，是逗号分割的字符串

tagids¶: 类型为整型list的标签id，如 [1,2,3] , 对应的 tagid_list 为 '1,2,3'

update(info)¶: 更新用户信息

地理位置对象Location¶

class yawxt.Location(latitude, longitude, precision=None, openid=None, create_time=None)¶

用户上报地址类

变量:	latitude -- 位置纬度 longitude -- 位置经度 precision -- 位置精确度 openid -- 在次位置的用户openid create_time -- 用户在此位置的时间

微信HTTP接口WxClient¶

微信HTTP接口主要封装在 WxClient 中

基本属性

appid appid
appsecret appsecret

用户管理¶

获取openid列表 get_openid_iter()

获取用户对象 get_user()

获取关注用户数目 get_user_count()

预览消息 preview_message()

网页JS开发相关¶

从网页授权code获取用户对象 get_user_from_web()

签名网页得到JS配置 js_sign()

模板消息管理¶

设置所属行业 set_industry()

获取所属行业 get_industry()

添加模板库模板 add_sys_template()

删除模板 del_template()

获取模板列表 get_template_list()

发送模板消息 send_template_message()

其他¶

语义理解 semantic_parse()

class yawxt.WxClient(appid, secret)¶

公众号API类，封装大部分公众号RESTful API的接口

参数:	appid -- 微信公众号appID secret -- 微信公众号appsecret

待处理

完成用户管理的标签管理，共8个API

待处理

完成用户的备注功能，共2个API

待处理

完成用户的拉黑功能，共2个API

get_openid_iter()¶

返回类型:	generator
返回:	关注公众号所有用户的迭代器，可以使用 `next()` 函数或 `for` 循环得到每一个用户的openid： it = client.get_openid_iter() first_openid = next(it) for openid in it: do_something(openid)

可以使用 list(client.get_openid_iter()) 直接获取所有用户的openid列表，要获取关注公众号的总用户数，请使用 get_user_count() , 尤其是用户数量比较多的情况下

get_user_count()¶

获取关注公众号的总用户人数

返回类型:	int

get_user(openid)¶

获取用户对象

参数:	openid -- 要获取的用户对象的openid
返回:	用户对象
返回类型:	User

preview_message(openid, text)¶

消息预览接口，给指定用户发送消息，此接口只是为了方便开发者查看消息的样式和排版

参数:	openid -- 用户的openid text -- 发送消息的文本内容
返回:	返回消息id，发送文本时消息id为 `None`

注解

此消息每日调用限制100次，请勿滥用

待处理

此接口可以发送文本、语音、图片、视频、卡券，待实现

get_user_from_web(code)¶

使用网页授权获得微信用户信息，此方法返回genertor，使用next方法先获取用户的openid，再获取 User 对象。如果仅想的得到open，则只要

user_gen = client.get_user_from_web(code)
openid = next(user_gen)

或者得到open和用户对象

openid, user = client.get_user_from_web(code)

参数:	code -- 用户网页授权链接跳转得到的code码
返回类型:	generator

js_sign(url, debug=True)¶

JS-SDK步骤三：config接入接口配置生成，这个过程需要在服务器端完成

参数:	url -- js注入的url debug -- js调试模式，默认为开启
返回:	JS-SDK config接入接口配置信息
返回类型:	dict

set_industry(industry_id1, industry_id2)¶

设置模板消息的公众号的所属行业，需要设置两个

参数:	industry_id1 -- 设置第一行业id，在1-41之间 industry_id2 -- 设置第二行业id，在1-41之间

get_industry()¶

获取模板消息的公众号的所属行业

返回类型:	dict
返回:	两个所属行业代码的字典，例如 {"primary_industry": {"first_class":"运输与仓储", "second_class":"快递"}, "secondary_industry": {"first_class":"IT科技", "second_class":"互联网\|电子商务"} }

add_sys_template(short_id)¶

从系统模板库选择模板设置为公众号模板

参数:	short_id -- 系统模板库模板id
返回:	设置为公众号模板后的模板id
返回类型:	str

del_template(template_id)¶

删除公众号模板

参数:	template_id -- 要删除的模板id

get_template_list()¶

获取公众号的所有消息模板列表

返回:	消息模板列表
返回类型:	list

send_template_message(to_openid, template_id, data, miniprogram_id=None, miniprogram_path=None, url=None)¶

给用户发送模板消息

参数:	to_openid -- 要发送的用户的openid template_id -- 发送的消息模板id data -- 模板的具体数据 miniprogram_id -- 要跳转的小程序id, 可不填 miniprogram_path -- 要跳转的小程序路径 url -- 要跳转的url，同时设置小程序，小程序优先
返回:	发送消息的id

semantic_parse(query, city=None, location=None, region=None, category=['restaurant', 'map', 'nearby', 'coupon', 'travel', 'hotel', 'train', 'flight', 'weather', 'stock', 'remind', 'telephone', 'movie', 'music', 'video', 'novel', 'cookbook', 'baike', 'news', 'tv', 'app', 'nstruction', 'tv_instruction', 'car_instruction', 'website', 'search'])¶

语义理解接口. 具体请参见微信语义接口开发文档

参数:	query -- 需要解析的文本字符串 city -- 所在的城市 location -- 所在的位置，设置openid可以使用使用上下文理解功能 region -- 所在的区域 category -- 理解场景的服务类型，默认包含所有类别
返回:	参见微信语义接口开发文档
返回类型:	dict

注解

此接口问题比较多，异常返回而且错误码未知，请谨慎使用

消息处理类MessageHandler¶

基本属性¶

用户openid openid

用户 user

消息对象 message

接收事件消息¶

上报地理位置事件 event_location()

关注及扫码关注事件 event_subscribe()

取消关注事件 event_unsubscribe()

点击菜单链接事件 event_view()

点击菜单拉取消息事件 event_click()

已关注用户扫码事件 event_scan()

模板消息发送任务完成事件 event_template_send_job_finished()

接收普通消息¶

文本消息 on_text()

图片消息 on_image()

语音消息 on_voice()

视频消息 on_video()

短视频消息 on_shortvideo()

地址消息 on_location()

链接消息 on_link()

回复消息¶

回复文本 reply_text()

回复调试文本 reply_debug_text()

回复图像 reply_image()

回复语音 reply_voice()

回复视频 reply_video()

回复图文消息 reply_news()

回复空消息 reply_empty()

生成回复消息文本 reply()

消息hook¶

消息处理前hook before()

回复消息生成后hook finish()

注意这些hook每次都会调用，和事件或消息处理函数都会调用，调用顺序 before() -> on_(event_)type() -> after()

class yawxt.MessageHandler(content, client=None, debug_to_wechat=False)¶

微信消息处理基类，继承此类定义不同消息的处理函数

继承以 event_ 开头的方法对event事件进行处理，这类消息一般不进行回复
继承以 on_ 开头的方法是对接收普通消息进行处理及回复消息
使用以 reply_ 开头的方法进行回复内容，注意，多次调用此方法只会回复最后一次调用的消息
使用 reply() 得到最终发送给微信服务器的文本字符串

参数:	content -- 从微信服务器接收的xml格式的消息字符串 client -- 微信公众号账号, `WxClient` 对象，默认为 `None` ，不设置 debug_to_wechat -- 使用 reply_debug_text 可以将调试信息发送到用户微信
变量:	openid -- 发送消息用户的openid message -- 接收到的消息对象，类型为 `yawxt.Message`

user¶: 发送微信消息的用户信息，为 User 对象，使用公众号 WxClient API获取，如果 client 为 None ，则返回 None

before()¶

在处理具体消息内容之前调用，可以使用 self.openid , self.user ,

self.messsage 等属性

event_location(location)¶

上报用户地理位置事件

参数:	location -- 地理位置 `Location` 对象

event_subscribe_from_qrcode(scene_value, ticket)¶

用户扫码关注公众号事件

参数:	scene_value -- 扫码关注时的二维码场景值 ticket -- 扫码关注时的票据，如果只处理订阅事件，忽略这两个参数

参见

event_scan() , event_subscribe() .

event_subscribe()¶: 用户关注公众号事件

参见

event_subscribe_from_qrcode()

event_unsubscribe()¶: 用户取消订阅公众号事件

event_view(view_key)¶

点击菜单跳转链接时的事件推送

参数:	view_key -- 跳转的链接

event_click(click_key)¶

点击菜单拉取消息时的事件推送

参数:	click_key -- 自定义菜单接口中KEY值

event_scan(scene_value, ticket)¶

已关注用户扫码事件

参数:	scene_value -- `int` 型，创建二维码时的二维码scene_id ticket -- 二维码的ticket，可用来换取二维码图片

参见

event_subscribe()

event_template_send_job_finished(status)¶

模板消息发送任务完成事件

参数:	status -- 消息发送完成之后的状态，包括以下三种： "success" "failed:user block" "failed: system failed"

on_text(text)¶

接收到文本消息处理方法

参数:	text -- 接受到的文本

on_image(media_id, pic_url)¶

接收到图片消息处理方法

参数:	media_id -- 图片的media_id pic_url -- 图片的下载地址

on_voice(media_id, voice_format, recognition)¶

接受到语音消息处理方法

参数:	media_id -- 语音的media_id voice_format -- 语音的格式 recognition -- 语音的识别的文字，需在公众号中开启，否则为 `None`

on_video(media_id, thumb_id)¶

接收到视频消息处理方法

参数:	media_id -- 视频的media_id thumb_id -- 视频的缩略图media_id

on_shortvideo(media_id, thumb_id)¶

接收到短视频消息处理方法

参数:	media_id -- 短视频的media_id thumb_id -- 短视频的缩略图media_id

on_location(x, y, scale, label)¶

用户发送地理位置消息的处理方法

参数:	x -- 纬度 y -- 经度 scale -- 地图的缩放级别 label -- 地理位置的名称

参见

event_location()

on_link(url, title, desc)¶

用户发送链接地址的处理方法

参数:	url -- 发送的链接地址 title -- 链接的标题 desc -- 连接的描述

reply_text(text)¶

回复一条文本消息

参数:	text -- 回复的文本字符串

reply_debug_text(text)¶

debug_to_wechat为True时回复的debug文本消息，否则不回复

参数:	text -- 回复的debug文本字符串

reply_image(image_id)¶

回复一条图片消息

参数:	image_id -- 图片的media_id

reply_voice(voice_id)¶

回复一条语言消息

参数:	voice_id -- 回复语音的media_id

reply_video(video_id, title=None, desc=None)¶

回复一条视频消息

参数:	video_id -- 回复视频的media_id title -- 回复视频的标题，可不填 desc -- 回复视频的描述，可不填

reply_music(music_id, title=None, description=None, url=None, hqurl=None)¶

回复一条歌曲消息

参数:	music_id -- 歌曲的media_id title -- 歌曲的标题 description -- 歌曲的描述 url -- 歌曲的url地址 hqurl -- 歌曲的高清url地址

reply_news(articles)¶

回复一条图文消息

参数:	articles -- 类型为 `list` , 包含每一条图文每一个图文为一个 `dict` ，必须包含 `title` , `description` , `picurl` , `url` 四个字段。消息最多包含8条，多余的会自动过滤。

reply_empty()¶: 对本条消息不作任何回复

finish()¶: 在回复完所有消息之后调用，此处可以使用类型为 Message 的消息回复对象 self.reply_message , 该对象在回复消息为空时为 None

reply()¶

返回:	事件或消息处理完成后最终回复给微信的文本内容

注解

此方法只允许调用一次

消息持久化处理类¶

class yawxt.persistence.PersistMessageHandler(content, client, db_session_maker, **kwargs)¶

消息持久化类，继承此类自动将每一条消息、地理位置上报、: 发送消息用户资料保存到数据库

参数:	content -- 微信发送的消息xml字符串 client -- 微信公众号账号, `WxClient` 对象 db_session_maker -- sqlalchemy session生成方法，一般为 `sessionmaker(bind=engine)` ，例如 Session = sessionmaker(bind=engine) processor = PersistMessageHandler(content, client, db_session_maker = Session)

user_location¶

用户的地理位置，用户最后一次上报的位置，从数据库中获取

Type:	`Location`

save_user_info(refresh_interval=None)¶

保存或更新发送消息的用户的信息

参数:	refresh_interval -- 从微信服务器刷新用户信息的间隔时间，从上次保存到数据库到现在超过时间间隔则从微信数据库拉取，单位为天，可以使用小数，默认为1天, refresh_interval为0时一直拉取.

其他类或方法¶

yawxt.check_signature(token, timestamp, nonce, signature, time_error=600)¶

微信消息的签名检查

参数:	token -- 公众号后台填写的token timestamp -- 从发送消息url query_string获取的timestamp参数 nonce -- 从发送消息url query_string获取的nonce参数 signature -- 从发送消息url query_string获取的signature参数 time_error -- 时间误差，与微信服务器时间的误差允许秒数，设置为0表示不检查，默认为600秒

yawxt.persistence.create_all(bind)¶

创建数据库及所有表

参数:	bind -- 一般为sqlalchemy `Engine` 对象

exception yawxt.exceptions.APIError(errcode, errmsg=None)¶

微信API调用异常类，通过 OfficalAccount 调用微信API错误码不是0时抛出此异常

参数:	errcode -- 错误码，和微信全局错误码一致 errmsg -- 错误消息，微信API调用错误消息

exception yawxt.exceptions.SystemAPIError(errmsg=None)¶: 微信系统繁忙，此时请开发者稍候再试，错误码-1

exception yawxt.exceptions.MaxQuotaError(errmsg=None)¶: API日调用次数打到上限异常, 错误码45009

exception yawxt.exceptions.ChangeIndustryError(errmsg=None)¶: 改变模板消息行业API调用过于频繁，错误码43100

exception yawxt.exceptions.SemanticAPIError(errcode, errmsg=None)¶: 微信语义消息解析错误, 错误码7000000~8000000

参见

yawxt.WxClient.semantic_parse()