twt233 / khl.py

Python SDK for kaiheila.cn API

khl.py

Python SDK for kookapp.cn(aka kaiheila.cn) API

Minimal Example

from khl import Bot, Message

# init Bot
bot = Bot(token='xxxxxxxxxxxxxxxxxxxxxxxxx')


# register command, send `/hello` in channel to invoke
@bot.command(name='hello')
async def world(msg: Message):
    await msg.reply('world!')


# everything done, go ahead now!
bot.run()
# now invite the bot to a server, and send '/hello' in any channel
# (remember to grant the bot with read & send permissions)

INSTALL

requirement: Python >= 3.6.8

pip install khl.py

Documentation

• Guide (authored by musnows)
• Example
• Wiki (archived FAQ)

if your question has not been listed yet, please create a issue or join our talk channel for help

CONTRIBUTING

welcome! we are glad to get help from community hands, and don't be shy to show your code, we can improve it together even if it's not perfect right now

if there is any bug/perf/feature request, we are willing to deal with your issue/pull request!

khl.py's Issues

设置单个命令的exc_handlers会导致其他命令报错

Describe the bug
根据 #231 这里的描述，我在其中一个命令中注册了通用错误处理器，但是在另外一个命令中，在正确执行命令后，又必定匹配到 khl.command.exception.Exceptions.Lexer.NotMatched 的错误，导致回复异常消息

To Reproduce
最小demo为：

async def common_error_handler(cmd: command.Command, exc: Exception, msg: Message):
    logger.error(f"Command {cmd.name} raised an exception: {exc}")
    if isinstance(exc, Exceptions.Handler.ArgLenNotMatched):
        cm = CardTemplate.warning_card(
            card_title="参数长度错误",
            main_modules=[
                Module.Section("请检查命令是否正确"),
                Module.Section("如果你不知道应该如何使用，请查看文档"),
            ],
        )
    elif isinstance(exc, ArgParseError):
        cm = CardTemplate.warning_card(
            card_title="参数解析错误",
            main_modules=[
                Module.Section(f"**错误**：{exc}"),
                Module.Section("如果你不知道应该如何使用，请查看文档"),
            ],
        )
    else:
        cm = CardTemplate.danger_card(
            card_title="发生了一个未知错误",
            main_modules=[
                Module.Section(f"发生了一个未知错误：{type(exc)} {exc}"),
                Module.Section("请重试。如果无法解决，请联系开发者"),
            ],
        )
    await msg.reply(cm.get_card_message())


default_exc_handlers: dict[Any, TypeEHandler] = {
    Exception: common_error_handler,
}

@bot.command(
      name="直播",
      aliases=["live"],
      exc_handlers=common.default_exc_handlers,
  )
async def set_live(message: PublicMessage, cmd: str, room_id: str, notify_role: str = ""):
  ...

@bot.command(
      name="帮助",
      aliases=["help"],
  )
async def help(msg: Message):
    ...

此时，我调用 /prefix 帮助时，会回复两个命令，一个是正常的帮助回复，一个是通用错误处理器里的错误，并得到日志：

Expected behavior
在单个命令中设置exc_handlers不会影响到其他命令

Logs/Screenshots

报错是

2024-05-04 13:38:50.882 | ERROR    | wtbot.kook.commands.common:common_error_handler:12 - Command 直播 raised an exception: 

Environment

• Python version: 3.11
• khl.py version: 0.3.17
• OS: Windows, Linux

Additional context
Add any other context about the problem here.

[Deprecated/弃用] PytzUsageWarning: The localize method is no longer necessary

Bug 描述
在代码中引入了Botmarket刷新任务后，启动Bot出现警告，提示方法已弃用。
警告内容：

Python\Python38\lib\site-packages\apscheduler\util.py:428: PytzUsageWarning: The localize method is no longer necessary, as this time zone supports the fold attribute (PEP 495). For more details on migrating to a PEP 495-compliant implementation, see https://pytz-deprecation-shim.readthedocs.io/en/latest/migration.html
  return tzinfo.localize(dt)

To Reproduce
引入以下代码:

