Squashed commit of the following:

commit ccfab5d
Author: Youfou <[email protected]>
Date:   Mon Mar 20 00:57:03 2017 +0800

    add back `except_self` for `Bot.register()`

commit 0eb8725
Merge: e1b5735 99e4cc9
Author: Youfou <[email protected]>
Date:   Sun Mar 19 23:14:42 2017 +0800

    Merge branch 'develop' of https://github.com/youfou/wxpy into develop

commit e1b5735
Author: Youfou <[email protected]>
Date:   Sun Mar 19 17:31:18 2017 +0800

    solve conflict

commit 99e4cc9
Author: Youfou <[email protected]>
Date:   Sun Mar 19 17:31:18 2017 +0800

    solve conflict

commit d503e69
Merge: 396c7a8 5e514fb
Author: Youfou <[email protected]>
Date:   Sun Mar 19 17:29:41 2017 +0800

    Merge branch 'develop' of https://github.com/youfou/wxpy into develop

    # Conflicts:
    #	docs/faq.rst

commit 396c7a8
Author: Youfou <[email protected]>
Date:   Sun Mar 19 17:25:52 2017 +0800

    + FAQ

commit 5e514fb
Author: Youfou <[email protected]>
Date:   Sun Mar 19 17:25:52 2017 +0800

    + FAQ

commit 261e765
Merge: 2b48811 7ed3c2f
Author: Youfou <[email protected]>
Date:   Sun Mar 19 16:13:53 2017 +0800

    Merge branch 'develop' of https://github.com/youfou/wxpy into develop

commit 2b48811
Author: Youfou <[email protected]>
Date:   Sun Mar 19 16:12:03 2017 +0800

    update requirements & docs

commit 7ed3c2f
Author: Youfou <[email protected]>
Date:   Sun Mar 19 16:12:03 2017 +0800

    update requirements & docs

commit 431faae
Author: Youfou <[email protected]>
Date:   Sun Mar 19 02:30:19 2017 +0800

     + Chat.get_avatar() & Member.remove()

commit 5a9a98a
Author: Youfou <[email protected]>
Date:   Sun Mar 19 00:39:53 2017 +0800

    no need to `bot.start()` now.

    Bot will be started automatically once logged in;
    use embed() instead to block the main thread.

commit 1440f50
Author: Youfou <[email protected]>
Date:   Sat Mar 18 16:25:17 2017 +0800

    update from master branch, and update __version__

commit 3b7f3d6
Merge: a413e21 6bfdbfd
Author: Youfou <[email protected]>
Date:   Sat Mar 18 16:24:19 2017 +0800

    Merge branch 'master' into develop

commit a413e21
Author: Youfou <[email protected]>
Date:   Sat Mar 18 16:23:28 2017 +0800

    Bot.register(senders) => Bot.register(chats)

    相比注册消息的发送者，注册消息所在的聊天对象，更为直观和方便。

README.rst

@@ -1,7 +1,7 @@
 wxpy: 用 Python 玩微信
 ==============================
 
-微信机器人 / 优雅的微信个人号API，基于 `itchat <https://github.com/littlecodersh/itchat>`_，全面优化接口，更有 Python 范儿。
+微信机器人 / 优雅的微信个人号API，基于 itchat，全面优化接口，更有 Python 范儿。
 
 
 用来干啥
@@ -65,8 +65,8 @@ wxpy: 用 Python 玩微信
     def reply_my_friend(msg):
         return 'received: {} ({})'.format(msg.text, msg.type)
 
-    # 开始监听和自动处理消息
-    bot.start()
+    # 堵塞线程，并进入 Python 命令行
+    embed()
 
 
 模块特色

docs/console.rst

@@ -19,14 +19,17 @@
 
     from wxpy import *
     bot = Bot()
-    embed() # 开始探索调试
+    embed() # 进入 Python 命令行
 
