API

应用对象

class werobot.robot.BaseRoBot(token=None, logger=None, enable_session=None, session_storage=None, app_id=None, app_secret=None, encoding_aes_key=None, config=None, \*kwargs*)

BaseRoBot 是整个应用的核心对象，负责提供 handler 的维护，消息和事件的处理等核心功能。

• 参数

  • logger – 用来输出 log 的 logger，如果是 None，将使用 werobot.logger

  • config – 用来设置的 werobot.config.Config 对象

注解

对于下面的参数推荐使用 Config 进行设置， 并且以下参数均已 deprecated。

• 参数

  • token – 微信公众号设置的 token (deprecated)

  • enable_session – 是否开启 session (deprecated)

  • session_storage – 用来储存 session 的对象，如果为 None， 将使用 werobot.session.sqlitestorage.SQLiteStorage (deprecated)

  • app_id – 微信公众号设置的 app id (deprecated)

  • app_secret – 微信公众号设置的 app secret (deprecated)

  • encoding_aes_key – 用来加解密消息的 aes key (deprecated)

• add_filter(func, rules)

  为 BaseRoBot 添加一个 filter handler。

  • 参数

    • func – 如果 rules 通过，则处理该消息的 handler。

    • rules – 一个 list，包含要匹配的字符串或者正则表达式。

    返回

    None

• add_handler(func, type=’all’)

  为 BaseRoBot 实例添加一个 handler。

  • 参数

    • func – 要作为 handler 的方法。

    • type – handler 的种类。

    返回

    None

• card_not_pass_check(f)

  为生成的卡券未通过审核 (card_not_pass_check_event) 事件添加一个 handler 方法的装饰器。

• card_pass_check(f)

  为生成的卡券通过审核 (card_pass_check_event) 事件添加一个 handler 方法的装饰器。

• card_pay_order(f)

  为券点发生变动 (card_pay_order_event) 事件添加一个 handler 方法的装饰器。

• card_sku_remind(f)

  为某个card_id的初始库存数大于200且当前库存小于等于100 (card_sku_remind_event) 事件添加一个 handler 方法的装饰器。

• check_signature(timestamp, nonce, signature)

  根据时间戳和生成签名的字符串 (nonce) 检查签名。

  • 参数

    • timestamp – 时间戳

    • nonce – 生成签名的随机字符串

    • signature – 要检查的签名

    返回

    如果签名合法将返回 True，不合法将返回 False

• click(f)

  为自定义菜单事件 (click) 事件添加一个 handler 方法的装饰器。

• error_page(f)

  为 robot 指定 Signature 验证不通过时显示的错误页面。

  Usage:

  @robot.error_page
  def make_error_page(url):
      return "<h1>喵喵喵 %s 不是给麻瓜访问的快走开</h1>" % url

• filter(\args*)

  为文本 (text) 消息添加 handler 的简便方法。

  使用 @filter("xxx"), @filter(re.compile("xxx")) 或 @filter("xxx", "xxx2") 的形式为特定内容添加 handler。

• get_encrypted_reply(message)

  对一个指定的 WeRoBot Message ，获取 handlers 处理后得到的 Reply。 如果可能，对该 Reply 进行加密。 返回 Reply Render 后的文本。

  • 参数

    message – 一个 WeRoBot Message 实例。

    返回

    reply （纯文本）

• get_reply(message)

  根据 message 的内容获取 Reply 对象。

  • 参数

    message – 要处理的 message

    返回

    获取的 Reply 对象

• handler(f)

  为每一条消息或事件添加一个 handler 方法的装饰器。

• image(f)

  为图像 (image) 消息添加一个 handler 方法的装饰器。

• key_click(key)

  为自定义菜单 (click) 事件添加 handler 的简便方法。

  @key_click(‘KEYNAME’) 用来为特定 key 的点击事件添加 handler 方法。

• link(f)

  为链接 (link) 消息添加一个 handler 方法的装饰器。

• location(f)

  为位置 (location) 消息添加一个 handler 方法的装饰器。

• location_event(f)

  为上报位置 (location_event) 事件添加一个 handler 方法的装饰器。

• location_select(f)

  为弹出地理位置选择器的事件推送 (location_select_event) 事件添加一个 handler 方法的装饰器。

• parse_message(body, timestamp=None, nonce=None, msg_signature=None)

  解析获取到的 Raw XML ，如果需要的话进行解密，返回 WeRoBot Message。 :param body: 微信服务器发来的请求中的 Body。 :return: WeRoBot Message

• pic_photo_or_album(f)

  为弹出拍照或者相册发图的事件推送 (pic_photo_or_album_event) 事件添加一个 handler 方法的装饰器。

