From a3f6ef0053f627d9a76f39e95f4e0717685a7308 Mon Sep 17 00:00:00 2001
From: Youfou <youfou@qq.com>
Date: Sun, 9 Apr 2017 15:22:44 +0800
Subject: [PATCH] =?UTF-8?q?add=20=E2=80=98rtype=E2=80=99=20in=20docstrings?=
 =?UTF-8?q?=20&=20update=20readme?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.rst                    |  4 +++-
 docs/index.rst                |  6 ++++--
 wxpy/api/bot.py               |  9 +++++++++
 wxpy/api/chats/chats.py       |  1 +
 wxpy/api/chats/group.py       |  1 +
 wxpy/api/chats/groups.py      |  1 +
 wxpy/api/chats/user.py        |  1 +
 wxpy/api/messages/message.py  | 10 +++++++++-
 wxpy/api/messages/messages.py |  1 +
 wxpy/ext/tuling.py            |  2 ++
 wxpy/utils/misc.py            |  3 +++
 wxpy/utils/tools.py           |  1 +
 12 files changed, 36 insertions(+), 4 deletions(-)

diff --git a/README.rst b/README.rst
index 81ce482..ab11643 100644
--- a/README.rst
+++ b/README.rst
@@ -1,7 +1,9 @@
 wxpy: 用 Python 玩微信
 ==============================
 
-微信机器人 / 优雅的微信个人号API，基于 itchat，全面优化接口，更有 Python 范儿。
+微信机器人 / 优雅的微信个人号API。
+
+在 itchat 的基础上优化接口，扩展功能，提升了模块的易用性。
 
 
 用来干啥
diff --git a/docs/index.rst b/docs/index.rst
index a5a3e0a..9fe8461 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -7,7 +7,9 @@
 wxpy: 用 Python 玩微信
 ==============================
 
-微信机器人 / 优雅的微信个人号API，基于 itchat，全面优化接口，更有 Python 范儿。
+微信机器人 / 优雅的微信个人号API。
+
+在 itchat 的基础上优化接口，扩展功能，提升了模块的易用性。
 
 
 用来干啥
@@ -77,7 +79,7 @@ wxpy: 用 Python 玩微信
     * 加好友，建群，邀请进群，踢出群
 
 
-了解更多
+文档目录
 ----------------
 
 ..  toctree::
diff --git a/wxpy/api/bot.py b/wxpy/api/bot.py
index 22f8a17..84d8c68 100644
--- a/wxpy/api/bot.py
+++ b/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()
diff --git a/wxpy/api/chats/chats.py b/wxpy/api/chats/chats.py
index 6513b7d..c5ee12c 100644
--- a/wxpy/api/chats/chats.py
+++ b/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):
diff --git a/wxpy/api/chats/group.py b/wxpy/api/chats/group.py
index 7f1ba28..1a68db7 100644
--- a/wxpy/api/chats/group.py
+++ b/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)
 
diff --git a/wxpy/api/chats/groups.py b/wxpy/api/chats/groups.py
index 9295caf..63e5133 100644
--- a/wxpy/api/chats/groups.py
+++ b/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)
diff --git a/wxpy/api/chats/user.py b/wxpy/api/chats/user.py
index f791920..bea3931 100644
--- a/wxpy/api/chats/user.py
+++ b/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)
diff --git a/wxpy/api/messages/message.py b/wxpy/api/messages/message.py
index a62c8bf..0a4ba56 100644
--- a/wxpy/api/messages/message.py
+++ b/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,6 +162,8 @@ def member(self):
         """
         * 若消息来自群聊，则此属性为消息的实际发送人(具体的群成员)
         * 若消息来自其他聊天对象(非群聊)，则此属性为 None
+        
+        :rtype: NoneType, :class:`wxpy.Member`
         """
 
         if isinstance(self.chat, Group):
@@ -163,7 +171,7 @@ def member(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(
diff --git a/wxpy/api/messages/messages.py b/wxpy/api/messages/messages.py
index 4d5ef36..ded77a1 100644
--- a/wxpy/api/messages/messages.py
+++ b/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):
diff --git a/wxpy/ext/tuling.py b/wxpy/ext/tuling.py
index be78f29..9e63514 100644
--- a/wxpy/ext/tuling.py
+++ b/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():
diff --git a/wxpy/utils/misc.py b/wxpy/utils/misc.py
index 67e3dee..f6afc02 100644
--- a/wxpy/utils/misc.py
+++ b/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
diff --git a/wxpy/utils/tools.py b/wxpy/utils/tools.py
index 108cf05..cea1777 100644
--- a/wxpy/utils/tools.py
+++ b/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