+    # 输入对象名称并回车
     >>> bot
     # Out[1]: <Bot: 游否>
     >>> bot.friends()
     # Out[2]: [<Friend: 路人甲>, <Friend: 路人乙>, <Friend: 路人丙>]
 
+
 ..  autofunction:: embed
+    :noindex:
 
 
 使用 `wxpy` 命令
@@ -99,3 +102,4 @@
 在此基础上，指定使用 bpython::
 
     wxpy bot1 bot2 -c -s bpython
+

docs/faq.rst

@@ -0,0 +1,65 @@
+常见问题解答 (FAQ)
+==============================
+
+..  module:: wxpy
+
+..  hint::
+
+    这里罗列了一些常见的问题，在提出新的问题前，请先看完本文。
+
+
+每次登陆都要扫二维码？
+--------------------------------
+
+可以启用登陆状态缓存功能，具体请见 :any:`Bot` 中的 `cache_path` 参数说明。
+
+
+能在纯命令行环境中使用吗？
+--------------------------------
+
+wxpy 不依赖于图形界面，因此完全兼容各种纯命令行的服务器。
+
+只有一点需要注意，在纯命令行环境中，登陆时必须使用"终端二维码"。
+
+具体请见 :any:`Bot` 中的 `console_qr` 参数说明。
+
+
+能不能抢红包，看朋友圈…？
+--------------------------------
+
+wxpy 使用了 Web 微信的通讯协议，因此仅能覆盖 Web 微信的所具备的功能。
+
+所以以下功能 **目前均不在支持范围内**
+
+* 支付相关 - 红包、转账、收款 等都不行
+* 在群聊中@他人 - 没错，Web 微信中被@后也不会被提醒
+* 发送名片 - 但可以通过 :any:`send_raw_msg()` 转发
+* 发送分享链接 - 并且无法转发
+* 发送语音消息
+* 朋友圈相关
+
+
+Python 2.x 还是 3.x?
+--------------------------------
+
+因为投入精力所限，现阶段会聚焦在 Python 3.x 版本的开发上，短期内不考虑兼容 2.x。
+
+欢迎其他热心同学参与贡献来支持 2.x。
+
+
+会不会被封号?
+--------------------------------
+
+目前来看并不会因为使用 wxpy 等类似的工具/模块导致封号。
+
+但是，如果你使用微信来骚扰他人、破坏环境，甚至违法犯法的话，那么不管用什么方式使用微信都会导致封号。
+
+wxpy 的初衷是帮助人们利用微信来使生活和工作更轻松。
+
+..  note::
+
+    请每位使用者：
+
+    * 维护良好的交流环境
+    * 永远不骚扰他人
+    * 绝不触犯法律

docs/index.rst

@@ -7,11 +7,7 @@
 wxpy: 用 Python 玩微信
 ==============================
 
-微信机器人 / 优雅的微信个人号API，基于 |itchat|，全面优化接口，更有 Python 范儿。
-
-..  |itchat| raw:: html
-
-    <a href="https://github.com/littlecodersh/itchat" target="_blank">itchat</a>
+微信机器人 / 优雅的微信个人号API，基于 itchat，全面优化接口，更有 Python 范儿。
 
 
 用来干啥
@@ -75,6 +71,7 @@ wxpy: 用 Python 玩微信
     console
     utils
     itchat
+    faq
 
 
 项目主页

docs/logging_with_wechat.rst

@@ -3,9 +3,7 @@
 
 ..  module:: wxpy
 
-你是否曾守着电脑不肯走开，生怕错过一条重要的警告日志？或者当你外出时，心里挂念着电脑上的程序运行得如何？
-
-现在，我们可以利用微信强大的通知能力，在微信上接收程序的日志。
+通过利用微信强大的通知能力，我们可以把程序中的警告/日志发到自己的微信上。
 
 wxpy 提供以下两种方式来实现这个需求。
 

docs/messages.rst

@@ -5,8 +5,8 @@
 
 每当机器人接收到消息时，会自动执行以下两个步骤
 