• pic_sysphoto(f)

  为弹出系统拍照发图的事件推送 (pic_sysphoto_event) 事件添加一个 handler 方法的装饰器。

• pic_weixin(f)

  为弹出微信相册发图器的事件推送 (pic_weixin_event) 事件添加一个 handler 方法的装饰器。

• scan(f)

  为扫描推送 (scan) 事件添加一个 handler 方法的装饰器。

• scancode_push(f)

  为扫描推送 (scancode_push) 事件添加一个 handler 方法的装饰器。

• scancode_waitmsg(f)

  为扫描弹消息 (scancode_waitmsg) 事件添加一个 handler 方法的装饰器。

• shortvideo(f)

  为小视频 (shortvideo) 消息添加一个 handler 方法的装饰器。

• submit_membercard_user_info(f)

  为用户通过一键激活的方式提交信息并点击激活或者用户修改会员卡信息 (submit_membercard_user_info_event) 事件添加一个 handler 方法的装饰器。

• subscribe(f)

  为被关注 (subscribe) 事件添加一个 handler 方法的装饰器。

• templatesendjobfinish_event(f)

  在模版消息发送任务完成后，微信服务器会将是否送达成功作为通知，发送到开发者中心中填写的服务器配置地址中

• text(f)

  为文本 (text) 消息添加一个 handler 方法的装饰器。

• unknown(f)

  为未知类型 (unknown) 消息添加一个 handler 方法的装饰器。

• unknown_event(f)

  为未知类型 (unknown_event) 事件添加一个 handler 方法的装饰器。

• unsubscribe(f)

  为被取消关注 (unsubscribe) 事件添加一个 handler 方法的装饰器。

• update_member_card(f)

  为用户的会员卡积分余额发生变动 (update_member_card_event) 事件添加一个 handler 方法的装饰器。

• user_consume_card(f)

  为卡券被核销 (user_consume_card_event) 事件添加一个 handler 方法的装饰器。

• user_del_card(f)

  为用户删除卡券 (user_del_card_event) 事件添加一个 handler 方法的装饰器。

• user_enter_session_from_card(f)

  为用户卡券里点击查看公众号进入会话 (user_enter_session_from_card_event) 事件添加一个 handler 方法的装饰器。

• user_get_card(f)

  为用户领取卡券 (user_get_card_event) 事件添加一个 handler 方法的装饰器。

• user_gifting_card(f)

  为用户转赠卡券 (user_gifting_card_event) 事件添加一个 handler 方法的装饰器。

• user_pay_from_pay_cell(f)

  为微信买单完成 (user_pay_from_pay_cell_event) 事件添加一个 handler 方法的装饰器。

• user_scan_product(f)

  为打开商品主页事件推送 (user_scan_product_event) 事件添加一个 handler 方法的装饰器。

• user_scan_product_async(f)

  为地理位置信息异步推送 (user_scan_product_async_event) 事件添加一个 handler 方法的装饰器。

• user_scan_product_enter_session(f)

  为进入公众号事件推送 (user_scan_product_enter_session_event) 事件添加一个 handler 方法的装饰器。

• user_scan_product_verify_action(f)

  为商品审核结果推送 (user_scan_product_verify_action_event) 事件添加一个 handler 方法的装饰器。

• user_view_card(f)

  为用户进入会员卡 (user_view_card_event) 事件添加一个 handler 方法的装饰器。

• video(f)

  为视频 (video) 消息添加一个 handler 方法的装饰器。

• view(f)

  为链接 (view) 事件添加一个 handler 方法的装饰器。

• voice(f)

  为语音 (voice) 消息添加一个 handler 方法的装饰器。

class werobot.robot.WeRoBot(token=None, logger=None, enable_session=None, session_storage=None, app_id=None, app_secret=None, encoding_aes_key=None, config=None, \*kwargs*)

WeRoBot 是一个继承自 BaseRoBot 的对象，在 BaseRoBot 的基础上使用了 bottle 框架， 提供接收微信服务器发来的请求的功能。

• run(server=None, host=None, port=None, enable_pretty_logging=True)

  运行 WeRoBot。

  • 参数

    • server – 传递给 Bottle 框架 run 方法的参数，详情见 bottle 文档

    • host – 运行时绑定的主机地址

    • port – 运行时绑定的主机端口

    • enable_pretty_logging – 是否开启 log 的输出格式优化

配置对象

class werobot.config.Config

• from_object(obj)

  在给定的 Python 对象中读取配置。

  • 参数

    obj – 一个 Python 对象

• from_pyfile(filename)

  在一个 Python 文件中读取配置。

  • 参数

    filename – 配置文件的文件名

    返回

    如果读取成功，返回 True，如果失败，会抛出错误异常

