add ‘rtype’ in docstrings & update readme

README.rst

@@ -1,7 +1,9 @@
 wxpy: 用 Python 玩微信
 ==============================
 
-微信机器人 / 优雅的微信个人号API，基于 itchat，全面优化接口，更有 Python 范儿。
+微信机器人 / 优雅的微信个人号API。
+
+在 itchat 的基础上优化接口，扩展功能，提升了模块的易用性。
 
 
 用来干啥

docs/index.rst

@@ -7,7 +7,9 @@
 wxpy: 用 Python 玩微信
 ==============================
 
-微信机器人 / 优雅的微信个人号API，基于 itchat，全面优化接口，更有 Python 范儿。
+微信机器人 / 优雅的微信个人号API。
+
+在 itchat 的基础上优化接口，扩展功能，提升了模块的易用性。
 
 
 用来干啥
@@ -77,7 +79,7 @@ wxpy: 用 Python 玩微信
     * 加好友，建群，邀请进群，踢出群
 
 
-了解更多
+文档目录
 ----------------
 
 ..  toctree::

wxpy/api/bot.py

@@ -108,6 +108,7 @@ def except_self(self, chats_or_dicts):
 
         :param chats_or_dicts: 聊天对象合集或用户字典列表
         :return: 排除自身后的列表
+        :rtype: :class:`wxpy.Chats`
         """
         return list(filter(lambda x: get_user_name(x) != self.self.user_name, chats_or_dicts))
 
@@ -117,6 +118,7 @@ def chats(self, update=False):
 
         :param update: 是否更新
         :return: 聊天对象合集
+        :rtype: :class:`wxpy.Chats`
         """
         return Chats(self.friends(update) + self.groups(update) + self.mps(update), self)
 
@@ -131,6 +133,7 @@ def friends(self, update=False):
 
         :param update: 是否更新
         :return: 聊天对象合集
+        :rtype: :class:`wxpy.Chats`
         """
 
         if update:
@@ -148,6 +151,7 @@ def groups(self, update=False, contact_only=False):
         :param update: 是否更新
         :param contact_only: 是否限于保存为联系人的群聊
         :return: 群聊合集
+        :rtype: :class:`wxpy.Groups`
         """
 
         # itchat 原代码有些难懂，似乎 itchat 中的 get_contact() 所获取的内容视其 update 参数而变化
@@ -166,6 +170,7 @@ def mps(self, update=False):
 
         :param update: 是否更新
         :return: 聊天对象合集
+        :rtype: :class:`wxpy.Chats`
         """
 
         if update:
@@ -211,6 +216,7 @@ def search(self, name=None, **attributes):
         :param name: 名称 (可以是昵称、备注等)
         :param attributes: 属性键值对，键可以是 sex(性别), province(省份), city(城市) 等。例如可指定 province='广东'
         :return: 匹配的聊天对象合集
+        :rtype: :class:`wxpy.Chats`
         """
 
         return self.chats().search(name, **attributes)
@@ -239,6 +245,7 @@ def accept_friend(self, user, verify_content=''):
         :param user: 用户对象或 user_name
         :param verify_content: 验证说明信息
         :return: 新的好友对象
+        :rtype: :class:`wxpy.Friend`
         """
 
         @handle_response()
@@ -263,6 +270,7 @@ def create_group(self, users, topic=None):
         :param users: 用户列表
         :param topic: 群名称
         :return: 若建群成功，返回一个新的群聊对象
+        :rtype: :class:`wxpy.Group`
         """
 
         @handle_response()
@@ -289,6 +297,7 @@ def upload_file(self, path):
 
         :param path: 文件路径
         :return: media_id
+        :rtype: str
         """
 
         @handle_response()

wxpy/api/chats/chats.py

@@ -27,6 +27,7 @@ def search(self, name=None, **attributes):
         :param name: 名称 (可以是昵称、备注等)
         :param attributes: 属性键值对，键可以是 sex(性别), province(省份), city(城市) 等。例如可指定 province='广东'
         :return: 匹配的聊天对象合集
+        :rtype: :class:`wxpy.Chats`
         """
 
         def match(chat):

wxpy/api/chats/group.py

@@ -54,6 +54,7 @@ def search(self, name=None, **attributes):
         :param name: 成员名称关键词
         :param attributes: 属性键值对
         :return: 匹配的群聊成员