-1. 将消息保存到 `Bot.messages` 中
-2. 查找消息预先注册的函数，并执行(若有注册)
+1. 将消息保存到 :class:`Bot.messages <Messages>` 中
+2. 查找消息预先注册的函数，并执行(若有匹配的函数)
 
 消息对象
 ----------------
@@ -63,37 +63,37 @@
 
     ..  method:: get_file(save_path=None)
 
-        :param save_path: 文件的保存路径，可与 :any:`file_name` 配合使用。若为 `None`，将直接返回字节数据
+        :param save_path: 文件的保存路径，若为 `None`，将直接返回字节数据
 
-        下载文件(包括图片、视频等)。
+        下载文件(包括图片、视频等)。可与 :any:`file_name` 配合使用。
 
     ..  attribute:: file_name
 
         文件名 (图片、视频等带有文件的消息)
 
     ..  method:: reply(...)
 
-        等同于 :meth:`Message.sender.send(...) <Chat.send>`
+        等同于 :meth:`Message.chat.send(...) <Chat.send>`
 
     ..  method:: reply_image(...)
 
-        等同于 :meth:`Message.sender.send_image(...) <Chat.send_image>`
+        等同于 :meth:`Message.chat.send_image(...) <Chat.send_image>`
 
     ..  method:: reply_file(...)
 
-        等同于 :meth:`Message.sender.send_file(...) <Chat.send_file>`
+        等同于 :meth:`Message.chat.send_file(...) <Chat.send_file>`
 
     ..  method:: reply_video(...)
 
-        等同于 :meth:`Message.sender.send_video(...) <Chat.send_video>`
+        等同于 :meth:`Message.chat.send_video(...) <Chat.send_video>`
 
     ..  method:: reply_msg(...)
 
-        等同于 :meth:`Message.sender.send_msg(...) <Chat.send_msg>`
+        等同于 :meth:`Message.chat.send_msg(...) <Chat.send_msg>`
 
     ..  method:: reply_raw_msg(...)
 
-        等同于 :meth:`Message.sender.send_raw_msg(...) <Chat.send_raw_msg>`
+        等同于 :meth:`Message.chat.send_raw_msg(...) <Chat.send_raw_msg>`
 
     ..  attribute:: img_height
 
@@ -133,31 +133,66 @@
 
 可通过 **预先注册** 的方式，实现消息的自动处理。
 
-..  hint:: **预先注册**: 预先将来自特定聊天对象的特定类型的消息，注册到相应的处理函数。
 
-消息注册
+"预先注册" 是指
+    预先将特定聊天对象的特定类型消息，注册到对应的处理函数，以实现自动回复等功能。
+
+
+注册消息
 ^^^^^^^^^^^^^^
 
-将 :meth:`以下方法 <Bot.register>` 作为函数的装饰器，即可完成注册。
+..  hint::
 
-当接收到符合条件的消息时，会自动执行被注册的函数，并以参数的形式传入 :class:`消息对象 <Message>`。
+    | 当接收到符合条件的消息时，会自动执行被注册的函数。
+    | 同时 :class:`消息对象 <Message>` 将作为唯一参数传入该函数。
 
-..  automethod:: Bot.register
+将 :meth:`Bot.register` 作为函数的装饰器，即可注册生效。
+
+::
+
+    # 打印所有群聊对象中的文本消息
+    @bot.register(Group, TEXT)
+    def print_group_msg(msg):
+        print(msg)
 
-..  note:: 每条消息仅匹配一个预先注册函数，且优先匹配后注册的函数！
+
+..  important:: 每条消息仅匹配一个预先注册函数，且优先匹配后注册的函数！
+
+..  automethod:: Bot.register
 
 ..  tip::
 
     1.  `chats` 和 `msg_types` 参数可以接收一个列表或干脆一个单项。按需使用，方便灵活。
     2.  `chats` 参数既可以是聊天对象实例，也可以是对象类。当为类时，表示匹配该类型的所有聊天对象。
     3. 在被注册函数中，可以直接通过 `return <回复内容>` 的方式来回复消息，等同于调用 `msg.reply(<回复内容>)`。
 
