WeRoBot: a robot framework for wechat
Project description
WeRoBot
=======
WeRoBot是一个微信机器人框架,采用MIT协议发布。
Hello World
------------
最简单的Hello World, 会给收到的每一条信息回复 `Hello World` ::
import werobot
robot = werobot.WeRoBot(token='tokenhere')
@robot.handler
def echo(message):
return 'Hello World!'
robot.run()
Handlers
-----------
WeRoBot会将合法的请求发送给handlers依次执行。
如果某一个Handler返回了非空值,WeRoBot就会根据这个值创建回复,后面的handlers将不会被执行。
你可以通过两种方式添加handler ::
import werobot
robot = werobot.WeRoBot(token='tokenhere')
# 通过修饰符添加handler
@robot.handler
def echo(message):
return 'Hello World!'
# 通过`add_handler`添加handler
def echo(message):
return 'Hello World!'
robot.add_handler(echo)
Messages
---------
目前WeRoBot共有五种Message: `TextMessage` , `ImageMessage` , `LocationMessage` , `EventMessage` 和 `UnknownMessage` 。他们都继承自 WeChatMessage 。
TextMessage
~~~~~~~~~~~~
TextMessage的属性:
======== ===================================
name value
======== ===================================
type 'text' 或 'hello' [1]_
target 信息的目标用户。通常是机器人用户。
source 信息的来源用户。通常是发送信息的用户。
time 信息发送的时间,一个UNIX时间戳。
content 信息的内容
======== ===================================
ImageMessage
~~~~~~~~~~~~~
ImageMessage的属性:
======= ==================================
name value
======= ==================================
type 'image'
target 信息的目标用户。通常是机器人用户。
source 信息的来源用户。通常是发送信息的用户。
time 信息发送的时间,一个UNIX时间戳。
img 图片网址。你可以从这个网址下到图片
======= ==================================
LocationMessage
~~~~~~~~~~~~~~~~
LocationMessage的属性:
========= ===================================
name value
========= ===================================
type 'location'
target 信息的目标用户。通常是机器人用户。
source 信息的来源用户。通常是发送信息的用户。
time 信息发送的时间,一个UNIX时间戳。
location 一个元组。(纬度, 经度)
scale 地图缩放大小
label 地理位置信息
========= ===================================
EventMessage
~~~~~~~~~~~~~~
EventMessage的属性:
========= ===================================
name value
========= ===================================
type 'enter' 或 'location' [2]_
target 信息的目标用户。通常是机器人用户。
source 信息的来源用户。通常是发送信息的用户。
time 信息发送的时间,一个UNIX时间戳。
location 一个元组。(纬度, 经度)。 type 为 'location' 时存在。
precision 地理位置精度。 type 为 'location' 时存在。
========= ===================================
UnknownMessage
~~~~~~~~~~~~~~~
UnknownMessage的属性:
========= =====================================
name value
========= =====================================
type 'unknown'
content 请求的正文部分。标准的XML格式。
========= =====================================
.. note:: 如果你不为 WeRoBot 贡献代码,你完全可以无视掉 UnknownMessage 。在正常的使用中,WeRoBot应该不会收到 `UnknownMessage` ——除非 WeRoBot 停止开发。
.. [1] 当有用户关注你的时候,你会收到一条来自该用户的、内容为 `Hello2BizUser` 的 TextMessage 。WeRoBot 会将其的type设为 `hello` 。
.. [2] 有两种时间推送: 如果是用户进入会话, type 为 `enter` ; 如果是地理位置, type 为 `location` 。
类型过滤
--------------
WeRoBot 一共有5类 Message , 6种 type 。显然,一个 handler 不可能把这6种 type 都支持全。
幸运的是, WeRoBot 可以帮你过滤收到的消息。
只想处理被新用户关注的消息?::
import werobot
robot = werobot.WeRoBot(token='tokenhere')
@robot.hello
def hello(message):
return 'Hello My Friend!'
robot.run()
或者,你的 handler 只能处理文本? ::
import werobot
robot = werobot.WeRoBot(token='tokenhere')
@robot.text
def echo(message):
return message.content
robot.run()
你也可以使用 `robot.image` 修饰符来只接受图像信息; `robot.location` 修饰符来只接受位置信息;`robot.enter`修饰符来只接受进入会话信息。。
.. note:: `robot.location` 修饰符会让你的 handler 接受到两类消息——位置信息和事件推送中的地理位置。
当然,还有 `robot.unknown` —— 如果你想收到未知属性的信息的话。
额,这个 handler 想处理文本信息和地理位置信息? ::
import werobot
robot = werobot.WeRoBot(token='tokenhere')
@robot.text
@robot.location
def handler(message):
# Do what you love to do
pass
robot.run()
当然,你也可以用 `add_handler` 函数添加handler,就像这样::
import werobot
robot = werobot.WeRoBot(token='tokenhere')
def handler(message):
# Do what you love to do
pass
robot.add_handler(handler, types=['text', 'location'])
robot.run()
.. note:: 通过 `robot.handler` 添加的 handler 将收到所有信息。
Replies
--------------
目前WeRoBot共有三种Reply: `TextReply` , `ArticlesReply` 和 `MusicReply` 。他们都继承自 `WeChatReply` 。
TextReply
~~~~~~~~~~~
`TextReply` 是简单的文本消息,构造函数的参数如下:
========= ===================================
name value
========= ===================================
content 信息正文。
target 信息的目标用户。通常是机器人用户。
source 信息的来源用户。通常是发送信息的用户。
time 信息发送的时间,一个UNIX时间戳。默认情况下会使用当前时间。
flag 如果是True, WeRoBot会对这条消息进行星标。你可以在公众平台后台看到所有的星标消息。
========= ===================================
你可以在构建Reply时传入一个合法的 `Message` 对象来自动生成 `source` 和 `target` ::
reply = TextReply(message=message, content='Hello!')
.. note:: 如果你的handler返回了一个字符串, WeRoBot会自动将其转化为一个文本消息。
ArticlesReply
~~~~~~~~~~~~~~~
`ArticlesReply` 是图文消息,构造函数的参数如下:
========= ===================================
name value
========= ===================================
content 信息正文。**可为空**。
target 信息的目标用户。通常是机器人用户。
source 信息的来源用户。通常是发送信息的用户。
time 信息发送的时间,一个UNIX时间戳。默认情况下会使用当前时间。
flag 如果是True, WeRoBot会对这条消息进行星标。你可以在公众平台后台看到所有的星标消息。
========= ===================================
你需要给 `ArticlesReply` 添加 `Article` 来增加图文。
`Article` 类位于 `werobot.reply.Article` 。
`Article` 的构造函数的参数如下:
============ ===================================
name value
============ ===================================
title 标题
description 描述
img 图片链接
url 点击图片后跳转链接
============ ===================================
注意,微信公众平台对图片链接有特殊的要求,详情可以在
`消息接口使用指南 <http://mp.weixin.qq.com/cgi-bin/readtemplate?t=wxm-callbackapi-doc&lang=zh_CN>`_ 里看到。
在构造完一个 `Article` 后, 你需要通过 `ArticlesReply` 的 `add_article` 参数把它添加进去。就像这样: ::
from werobot.reply import ArticlesReply, Article
reply = ArticlesReply(message=message)
article = Article(
title="WeRoBot",
desription="WeRoBot是一个微信机器人框架",
img="https://github.com/apple-touch-icon-144.png",
url="https://github.com/whtsky/WeRoBot"
)
reply.add_article(article)
.. note:: 每个ArticlesReply中 **最多添加10个Article** 。
你也可以让你的 handler 返回一个列表, 里面每一个元素都是一个长度为四的列表,
WeRoBot 会将其自动转为 ArticlesReply 。就像这样: ::
import werobot
robot = werobot.WeRoBot(token='tokenhere')
@robot.text
def articles(message):
return [
[
"title",
"description",
"img",
"url"
],
[
"whtsky",
"I wrote WeRoBot",
"https://secure.gravatar.com/avatar/0024710771815ef9b74881ab21ba4173?s=420",
"http://whouz.com/"
]
]
robot.run()
MusicReply
~~~~~~~~~~~
`MusicReply` 是音乐消息,构造函数的参数如下:
========= ===================================
name value
========= ===================================
target 信息的目标用户。通常是机器人用户。
source 信息的来源用户。通常是发送信息的用户。
time 信息发送的时间,一个UNIX时间戳。默认情况下会使用当前时间。
title 标题
description 描述
url 音乐链接
hq_url 高质量音乐链接,WIFI环境优先使用该链接播放音乐。可为空 [3]_
flag 如果是True, WeRoBot会对这条消息进行星标。你可以在公众平台后台看到所有的星标消息。
========= ===================================
你也可以让你的 handler 返回一个长度为三或四的列表, [3]_
WeRoBot 会将其自动转为 MusicReply 。就像这样: ::
import werobot
robot = werobot.WeRoBot(token='tokenhere')
@robot.text
def music(message):
return [
"title",
"description",
"music_url",
"hq_music_url"
]
@robot.text
def music2(message):
return [
"微信你不懂爱",
"龚琳娜最新力作",
"http://weixin.com/budongai.mp3",
]
robot.run()
.. [3] 如果你省略了高质量音乐链接的地址, WeRoBot 会自动将音乐链接的地址用于高质量音乐链接。
不知道该用什么Token?
----------------------
WeRoBot帮你准备了一个Token生成器: ::
import werobot.utils
print(werobot.utils.generate_token())
贡献代码
-----------
WeRoBot欢迎每个人贡献代码。
在提交Pull Request前请注意,我有pep8强迫症。。请确定自己的代码通过flake8检测。
另外,不能自动merge的和不能通过测试的代码不会被接受。你可以在安装nose(`pip install nose`)之后运行`nosetests`来进行测试。
捐助
--------
Buy me a cup of coffee :)
Via Alipay(支付宝) ::
"whtsky#gmail.com".replace("#", "@")
Changelog
-----------
Version 0.3.0
~~~~~~~~~~~~~~~~
Add new messages and replies support for WeChat 4.5
=======
WeRoBot是一个微信机器人框架,采用MIT协议发布。
Hello World
------------
最简单的Hello World, 会给收到的每一条信息回复 `Hello World` ::
import werobot
robot = werobot.WeRoBot(token='tokenhere')
@robot.handler
def echo(message):
return 'Hello World!'
robot.run()
Handlers
-----------
WeRoBot会将合法的请求发送给handlers依次执行。
如果某一个Handler返回了非空值,WeRoBot就会根据这个值创建回复,后面的handlers将不会被执行。
你可以通过两种方式添加handler ::
import werobot
robot = werobot.WeRoBot(token='tokenhere')
# 通过修饰符添加handler
@robot.handler
def echo(message):
return 'Hello World!'
# 通过`add_handler`添加handler
def echo(message):
return 'Hello World!'
robot.add_handler(echo)
Messages
---------
目前WeRoBot共有五种Message: `TextMessage` , `ImageMessage` , `LocationMessage` , `EventMessage` 和 `UnknownMessage` 。他们都继承自 WeChatMessage 。
TextMessage
~~~~~~~~~~~~
TextMessage的属性:
======== ===================================
name value
======== ===================================
type 'text' 或 'hello' [1]_
target 信息的目标用户。通常是机器人用户。
source 信息的来源用户。通常是发送信息的用户。
time 信息发送的时间,一个UNIX时间戳。
content 信息的内容
======== ===================================
ImageMessage
~~~~~~~~~~~~~
ImageMessage的属性:
======= ==================================
name value
======= ==================================
type 'image'
target 信息的目标用户。通常是机器人用户。
source 信息的来源用户。通常是发送信息的用户。
time 信息发送的时间,一个UNIX时间戳。
img 图片网址。你可以从这个网址下到图片
======= ==================================
LocationMessage
~~~~~~~~~~~~~~~~
LocationMessage的属性:
========= ===================================
name value
========= ===================================
type 'location'
target 信息的目标用户。通常是机器人用户。
source 信息的来源用户。通常是发送信息的用户。
time 信息发送的时间,一个UNIX时间戳。
location 一个元组。(纬度, 经度)
scale 地图缩放大小
label 地理位置信息
========= ===================================
EventMessage
~~~~~~~~~~~~~~
EventMessage的属性:
========= ===================================
name value
========= ===================================
type 'enter' 或 'location' [2]_
target 信息的目标用户。通常是机器人用户。
source 信息的来源用户。通常是发送信息的用户。
time 信息发送的时间,一个UNIX时间戳。
location 一个元组。(纬度, 经度)。 type 为 'location' 时存在。
precision 地理位置精度。 type 为 'location' 时存在。
========= ===================================
UnknownMessage
~~~~~~~~~~~~~~~
UnknownMessage的属性:
========= =====================================
name value
========= =====================================
type 'unknown'
content 请求的正文部分。标准的XML格式。
========= =====================================
.. note:: 如果你不为 WeRoBot 贡献代码,你完全可以无视掉 UnknownMessage 。在正常的使用中,WeRoBot应该不会收到 `UnknownMessage` ——除非 WeRoBot 停止开发。
.. [1] 当有用户关注你的时候,你会收到一条来自该用户的、内容为 `Hello2BizUser` 的 TextMessage 。WeRoBot 会将其的type设为 `hello` 。
.. [2] 有两种时间推送: 如果是用户进入会话, type 为 `enter` ; 如果是地理位置, type 为 `location` 。
类型过滤
--------------
WeRoBot 一共有5类 Message , 6种 type 。显然,一个 handler 不可能把这6种 type 都支持全。
幸运的是, WeRoBot 可以帮你过滤收到的消息。
只想处理被新用户关注的消息?::
import werobot
robot = werobot.WeRoBot(token='tokenhere')
@robot.hello
def hello(message):
return 'Hello My Friend!'
robot.run()
或者,你的 handler 只能处理文本? ::
import werobot
robot = werobot.WeRoBot(token='tokenhere')
@robot.text
def echo(message):
return message.content
robot.run()
你也可以使用 `robot.image` 修饰符来只接受图像信息; `robot.location` 修饰符来只接受位置信息;`robot.enter`修饰符来只接受进入会话信息。。
.. note:: `robot.location` 修饰符会让你的 handler 接受到两类消息——位置信息和事件推送中的地理位置。
当然,还有 `robot.unknown` —— 如果你想收到未知属性的信息的话。
额,这个 handler 想处理文本信息和地理位置信息? ::
import werobot
robot = werobot.WeRoBot(token='tokenhere')
@robot.text
@robot.location
def handler(message):
# Do what you love to do
pass
robot.run()
当然,你也可以用 `add_handler` 函数添加handler,就像这样::
import werobot
robot = werobot.WeRoBot(token='tokenhere')
def handler(message):
# Do what you love to do
pass
robot.add_handler(handler, types=['text', 'location'])
robot.run()
.. note:: 通过 `robot.handler` 添加的 handler 将收到所有信息。
Replies
--------------
目前WeRoBot共有三种Reply: `TextReply` , `ArticlesReply` 和 `MusicReply` 。他们都继承自 `WeChatReply` 。
TextReply
~~~~~~~~~~~
`TextReply` 是简单的文本消息,构造函数的参数如下:
========= ===================================
name value
========= ===================================
content 信息正文。
target 信息的目标用户。通常是机器人用户。
source 信息的来源用户。通常是发送信息的用户。
time 信息发送的时间,一个UNIX时间戳。默认情况下会使用当前时间。
flag 如果是True, WeRoBot会对这条消息进行星标。你可以在公众平台后台看到所有的星标消息。
========= ===================================
你可以在构建Reply时传入一个合法的 `Message` 对象来自动生成 `source` 和 `target` ::
reply = TextReply(message=message, content='Hello!')
.. note:: 如果你的handler返回了一个字符串, WeRoBot会自动将其转化为一个文本消息。
ArticlesReply
~~~~~~~~~~~~~~~
`ArticlesReply` 是图文消息,构造函数的参数如下:
========= ===================================
name value
========= ===================================
content 信息正文。**可为空**。
target 信息的目标用户。通常是机器人用户。
source 信息的来源用户。通常是发送信息的用户。
time 信息发送的时间,一个UNIX时间戳。默认情况下会使用当前时间。
flag 如果是True, WeRoBot会对这条消息进行星标。你可以在公众平台后台看到所有的星标消息。
========= ===================================
你需要给 `ArticlesReply` 添加 `Article` 来增加图文。
`Article` 类位于 `werobot.reply.Article` 。
`Article` 的构造函数的参数如下:
============ ===================================
name value
============ ===================================
title 标题
description 描述
img 图片链接
url 点击图片后跳转链接
============ ===================================
注意,微信公众平台对图片链接有特殊的要求,详情可以在
`消息接口使用指南 <http://mp.weixin.qq.com/cgi-bin/readtemplate?t=wxm-callbackapi-doc&lang=zh_CN>`_ 里看到。
在构造完一个 `Article` 后, 你需要通过 `ArticlesReply` 的 `add_article` 参数把它添加进去。就像这样: ::
from werobot.reply import ArticlesReply, Article
reply = ArticlesReply(message=message)
article = Article(
title="WeRoBot",
desription="WeRoBot是一个微信机器人框架",
img="https://github.com/apple-touch-icon-144.png",
url="https://github.com/whtsky/WeRoBot"
)
reply.add_article(article)
.. note:: 每个ArticlesReply中 **最多添加10个Article** 。
你也可以让你的 handler 返回一个列表, 里面每一个元素都是一个长度为四的列表,
WeRoBot 会将其自动转为 ArticlesReply 。就像这样: ::
import werobot
robot = werobot.WeRoBot(token='tokenhere')
@robot.text
def articles(message):
return [
[
"title",
"description",
"img",
"url"
],
[
"whtsky",
"I wrote WeRoBot",
"https://secure.gravatar.com/avatar/0024710771815ef9b74881ab21ba4173?s=420",
"http://whouz.com/"
]
]
robot.run()
MusicReply
~~~~~~~~~~~
`MusicReply` 是音乐消息,构造函数的参数如下:
========= ===================================
name value
========= ===================================
target 信息的目标用户。通常是机器人用户。
source 信息的来源用户。通常是发送信息的用户。
time 信息发送的时间,一个UNIX时间戳。默认情况下会使用当前时间。
title 标题
description 描述
url 音乐链接
hq_url 高质量音乐链接,WIFI环境优先使用该链接播放音乐。可为空 [3]_
flag 如果是True, WeRoBot会对这条消息进行星标。你可以在公众平台后台看到所有的星标消息。
========= ===================================
你也可以让你的 handler 返回一个长度为三或四的列表, [3]_
WeRoBot 会将其自动转为 MusicReply 。就像这样: ::
import werobot
robot = werobot.WeRoBot(token='tokenhere')
@robot.text
def music(message):
return [
"title",
"description",
"music_url",
"hq_music_url"
]
@robot.text
def music2(message):
return [
"微信你不懂爱",
"龚琳娜最新力作",
"http://weixin.com/budongai.mp3",
]
robot.run()
.. [3] 如果你省略了高质量音乐链接的地址, WeRoBot 会自动将音乐链接的地址用于高质量音乐链接。
不知道该用什么Token?
----------------------
WeRoBot帮你准备了一个Token生成器: ::
import werobot.utils
print(werobot.utils.generate_token())
贡献代码
-----------
WeRoBot欢迎每个人贡献代码。
在提交Pull Request前请注意,我有pep8强迫症。。请确定自己的代码通过flake8检测。
另外,不能自动merge的和不能通过测试的代码不会被接受。你可以在安装nose(`pip install nose`)之后运行`nosetests`来进行测试。
捐助
--------
Buy me a cup of coffee :)
Via Alipay(支付宝) ::
"whtsky#gmail.com".replace("#", "@")
Changelog
-----------
Version 0.3.0
~~~~~~~~~~~~~~~~
Add new messages and replies support for WeChat 4.5
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
WeRoBot-0.3.0.tar.gz
(18.7 kB
view details)
Built Distribution
WeRoBot-0.3.0-py2.7.egg
(19.7 kB
view details)
File details
Details for the file WeRoBot-0.3.0.tar.gz
.
File metadata
- Download URL: WeRoBot-0.3.0.tar.gz
- Upload date:
- Size: 18.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 48d5d3ab82bf1295b0ba28f810a39050717a777aa990f1057673b7432e8c66e6 |
|
MD5 | 714504559bf78cda28ce5d157d472fe6 |
|
BLAKE2b-256 | 66bf8842a43baf927d1bcad715d200807575f1d89e047aa1bcfb8644df3369e8 |
File details
Details for the file WeRoBot-0.3.0-py2.7.egg
.
File metadata
- Download URL: WeRoBot-0.3.0-py2.7.egg
- Upload date:
- Size: 19.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | d3243297680c57344a816152c839b51cab3bbc098aa0bed10be90f6100e2184f |
|
MD5 | e149cc5a425c362fb2bc5667433855be |
|
BLAKE2b-256 | 85c93cb2fe6dc71bbd6cc3fadb49457dd6a25ddca28ea5ad8528507d5e05c6c2 |