+        :rtype: :class:`wxpy.Chats`
         """
         return self.members.search(name, **attributes)
 

wxpy/api/chats/groups.py

@@ -19,6 +19,7 @@ def search(self, name=None, users=None, **attributes):
         :param users: 需包含的用户
         :param attributes: 属性键值对，键可以是 owner(群主对象), is_owner(自身是否为群主), nick_name(精准名称) 等。
         :return: 匹配条件的群聊列表
+        :rtype: :class:`wxpy.Groups`
         """
 
         users = ensure_list(users)

wxpy/api/chats/user.py

@@ -71,5 +71,6 @@ def accept(self, verify_content=''):
 
         :param verify_content: 验证信息(文本)
         :return: 新的好友对象
+        :rtype: :class:`wxpy.Friend`
         """
         return self.bot.accept_friend(user=self, verify_content=verify_content)

wxpy/api/messages/message.py

@@ -128,6 +128,8 @@ def chat(self):
 
         * 对于自己发送的消息，为消息的接收者
         * 对于别人发送的消息，为消息的发送者
+        
+        :rtype: :class:`wxpy.User`, :class:`wxpy.Group`
         """
 
         if self.raw.get('FromUserName') == self.bot.self.user_name:
@@ -139,6 +141,8 @@ def chat(self):
     def sender(self):
         """
         消息的发送者
+        
+        :rtype: :class:`wxpy.User`, :class:`wxpy.Group`
         """
 
         return self._get_chat_by_user_name(self.raw.get('FromUserName'))
@@ -147,6 +151,8 @@ def sender(self):
     def receiver(self):
         """
         消息的接收者
+        
+        :rtype: :class:`wxpy.User`, :class:`wxpy.Group`
         """
 
         return self._get_chat_by_user_name(self.raw.get('ToUserName'))
@@ -156,14 +162,16 @@ def member(self):
         """
         * 若消息来自群聊，则此属性为消息的实际发送人(具体的群成员)
         * 若消息来自其他聊天对象(非群聊)，则此属性为 None
+        
+        :rtype: NoneType, :class:`wxpy.Member`
         """
 
         if isinstance(self.chat, Group):
             if self.sender == self.bot.self:
                 return self.chat.self
             else:
                 actual_user_name = self.raw.get('ActualUserName')
-                for _member in self.chat:
+                for _member in self.chat.members:
                     if _member.user_name == actual_user_name:
                         return _member
                 return Member(dict(

wxpy/api/messages/messages.py

@@ -23,6 +23,7 @@ def search(self, keywords=None, **attributes):
         :param keywords: 文本关键词
         :param attributes: 属性键值对
         :return: 所有匹配的消息
+        :rtype: :class:`wxpy.Messages`
         """
 
         def match(msg):

wxpy/ext/tuling.py

@@ -49,6 +49,7 @@ def do_reply(self, msg, at_member=True):
         :param msg: Message 对象
         :param at_member: 若消息来自群聊，回复时 @发消息的群成员
         :return: 答复文本
+        :rtype: str
         """
         ret = self.reply_text(msg, at_member)
         msg.reply(ret)
@@ -61,6 +62,7 @@ def reply_text(self, msg, at_member=True):
         :param msg: Message 对象
         :param at_member: 若消息来自群聊，回复时 @发消息的群成员
         :return: 答复文本
+        :rtype: str
         """
 
         def process_answer():

wxpy/utils/misc.py

@@ -84,6 +84,7 @@ def ensure_list(x, except_false=True):
     :param x: 输入对象
     :param except_false: None, False 等例外，会直接返回原值
     :return: 列表，或 None, False 等
+    :rtype: list
     """
 
     if isinstance(x, (list, tuple)) or (not x and except_false):
@@ -233,6 +234,7 @@ def get_receiver(receiver=None):
         * 当为 :class:`机器人 <Bot>` 时，将返回该机器人的"文件传输助手"
         * 当为 :class:`聊天对象 <Chat>` 时，将返回该聊天对象
     :return: 作为接收者的聊天对象
+    :rtype: :class:`wxpy.Chat`
     """
 
     from wxpy.api.chats import Chat
@@ -274,6 +276,7 @@ def get_text_without_at_bot(msg):
 
     :param msg: Message 对象
     :return: 清理 @ 机器人部分后的文本内容
+    :rtype: str
     """
 
     from wxpy.api.chats import Group

wxpy/utils/tools.py

@@ -46,6 +46,7 @@ def mutual_friends(*args):
 
     :param args: 每个参数为一个微信用户的机器人(Bot)，或是聊天对象合集(Chats)
     :return: 共同好友列表
+    :rtype: :class:`wxpy.Chats`
     """
 
     from wxpy.api.bot import Bot