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

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) 消息添加一个 handler 方法的装饰器。

location(f)

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

location_event(f)

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

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

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

scancode_push(f)

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

scancode_waitmsg(f)

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

subscribe(f)

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

text(f)

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

unknown(f)

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

unknown_event(f)

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

unsubscribe(f)

为被取消关注 (unsubscribe) 事件添加一个 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_

log

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

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

参数:
  • logger – 配置的 logger 对象
  • level – 要为 logger 设置的等级