Improve message sending APIs

docs/changelog.md

@@ -4,6 +4,11 @@ sidebar: auto
 
 # 更新日志
 
+## next
+
+- 给所有发送消息的函数和方法（`BaseSession.send()`、`CommandSession.pause()`、`CommandSession.finish()` 等）新增了 `**kwargs`，并将此参数继续传递给 python-aiocqhttp 的 `CQHttp.send()` 方法，从而支持 `at_sender` 参数（默认 `False`）
+- `BaseSession.send()` 方法新增 `ensure_private` 参数，类型 `bool`，默认 `False`，可用于确保发送消息到私聊（对于群消息，会私聊发送给发送人）
+
 ## v0.5.0
 
 - 修复调用不存在的多级命令（例如 `/echo/nonexist`）时，抛出异常导致 WebSocket 连接断开的问题

none/command.py

@@ -307,7 +307,7 @@ class CommandSession(BaseSession):
                                    if s.type == 'image' and 'url' in s.data]
 
     def get(self, key: Any, *,
-            prompt: Optional[Message_T] = None) -> Any:
+            prompt: Optional[Message_T] = None, **kwargs) -> Any:
         """
         Get an argument with a given key.
 
@@ -326,23 +326,23 @@ class CommandSession(BaseSession):
 
         self.current_key = key
         # ask the user for more information
-        self.pause(prompt)
+        self.pause(prompt, **kwargs)
 
     def get_optional(self, key: Any,
                      default: Optional[Any] = None) -> Optional[Any]:
         """Simply get a argument with given key."""
         return self.args.get(key, default)
 
-    def pause(self, message: Optional[Message_T] = None) -> None:
+    def pause(self, message: Optional[Message_T] = None, **kwargs) -> None:
         """Pause the session for further interaction."""
         if message:
-            asyncio.ensure_future(self.send(message))
+            asyncio.ensure_future(self.send(message, **kwargs))
         raise _FurtherInteractionNeeded
 
-    def finish(self, message: Optional[Message_T] = None) -> None:
+    def finish(self, message: Optional[Message_T] = None, **kwargs) -> None:
         """Finish the session."""
         if message:
-            asyncio.ensure_future(self.send(message))
+            asyncio.ensure_future(self.send(message, **kwargs))
         raise _FinishException
 
     def switch(self, new_ctx_message: Message_T) -> None:

none/helpers.py

@@ -44,22 +44,17 @@ def context_id(ctx: Context_T, *,
     return ctx_id
 
 
-async def send(bot: NoneBot, ctx: Context_T, message: Message_T, *,
-               ignore_failure: bool = True) -> None:
+async def send(bot: NoneBot, ctx: Context_T,
+               message: Message_T, *,
+               ensure_private: bool = False,
+               ignore_failure: bool = True,
+               **kwargs) -> None:
     """Send a message ignoring failure by default."""
     try:
-        if ctx.get('post_type') == 'message':
-            await bot.send(ctx, message)
-        else:
+        if ensure_private:
             ctx = ctx.copy()
-            if 'message' in ctx:
-                del ctx['message']
-            if 'group_id' in ctx:
-                await bot.send_group_msg(**ctx, message=message)
-            elif 'discuss_id' in ctx:
-                await bot.send_discuss_msg(**ctx, message=message)
-            elif 'user_id' in ctx:
-                await bot.send_private_msg(**ctx, message=message)
+            ctx['message_type'] = 'private'
+        await bot.send(ctx, message, **kwargs)
     except CQHttpError:
         if not ignore_failure:
             raise

none/session.py

@@ -11,7 +11,20 @@ class BaseSession:
         self.ctx = ctx
 
     async def send(self, message: Message_T, *,
-                   ignore_failure: bool = True) -> None:
-        """Send a message ignoring failure by default."""
+                   at_sender: bool = False,
+                   ensure_private: bool = False,
+                   ignore_failure: bool = True,
+                   **kwargs) -> None:
+        """
+        Send a message ignoring failure by default.
+
+        :param message: message to send
+        :param at_sender: @ the sender if in group or discuss chat
+        :param ensure_private: ensure the message is sent to private chat
+        :param ignore_failure: if any CQHttpError raised, ignore it
+        :return: the result returned by CQHTTP
+        """
         return await send(self.bot, self.ctx, message,
-                          ignore_failure=ignore_failure)
+                          at_sender=at_sender,
+                          ensure_private=ensure_private,
+                          ignore_failure=ignore_failure, **kwargs)