Code refactor & rename Robot to Bot (keep Robot as alias)

.gitignore

@@ -1,5 +1,6 @@
 .idea
 *.pkl
+_installed_files.txt
 _private
 
 ### Linux template

README.rst

@@ -39,12 +39,12 @@ wxpy: 用 Python 玩微信
     # 导入模块
     from wxpy import *
     # 初始化机器人，扫码登陆
-    robot = Robot()
+    bot = Bot()
 
 找到好友::
 
     # 搜索名称含有 "游否" 的男性深圳好友
-    my_friend = robot.friends().search('游否', sex=MALE, city="深圳")[0]
+    my_friend = bot.friends().search('游否', sex=MALE, city="深圳")[0]
 
 发送消息::
 
@@ -56,17 +56,17 @@ wxpy: 用 Python 玩微信
 自动响应各类消息::
 
     # 打印来自其他好友、群聊和公众号的消息
-    @robot.register()
+    @bot.register()
     def print_others(msg):
         print(msg)
 
     # 回复 my_friend 的消息 (优先匹配后注册的函数!)
-    @robot.register(my_friend)
+    @bot.register(my_friend)
     def reply_my_friend(msg):
         return 'received: {} ({})'.format(msg.text, msg.type)
 
     # 开始监听和自动处理消息
-    robot.start()
+    bot.start()
 
 
 模块特色

docs/Makefile

@@ -1,7 +1,7 @@
 # Minimal makefile for Sphinx documentation
 #
 
-# You can set these variables from the command line.
+# You can set these variables from the shell_entry line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = wxpy

docs/api/robot.rst → docs/api/bot.rst

@@ -3,7 +3,7 @@
 
 ..  module:: wxpy
 
-机器人(:class:`Robot`)对象可被理解为一个抽象的 Web 微信客户端。
+机器人 :class:`Bot` 对象可被理解为一个 Web 微信客户端。
 
 
 ..  note::
@@ -17,34 +17,34 @@
 
 ..  note::
 
-    :class:`Robot` 在初始化时便会执行登陆操作，需要手机扫描登陆。
+    :class:`Bot` 在初始化时便会执行登陆操作，需要手机扫描登陆。
 
-..  autoclass:: Robot
+..  autoclass:: Bot
 
 
 获取聊天对象
 ----------------
 
-..  automethod:: Robot.chats
+..  automethod:: Bot.chats
 
-..  automethod:: Robot.friends
+..  automethod:: Bot.friends
 
-..  automethod:: Robot.groups
+..  automethod:: Bot.groups
 
-..  automethod:: Robot.mps
+..  automethod:: Bot.mps
 
 
 加好友和建群
 ----------------
 
-..  automethod:: Robot.add_friend
+..  automethod:: Bot.add_friend
 
-..  automethod:: Robot.accept_friend
+..  automethod:: Bot.accept_friend
 
 代码示例: 自动接受好友请求::
 
     # 注册好友请求类消息
-    @robot.register(FRIENDS)
+    @bot.register(FRIENDS)
     # 自动接受验证信息中包含 'wxpy' 的好友请求
     def auto_accept_friends(msg):
         # 判断好友请求中的验证文本
@@ -54,16 +54,16 @@
             # 向新的好友发送消息
             new_friend.send('哈哈，我自动接受了你的好友请求')
 
-..  automethod:: Robot.create_group
+..  automethod:: Bot.create_group
 
 
 获取用户详细信息
 ----------------
 
-..  automethod:: Robot.user_details
+..  automethod:: Bot.user_details
 
 
 登出
 ----------------
 
-..  automethod:: Robot.logout
+..  automethod:: Bot.logout

docs/api/chats.rst

@@ -3,17 +3,17 @@
 
 ..  module:: wxpy
 
-通过机器人对象 :class:`Robot <Robot>` 的
-:meth:`chats() <Robot.chats>`,
-:meth:`friends() <Robot.friends>`，:meth:`groups() <Robot.groups>`,
-:meth:`mps() <Robot.mps>` 方法,
+通过机器人对象 :class:`Bot <Bot>` 的
+:meth:`chats() <Bot.chats>`,
+:meth:`friends() <Bot.friends>`，:meth:`groups() <Bot.groups>`,
+:meth:`mps() <Bot.mps>` 方法,
 可分别获取到当前机器人的 所有聊天对象、好友、群聊，以及公众号列表。
 
 而获得到的聊天对象合集 :class:`Chats` 和 :class:`Groups` 具有一些合集方法，例如：:meth:`Chats.search` 可用于按条件搜索聊天对象::
 
     from wxpy import *