@bot.task.add_interval(minutes=20)
async def botmarket_ping_task():
    api = "http://bot.gekj.net/api/v1/online.bot"
    headers = {'uuid': f"{bot_config['market_uuid']}"}
    async with aiohttp.ClientSession() as session:
        await session.post(api, headers=headers)
    Log.info(
        f'[Botmarket] 刷新了在线状态')

Expected behavior
将apscheduler更换为支持PEP 495标准的库
增加关于cron_job的教程（之前的教程很不错，辛苦了）

Environment

• Python version: 3.8
• khl.py version: Latest
• OS: Windows Server 2016 / Windows 10 21H2

想问下如何向频道里加入机器人命令提示

Describe the bug
想问下如何向频道里加入机器人命令提示

比如打个</>后能提示出机器人支持的所有命令

是否支持无定义命令

是否支持无定义命令，形如

@bot.command(name='', prefixes=[[".bot"]])
    async def default(msg: Message):
        await msg.reply("Hello, I'm Kook!")

预想的情况是，这样定义时，能在消息仅匹配了prefix的条件下匹配到

.bot 

时触发

The custom parser feature is completely broken

Describe the bug
The Parser.register method requires the parser passed in to be non-async and have only 1 parameter with str type. However, even if I passed in the correct type of parser, khl.command.exception.Exceptions.Parser.ParseFailed would still be raised.

Possible cause
In this (khl/command/parser.py) file, the default parsers have 3 parameters like (Message, Client, str) -> Type. Both async and non-async functions are acceptable as well. The Parser.parse method calls the parsers like func(msg, client, token), which conflicts with the Parser.register requirements. The async check in Parser.register should be removed and the parameter check should be fixed.

To Reproduce

from khl.command import Parser

def parser_bool(token: str) -> bool:
    return bool(token)

class CustomParser(Parser):

    def __init__(self) -> None:
        super().__init__()
        self.register(parser_bool)

CUSTOM_PARSER: CustomParser = CustomParser()

And use the parser in @bot.command.

Expected behavior
Either the function above can be accepted, or change the requirements so that I can pass such functions as these two in, whose parameter types are the same as those of default ones.

def parser_bool(message: Message, client: Client, token: str) -> bool:
    return bool(token)

async def parser_bool_async(message: Message, client: Client, token: str) -> bool:
    return bool(token)

Logs/Screenshots
Registration failures:

  File "D:\Program Files\Python\3.10.7\lib\site-packages\khl\command\parser.py", line 114, in register
    raise TypeError('parse function should not be async')
TypeError: parse function should not be async

  File "D:\Program Files\Python\3.10.7\lib\site-packages\khl\command\parser.py", line 116, in register
    raise TypeError('parse function should own only one param, and the param type is str')
TypeError: parse function should own only one param, and the param type is str

Parse failures (successfully registered (str) -> Type functions):

Traceback (most recent call last):
  File "D:\Program Files\Python\3.10.7\lib\site-packages\khl\command\command.py", line 139, in handle
    parsed_args = await self.parser.parse(msg, client, self.lexer.lex(msg), to_be_parsed)
  File "D:\Program Files\Python\3.10.7\lib\site-packages\khl\command\parser.py", line 98, in parse
    raise Exceptions.Parser.ParseFailed(param, token, func, e)
khl.command.exception.Exceptions.Parser.ParseFailed

Environment

• Python version: 3.10.7
• khl.py version: 0.3.13
• OS: Windows 11 Home

Additional context

@bot.command( rules=[Rule.is_bot_mentioned(bot)]) not triggered

The following code in ex 6 dose not triggered:

@bot.command( rules=[Rule.is_bot_mentioned(bot)])
async def world(msg: Message, mention_str: str):
await msg.reply(f'world! I am mentioned with {mention_str}')

mypy扫描提示错误：error: Skipping analyzing "khl": module is installed, but missing library stubs or py.typed marker

Describe the bug
mypy扫描提示错误：error: Skipping analyzing "khl": module is installed, but missing library stubs or py.typed marker

To Reproduce

mypy ./folder

Expected behavior
根据错误提示，

note: See https://mypy.readthedocs.io/en/stable/running_mypy.html#missing-imports

可知，这类问题是因为库未类型化引起的。

是否有计划增加类型化处理，来避免这个扫描错误？

Logs/Screenshots