-开始监听
+
+开始运行
 ^^^^^^^^^^^^^^
 
-..  note:: 在完成消息注册后，务必通过以下方法开始监听和处理消息。
+..  note::
+
+    | 根据 Python 的特性，在完成以上注册操作后，若没有其他操作，程序会因主线程结束而退出。
+      **因此必须堵塞线程以保持监听状态。**
+    | wxpy 的 :any:`embed()` 可在堵塞线程的同时，进入 Python 命令行，方便调试，一举两得。
+
+
+::
+
+    from wxpy import *
+
+    bot = Bot()
+
+    @bot.register()
+    def print_messages(msg):
+        print(msg)
+
+    # 堵塞线程，并进入 Python 命令行
+    embed()
+
+
+..  autofunction:: embed
 
-..  automethod:: Bot.start
 
 示例代码
 ^^^^^^^^^^^^^
@@ -187,7 +222,7 @@
     @bot.register([my_friend, Group], TEXT)
     def auto_reply(msg):
         # 如果是群聊，但没有被 @，则不回复
-        if not (isinstance(msg.sender, Group) and not msg.is_at):
+        if not (isinstance(msg.chat, Group) and not msg.is_at):
             # 回复消息内容和类型
             return '收到消息: {} ({})'.format(msg.text, msg.type)
 
@@ -199,9 +234,9 @@
         return
 
 
-开始监听和自动处理::
+堵塞线程，并进入 Python 命令行::
 
-    bot.start()
+    embed()
 
 
 动态开关注册配置
@@ -212,30 +247,30 @@
 
 查看当前的注册配置情况::
 
-    bot.message_configs
+    bot.registered
     # [<MessageConfig: just_print (Async, Enabled)>,
     #  <MessageConfig: auto_reply (Async, Enabled)>,
     #  <MessageConfig: ignore (Async, Enabled)>]
 
 关闭所有注册配置::
 
-    bot.message_configs.disable()
+    bot.registered.disable()
 
 重新开启 `just_print` 函数::
 
-    bot.message_configs.enable(just_print)
+    bot.registered.enable(just_print)
 
 查看当前开启的注册配置::
 
-    bot.message_configs.enabled
+    bot.registered.enabled
     # [<MessageConfig: just_print (Async, Enabled)>]
 
 
 
 消息记录
 ----------------
 
-可通过访问 `bot.messages` 来查看自 `bot.start()` 后收到的消息列表。
+可通过访问 `bot.messages` 来查看历史消息列表。
 
 消息列表为 :class:`Messages` 对象，具有搜索功能。
 

requirements.txt

@@ -1,2 +1,2 @@
-itchat>=1.2.30
+itchat>=1.2.32
 requests

setup.py

@@ -25,7 +25,7 @@
             ]
         },
     install_requires=[
-        'itchat>=1.2.30',
+        'itchat>=1.2.32',
         'requests',
     ],
     url='https://github.com/youfou/wxpy',

wxpy/__init__.py

@@ -35,8 +35,8 @@ def print_others(msg):
     def reply_my_friend(msg):
        return 'received: {} ({})'.format(msg.text, msg.type)
 
-    # 开始监听和自动处理消息
-    bot.start()
+    # 堵塞线程，并进入 Python 命令行
+    embed()
 
 
 """
@@ -52,7 +52,7 @@ def reply_my_friend(msg):
 from .utils import dont_raise_response_error, embed, ensure_one, mutual_friends
 
 __title__ = 'wxpy'
-__version__ = '0.2.6'
+__version__ = '0.3.0'
 __author__ = 'Youfou'
 __license__ = 'MIT'
 __copyright__ = '2017, Youfou'