-    robot = Robot()
-    my_friend = robot.friends().search('游否', sex=MALE, city='深圳')[0]
+    bot = Bot()
+    my_friend = bot.friends().search('游否', sex=MALE, city='深圳')[0]
     # <Friend: 游否>
 
 在找到好友(或其他聊天对象)后，还可使用该聊天对象的 :meth:`send <Chat.send>` 系列方法，对其发送消息::
@@ -38,9 +38,9 @@
 ..  autoclass:: Chat
     :members:
 
-    ..  attribute:: robot
+    ..  attribute:: bot
 
-        所属的 :class:`机器人对象 <Robot>`
+        所属的 :class:`机器人对象 <Bot>`
 
     ..  attribute:: user_name
 
@@ -52,7 +52,12 @@
 
     ..  attribute:: nick_name
 
-        该聊天对象的昵称 (好友、群员的名称，或群名称)
+        该聊天对象的昵称 (好友、群员的昵称，或群名称)
+
+    ..  attribute:: name
+
+        | 该聊天对象的友好名称
+        | 具体为: 从 备注名称、昵称(或群名称)，以及群聊显示名称 中按序选择第一个可用的
 
 ..  autoclass:: User
     :members:
@@ -79,7 +84,7 @@
 
     ..  attribute:: signature
 
-        签名
+        个性签名
 
 好友
 -------------------
@@ -114,7 +119,7 @@
 
 在 :class:`Chats` 对象中，除了最常用到的 :meth:`search() <Chats.search>` 外，还有两个特别的方法，:meth:`stats() <Chats.stats>` 与 :meth:`stats_text() <Chats.stats_text>`，可用来统计好友或群成员的性别和地区分布::
 
-    robot.friends().stats_text()
+    bot.friends().stats_text()
     # 游否 共有 100 位微信好友\n\n男性: 67 (67.0%)\n女性: 23 (23.0%) ...
 
 ..  autoclass:: Chats

docs/api/console.rst

@@ -18,12 +18,12 @@
 例如，初始化一个机器人，然后看看它能做些什么::
 
     from wxpy import *
-    robot = Robot()
+    bot = Bot()
     embed() # 开始探索调试
 
-    >>> robot
-    # Out[1]: <Robot: 游否>
-    >>> robot.friends()
+    >>> bot
+    # Out[1]: <Bot: 游否>
+    >>> bot.friends()
     # Out[2]: [<Friend: 路人甲>, <Friend: 路人乙>, <Friend: 路人丙>]
 
 ..  autofunction:: embed
@@ -45,7 +45,7 @@
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
-* robot1 robot2 robot3...
+* bot1 bot2 bot3...
     * 一个或多个需要初始化的机器人对象的名称，以空格分割
     * 默认：不初始化机器人
     * 例子: `r1 r2`
@@ -80,13 +80,13 @@
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
-初始化一个变量名为 `robot` 的机器人::
+初始化一个变量名为 `bot` 的机器人::
 
-    wxpy robot
+    wxpy bot
 
 在上述基础上，使用终端二维码，且单元格宽度为 2::
 
-    wxpy robot -q 2
+    wxpy bot -q 2
 
 分别初始化变量名为 `r1` 和 `r2` 的两个机器人::
 

docs/api/itchat.rst

@@ -19,13 +19,13 @@
 使用 itchat 的原接口
 ------------------------------
 
-只需在 wxpy 的 :class:`Robot` 对象后紧跟 `.core.*` 即可调用 itchat 的原接口。
+只需在 wxpy 的 :class:`Bot` 对象后紧跟 `.core.*` 即可调用 itchat 的原接口。
 
 例如，使用 itchat 的 `search_friends` 接口::
 
     from wxpy import *
-    robot = Robot()
-    found = robot.core.search_friends('游否')
+    bot = Bot()
+    found = bot.core.search_friends('游否')
 
 ..  attention:: 通过 itchat 原接口所获取到的结果为原始数据，可能无法直接传递到 wxpy 的对应方法中。
 
@@ -38,6 +38,6 @@ wxpy 的所有 **聊天对象** 和 **消息对象** 均基于从 itchat 获取
 例如，查看一个 :class:`好友 <Friend>` 对象的原始数据::
 
     from wxpy import *