Environment

• Python version: 3.12
• khl.py version: 0.3.17
• OS: Windows

Additional context
此外，用vscode似乎无法自动 from khl import xxx，似乎也是这个问题导致的

请问exp05和06的readme教程是暂时下线了吗

非常感谢大佬的教程，我这个没学过py的感觉都能搞定了
不过我这里没看到exp05和06的教程readme（05的有但是不完整的样子），是暂时下线了吗？

api.ChannelRole.update 无法更新 role_id=0 (@全体成员)的权限

khl.requester.HTTPRequester.APIRequestFailed: ('POST', 'channel-role/update', {'data': {'channel_id': '6686856781955880', 'type': 'role_id', 'value': 0, 'allow': 0, 'deny': 2048}, 'headers': {'Authorization': 'Bot *'}}, 40000, '服务器角色不存在或者你没有权限操作')

我本以为是API问题，但是我手动用postman发送请求提示成功，如图所示

这是什么问题？？？？？？？？

No closing quotation

[INFO] 2021-06-23 15:45:17,652 @ khl.Bot(run): launching
Task exception was never retrieved
future: <Task finished name='Task-8' coro=<Bot._event_handler.._dispatch_msg() done, defined at C:\Users\Administrator\AppData\Local\Programs\Python\Python38\lib\site-packages\khl\bot.py:104> exception=ValueError('No
closing quotation')>
Traceback (most recent call last):
File "C:\Users\Administrator\AppData\Local\Programs\Python\Python38\lib\site-packages\khl\bot.py", line 115, in _dispatch_msg
await self._cmd_handler(m)
File "C:\Users\Administrator\AppData\Local\Programs\Python\Python38\lib\site-packages\khl\bot.py", line 89, in _cmd_handler
(msg, raw_cmd) = parser(msg, self.cmd_prefix)
File "C:\Users\Administrator\AppData\Local\Programs\Python\Python38\lib\site-packages\khl\parser.py", line 11, in parser
raw_cmd = shlex.split(msg.content[len(prefix):])
File "C:\Users\Administrator\AppData\Local\Programs\Python\Python38\lib\shlex.py", line 311, in split
return list(lex)
File "C:\Users\Administrator\AppData\Local\Programs\Python\Python38\lib\shlex.py", line 300, in next
token = self.get_token()
File "C:\Users\Administrator\AppData\Local\Programs\Python\Python38\lib\shlex.py", line 109, in get_token
raw = self.read_token()
File "C:\Users\Administrator\AppData\Local\Programs\Python\Python38\lib\shlex.py", line 191, in read_token
raise ValueError("No closing quotation")
ValueError: No closing quotation

@bot.command(name = 'music')
async def music(msg:TextMsg, *args):

args里如果出现‘则会出现报错

ImportError: cannot import name 'Types' from 'khl.card'

Describe the bug
ImportError: cannot import name 'Types' from 'khl.card'

To Reproduce
ImportError: cannot import name 'Types' from 'khl.card'

Expected behavior
should work fine

Environment

• Python version:3.7.6
• khl.py version: 0.2.3

怎么删除主动发送在频道中的消息？

形如 ret = await ch.send(“Hello")，可以从ret中拿到msg_id，接着我应该使用哪个方法删除掉这条消息

Kook开放了官方的语音相关接口

如题 只不过现在还在测试罢了
语音相关接口

接口request: 点击「反应」自动给user添加身份

如图:

PublicVoiceChannel 类中的 fetch_user_list 函数实现有误

Describe the bug
使用 fetch_user_list 报错

To Reproduce

if not isinstance(public_channel, PublicVoiceChannel):
    return

users = await public_channel.fetch_user_list()

Expected behavior
正常获取到语音频道用户列表

Logs/Screenshots
报错如下：

Traceback (most recent call last):
  File "\venv\lib\site-packages\khl\client.py", line 112, in safe_handler
    await handler(msg)
  File "\venv\lib\site-packages\khl\bot\bot.py", line 142, in handler
    await event_handler(self, event)
  File "\plugins\kook\__init__.py", line 49, in handle_kook_join_channel
    users = await public_channel.fetch_user_list()
  File "\venv\lib\site-packages\khl\channel.py", line 183, in fetch_user_list
    users = await self.gate.exec_paged_req(api.Channel.userList(channel_id=self.id))
  File "\venv\lib\site-packages\khl\gateway.py", line 34, in exec_paged_req
    return await self.requester.exec_paged_req(r, **kwargs)
  File "\venv\lib\site-packages\khl\requester.py", line 81, in exec_paged_req
    ret.extend(p['items'])
TypeError: list indices must be integers or slices, not str

Environment

• Python version: 3.10
• khl.py version: 0.3.13
• OS: Windows 11 x64

Additional context
/api/v3/channel/user-list 接口返回格式为：

{
    "code": 0,
    "message": "操作成功",
    "data": [
        {
            "id": "999999999",
            "username": "XXX",
            "identify_num": "9999",
            "online": true,
            "os": "Websocket",
            "status": 1,
            "avatar": "XXX",
            "vip_avatar": "XXX",
            "banner": "",
            "nickname": "XXX",
            "roles": [
                4131873
            ],
            "is_vip": false,
            "is_ai_reduce_noise": true,
            "is_personal_card_bg": false,
            "bot": false,
            "mobile_verified": true,
            "joined_at": 1639808384000,
            "active_time": 1639808384000,
            "live_info": {
                "in_live": false,
                "audience_count": 0,
                "live_thumb": "",
                "live_start_time": 0
            }
        }
    ]
}

而 khl 中调用 requester.py 中的 exec_paged_req 函数，data 部分实际上为 list，exec_paged_req 按照 dict 处理，取 p['items']，因此报错 TypeError: list indices must be integers or slices, not str

Unexpected decompress error

data = self.compress and zlib.decompress(data) or data
TypeError: a bytes-like object is required, not 'str'

Temporary solution:
try:
req_json = self.__raw_2_req(msg.data)
except Exception as e:
logging.error(e)
return

上传mp4文件的时候报错

Describe the bug
场景：使用bot.client.create_asset上传视频.mp4文件的时候报错。
报错内容：Requesting 'POST asset/create' failed with 40000: Width必须是整数。
报错堆栈：Traceback (most recent call last):
File "C:\Users\Administrator\Downloads_***_bots\kook_bot\kook_bot.py", line 207, in h4
file_url = await bot.client.create_asset(path_to_load) # 上传测试文件
File "C:\Users\Administrator\AppData\Local\Programs\Python\Python310\lib\site-packages\khl\client.py", line 126, in create_asset
return (await self.gate.exec_req(api.Asset.create(file=f)))['url']
File "C:\Users\Administrator\AppData\Local\Programs\Python\Python310\lib\site-packages\khl\gateway.py", line 30, in exec_req
return await self.requester.exec_req(r)
File "C:\Users\Administrator\AppData\Local\Programs\Python\Python310\lib\site-packages\khl\requester.py", line 48, in exec_req
return await self.request(r.method, r.route, **r.params)
File "C:\Users\Administrator\AppData\Local\Programs\Python\Python310\lib\site-packages\khl\requester.py", line 39, in request
raise HTTPRequester.APIRequestFailed(method, route, params, rsp['code'], rsp['message'])
khl.requester.HTTPRequester.APIRequestFailed: Requesting 'POST asset/create' failed with 40000: Width必须是整数。

Expected behavior
正常的上传文件

Environment

• Python version:3.10.9
• khl.py version:0.3.17
• OS:windows

报错分析
传递给服务器中的请求的headers中content-type字段缺少boundary字段，原因是khl/requester.py中的第471行为
@req('POST', headers={'Content-Type': 'multipart/form-data'})
指定了content-type。

推荐解决办法
将@req('POST', headers={'Content-Type': 'multipart/form-data'})改为@req('POST')，此时程序会自动指定content-type字段

开发时与部署时 命令不带参数的行为不一致

Describe the bug
我的两个环境的@bot.command()的表现行为不一致
开发环境使用的是 WSL2 Ubuntu22.04
部署环境是腾讯云 Ubuntu20.04
python3 和 khl.py的版本一致

@bot.command(name="hideout_all", aliases=["藏身处满级"])
@log(command="hideout_all")
async def ta_price(msg: Message, version: str = ""):
    if not version:
        await msg.channel.send("当前未输入版本，默认为黑边(仓库满级不做计算) 如果需要修改 /藏身处满级 白边")
    pass

To Reproduce

git clone https://github.com/is-a-gamer/sticky_rice_bot.git
cd sticky_rice_bot
python3 -m venv venv
source ./venv/bin/activate
pip install -r requirements.txt
# vim .env
python3 startup.py

Expected behavior

在开发环境， 也就是WSL2中，当我输入/hideout_all时，机器人提醒我当前未输入版本
当我部署到腾讯云上时，直接输入/hideout_all无任何返回，查看后台，出现报错

Logs/Screenshots

Environment

• Python version: 3.10.12
• khl.py version: 0.3.16

async def on_command方法中创建的实例不会销毁

Describe the bug
我参考了文档定义了一个函数，用于在多文件条件下维护命令，我的定义如下：

def init_system_command(bot: Bot, controller: SystemController):
    @bot.command(name="help", aliases=["帮助"])
    async def help(msg: Message):
        cm = CardTemplate(card_title="帮助信息")
        cm.add_module(
            Module.Section(
                "这是一个帮助信息",
            )
        )
        await msg.reply(cm.get_card_message())

在main文件中我这样注册他

bot = Bot(token=token)
system_controller = SystemController()
init_system_command(bot, system_controller)

而 CardTemplate定义如下：

class CardTemplate:
    _default_card_footer = [
        Module.Divider(),
    ]

    def __init__(
        self,
        card_title: str,
        main_modules: list = [],
        theme: Types.Theme = Types.Theme.SUCCESS,
        size: Types.Size = Types.Size.LG,
    ):
        self._card_title = card_title
        self._main_modules = main_modules
        self._theme = theme
        self._size = size

    def _generate_card_header(self):
        return [
            Module.Header(self._card_title),
            Module.Divider(),
        ]

    def add_module(self, module: Module):
        self._main_modules.append(module)

    def get_card_message(self) -> CardMessage:
        cm = CardMessage()
        c = Card(
            theme=self._theme,
            size=self._size,
            *self._generate_card_header(),
            *self._main_modules,
            *self._default_card_footer,
        )
        cm.append(c)
        logger.debug("card message is {}", json.dumps(cm, ensure_ascii=False))
        return cm

但是当我触发了两次help命令时，第一次是输出

...卡片略...
帮助信息
...卡片略...

第二次触发help是输出

...卡片略...
帮助信息
帮助信息
...卡片略...

第N次就是输出N条帮助信息

这是否意味着cm这个实例没有正确销毁？

To Reproduce
提供了一个最小demo，见 https://gist.github.com/axiangcoding/c96e2e82369cfece2bde8874229a83f0

Expected behavior
cm 应当正常销毁，add_module应该是永远给新创建的实例添加内容？

Logs/Screenshots
If applicable, add logs or screenshots to help explain your problem.

Environment

• Python version: 3.11
• khl.py version: 0.3.17
• OS: Windows

Additional context
Add any other context about the problem here.

建议: 加入类似于aiocqhttp的快速处理功能

在实际编写代码的过程中, 有部分命令会在参数错误的时候提示用户, 但是单纯使用bot.reply()方法的时候会让后续代码继续运行.
为了达到需要的效果, 往往bot.reply()方法后面跟一个return None.

建议: 参考aiocqhtto, 允许直接在return里面返回需要的操作, 类似于这样:
return {"reply": "参数输入有误!", is_temp: True}

Error when receiving picture

An exception occurred when the robot received a picture.

Error message:

Task exception was never retrieved
future: <Task finished name='Task-33' coro=<Bot._event_handler.<locals>._dispatch_msg() done, defined at D:\Python\Python39\lib\site-packages\khl\bot.py:104> exception=AttributeError("'NoneType' object has no attribute 'type'")>
Traceback (most recent call last):
  File "D:\Python\Python39\lib\site-packages\khl\bot.py", line 107, in _dispatch_msg
    if m.type == Msg.Types.SYS:
AttributeError: 'NoneType' object has no attribute 'type'

How to reproduce:

Just send a picture

Operating environment:

OS: Windows 10.0.19043.1151
Python v3.9.5:0a7dcbd
khl.py 0.0.9

TimeZone Error Problem

Describe the bug
When running the Minimal example in the README, timezone unkown error problem caused.

To Reproduce
null

Expected behavior
maybe the Bot class can add a timezone parameter or auto change timezone from beijing to shanghai.

Logs/Screenshots

Traceback (most recent call last):
  File "/home/user/Projects/Python/kook_chat/main.py", line 4, in <module>
    bot = Bot(token='1/MTQyMjM=/vJhMqBfaUly2XFiYCphTlQ==')
  File "/home/user/app/anaconda3/envs/kook/lib/python3.9/site-packages/khl/bot/bot.py", line 74, in __init__
    self.task = TaskManager()
  File "/home/user/app/anaconda3/envs/kook/lib/python3.9/site-packages/khl/task/manager.py", line 19, in __init__
    self._scheduler = AsyncIOScheduler()
  File "/home/user/app/anaconda3/envs/kook/lib/python3.9/site-packages/apscheduler/schedulers/base.py", line 87, in __init__
    self.configure(gconfig, **options)
  File "/home/user/app/anaconda3/envs/kook/lib/python3.9/site-packages/apscheduler/schedulers/base.py", line 131, in configure
    self._configure(config)
  File "/home/user/app/anaconda3/envs/kook/lib/python3.9/site-packages/apscheduler/schedulers/asyncio.py", line 54, in _configure
    super(AsyncIOScheduler, self)._configure(config)
  File "/home/user/app/anaconda3/envs/kook/lib/python3.9/site-packages/apscheduler/schedulers/base.py", line 701, in _configure
    self.timezone = astimezone(config.pop('timezone', None)) or get_localzone()
  File "/home/user/app/anaconda3/envs/kook/lib/python3.9/site-packages/tzlocal/unix.py", line 203, in get_localzone
    _cache_tz = _get_localzone()
  File "/home/user/app/anaconda3/envs/kook/lib/python3.9/site-packages/tzlocal/unix.py", line 180, in _get_localzone
    tz = pds.timezone(tzname)
  File "/home/user/app/anaconda3/envs/kook/lib/python3.9/site-packages/pytz_deprecation_shim/_impl.py", line 41, in timezone
    raise get_exception(UnknownTimeZoneError, key)
pytz_deprecation_shim._exceptions._make_pytz_derived_errors.<locals>.UnknownTimeZoneError: 'Asia/Beijing'

Environment

• Python version: 3.9
• khl.py version: 0.3.11
• OS: Deepin 23

Additional context
null

是否支持通用错误拦截？

每个命令写拦截处理器太繁琐了，而且可能会漏掉一些没考虑到的错误，所以期望能做到一个通用拦截作为兜底处理。

接口Request: 点击「反应」自动给user添加身份

如图:

引号问题

消息出现引号就会报
ValueError: No closing quotation

命令函数都进不去，直接在command里报错

Kook对频道所有消息处理

rt
背景：在使用bot时有对非command的消息(全部消息）做处理的需求
描述：在文档以及demo中并未看到相关的讲解，想问下现在是否支持？如有支持求指个路谢谢

例如：将a频道的所有聊天记录进行分析，将违规的消息经过处理转到b频道中

How can instances of Bot be referenced in other modules in order to use @bot.command or another decorator

Besides manually registering commands using the CommandManager like this:

client.register(MessageTypes.TEXT, lambda msg: command.handle(loop, client, msg, {Message: msg, Bot: bot}))

What other methods can register commands in multi-module projects

error raised during websocket heartbeat after bot run over 10 hours

error raised during websocket heartbeat
Traceback (most recent call last):
File "khl\receiver.py", line 59, in heartbeat
File "aiohttp\client_ws.py", line 165, in send_json
File "aiohttp\client_ws.py", line 151, in send_str
File "aiohttp\http_websocket.py", line 690, in send
File "aiohttp\http_websocket.py", line 601, in _send_frame
ConnectionResetError: Cannot write to closing transport

KOOK图片接收

如何接受用户发出的图片呢？这让我一直很苦恼，图片发出后，不知道如何接收图片地址，而没法再次发出用户的图片 /cry
请求帮助 辛苦了