Docs update

blueset · blueset · commit 38136ac4ce1b · 2016-11-26T14:56:29.000+08:00
diff --git a/docs/EWS.md b/docs/EWS.md
@@ -0,0 +1,66 @@
+# EFB WeChat Slave Channel
+
+EFB WeChat Slave Channel is a slave channel for EFB based on [ItChat](https://github.com/littlecodersh/ItChat) and WeChat Web <span style="font-size: 0.5em;">(rev.eng.)</span> API.
+
+## Specs
+* Unique name: `eh_wechat_slave`
+* Import path: `plugins.eh_wechat_slave`
+* Class name: `WeChatChannel`
+
+## Installation
+### Dependencies
+#### Python dependencies
+```
+itchat
+pymagic
+pillow
+xmltodict
+```
+> **Note**  
+> Please refer to [Pillow documentation](https://pillow.readthedocs.io/en/3.0.x/installation.html) for details on installing Pillow.
+
+#### Non-python dependencies
+```
+libmagic
+```
+and all other required by Pillow.
+
+### Configuration
+* Copy `eh_wechat_slave.py` to "plugins" directory,
+* Append `("plugins.we_wechat_slave", "WeChatChannel")` to `slaves` dict in `config.py`
+* No other configuration is required
+
+### Start up
+* Scan QR code with your *mobile WeChat client*, then tap "Accept", if required.
+
+## Feature availability
+### Supported message types
+* TO WeChat
+    * Text
+    * Image (Sticker sent as Image)
+    * File
+* FROM WeChat
+    * Text
+    * Image
+    * Sticker
+    * Video
+    * Location
+    * Voice
+    * Link
+    * Card
+    * File
+    * System notices
+
+### Command messages, Extra Functions
+* Add "Card" as friend or accept friend request
+* Change "alias" of friends
+
+## FAQ
+* **How do I log in to another WeChat Account?**  
+  Please remove the `itchat.pkl` file in the EFB root directory, and restart EFB for QR code scanning.
+* **Can I log in 2 WeChat accounts concurrently?**  
+  No. The feature is not yet available to EWS.
+* **I want to report a bug.**  
+  **I have some suggestions.**  
+  **Can I submit a pull request?**  
+  All bug reports, suggestions and pull requests are welcomed. Please read through and understand the [Contribution guideline](CONTRIBUTION.md) before submitting.
diff --git a/docs/home.md b/docs/home.md
@@ -4,7 +4,7 @@
 
 ![EFB](https://images.1a23.com/upload/images/SPET.png)
 
-_Codename_ **EH Forwarder Bot** (EFB) is a extensible chat tunnel framework which allows users to contact people from other chat platforms, and ultimately remotely control their accounts in other platforms.
+_Codename_ **EH Forwarder Bot** (EFB) is an extensible chat tunnel framework which allows users to contact people from other chat platforms, and ultimately remotely control their accounts in other platforms.
 
 ## Navigation
 * [Installation](installation.md)
diff --git a/docs/installation.md b/docs/installation.md
@@ -3,6 +3,16 @@ EFB framework itself does not require any external modules for it to work. Howev
 
 You may follow the following instructions to install dependencies for **all** channels maintained by me, or you may refer to the documentations of each respective channel for their installation instructions.
 
+## Storage directory
+
+In order to process files and media (pictures, voices, videos, etc.), a storage folder is used to temporarily save and process them. Please create a `storage` folder, if not existing, and give write and read permission to it.
+
+Script for \*nix users:
+```bash
+mkdir storage
+chmod +rw ./storage
+```
+
 ## Non-python dependencies
 
 * __gcc__
diff --git a/docs/slave-channel.md b/docs/slave-channel.md
@@ -90,3 +90,39 @@ Slave channels can send messages that offer the user options to take action. Thi
 Aside from sending a message with "Command" type (refer to the specification in "Message" documentation), the slave channel have to also provide a method for the command to be issued.
 
 The method can take any argument of Python's standard data structure, and returns a string which is shown to the user as the result of the action.
+
+## Extra functions
+
+In some cases, your slave channel may allow the user to achieve extra functionality, such as creating groups, managing group members, etc.
+
+You can receive such commands issued in a CLI-like style. An "extra function" method should only take one string parameter aside from `self`, and wrap it with `@extra` decorator from `utils` module. The extra decorator takes 2 arguments: `name`, a short name of the function, and `desc` a description of the function and its usage.
+
+> **More on `desc`**  
+`desc` should describe what the function does and how to use it. It's more like the help text for an CLI program. Since method of calling an extra function depends on the implementation of the master channel, you should use `{function_name}` as the function name in `desc`, and master channel will replace it with respective name.
+
+The method should in the end return a string, which will be shown to the user as the result. Depends on the functionality of the function, it may be just a simple success message, or a long chunk of results.
+
+Example:
+```python
+@extra(name="New group",
+       desc="Create a new group.\n" +
+            "Usage:\n" +
+            "    {function_name} group_name|member_id_1|member_id_2|...\n" +
+            "    e.g.: {function_name} My Group|123456|654321|393901"
+            "    group_name: Name of new group, \"|\" is not allowed.\n" +
+            "    member_id_n: ID of group members, you should fill at least one.")
+def new_group(self, param):
+    param = param.split('|')
+    if len(param) < 2:
+        return "Group name and at least one member ID should be provided."
+    group_name = param[0]
+    members = param[1:]
+    try:
+        self.myChat.create_group(group_name, members)
+    except Exception as e:
+        return repr(e)
+    return "Group %s created with members %s." % (group_name, members).
+```
+
+## Media processing
+Please refer to the _Media Processing_ section in the [Workflow](workflow.md) page.
diff --git a/docs/workflow.md b/docs/workflow.md
@@ -41,9 +41,11 @@ To deliver user's message to a slave channel, you should first gather all the in
 ## Slave Channel
 Slave channel has rather less things to do, get and enqueue incoming message, and send message to the platform. Also you may need to generate a list of possible recipients for the Master channel. That should be most of it.
 
-# Commands
+## Commands
 Once there's any message from a slave channel that allows the user to take action, the slave channel will enclose detail of actions (namely method names and arguments) into an `EFBMsg` object and send it to the master channel.
 
 Master channel will use it's own method to ask the user to make a decision, and with the decision, the master channel will call the respective method of the slave channel with the argument given.
 
 The method of slave channel returns a string as the result which is then reflected back to the user.
+
+## Media processing
diff --git a/plugins/eh_telegram_master/__init__.py b/plugins/eh_telegram_master/__init__.py
@@ -112,6 +112,13 @@ def _utf8_byte_truncate(self, text, max_bytes):
         return utf8[:i].decode()
 
     def callback_query_dispatcher(self, bot, update):
+        """
+        Dispatch a callback query based on the message session status.
+
+        Args:
+            bot (telegram.bot): bot
+            update (telegram.Update): update
+        """
         # Get essential information about the query
         query = update.callback_query
         chat_id = query.message.chat.id
@@ -137,6 +144,12 @@ def _reply_error(bot, update, errmsg):
         return bot.sendMessage(update.message.chat.id, errmsg, reply_to_message_id=update.message.message_id)
 
     def process_msg(self, msg):
+        """
+        Process a message from slave channel and deliver it to the user.
+
+        Args:
+            msg (EFBMsg): The message.
+        """
         chat_uid = "%s.%s" % (msg.channel_id, msg.origin['uid'])
         tg_chat = db.get_chat_assoc(slave_uid=chat_uid) or False
         msg_prefix = ""
@@ -263,7 +276,21 @@ def process_msg(self, msg):
         db.add_msg_log(**msg_log)
 
     def slave_chats_pagination(self, message_id, offset=0):
-
+        """
+        Generate a list of (list of) `InlineKeyboardButton`s of chats in slave channels,
+        based on the status of message located by `message_id` and the paging from
+        `offset` value.
+
+        Args:
+            message_id (int): Message ID for generating the buttons list.
+            offset (int): Offset for pagination
+
+        Returns:
+            tuple (str, list of list of InlineKeyboardButton):
+                A tuple: legend, chat_btn_list
+                `legend` is the legend of all Emoji headings in the entire list.
+                `chat_btn_list` is a list which can be fit into `telegram.InlineKeyboardMarkup`.
+        """
         legend = [
             "%s: Linked" % utils.Emojis.LINK_EMOJI,
             "%s: User" % utils.Emojis.USER_EMOJI,
diff --git a/plugins/eh_wechat_slave.py b/plugins/eh_wechat_slave.py
@@ -1,5 +1,4 @@
 import itchat
-import requests
 import re
 import xmltodict
 import logging
@@ -82,14 +81,14 @@ def get_uid(self, UserName=None, NickName=None):
             NickName (str): Display Name (`NickName`) of the chat.
 
         Returns:
-            int|str|bool: Unique ID of the chat. `False` if not found.
+            str|bool: Unique ID of the chat. `False` if not found.
         """
         if not (UserName or NickName):
             self.logger.error('No name provided.')
             return False
         r = self.search_user(UserName=UserName, name=NickName)
         if r:
-            return r[0]['AttrStatus'] or r[0]['Uin'] or crc32(r[0]['NickName'].encode("utf-8"))
+            return str(r[0]['AttrStatus'] or r[0]['Uin'] or crc32(r[0]['NickName'].encode("utf-8")))
         else:
             return False
 
@@ -98,7 +97,7 @@ def get_UserName(self, uid, refresh=False):
         Get WeChat `UserName` of a chat by UID.
 
         Args:
-            uid (str|int): UID of the chat.
+            uid (str): UID of the chat.
             refresh (bool): Refresh the chat list from WeChat, `False` by default.
 
         Returns:
@@ -110,39 +109,69 @@ def get_UserName(self, uid, refresh=False):
         return False
 
     def search_user(self, UserName=None, uid=None, wid=None, name=None, ActualUserName=None, refresh=False):
+        """
+        Search for a WeChat "User" (a user, a group/chat room or an MPS account,
+        by `UserName`, unique ID, WeChat ID, name/alias, and/or group member `UserName`.
+
+        At least one of `UserName`, `uid`, `wid`, or `name` should be provided.
+
+        When matching for a group, all of `UserName`, `uid`, `wid`, and `name` will be used
+        to match for group and member.
+
+        Args:
+            UserName (str): UserName of a "User"
+            uid (str): Unique ID generated by the channel
+            wid (str): WeChat ID.
+            name (str): Name or Alias
+            ActualUserName (str): UserName of a group member, used only when a group is matched.
+            refresh (bool): Refresh the user list, False by default.
+
+        Returns:
+            list of dict: A list of matching users in ItChat user dict format.
+        """
         result = []
+        UserName = None if UserName is None else str(UserName)
+        uid = None if uid is None else str(uid)
+        wid = None if wid is None else str(wid)
+        name = None if name is None else str(name)
+        ActualUserName = None if ActualUserName is None else str(ActualUserName)
+
+        if all(i is None for i in [UserName, uid, wid, name]):
+            raise ValueError("At least one of [UserName, uid, wid, name] should be given.")
+
         for i in itchat.get_friends(refresh) + itchat.get_mps(refresh):
-            if str(i['UserName']) == str(UserName) or \
-               str(i['AttrStatus']) == str(uid) or \
-               str(i['Alias']) == str(wid) or \
-               str(i['NickName']) == str(name) or \
-               str(i['DisplayName']) == str(name) or \
-               str(crc32(i['NickName'].encode("utf-8"))) == str(uid):
+            if str(i['UserName']) == UserName or \
+               str(i['AttrStatus']) == uid or \
+               str(i['Alias']) == wid or \
+               str(i['NickName']) == name or \
+               str(i['DisplayName']) == name or \
+               str(crc32(i['NickName'].encode("utf-8"))) == uid:
                 result.append(i.copy())
         for i in itchat.get_chatrooms(refresh):
             if not i['MemberList']:
                 i = itchat.update_chatroom(i['UserName'])
-            if str(i['UserName']) == str(UserName) or \
-               str(i['Uin']) == str(uid) or \
-               str(i['Alias']) == str(wid) or \
-               str(i['NickName']) == str(name) or \
-               str(i['DisplayName']) == str(name) or \
-               str(crc32(i['NickName'].encode("utf-8"))) == str(uid):
+            if str(i['UserName']) == UserName or \
+               str(i['Uin']) == uid or \
+               str(i['Alias']) == wid or \
+               str(i['NickName']) == name or \
+               str(i['DisplayName']) == name or \
+               str(crc32(i['NickName'].encode("utf-8"))) == uid:
                 result.append(i.copy())
                 result[-1]['MemberList'] = []
                 if ActualUserName:
                     for j in itchat.search_chatrooms(userName=i['UserName'])['MemberList']:
-                        if str(j['UserName']) == str(ActualUserName) or \
-                           str(j['AttrStatus']) == str(uid) or \
-                           str(j['NickName']) == str(name) or \
-                           str(j['DisplayName']) == str(name):
+                        if str(j['UserName']) == ActualUserName or \
+                           str(j['AttrStatus']) == uid or \
+                           str(j['NickName']) == name or \
+                           str(j['DisplayName']) == name:
                             result[-1]['MemberList'].append(j)
         if not result and not refresh:
             return self.search_user(UserName, uid, wid, name, ActualUserName, refresh=True)
         return result
 
     def poll(self):
         self.usersdata = itchat.get_friends(True) + itchat.get_chatrooms()
+
         @itchat.msg_register(['Text'], isFriendChat=True, isMpChat=True)
         def wcText(msg):
             self.textMsg(msg)
@@ -471,8 +500,7 @@ def send_message(self, msg):
     # Extra functions
 
     @extra(name="Show chat list",
-           desc="Get a list of chat from Wechat.\nUsage:\n    {function_name} [-r]\n    -r: Force refresh",
-           emoji="📃")
+           desc="Get a list of chat from Wechat.\nUsage:\n    {function_name} [-r]\n    -r: Force refresh")
     def get_chat_list(self, param=""):
         refresh = False
         if param:
@@ -505,8 +533,7 @@ def get_chat_list(self, param=""):
     @extra(name="Set alias",
            desc="Set alias for a contact in WeChat. You may not set alias to a group or a MPS contact.\n" + \
                 "Usage:\n    {function_name} [-r] id [alias]\n    id: Chad ID (You may obtain it from \"Show chat list\" function.\n" + \
-                "    alias: Alias to be set. Omit to remove.\n    -r: Force refresh",
-           emoji="📃")
+                "    alias: Alias to be set. Omit to remove.\n    -r: Force refresh")
     def get_chat_list(self, param=""):
         refresh = False
         if param:
diff --git a/utils.py b/utils.py
@@ -19,6 +19,8 @@ def get_source_emoji(t):
 
 def extra(**kw):
     def attr_dec(f):
+        if not "name" in kw or not "desc" in kw:
+            raise ValueError("Key `name` and `desc` is required for extra functions.")
         f.__setattr__("extra_fn", True)
         for i in kw:
             f.__setattr__(i, kw[i])