Session 对象

class werobot.session.sqlitestorage.SQLiteStorage(filename=’werobot_session.sqlite3’)

SQLiteStorge 会把 Session 数据储存在一个 SQLite 数据库文件中

import werobot
from werobot.session.sqlitestorage import SQLiteStorage
session_storage = SQLiteStorage
robot = werobot.WeRoBot(token="token", enable_session=True,
                        session_storage=session_storage)

• 参数

  filename – SQLite数据库的文件名, 默认是 werobot_session.sqlite3

class werobot.session.filestorage.FileStorage(filename=’werobot_session’)

FileStorage 会把你的 Session 数据以 dbm 形式储存在文件中。

• 参数

  filename – 文件名， 默认为 werobot_session

class werobot.session.mongodbstorage.MongoDBStorage(collection)

MongoDBStorage 会把你的 Session 数据储存在一个 MongoDB Collection 中

import pymongo
import werobot
from werobot.session.mongodbstorage import MongoDBStorage
collection = pymongo.MongoClient()["wechat"]["session"]
session_storage = MongoDBStorage(collection)
robot = werobot.WeRoBot(token="token", enable_session=True,
                        session_storage=session_storage)

你需要安装 pymongo 才能使用 MongoDBStorage 。

• 参数

  collection – 一个 MongoDB Collection。

class werobot.session.redisstorage.RedisStorage(redis, prefix=’ws_‘)

RedisStorage 会把你的 Session 数据储存在 Redis 中

import redis
import werobot
from werobot.session.redisstorage import RedisStorage
db = redis.Redis()
session_storage = RedisStorage(db, prefix="my_prefix_")
robot = werobot.WeRoBot(token="token", enable_session=True,
                        session_storage=session_storage)

你需要安装 redis 才能使用 RedisStorage 。

• 参数

  • redis – 一个 Redis Client。

  • prefix – Reids 中 Session 数据 key 的 prefix 。默认为 ws_

class werobot.session.saekvstorage.SaeKVDBStorage(prefix=’ws_‘)

SaeKVDBStorage 使用SAE 的 KVDB 来保存你的session

import werobot
from werobot.session.saekvstorage import SaeKVDBStorage
session_storage = SaeKVDBStorage()
robot = werobot.WeRoBot(token="token", enable_session=True,
                        session_storage=session_storage)

需要先在后台开启 KVDB 支持

• 参数

  prefix – KVDB 中 Session 数据 key 的 prefix 。默认为 ws_

class werobot.session.mysqlstorage.MySQLStorage(conn)

MySQLStorage 会把你的 Session 数据储存在 MySQL 中

import MySQLdb # 使用 mysqlclient
import werobot
from werobot.session.mysqlstorage import MySQLStorage
conn = MySQLdb.connect(user='', db='', passwd='', host='')
session_storage = MySQLStorage(conn)
robot = werobot.WeRoBot(token="token", enable_session=True,
                        session_storage=session_storage)

或者

import pymysql # 使用 pymysql
import werobot
from werobot.session.mysqlstorage import MySQLStorage
session_storage = MySQLStorage(
conn=pymysql.connect(
    user='喵',
    password='喵喵',
    db='werobot',
    host='127.0.0.1',
    charset='utf8'
))
robot = werobot.WeRoBot(token="token", enable_session=True,
                        session_storage=session_storage)

你需要安装一个 MySQL Client 才能使用 MySQLStorage，比如 pymysql，mysqlclient 。

理论上符合 PEP-249 的库都可以使用， 测试时使用的是 pymysql。

• 参数

  conn –

  PEP-249 定义的 Connection 对象

class werobot.session.postgresqlstorage.PostgreSQLStorage(conn)

PostgreSQLStorage 会把你的 Session 数据储存在 PostgreSQL 中

import psycopg2  # pip install psycopg2-binary
import werobot
from werobot.session.postgresqlstorage import PostgreSQLStorage
conn = psycopg2.connect(host='127.0.0.1', port='5432', dbname='werobot', user='nya', password='nyanya')
session_storage = PostgreSQLStorage(conn)
robot = werobot.WeRoBot(token="token", enable_session=True,
                        session_storage=session_storage)

你需要安装一个 PostgreSQL Client 才能使用 PostgreSQLStorage，比如 psycopg2。

理论上符合 PEP-249 的库都可以使用， 测试时使用的是 psycopg2。

• 参数

  conn –

  PEP-249 定义的 Connection 对象

log

werobot.logger.enable_pretty_logging(logger, level=’info’)

按照配置开启 log 的格式化优化。

• 参数

  • logger – 配置的 logger 对象

  • level – 要为 logger 设置的等级