-    robot = Robot()
-    a_friend = robot.friends()[0]
+    bot = Bot()
+    a_friend = bot.friends()[0]
     print(a_friend.raw)

docs/api/messages.rst

@@ -5,7 +5,7 @@
 
 每当机器人接收到消息时，会自动执行以下两个步骤
 
-1. 将消息保存到 `Robot.messages` 中
+1. 将消息保存到 `Bot.messages` 中
 2. 查找消息预先注册的函数，并执行(若有注册)
 
 消息对象
@@ -48,9 +48,9 @@
 
         消息的文本内容
 
-    ..  attribute:: robot
+    ..  attribute:: bot
 
-        接收消息的 :class:`机器人对象 <Robot>`
+        接收消息的 :class:`机器人对象 <Bot>`
 
     ..  attribute:: type
 
@@ -134,11 +134,11 @@
 消息注册
 ^^^^^^^^^^^^^^
 
-将 :meth:`以下方法 <Robot.register>` 作为函数的装饰器，即可完成注册。
+将 :meth:`以下方法 <Bot.register>` 作为函数的装饰器，即可完成注册。
 
 当接收到符合条件的消息时，会自动执行被注册的函数，并以参数的形式传入 :class:`消息对象 <Message>`。
 
-..  automethod:: Robot.register
+..  automethod:: Bot.register
 
 ..  note:: 每条消息仅匹配一个预先注册函数，且优先匹配后注册的函数！
 
@@ -153,7 +153,7 @@
 
 ..  note:: 在完成消息注册后，务必通过以下方法开始监听和处理消息。
 
-..  automethod:: Robot.start
+..  automethod:: Bot.start
 
 示例代码
 ^^^^^^^^^^^^^
@@ -167,20 +167,20 @@
 初始化机器人，并找到好友和群聊::
 
     from wxpy import *
-    robot = Robot()
-    my_friend = robot.friends().search('游否')[0]
-    boring_group = robot.groups().search('一个无聊的群')[0]
+    bot = Bot()
+    my_friend = bot.friends().search('游否')[0]
+    boring_group = bot.groups().search('一个无聊的群')[0]
 
 打印所有其他消息::
 
-    @robot.register()
+    @bot.register()
     def just_print(msg):
         # 打印消息
         print(msg)
 
 回复好友"游否"和其他群聊中被 @ 的 TEXT 类消息::
 
-    @robot.register([my_friend, Group], TEXT)
+    @bot.register([my_friend, Group], TEXT)
     def auto_reply(msg):
         # 如果是群聊，但没有被 @，则不回复
         if not (isinstance(msg.chat, Group) and not msg.is_at):
@@ -189,15 +189,15 @@
 
 忽略"一个无聊的群"的所有消息::
 
-    @robot.register(boring_group)
+    @bot.register(boring_group)
     def ignore(msg):
         # 啥也不做
         return
 
 
 开始监听和自动处理::
 
-    robot.start()
+    bot.start()
 
 
 动态开关注册配置
@@ -208,21 +208,21 @@
 
 查看当前的注册配置情况::
 
-    robot.message_configs
+    bot.message_configs
     # [<MessageConfig: just_print (Async, Enabled)>,
     #  <MessageConfig: auto_reply (Async, Enabled)>,
     #  <MessageConfig: ignore (Async, Enabled)>]
 
 关闭所有注册配置::
 
-    robot.message_configs.disable()
+    bot.message_configs.disable()
 
 重新开启 `just_print` 函数::
 
-    robot.message_configs.enable(just_print)
+    bot.message_configs.enable(just_print)
 
 查看当前开启的注册配置::
 
-    robot.message_configs.enabled
+    bot.message_configs.enabled
     # [<MessageConfig: just_print (Async, Enabled)>]
 

docs/api/utils.rst

@@ -5,5 +5,8 @@
 
 ..  module:: wxpy
 
-..  automodule:: wxpy.utils
+..  automodule:: wxpy.utils.tuling
+    :members:
+
+..  automodule:: wxpy.utils.tools
     :members:

docs/conf.py

@@ -80,7 +80,7 @@
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
+# Usually you set "language" from the shell_entry line for these cases.
 language = 'zh_CN'
 
 # List of patterns, relative to source directory, that match files and