cqhttp_helper.py

import cqhttp as _cqhttp

# working as a replacement.
Error = _cqhttp.Error


class CQHttp(_cqhttp.CQHttp):
    """
    **CoolQ HTTP API Python SDK封装类**

    :作者: SuperMarioSF
    :参考: HTTP API v3.4
    :版本: v1.0

    本类封装了CoolQ HTTP API的Python SDK中对应HTTP API的所有API。
    封装时参考并引用了HTTP API所提供的文档。


    感谢 **richardchien** 为我们提供了如此简便酷Q应用开发方式。

    本文件使用 WTFPL 2.0 许可证发布。

    ------------

    本文件适用于JetBrains PyCharm开发环境。
    你可以在PyCharm中在任何使用到本类的封装方法的位置按下 **Ctrl+Q** 来快速查看文档的内容。

    本页帮助文档也会下方会介绍原Python SDK中已有的功能的用法。

    要查看HTTP API的完整在线文档，请访问：

    | https://richardchien.github.io/coolq-http-api/
    | http://richardchien.gitee.io/coolq-http-api/docs/

    ------------

    **使用本文件**

    你可以将本文件作为导入 cqhttp 包的替代来使用。
    但需要注意，本文件需要你的 Python 环境中能够导入原 cqhttp 包，因为本文件只是对原 cqhttp 包的封装。
    在用本文件在PyCharm IDE开发完毕之后，你可以直接把对本文件的引用恢复为对原 cqhttp 包的引用。

    将原先导入 cqhttp 包的写法:

    >>> from cqhttp import CQHttp, Error

    更换成:

    >>> from cqhttp_helper import CQHttp, Error

    即可完成对本文件的所有内容的引用，享受自动补全和即时文档吧！

    在本帮助页面中，`bot` 指的是已初始化的 CQHttp 对象。

    ------------

    **对象列表**

    | cqhttp_helper.CQHttp(api_root=None, access_token=None, secret=None): CQHttp 封装类，继承原 cqhttp 的 CQHttp 类，提供封装的方法列表和实时帮助信息。
    | cqhttp_helper.Error(status_code, retcode=None): CQHttp 异常类。直接引用 cqhttp 的 Error 类，用于兼容目的。

    ------------

    **cqhttp_helper.CQHttp 中封装的方法列表**

    | send_private_msg(self, *, user_id, message, auto_escape=False): 发送私聊消息
    | send_private_msg_async(self, *, user_id, message, auto_escape=False): 发送私聊消息 (异步版本)
    | send_group_msg(self, *, group_id, message, auto_escape=False): 发送群消息
    | send_group_msg_async(self, *, group_id, message, auto_escape=False): 发送群消息 (异步版本)
    | send_discuss_msg(self, *, discuss_id, message, auto_escape=False): 发送讨论组消息
    | send_discuss_msg_async(self, *, discuss_id, message, auto_escape=False): 发送讨论组消息 (异步版本)
    | send_msg(self, *, message_type, user_id=None, group_id=None, discuss_id=None, message, auto_escape=False): 发送消息
    | send_msg_async(self, *, message_type, user_id=None, group_id=None, discuss_id=None, message, auto_escape=False): 发送消息 (异步版本)
    | delete_msg(self, *, message_id): 撤回消息
    | send_like(self, *, user_id, times=1): 发送好友赞
    | set_group_kick(self, *, group_id, user_id, reject_add_request=False): 群组踢人
    | set_group_ban(self, *, group_id, user_id, duration=30 * 60): 群组单人禁言
    | set_group_anonymous_ban(self, *, group_id, flag, duration=30 * 60): 群组匿名用户禁言
    | set_group_whole_ban(self, *, group_id, enable=True): 群组全员禁言
    | set_group_admin(self, *, group_id, user_id, enable=True): 群组设置管理员
    | set_group_anonymous(self, *, group_id, enable=True): 群组匿名
    | set_group_card(self, *, group_id, user_id, card=None): 设置群名片（群备注）
    | set_group_leave(self, *, group_id, is_dismiss=False): 退出群组
    | set_group_special_title(self, *, group_id, user_id, special_title, duration=-1): 设置群组专属头衔
    | set_discuss_leave(self, *, discuss_id): 退出讨论组
    | set_friend_add_request(self, *, flag, approve=True, remark=None): 处理加好友请求
    | set_group_add_request(self, *, flag, type, approve=True, reason=None): 处理加群请求、群组成员邀请
    | get_login_info(self): 获取登录号信息
    | get_stranger_info(self, *, user_id, no_cache=False): 获取陌生人信息
    | get_group_list(self): 获取群列表
    | get_group_member_info(self, *, group_id, user_id, no_cache=False): 获取群成员信息
    | get_group_member_list(self, *, group_id): 获取群成员列表
    | get_cookies(self): 获取 Cookies
    | get_csrf_token(self): 获取 CSRF Token
    | get_record(self, *, file, out_format): 获取语音
    | get_status(self): 获取插件运行状态
    | get_version_info(self): 获取酷 Q 及 HTTP API 插件的版本信息
    | set_restart(self): 重启酷 Q，并以当前登录号自动登录（需勾选快速登录）
    | set_restart_plugin(self): 重启 HTTP API 插件
    | clean_data_dir(self, *, data_dir): 清理数据目录
    | clean_data_dir_async(self, *, data_dir): 清理数据目录 (异步版本)
    | _get_friend_list(self): 获取好友列表 (实验性功能)

    ------------

    **创建实例**

    首先创建 CQHttp 类的实例，传入 api_root，即为酷 Q HTTP API 插件的监听地址，如果你不需要调用 API，也可以不传入。Access token 和签名密钥也在这里传入，如果没有配置 access_token 或 secret 项，则不传。

    ------------

    **异常处理**

    每个 API 调用最后都会由 `requests` 库来发出请求，如果网络无法连接，它可能会抛出 `ConnectionError` 等异常，见 requests错误与异常_ 。而一旦请求成功，本 SDK 会判断 HTTP 响应状态码，只有当状态码为 200，且 status 字段为 ok 或 async 时，会返回 data 字段的内容，否则抛出 cqhttp.Error 异常，在这个异常中你可以通过 status_code 和 retcode 属性来获取 HTTP 状态码和插件的 retcode（如果状态码不为 200，则 retcode 为 None），具体响应状态码和 retcode 的含义，见 响应说明_ 。

    .. _requests错误与异常: http://cn.python-requests.org/zh_CN/latest/user/quickstart.html#id11
    .. _响应说明: https://richardchien.github.io/coolq-http-api/#/API?id=%E5%93%8D%E5%BA%94%E8%AF%B4%E6%98%8E

    ------------

    **消息发送**

    为了简化发送消息的操作，Python SDK 提供了 send(context, message) 函数，这里的第一个参数 context 也就是上报数据，传入之后函数会自己判断当前需要发送到哪里（哪个好友，或哪个群），无需手动再指定，其它参数仍然可以从 keyword argument 指定，例如 auto_escape=True。

    以 `send_` 开头（也就是消息发送相关）的接口都会包含一个 `message` 的参数。此参数接受普通的字符串(str)，也接受一个特定格式的列表(list)。列表格式在原HTTP API文档中是表示为 `array` ，称为 JSON数组类型。在Python中，表示为一个列表(list)中包括的数个字典(dict)。

    以下是调用范例:

    .. code-block:: python

        # 以字符串形式发送的普通消息。
        bot.send_private_message(user_id=1234567,
                    message="这是一条普通消息。\\n可以用这种方式换行。"

        # 以列表(list)形式发送的多段消息组合。
        bot.send_private_message(user_id=1234567,
                message=[
                                {
                                    "type": "text",
                                    "data": {"text": "这是第一段"}
                                },
                                {
                                    "type": "face",
                                    "data": {"id": "111"}
                                },
                                {
                                    "type": "text",
                                    "data": {"text": "这是表情之后的一段。"}
                                }
                        ])

    关于多段消息的每个单段的具体格式，请参见 HTTP API 文档中的 **消息格式** 的 **消息段（广义 CQ 码）** 一节。

    ------------

    **事件处理**

    `on_message`、`on_event`、`on_request` 三个装饰器分别对应三个上报类型（`post_type`），括号中指出要处理的消息类型（`message_type`）、事件名（`event`）、请求类型（`request_type`），一次可指定多个，如果留空，则会处理所有这个上报类型的上报。

    以下为范例:

    .. code-block:: python

        # 监听消息输入
        @bot.on_message()
        def handle_msg(context):
          bot.send(context, '你好呀，下面一条是你刚刚发的：')
          return {'reply': context['message'], 'at_sender': False}

        # 监听群组成员增加事件
        @bot.on_event('group_increase')
        def handle_group_increase(context):
           bot.send(context, message='欢迎新人～', is_raw=True)  # 发送欢迎新人

        # 监听加群和加好友请求
        @bot.on_request('group', 'friend')
        def handle_request(context):
           return {'approve': True}  # 同意所有加群、加好友请求


        bot.run(host='127.0.0.1', port=8080)

    上面三个装饰器装饰的函数，统一接受一个参数，即为上报的数据，具体数据内容见  事件上报_ ；返回值可以是一个字典，会被自动作为 JSON 响应返回给 HTTP API 插件，具体见 上报请求的响应数据格式_ 。


    .. _事件上报: https://richardchien.github.io/coolq-http-api/#/Post
    .. _上报请求的响应数据格式: https://richardchien.github.io/coolq-http-api/#/Post?id=%E4%B8%8A%E6%8A%A5%E8%AF%B7%E6%B1%82%E7%9A%84%E5%93%8D%E5%BA%94%E6%95%B0%E6%8D%AE%E6%A0%BC%E5%BC%8F

    ------------

    **运行实例**

    使用装饰器定义好处理函数之后，调用 `bot.run()` 即可运行。你需要传入 `host` 和 `port` 参数，来指定服务端需要运行在哪个地址，**然后在 HTTP API 插件的配置文件中，在 `post_url` 项中配置此地址（http://host:port/）**。

    **务必注意:** 如果不在插件配置文件中指定 `post_url` 为运行实例时指定的地址，Python SDK 将无法收到任何消息和事件。



    """
    def __init__(self, api_root=None, access_token=None, secret=None):
        """
        创建 CoolQ HTTP API 对象

        ------------

        :param str | None api_root: 酷 Q HTTP API 插件的监听地址的 URL ，与 HTTP API 的配置文件设定和实际使用环境相关。如果你不需要调用 API，也可以不传入。
        :param str | None access_token: 插件配置文件中所指定的 `access_token` 。如果未设定可不传此参数。
        :param str | None secret: 插件配置文件中所指定的 `secret` 。如果未设定可不传此参数。
        """
        super().__init__(api_root=api_root, access_token=access_token, secret=secret)

    def send_private_msg(self, *, user_id, message, auto_escape=False):
        '''
        发送私聊消息

        ------------

        :param int user_id: 对方 QQ 号
        :param str | list[ dict[ str, unknown ] ] message: 要发送的内容
        :param bool auto_escape: 消息内容是否作为纯文本发送（即不解析 CQ 码），`message` 数据类型为 `list` 时无效
        :return: {"message_id": int 消息ID}
        :rtype: dict[string, int]
        '''
        return super().__getattr__('send_private_msg') \
            (user_id=user_id, message=message, auto_escape=auto_escape)

    def send_private_msg_async(self, *, user_id, message, auto_escape=False):
        """
        发送私聊消息 (异步版本)

        ------------

        :param int user_id: 对方 QQ 号
        :param str | list[ dict[ str, unknown ] ] message: 要发送的内容
        :param bool auto_escape: 消息内容是否作为纯文本发送（即不解析 CQ 码），`message` 数据类型为 `list` 时无效
        :return: None
        :rtype: None
        """
        return super().__getattr__('send_private_msg_async') \
            (user_id=user_id, message=message, auto_escape=auto_escape)

    def send_group_msg(self, *, group_id, message, auto_escape=False):
        """
        发送群消息

        ------------

        :param int group_id: 群号
        :param str | list[ dict[ str, unknown ] ] message: 要发送的内容
        :param bool auto_escape: 消息内容是否作为纯文本发送（即不解析 CQ 码），`message` 数据类型为 `list` 时无效
        :return: {"message_id": int 消息ID}
        :rtype: dict[string, int]
        """
        return super().__getattr__('send_group_msg') \
            (group_id=group_id, message=message, auto_escape=auto_escape)

    def send_group_msg_async(self, *, group_id, message, auto_escape=False):
        """
        发送群消息 (异步版本)

        ------------

        :param int group_id: 群号
        :param str | list[ dict[ str, unknown ] ] message: 要发送的内容
        :param bool auto_escape: 消息内容是否作为纯文本发送（即不解析 CQ 码），`message` 数据类型为 `list` 时无效
        :return: None
        :rtype: None
        """
        return super().__getattr__('send_group_msg_async') \
            (group_id=group_id, message=message, auto_escape=auto_escape)

    def send_discuss_msg(self, *, discuss_id, message, auto_escape=False):
        """
        发送讨论组消息

        ------------

        :param int discuss_id: 讨论组 ID（正常情况下看不到，需要从讨论组消息上报的数据中获得）
        :param str | list[ dict[ str, unknown ] ] message: 要发送的内容
        :param bool auto_escape: 消息内容是否作为纯文本发送（即不解析 CQ 码），`message` 数据类型为 `list` 时无效
        :return: {"message_id": int 消息ID}
        :rtype: dict[string, int]
        """
        return super().__getattr__('send_discuss_msg') \
            (discuss_id=discuss_id, message=message, auto_escape=auto_escape)

    def send_discuss_msg_async(self, *, discuss_id, message, auto_escape=False):
        """
        发送讨论组消息 (异步版本)

        ------------

        :param int discuss_id: 讨论组 ID（正常情况下看不到，需要从讨论组消息上报的数据中获得）
        :param str | list[ dict[ str, unknown ] ] message: 要发送的内容
        :param bool auto_escape: 消息内容是否作为纯文本发送（即不解析 CQ 码），`message` 数据类型为 `list` 时无效
        :return: None
        :rtype: None
        """
        return super().__getattr__('send_discuss_msg_async') \
            (discuss_id=discuss_id, message=message, auto_escape=auto_escape)

    def send_msg(self, *, message_type, user_id=None, group_id=None, discuss_id=None, message, auto_escape=False):
        """
        发送消息

        ------------

        :param str message_type: 消息类型，支持 `private`、`group`、`discuss`，分别对应私聊、群组、讨论组
        :param int user_id: 对方 QQ 号（消息类型为 `private` 时需要）
        :param int group_id: 群号（消息类型为 `group` 时需要）
        :param int discuss_id: 讨论组 ID（需要从上报消息中获取，消息类型为 `discuss` 时需要）
        :param str | list[ dict[ str, unknown ] ] message: 要发送的内容
        :param bool auto_escape: 消息内容是否作为纯文本发送（即不解析 CQ 码），`message` 数据类型为 `list` 时无效
        :return: {"message_id": int 消息ID}
        :rtype: dict[string, int]
        """
        return super().__getattr__('send_msg') \
            (message_type=message_type, user_id=user_id, group_id=group_id,
             discuss_id=discuss_id, message=message, auto_escape=auto_escape)

    def send_msg_async(self, *, message_type, user_id=None, group_id=None, discuss_id=None, message, auto_escape=False):
        """
        发送消息 (异步版本)

        ------------

        :param str message_type: 消息类型，支持 `private`、`group`、`discuss`，分别对应私聊、群组、讨论组
        :param int user_id: 对方 QQ 号（消息类型为 `private` 时需要）
        :param int group_id: 群号（消息类型为 `group` 时需要）
        :param int discuss_id: 讨论组 ID（需要从上报消息中获取，消息类型为 `discuss` 时需要）
        :param str | list[ dict[ str, unknown ] ] message: 要发送的内容
        :param bool auto_escape: 消息内容是否作为纯文本发送（即不解析 CQ 码），`message` 数据类型为 `list` 时无效
        :return: None
        :rtype: None
        """
        return super().__getattr__('send_msg_async') \
            (message_type=message_type, user_id=user_id, group_id=group_id,
             discuss_id=discuss_id, message=message, auto_escape=auto_escape)

    def delete_msg(self, *, message_id):
        """
        撤回消息

        ------------

        :param int message_id: 消息 ID
        :return: None
        :rtype: None
        """
        return super().__getattr__('delete_msg') \
            (message_id=message_id)

    def send_like(self, *, user_id, times=1):
        """
        发送好友赞

        ------------

        :param int user_id: 对方 QQ 号
        :param int times: 赞的次数，每个好友每天最多 10 次
        :return: None
        :rtype: None
        """
        return super().__getattr__('send_like') \
            (user_id=user_id, times=times)

    def set_group_kick(self, *, group_id, user_id, reject_add_request=False):
        """
        群组踢人

        ------------

        :param int group_id: 群号
        :param int user_id: 要踢的 QQ 号
        :param bool reject_add_request: 拒绝此人的加群请求
        :return: None
        :rtype: None
        """
        return super().__getattr__('set_group_kick') \
            (group_id=group_id, user_id=user_id, reject_add_request=reject_add_request)

    def set_group_ban(self, *, group_id, user_id, duration=30 * 60):
        """
        群组单人禁言

        ------------

        :param int group_id: 群号
        :param int user_id: 要禁言的 QQ 号
        :param int duration: 禁言时长，单位秒，0 表示取消禁言
        :return: None
        :rtype: None
        """
        return super().__getattr__('set_group_ban') \
            (group_id=group_id, user_id=user_id, duration=duration)

    def set_group_anonymous_ban(self, *, group_id, flag, duration=30 * 60):
        """
        群组匿名用户禁言

        ------------

        :param int group_id: 群号
        :param str flag: 要禁言的匿名用户的 flag（需从群消息上报的数据中获得）
        :param int duration: 禁言时长，单位秒，**无法取消匿名用户禁言**
        :return: None
        :rtype: None
        """
        return super().__getattr__('set_group_anonymous_ban') \
            (group_id=group_id, flag=flag, duration=duration)

    def set_group_whole_ban(self, *, group_id, enable=True):
        """
        群组全员禁言

        ------------

        :param int group_id: 群号
        :param bool enable: 是否禁言
        :return: None
        :rtype: None
        """
        return super().__getattr__('set_group_whole_ban') \
            (group_id=group_id, enable=enable)

    def set_group_admin(self, *, group_id, user_id, enable=True):
        """
        群组设置管理员

        ------------

        :param int group_id: 群号
        :param user_id: 要设置管理员的 QQ 号
        :param enable: True 为设置，False 为取消
        :return: None
        :rtype: None
        """
        return super().__getattr__('set_group_admin') \
            (group_id=group_id, user_id=user_id, enable=enable)

    def set_group_anonymous(self, *, group_id, enable=True):
        """
        群组匿名

        ------------

        :param int group_id: 群号
        :param bool enable: 是否允许匿名聊天
        :return: None
        :rtype: None
        """
        return super().__getattr__('set_group_anonymous') \
            (group_id=group_id, enable=enable)

    def set_group_card(self, *, group_id, user_id, card=None):
        """
        设置群名片（群备注）

        ------------

        :param int group_id: 群号
        :param int user_id: 要设置的 QQ 号
        :param str | None card: 群名片内容，不填或空字符串表示删除群名片
        :return: None
        :rtype: None
        """
        return super().__getattr__('set_group_card') \
            (group_id=group_id, user_id=user_id, card=card)

    def set_group_leave(self, *, group_id, is_dismiss=False):
        """
        退出群组

        ------------

        :param int group_id: 群号
        :param bool is_dismiss: 是否解散，如果登录号是群主，则仅在此项为 true 时能够解散
        :return: None
        :rtype: None
        """
        return super().__getattr__('set_group_leave') \
            (group_id=group_id, is_dismiss=is_dismiss)

    def set_group_special_title(self, *, group_id, user_id, special_title, duration=-1):
        """
        设置群组专属头衔

        ------------

        :param int group_id: 群号
        :param int user_id: 要设置的 QQ 号
        :param str special_title: 专属头衔，不填或空字符串表示删除专属头衔，只能保留前6个英文与汉字，Emoji 根据字符实际字符长度占用只能放最多3个甚至更少，超出长度部分会被截断
        :param int duration: 专属头衔有效期，单位秒，-1 表示永久，不过此项似乎没有效果，可能是只有某些特殊的时间长度有效，有待测试
        :return: None
        :rtype: None
        """
        return super().__getattr__('set_group_special_title') \
            (group_id=group_id, user_id=user_id, special_title=special_title, duration=duration)

    def set_discuss_leave(self, *, discuss_id):
        """
        退出讨论组

        ------------

        :param int discuss_id: 讨论组 ID（正常情况下看不到，需要从讨论组消息上报的数据中获得）
        :return: None
        :rtype: None
        """
        return super().__getattr__('set_discuss_leave') \
            (discuss_id=discuss_id)

    def set_friend_add_request(self, *, flag, approve=True, remark=None):
        """
        处理加好友请求

        ------------

        :param str flag: 加好友请求的 flag（需从上报的数据中获得）
        :param bool approve: 是否同意请求
        :param str remark: 添加后的好友备注（仅在同意时有效）
        :return: None
        :rtype: None
        """
        return super().__getattr__('set_friend_add_request') \
            (flag=flag, approve=approve, remark=remark)

    def set_group_add_request(self, *, flag, type, approve=True, reason=None):
        """
        处理加群请求、群组成员邀请

        ------------

        :param str flag: 加群请求的 flag（需从上报的数据中获得）
        :param str type: `add` 或 `invite`，请求类型（需要和上报消息中的 `sub_type` 字段相符）
        :param bool approve: 是否同意请求/邀请
        :param str reason: 拒绝理由（仅在拒绝时有效）
        :return: None
        :rtype: None
        """
        return super().__getattr__('set_group_add_request') \
            (flag=flag, type=type, approve=approve, reason=reason)

    def get_login_info(self):
        """
        获取登录号信息

        ------------

        :return: { "user_id": (QQ 号: int), "nickname": (QQ 昵称: str) }
        :rtype: dict[ str, int | str ]

        ------------

        =========  =========  =========
        响应数据
        -------------------------------
        数据类型   字段名      说明
        =========  =========  =========
        int        user_id    QQ 号
        str        nickname   QQ 昵称
        =========  =========  =========
        """
        return super().__getattr__('get_login_info') \
            ()

    def get_stranger_info(self, *, user_id, no_cache=False):
        """
        获取陌生人信息

        ------------

        :param int user_id: QQ 号（不可以是登录号）
        :param bool no_cache: 是否不使用缓存（使用缓存可能更新不及时，但响应更快）
        :return: { "user_id": (QQ 号: int), "nickname": (昵称: str), "sex": (性别: str in ['male', 'female', 'unknown']), "age": (年龄: int) }
        :rtype: dict[ str, int | str ]

        ------------

        ========  =========  ======================================
        响应数据
        -----------------------------------------------------------
        数据类型  字段名     说明
        ========  =========  ======================================
        int       user_id    QQ 号
        str       nickname   昵称
        str       sex        性别，`male` 或 `female` 或 `unknown`
        int       age        年龄
        ========  =========  ======================================

        """
        return super().__getattr__('get_stranger_info') \
            (user_id=user_id, no_cache=no_cache)

    def get_group_list(self):
        """
        获取群列表

        ------------

        :return: [{ "group_id": (群号: int), "group_name": (群名称: str) }, ...]
        :rtype: list[ dict[ str, int | str ] ]

        ------------

        ========  ===========  =========
        响应数据
        --------------------------------
        数据类型  字段名       说明
        ========  ===========  =========
        int       group_id     群号
        str       group_name   群名称
        ========  ===========  =========

        """
        return super().__getattr__('get_group_list') \
            ()

    def get_group_member_info(self, *, group_id, user_id, no_cache=False):
        """
        获取群成员信息

        ------------

        :param int group_id: 群号
        :param int user_id: QQ 号（不可以是登录号）
        :param bool no_cache: 是否不使用缓存（使用缓存可能更新不及时，但响应更快）
        :return: { "group_id": (群号: int), "user_id": (QQ 号: int), "nickname": (昵称: str), "card": (群名片/备注: str), "sex": (性别: str in ['male', 'female', 'unknown']), "age": (年龄: int), "area": (地区: str), "join_time": (加群时间戳: int), "last_sent_time": (最后发言时间戳: int), "level": (成员等级: str), "role": (角色: str in ['owner', 'admin', 'member']), "unfriendly": (是否不良记录成员: bool), "title": (专属头衔: str), "title_expire_time": (专属头衔过期时间戳: int), "card_changeable": (是否允许修改群名片: bool) }
        :rtype: dict[ str, int | str | bool ]

        ------------

        ========  ===================  ======================================
            响应数据
        ---------------------------------------------------------------------
        数据类型  字段名               说明
        ========  ===================  ======================================
        int       group_id             群号
        int       user_id              QQ 号
        str       nickname             昵称
        str       card                 群名片/备注
        str       sex                  性别，`male` 或 `female` 或 `unknown`
        int       age                  年龄
        str       area                 地区
        int       join_time            加群时间戳
        int       last_sent_time       最后发言时间戳
        str       level                成员等级
        str       role                 角色，`owner` 或 `admin` 或 `member`
        bool      unfriendly           是否不良记录成员
        str       title                专属头衔
        int       title_expire_time    专属头衔过期时间戳
        bool      card_changeable      是否允许修改群名片
        ========  ===================  ======================================
        """
        return super().__getattr__('get_group_member_info') \
            (group_id=group_id, user_id=user_id, no_cache=no_cache)

    def get_group_member_list(self, *, group_id):
        """
        获取群成员列表

        ------------

        :param int group_id: 群号
        :return: [{ "group_id": (群号: int), "user_id": (QQ 号: int), "nickname": (昵称: str), "card": (群名片/备注: str), "sex": (性别: str in ['male', 'female', 'unknown']), "age": (年龄: int), "area": (地区: str), "join_time": (加群时间戳: int), "last_sent_time": (最后发言时间戳: int), "level": (成员等级: str), "role": (角色: str in ['owner', 'admin', 'member']), "unfriendly": (是否不良记录成员: bool), "title": (专属头衔: str), "title_expire_time": (专属头衔过期时间戳: int), "card_changeable": (是否允许修改群名片: bool) }, ...]
        :rtype: list[ dict[ str, int | str | bool ] ]

        ------------

        响应数据以 **列表** 包装的字典的形式提供。`( List[ Dict[ ...] ] )`

        ========  ===================  ======================================
            响应数据
        ---------------------------------------------------------------------
        数据类型  字段名               说明
        ========  ===================  ======================================
        int       group_id             群号
        int       user_id              QQ 号
        str       nickname             昵称
        str       card                 群名片/备注
        str       sex                  性别，`male` 或 `female` 或 `unknown`
        int       age                  年龄
        str       area                 地区
        int       join_time            加群时间戳
        int       last_sent_time       最后发言时间戳
        str       level                成员等级
        str       role                 角色，`owner` 或 `admin` 或 `member`
        bool      unfriendly           是否不良记录成员
        str       title                专属头衔
        int       title_expire_time    专属头衔过期时间戳
        bool      card_changeable      是否允许修改群名片
        ========  ===================  ======================================

        **备注:** 响应内容为包含字典的列表 *( List[ Dict[] ] )* ，每个元素的内容和 `get_group_member_info` 接口相同，但对于同一个群组的同一个成员，获取列表时和获取单独的成员信息时，某些字段可能有所不同，例如 `area`、`title` 等字段在获取列表时无法获得，具体应以单独的成员信息为准。

        """
        return super().__getattr__('get_group_member_list') \
            (group_id=group_id)

    def get_cookies(self):
        """
        获取 Cookies

        ------------

        :return: { "cookies": (Cookies: str)}
        :rtype: dict[ str, str ]

        ------------

        ========  ===========  =========
        响应数据
        --------------------------------
        数据类型  字段名       说明
        ========  ===========  =========
        str       cookies      Cookies
        ========  ===========  =========

        """
        return super().__getattr__('get_cookies') \
            ()

    def get_csrf_token(self):
        """
        获取 CSRF Token

        ------------

        :return: { "token": (CSRF Token: int)}
        :rtype: dict[ str, int ]

        ------------

        ========  ===========  ==========
        响应数据
        ---------------------------------
        数据类型  字段名       说明
        ========  ===========  ==========
        int       token        CSRF Token
        ========  ===========  ==========

        """
        return super().__getattr__('get_csrf_token') \
            ()

    def get_record(self, *, file, out_format):
        """
        获取语音

        ------------

        :param str file: 收到的语音文件名，如 `0B38145AA44505000B38145AA4450500.silk`
        :param str out_format: 要转换到的格式，目前支持 `mp3`、`amr`、`wma`、`m4a`、`spx`、`ogg`、`wav`、`flac`
        :return: { "file": (转换后的语音文件名: str)}
        :rtype: dict[ str, str ]


        ------------

        其实并不是真的获取语音，而是转换语音到指定的格式，然后返回语音文件名（`data/record` 目录下）。

        ========  ===========  =============================================================
        响应数据
        ------------------------------------------------------------------------------------
        数据类型   字段名       说明
        ========  ===========  =============================================================
        str       file          转换后的语音文件名，如 `0B38145AA44505000B38145AA4450500.mp3`
        ========  ===========  =============================================================

        """
        return super().__getattr__('get_record') \
            (file=file, out_format=out_format)

    def get_status(self):
        """
        获取插件运行状态

        ------------

        :return: { "good": (正常运行: bool), "app_initialized": (插件已初始化: bool), "app_enabled": (插件已启用: bool), "online": (当前QQ在线: bool), "http_service_good": (HTTP服务正常运行: bool), "ws_service_good": (WebSocket服务正常运行: bool), "ws_reverse_service_good": (反向WebSocket服务正常运行: bool) }
        :rtype: dict[ str, bool ]

        ------------

        ========  ========================  ====================================
        响应数据
        ------------------------------------------------------------------------
        数据类型  字段名                    说明
        ========  ========================  ====================================
        bool      good                      插件状态符合预期，意味着插件已初始化，需要启动的服务都在正常运行，且 QQ 在线
        bool      app_initialized           插件已初始化
        bool      app_enabled               插件已启用
        bool      online                    当前 QQ 在线
        bool      http_service_good         `use_http` 配置项为 `yes` 时有此字段，表示 HTTP 服务正常运行
        bool      ws_service_good           `use_ws` 配置项为 `yes` 时有此字段，表示 WebSocket 服务正常运行
        bool      ws_reverse_service_good   `use_ws_reverse` 配置项为 `yes` 时有此字段，表示反向 WebSocket 服务正常运行
        ========  ========================  ====================================
        """
        return super().__getattr__('get_status') \
            ()

    def get_version_info(self):
        """
        获取酷 Q 及 HTTP API 插件的版本信息

        ------------

        :return: { "coolq_directory": (酷Q根目录路径: str), "coolq_edition": (酷Q版本: str in ['air', 'pro']), "plugin_version": (API插件版本: str), "plugin_build_number": (API插件build号: int), "plugin_build_configuration": (API插件编译配置: str in ['debug', 'release']) }
        :rtype: dict[ str, int | str ]


        ------------

        ========  ==========================  ===============================
        响应数据
        ---------------------------------------------------------------------
        数据类型  字段名                      说明
        ========  ==========================  ===============================
        str       coolq_directory             酷 Q 根目录路径
        str       coolq_edition               酷 Q 版本，`air` 或 `pro`
        str       plugin_version              HTTP API 插件版本，例如 2.1.3
        int       plugin_build_number         HTTP API 插件 build 号
        str       plugin_build_configuration  HTTP API 插件编译配置，`debug` 或 `release`
        ========  ==========================  ===============================
        """
        return super().__getattr__('get_version_info') \
            ()

    def set_restart(self):
        """
        重启酷 Q，并以当前登录号自动登录（需勾选快速登录）

        ------------

        :return: None
        :rtype: None
        """
        return super().__getattr__('set_restart') \
            ()

    def set_restart_plugin(self):
        """
        重启 HTTP API 插件

        ------------

        :return: None
        :rtype: None

        ------------

        由于重启插件同时需要重启 API 服务，这意味着当前的 API 请求会被中断，因此这个接口会延迟 2 秒重启插件，接口返回的 status 是 async。

        **在Python SDK中返回 None 。**
        """
        return super().__getattr__('set_restart_plugin') \
            ()

    def clean_data_dir(self, *, data_dir):
        """
        清理数据目录

        ------------

        :param str data_dir: 收到清理的目录名，支持 `image`、`record`、`show`、`bface`
        :return: None
        :rtype: None

        ------------

        用于清理积攒了太多旧文件的数据目录，如 `image`。

        HTTP API v3.3.4 新增
        """
        return super().__getattr__('clean_data_dir') \
            (data_dir=data_dir)

    def clean_data_dir_async(self, *, data_dir):
        """
        清理数据目录 (异步版本)

        ------------

        :param str data_dir: 收到清理的目录名，支持 `image`、`record`、`show`、`bface`
        :return: None
        :rtype: None

        ------------

        用于清理积攒了太多旧文件的数据目录，如 `image`。

        HTTP API v3.3.4 新增
        """
        return super().__getattr__('clean_data_dir_async') \
            (data_dir=data_dir)

    def _get_friend_list(self):
        """
        获取好友列表 (实验性功能)

        ------------

        :return: [{ "friend_group_id": (好友分组 ID: int), "friend_group_name": (好友分组名称: str), "friends": (分组中的好友: [{ "nickname": (好友昵称: str), "remark": (好友备注: str), "user_id": (好友 QQ 号: int) }, ...]) }, ...]
        :rtype: list[ dict[ str, int | str | list[ dict[ str, int | str ] ] ] ]

        ------------

        响应数据以 **列表** 包装的字典的形式提供。`( List[ Dict[ ...] ] )`

        ========  ==================  ===============================
        响应数据
        -------------------------------------------------------------
        数据类型  字段名                      说明
        ========  ==================  ===============================
        int       friend_group_id     好友分组 ID
        str       friend_group_name   好友分组名称
        list      friends             分组中的好友
        ========  ==================  ===============================

        其中，好友信息结构以 **字典** 的形式存储在响应数据中的分组中的好友 `friends` 的 **列表** 中。`( List[ Dict[ ...] ] )`

        ========  ==================  ===============================
        好友信息结构
        -------------------------------------------------------------
        数据类型  字段名                      说明
        ========  ==================  ===============================
        str       nickname            好友昵称
        str       remark              好友备注
        int       user_id             好友 QQ 号
        ========  ==================  ===============================

        """
        return super().__getattr__('_get_friend_list') \
            ()