ElapsingDreams/LiteyukiBot
1
0
Fork 0
forked from LiteyukiStudio/LiteyukiBot
Code Pull Requests Activity

⬇️

Browse Source
This commit is contained in:
snowy 2024-08-29 13:50:12 +08:00
parent 3a3ef4d6ae
commit cb3ee4b72f
93 changed files with 1632 additions and 9271 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.github/workflows/deploy-docs.yml vendored
View File

@ -42,7 +42,9 @@ jobs:
- name: 生成API markdown
run: |-
python -m pip install pydantic
python liteyuki/mkdoc.py
python -m docs/litedoc liteyuki -o docs/api -l zh-Hans
python -m docs/litedoc liteyuki -o docs/en/api -l en
- name: 构建文档

8
docs/dev/README.md
View File

@ -1,8 +0,0 @@
---
title: 开发及贡献
index: false
icon: laptop-code
category: 开发
---
<Catalog />

7
docs/dev/api/README.md
View File

@ -1,7 +0,0 @@
---
title: liteyuki
index: true
icon: laptop-code
category: API
---

581
docs/dev/api/bot/README.md
View File

@ -1,581 +0,0 @@
---
title: liteyuki.bot
index: true
icon: laptop-code
category: API
---
### ***def*** `get_bot() -> LiteyukiBot`
获取轻雪实例
Returns:
LiteyukiBot: 当前的轻雪实例
<details>
<summary>源代码</summary>
```python
def get_bot() -> LiteyukiBot:
"""
获取轻雪实例
Returns:
LiteyukiBot: 当前的轻雪实例
"""
if IS_MAIN_PROCESS:
if _BOT_INSTANCE is None:
raise RuntimeError('Liteyuki instance not initialized.')
return _BOT_INSTANCE
else:
raise RuntimeError("Can't get bot instance in sub process.")
```
</details>
### ***def*** `get_config(key: str, default: Any) -> Any`
获取配置
Args:
key: 配置键
default: 默认值
Returns:
Any: 配置值
<details>
<summary>源代码</summary>
```python
def get_config(key: str, default: Any=None) -> Any:
"""
获取配置
Args:
key: 配置键
default: 默认值
Returns:
Any: 配置值
"""
return get_bot().config.get(key, default)
```
</details>
### ***def*** `get_config_with_compat(key: str, compat_keys: tuple[str], default: Any) -> Any`
获取配置，兼容旧版本
Args:
key: 配置键
compat_keys: 兼容键
default: 默认值
Returns:
Any: 配置值
<details>
<summary>源代码</summary>
```python
def get_config_with_compat(key: str, compat_keys: tuple[str], default: Any=None) -> Any:
"""
获取配置，兼容旧版本
Args:
key: 配置键
compat_keys: 兼容键
default: 默认值
Returns:
Any: 配置值
"""
if key in get_bot().config:
return get_bot().config[key]
for compat_key in compat_keys:
if compat_key in get_bot().config:
logger.warning(f'Config key "{compat_key}" will be deprecated, use "{key}" instead.')
return get_bot().config[compat_key]
return default
```
</details>
### ***def*** `print_logo() -> None`
<details>
<summary>源代码</summary>
```python
def print_logo():
print('\x1b[34m' + '\n __ ______ ________ ________ __ __ __ __ __ __ ______ \n / | / |/ |/ |/ \\ / |/ | / |/ | / |/ |\n $$ | $$$$$$/ $$$$$$$$/ $$$$$$$$/ $$ \\ /$$/ $$ | $$ |$$ | /$$/ $$$$$$/ \n $$ | $$ | $$ | $$ |__ $$ \\/$$/ $$ | $$ |$$ |/$$/ $$ | \n $$ | $$ | $$ | $$ | $$ $$/ $$ | $$ |$$ $$< $$ | \n $$ | $$ | $$ | $$$$$/ $$$$/ $$ | $$ |$$$$$ \\ $$ | \n $$ |_____ _$$ |_ $$ | $$ |_____ $$ | $$ \\__$$ |$$ |$$ \\ _$$ |_ \n $$ |/ $$ | $$ | $$ | $$ | $$ $$/ $$ | $$ |/ $$ |\n $$$$$$$$/ $$$$$$/ $$/ $$$$$$$$/ $$/ $$$$$$/ $$/ $$/ $$$$$$/ \n ' + '\x1b[0m')
```
</details>
### ***class*** `LiteyukiBot`
### &emsp; ***def*** `__init__(self) -> None`
&emsp;初始化轻雪实例
Args:
*args:
**kwargs: 配置
<details>
<summary>源代码</summary>
```python
def __init__(self, *args, **kwargs) -> None:
"""
初始化轻雪实例
Args:
*args:
**kwargs: 配置
"""
'常规操作'
print_logo()
global _BOT_INSTANCE
_BOT_INSTANCE = self
'配置'
self.config: dict[str, Any] = kwargs
'初始化'
self.init(**self.config)
logger.info('Liteyuki is initializing...')
'生命周期管理'
self.lifespan = Lifespan()
self.process_manager: ProcessManager = ProcessManager(lifespan=self.lifespan)
'事件循环'
self.loop = asyncio.new_event_loop()
asyncio.set_event_loop(self.loop)
self.stop_event = threading.Event()
self.call_restart_count = 0
'加载插件加载器'
load_plugin('liteyuki.plugins.plugin_loader')
'信号处理'
signal.signal(signal.SIGINT, self._handle_exit)
signal.signal(signal.SIGTERM, self._handle_exit)
atexit.register(self.process_manager.terminate_all)
```
</details>
### &emsp; ***def*** `run(self) -> None`
&emsp;启动逻辑
<details>
<summary>源代码</summary>
```python
def run(self):
"""
启动逻辑
"""
self.lifespan.before_start()
self.process_manager.start_all()
self.lifespan.after_start()
self.keep_alive()
```
</details>
### &emsp; ***def*** `keep_alive(self) -> None`
&emsp;保持轻雪运行
Returns:
<details>
<summary>源代码</summary>
```python
def keep_alive(self):
"""
保持轻雪运行
Returns:
"""
try:
while not self.stop_event.is_set():
time.sleep(0.5)
except KeyboardInterrupt:
logger.info('Liteyuki is stopping...')
self.stop()
```
</details>
### &emsp; ***def*** `restart(self, delay: int) -> None`
&emsp;重启轻雪本体
Returns:
<details>
<summary>源代码</summary>
```python
def restart(self, delay: int=0):
"""
重启轻雪本体
Returns:
"""
if self.call_restart_count < 1:
executable = sys.executable
args = sys.argv
logger.info('Restarting LiteyukiBot...')
time.sleep(delay)
if platform.system() == 'Windows':
cmd = 'start'
elif platform.system() == 'Linux':
cmd = 'nohup'
elif platform.system() == 'Darwin':
cmd = 'open'
else:
cmd = 'nohup'
self.process_manager.terminate_all()
threading.Thread(target=os.system, args=(f"{cmd} {executable} {' '.join(args)}",)).start()
sys.exit(0)
self.call_restart_count += 1
```
</details>
### &emsp; ***def*** `restart_process(self, name: Optional[str]) -> None`
&emsp;停止轻雪
Args:
name: 进程名称, 默认为None, 所有进程
Returns:
<details>
<summary>源代码</summary>
```python
def restart_process(self, name: Optional[str]=None):
"""
停止轻雪
Args:
name: 进程名称, 默认为None, 所有进程
Returns:
"""
self.lifespan.before_process_shutdown()
self.lifespan.before_process_shutdown()
if name is not None:
chan_active = get_channel(f'{name}-active')
chan_active.send(1)
else:
for process_name in self.process_manager.processes:
chan_active = get_channel(f'{process_name}-active')
chan_active.send(1)
```
</details>
### &emsp; ***def*** `init(self) -> None`
&emsp;初始化轻雪, 自动调用
Returns:
<details>
<summary>源代码</summary>
```python
def init(self, *args, **kwargs):
"""
初始化轻雪, 自动调用
Returns:
"""
self.init_logger()
```
</details>
### &emsp; ***def*** `init_logger(self) -> None`
&emsp;
<details>
<summary>源代码</summary>
```python
def init_logger(self):
init_log(config=self.config)
```
</details>
### &emsp; ***def*** `stop(self) -> None`
&emsp;停止轻雪
Returns:
<details>
<summary>源代码</summary>
```python
def stop(self):
"""
停止轻雪
Returns:
"""
self.stop_event.set()
self.loop.stop()
```
</details>
### &emsp; ***def*** `on_before_start(self, func: LIFESPAN_FUNC) -> None`
&emsp;注册启动前的函数
Args:
func:
Returns:
<details>
<summary>源代码</summary>
```python
def on_before_start(self, func: LIFESPAN_FUNC):
"""
注册启动前的函数
Args:
func:
Returns:
"""
return self.lifespan.on_before_start(func)
```
</details>
### &emsp; ***def*** `on_after_start(self, func: LIFESPAN_FUNC) -> None`
&emsp;注册启动后的函数
Args:
func:
Returns:
<details>
<summary>源代码</summary>
```python
def on_after_start(self, func: LIFESPAN_FUNC):
"""
注册启动后的函数
Args:
func:
Returns:
"""
return self.lifespan.on_after_start(func)
```
</details>
### &emsp; ***def*** `on_after_shutdown(self, func: LIFESPAN_FUNC) -> None`
&emsp;注册停止后的函数：未实现
Args:
func:
Returns:
<details>
<summary>源代码</summary>
```python
def on_after_shutdown(self, func: LIFESPAN_FUNC):
"""
注册停止后的函数：未实现
Args:
func:
Returns:
"""
return self.lifespan.on_after_shutdown(func)
```
</details>
### &emsp; ***def*** `on_before_process_shutdown(self, func: LIFESPAN_FUNC) -> None`
&emsp;注册进程停止前的函数，为子进程停止时调用
Args:
func:
Returns:
<details>
<summary>源代码</summary>
```python
def on_before_process_shutdown(self, func: LIFESPAN_FUNC):
"""
注册进程停止前的函数，为子进程停止时调用
Args:
func:
Returns:
"""
return self.lifespan.on_before_process_shutdown(func)
```
</details>
### &emsp; ***def*** `on_before_process_restart(self, func: LIFESPAN_FUNC) -> None`
&emsp;注册进程重启前的函数，为子进程重启时调用
Args:
func:
Returns:
<details>
<summary>源代码</summary>
```python
def on_before_process_restart(self, func: LIFESPAN_FUNC):
"""
注册进程重启前的函数，为子进程重启时调用
Args:
func:
Returns:
"""
return self.lifespan.on_before_process_restart(func)
```
</details>
### &emsp; ***def*** `on_after_restart(self, func: LIFESPAN_FUNC) -> None`
&emsp;注册重启后的函数：未实现
Args:
func:
Returns:
<details>
<summary>源代码</summary>
```python
def on_after_restart(self, func: LIFESPAN_FUNC):
"""
注册重启后的函数：未实现
Args:
func:
Returns:
"""
return self.lifespan.on_after_restart(func)
```
</details>
### &emsp; ***def*** `on_after_nonebot_init(self, func: LIFESPAN_FUNC) -> None`
&emsp;注册nonebot初始化后的函数
Args:
func:
Returns:
<details>
<summary>源代码</summary>
```python
def on_after_nonebot_init(self, func: LIFESPAN_FUNC):
"""
注册nonebot初始化后的函数
Args:
func:
Returns:
"""
return self.lifespan.on_after_nonebot_init(func)
```
</details>
### ***var*** `executable = sys.executable`
### ***var*** `args = sys.argv`
### ***var*** `chan_active = get_channel(f'{name}-active')`
### ***var*** `cmd = 'start'`
### ***var*** `chan_active = get_channel(f'{process_name}-active')`
### ***var*** `cmd = 'nohup'`
### ***var*** `cmd = 'open'`
### ***var*** `cmd = 'nohup'`

450
docs/dev/api/bot/lifespan.md
View File

@ -1,450 +0,0 @@
---
title: liteyuki.bot.lifespan
order: 1
icon: laptop-code
category: API
---
### ***def*** `run_funcs(funcs: list[LIFESPAN_FUNC | PROCESS_LIFESPAN_FUNC]) -> None`
运行函数
Args:
funcs:
Returns:
<details>
<summary>源代码</summary>
```python
@staticmethod
def run_funcs(funcs: list[LIFESPAN_FUNC | PROCESS_LIFESPAN_FUNC], *args, **kwargs) -> None:
"""
运行函数
Args:
funcs:
Returns:
"""
try:
loop = asyncio.get_event_loop()
except RuntimeError:
loop = asyncio.new_event_loop()
asyncio.set_event_loop(loop)
tasks = []
for func in funcs:
if is_coroutine_callable(func):
tasks.append(func(*args, **kwargs))
else:
tasks.append(async_wrapper(func)(*args, **kwargs))
loop.run_until_complete(asyncio.gather(*tasks))
```
</details>
### ***class*** `Lifespan`
### &emsp; ***def*** `__init__(self) -> None`
&emsp;轻雪生命周期管理，启动、停止、重启
<details>
<summary>源代码</summary>
```python
def __init__(self) -> None:
"""
轻雪生命周期管理，启动、停止、重启
"""
self.life_flag: int = 0
self._before_start_funcs: list[LIFESPAN_FUNC] = []
self._after_start_funcs: list[LIFESPAN_FUNC] = []
self._before_process_shutdown_funcs: list[LIFESPAN_FUNC] = []
self._after_shutdown_funcs: list[LIFESPAN_FUNC] = []
self._before_process_restart_funcs: list[LIFESPAN_FUNC] = []
self._after_restart_funcs: list[LIFESPAN_FUNC] = []
self._after_nonebot_init_funcs: list[LIFESPAN_FUNC] = []
```
</details>
### &emsp; ***@staticmethod***
### &emsp; ***def*** `run_funcs(funcs: list[LIFESPAN_FUNC | PROCESS_LIFESPAN_FUNC]) -> None`
&emsp;运行函数
Args:
funcs:
Returns:
<details>
<summary>源代码</summary>
```python
@staticmethod
def run_funcs(funcs: list[LIFESPAN_FUNC | PROCESS_LIFESPAN_FUNC], *args, **kwargs) -> None:
"""
运行函数
Args:
funcs:
Returns:
"""
try:
loop = asyncio.get_event_loop()
except RuntimeError:
loop = asyncio.new_event_loop()
asyncio.set_event_loop(loop)
tasks = []
for func in funcs:
if is_coroutine_callable(func):
tasks.append(func(*args, **kwargs))
else:
tasks.append(async_wrapper(func)(*args, **kwargs))
loop.run_until_complete(asyncio.gather(*tasks))
```
</details>
### &emsp; ***def*** `on_before_start(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC`
&emsp;注册启动时的函数
Args:
func:
Returns:
LIFESPAN_FUNC:
<details>
<summary>源代码</summary>
```python
def on_before_start(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC:
"""
注册启动时的函数
Args:
func:
Returns:
LIFESPAN_FUNC:
"""
self._before_start_funcs.append(func)
return func
```
</details>
### &emsp; ***def*** `on_after_start(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC`
&emsp;注册启动时的函数
Args:
func:
Returns:
LIFESPAN_FUNC:
<details>
<summary>源代码</summary>
```python
def on_after_start(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC:
"""
注册启动时的函数
Args:
func:
Returns:
LIFESPAN_FUNC:
"""
self._after_start_funcs.append(func)
return func
```
</details>
### &emsp; ***def*** `on_before_process_shutdown(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC`
&emsp;注册停止前的函数
Args:
func:
Returns:
LIFESPAN_FUNC:
<details>
<summary>源代码</summary>
```python
def on_before_process_shutdown(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC:
"""
注册停止前的函数
Args:
func:
Returns:
LIFESPAN_FUNC:
"""
self._before_process_shutdown_funcs.append(func)
return func
```
</details>
### &emsp; ***def*** `on_after_shutdown(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC`
&emsp;注册停止后的函数
Args:
func:
Returns:
LIFESPAN_FUNC:
<details>
<summary>源代码</summary>
```python
def on_after_shutdown(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC:
"""
注册停止后的函数
Args:
func:
Returns:
LIFESPAN_FUNC:
"""
self._after_shutdown_funcs.append(func)
return func
```
</details>
### &emsp; ***def*** `on_before_process_restart(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC`
&emsp;注册重启时的函数
Args:
func:
Returns:
LIFESPAN_FUNC:
<details>
<summary>源代码</summary>
```python
def on_before_process_restart(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC:
"""
注册重启时的函数
Args:
func:
Returns:
LIFESPAN_FUNC:
"""
self._before_process_restart_funcs.append(func)
return func
```
</details>
### &emsp; ***def*** `on_after_restart(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC`
&emsp;注册重启后的函数
Args:
func:
Returns:
LIFESPAN_FUNC:
<details>
<summary>源代码</summary>
```python
def on_after_restart(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC:
"""
注册重启后的函数
Args:
func:
Returns:
LIFESPAN_FUNC:
"""
self._after_restart_funcs.append(func)
return func
```
</details>
### &emsp; ***def*** `on_after_nonebot_init(self, func: Any) -> None`
&emsp;注册 NoneBot 初始化后的函数
Args:
func:
Returns:
<details>
<summary>源代码</summary>
```python
def on_after_nonebot_init(self, func):
"""
注册 NoneBot 初始化后的函数
Args:
func:
Returns:
"""
self._after_nonebot_init_funcs.append(func)
return func
```
</details>
### &emsp; ***def*** `before_start(self) -> None`
&emsp;启动前
Returns:
<details>
<summary>源代码</summary>
```python
def before_start(self) -> None:
"""
启动前
Returns:
"""
logger.debug('Running before_start functions')
self.run_funcs(self._before_start_funcs)
```
</details>
### &emsp; ***def*** `after_start(self) -> None`
&emsp;启动后
Returns:
<details>
<summary>源代码</summary>
```python
def after_start(self) -> None:
"""
启动后
Returns:
"""
logger.debug('Running after_start functions')
self.run_funcs(self._after_start_funcs)
```
</details>
### &emsp; ***def*** `before_process_shutdown(self) -> None`
&emsp;停止前
Returns:
<details>
<summary>源代码</summary>
```python
def before_process_shutdown(self) -> None:
"""
停止前
Returns:
"""
logger.debug('Running before_shutdown functions')
self.run_funcs(self._before_process_shutdown_funcs)
```
</details>
### &emsp; ***def*** `after_shutdown(self) -> None`
&emsp;停止后
Returns:
<details>
<summary>源代码</summary>
```python
def after_shutdown(self) -> None:
"""
停止后
Returns:
"""
logger.debug('Running after_shutdown functions')
self.run_funcs(self._after_shutdown_funcs)
```
</details>
### &emsp; ***def*** `before_process_restart(self) -> None`
&emsp;重启前
Returns:
<details>
<summary>源代码</summary>
```python
def before_process_restart(self) -> None:
"""
重启前
Returns:
"""
logger.debug('Running before_restart functions')
self.run_funcs(self._before_process_restart_funcs)
```
</details>
### &emsp; ***def*** `after_restart(self) -> None`
&emsp;重启后
Returns:
<details>
<summary>源代码</summary>
```python
def after_restart(self) -> None:
"""
重启后
Returns:
"""
logger.debug('Running after_restart functions')
self.run_funcs(self._after_restart_funcs)
```
</details>
### ***var*** `tasks = []`
### ***var*** `loop = asyncio.get_event_loop()`
### ***var*** `loop = asyncio.new_event_loop()`

7
docs/dev/api/comm/README.md
View File

@ -1,7 +0,0 @@
---
title: liteyuki.comm
index: true
icon: laptop-code
category: API
---

427
docs/dev/api/comm/channel.md
View File

@ -1,427 +0,0 @@
---
title: liteyuki.comm.channel
order: 1
icon: laptop-code
category: API
---
### ***def*** `set_channel(name: str, channel: Channel) -> None`
设置通道实例
Args:
name: 通道名称
channel: 通道实例
<details>
<summary>源代码</summary>
```python
def set_channel(name: str, channel: Channel):
"""
设置通道实例
Args:
name: 通道名称
channel: 通道实例
"""
if not isinstance(channel, Channel):
raise TypeError(f'channel_ must be an instance of Channel, {type(channel)} found')
if IS_MAIN_PROCESS:
_channel[name] = channel
else:
channel_deliver_passive_channel.send(('set_channel', {'name': name, 'channel_': channel}))
```
</details>
### ***def*** `set_channels(channels: dict[str, Channel]) -> None`
设置通道实例
Args:
channels: 通道名称
<details>
<summary>源代码</summary>
```python
def set_channels(channels: dict[str, Channel]):
"""
设置通道实例
Args:
channels: 通道名称
"""
for name, channel in channels.items():
set_channel(name, channel)
```
</details>
### ***def*** `get_channel(name: str) -> Channel`
获取通道实例
Args:
name: 通道名称
Returns:
<details>
<summary>源代码</summary>
```python
def get_channel(name: str) -> Channel:
"""
获取通道实例
Args:
name: 通道名称
Returns:
"""
if IS_MAIN_PROCESS:
return _channel[name]
else:
recv_chan = Channel[Channel[Any]]('recv_chan')
channel_deliver_passive_channel.send(('get_channel', {'name': name, 'recv_chan': recv_chan}))
return recv_chan.receive()
```
</details>
### ***def*** `get_channels() -> dict[str, Channel]`
获取通道实例
Returns:
<details>
<summary>源代码</summary>
```python
def get_channels() -> dict[str, Channel]:
"""
获取通道实例
Returns:
"""
if IS_MAIN_PROCESS:
return _channel
else:
recv_chan = Channel[dict[str, Channel[Any]]]('recv_chan')
channel_deliver_passive_channel.send(('get_channels', {'recv_chan': recv_chan}))
return recv_chan.receive()
```
</details>
### ***def*** `on_set_channel(data: tuple[str, dict[str, Any]]) -> None`
<details>
<summary>源代码</summary>
```python
@channel_deliver_passive_channel.on_receive(filter_func=lambda data: data[0] == 'set_channel')
def on_set_channel(data: tuple[str, dict[str, Any]]):
name, channel = (data[1]['name'], data[1]['channel_'])
set_channel(name, channel)
```
</details>
### ***def*** `on_get_channel(data: tuple[str, dict[str, Any]]) -> None`
<details>
<summary>源代码</summary>
```python
@channel_deliver_passive_channel.on_receive(filter_func=lambda data: data[0] == 'get_channel')
def on_get_channel(data: tuple[str, dict[str, Any]]):
name, recv_chan = (data[1]['name'], data[1]['recv_chan'])
recv_chan.send(get_channel(name))
```
</details>
### ***def*** `on_get_channels(data: tuple[str, dict[str, Any]]) -> None`
<details>
<summary>源代码</summary>
```python
@channel_deliver_passive_channel.on_receive(filter_func=lambda data: data[0] == 'get_channels')
def on_get_channels(data: tuple[str, dict[str, Any]]):
recv_chan = data[1]['recv_chan']
recv_chan.send(get_channels())
```
</details>
### ***def*** `decorator(func: Callable[[T], Any]) -> Callable[[T], Any]`
<details>
<summary>源代码</summary>
```python
def decorator(func: Callable[[T], Any]) -> Callable[[T], Any]:
global _func_id
async def wrapper(data: T) -> Any:
if filter_func is not None:
if is_coroutine_callable(filter_func):
if not await filter_func(data):
return
elif not filter_func(data):
return
if is_coroutine_callable(func):
return await func(data)
else:
return func(data)
_callback_funcs[_func_id] = wrapper
if IS_MAIN_PROCESS:
self._on_main_receive_funcs.append(_func_id)
else:
self._on_sub_receive_funcs.append(_func_id)
_func_id += 1
return func
```
</details>
### ***async def*** `wrapper(data: T) -> Any`
<details>
<summary>源代码</summary>
```python
async def wrapper(data: T) -> Any:
if filter_func is not None:
if is_coroutine_callable(filter_func):
if not await filter_func(data):
return
elif not filter_func(data):
return
if is_coroutine_callable(func):
return await func(data)
else:
return func(data)
```
</details>
### ***class*** `Channel(Generic[T])`
通道类，可以在进程间和进程内通信，双向但同时只能有一个发送者和一个接收者
有两种接收工作方式，但是只能选择一种，主动接收和被动接收，主动接收使用 `receive` 方法，被动接收使用 `on_receive` 装饰器
### &emsp; ***def*** `__init__(self, _id: str, type_check: Optional[bool]) -> None`
&emsp;初始化通道
Args:
_id: 通道ID
type_check: 是否开启类型检查, 若为空，则传入泛型默认开启，否则默认关闭
<details>
<summary>源代码</summary>
```python
def __init__(self, _id: str, type_check: Optional[bool]=None):
"""
初始化通道
Args:
_id: 通道ID
type_check: 是否开启类型检查, 若为空，则传入泛型默认开启，否则默认关闭
"""
self.conn_send, self.conn_recv = Pipe()
self._closed = False
self._on_main_receive_funcs: list[int] = []
self._on_sub_receive_funcs: list[int] = []
self.name: str = _id
self.is_main_receive_loop_running = False
self.is_sub_receive_loop_running = False
if type_check is None:
type_check = self._get_generic_type() is not None
elif type_check:
if self._get_generic_type() is None:
raise TypeError('Type hint is required for enforcing type check.')
self.type_check = type_check
```
</details>
### &emsp; ***def*** `send(self, data: T) -> None`
&emsp;发送数据
Args:
data: 数据
<details>
<summary>源代码</summary>
```python
def send(self, data: T):
"""
发送数据
Args:
data: 数据
"""
if self.type_check:
_type = self._get_generic_type()
if _type is not None and (not self._validate_structure(data, _type)):
raise TypeError(f'Data must be an instance of {_type}, {type(data)} found')
if self._closed:
raise RuntimeError('Cannot send to a closed channel_')
self.conn_send.send(data)
```
</details>
### &emsp; ***def*** `receive(self) -> T`
&emsp;接收数据
Args:
<details>
<summary>源代码</summary>
```python
def receive(self) -> T:
"""
接收数据
Args:
"""
if self._closed:
raise RuntimeError('Cannot receive from a closed channel_')
while True:
data = self.conn_recv.recv()
return data
```
</details>
### &emsp; ***def*** `close(self) -> None`
&emsp;关闭通道
<details>
<summary>源代码</summary>
```python
def close(self):
"""
关闭通道
"""
self._closed = True
self.conn_send.close()
self.conn_recv.close()
```
</details>
### &emsp; ***def*** `on_receive(self, filter_func: Optional[FILTER_FUNC]) -> Callable[[Callable[[T], Any]], Callable[[T], Any]]`
&emsp;接收数据并执行函数
Args:
filter_func: 过滤函数，为None则不过滤
Returns:
装饰器，装饰一个函数在接收到数据后执行
<details>
<summary>源代码</summary>
```python
def on_receive(self, filter_func: Optional[FILTER_FUNC]=None) -> Callable[[Callable[[T], Any]], Callable[[T], Any]]:
"""
接收数据并执行函数
Args:
filter_func: 过滤函数，为None则不过滤
Returns:
装饰器，装饰一个函数在接收到数据后执行
"""
if not self.is_sub_receive_loop_running and (not IS_MAIN_PROCESS):
threading.Thread(target=self._start_sub_receive_loop, daemon=True).start()
if not self.is_main_receive_loop_running and IS_MAIN_PROCESS:
threading.Thread(target=self._start_main_receive_loop, daemon=True).start()
def decorator(func: Callable[[T], Any]) -> Callable[[T], Any]:
global _func_id
async def wrapper(data: T) -> Any:
if filter_func is not None:
if is_coroutine_callable(filter_func):
if not await filter_func(data):
return
elif not filter_func(data):
return
if is_coroutine_callable(func):
return await func(data)
else:
return func(data)
_callback_funcs[_func_id] = wrapper
if IS_MAIN_PROCESS:
self._on_main_receive_funcs.append(_func_id)
else:
self._on_sub_receive_funcs.append(_func_id)
_func_id += 1
return func
return decorator
```
</details>
### ***var*** `T = TypeVar('T')`
### ***var*** `channel_deliver_active_channel = Channel(_id='channel_deliver_active_channel')`
### ***var*** `channel_deliver_passive_channel = Channel(_id='channel_deliver_passive_channel')`
### ***var*** `recv_chan = data[1]['recv_chan']`
### ***var*** `recv_chan = Channel[Channel[Any]]('recv_chan')`
### ***var*** `recv_chan = Channel[dict[str, Channel[Any]]]('recv_chan')`
### ***var*** `type_check = self._get_generic_type() is not None`
### ***var*** `data = self.conn_recv.recv()`
### ***var*** `func = _callback_funcs[func_id]`
### ***var*** `func = _callback_funcs[func_id]`
### ***var*** `data = self.conn_recv.recv()`
### ***var*** `data = self.conn_recv.recv()`

25
docs/dev/api/comm/event.md
View File

@ -1,25 +0,0 @@
---
title: liteyuki.comm.event
order: 1
icon: laptop-code
category: API
---
### ***class*** `Event`
事件类
### &emsp; ***def*** `__init__(self, name: str, data: dict[str, Any]) -> None`
&emsp;
<details>
<summary>源代码</summary>
```python
def __init__(self, name: str, data: dict[str, Any]):
self.name = name
self.data = data
```
</details>

563
docs/dev/api/comm/storage.md
View File

@ -1,563 +0,0 @@
---
title: liteyuki.comm.storage
order: 1
icon: laptop-code
category: API
---
### ***def*** `run_subscriber_receive_funcs(channel_: str, data: Any) -> None`
运行订阅者接收函数
Args:
channel_: 频道
data: 数据
<details>
<summary>源代码</summary>
```python
@staticmethod
def run_subscriber_receive_funcs(channel_: str, data: Any):
"""
运行订阅者接收函数
Args:
channel_: 频道
data: 数据
"""
if IS_MAIN_PROCESS:
if channel_ in _on_main_subscriber_receive_funcs and _on_main_subscriber_receive_funcs[channel_]:
run_coroutine(*[func(data) for func in _on_main_subscriber_receive_funcs[channel_]])
elif channel_ in _on_sub_subscriber_receive_funcs and _on_sub_subscriber_receive_funcs[channel_]:
run_coroutine(*[func(data) for func in _on_sub_subscriber_receive_funcs[channel_]])
```
</details>
### ***def*** `on_get(data: tuple[str, dict[str, Any]]) -> None`
<details>
<summary>源代码</summary>
```python
@shared_memory.passive_chan.on_receive(lambda d: d[0] == 'get')
def on_get(data: tuple[str, dict[str, Any]]):
key = data[1]['key']
default = data[1]['default']
recv_chan = data[1]['recv_chan']
recv_chan.send(shared_memory.get(key, default))
```
</details>
### ***def*** `on_set(data: tuple[str, dict[str, Any]]) -> None`
<details>
<summary>源代码</summary>
```python
@shared_memory.passive_chan.on_receive(lambda d: d[0] == 'set')
def on_set(data: tuple[str, dict[str, Any]]):
key = data[1]['key']
value = data[1]['value']
shared_memory.set(key, value)
```
</details>
### ***def*** `on_delete(data: tuple[str, dict[str, Any]]) -> None`
<details>
<summary>源代码</summary>
```python
@shared_memory.passive_chan.on_receive(lambda d: d[0] == 'delete')
def on_delete(data: tuple[str, dict[str, Any]]):
key = data[1]['key']
shared_memory.delete(key)
```
</details>
### ***def*** `on_get_all(data: tuple[str, dict[str, Any]]) -> None`
<details>
<summary>源代码</summary>
```python
@shared_memory.passive_chan.on_receive(lambda d: d[0] == 'get_all')
def on_get_all(data: tuple[str, dict[str, Any]]):
recv_chan = data[1]['recv_chan']
recv_chan.send(shared_memory.get_all())
```
</details>
### ***def*** `on_publish(data: tuple[str, Any]) -> None`
<details>
<summary>源代码</summary>
```python
@channel.publish_channel.on_receive()
def on_publish(data: tuple[str, Any]):
channel_, data = data
shared_memory.run_subscriber_receive_funcs(channel_, data)
```
</details>
### ***def*** `decorator(func: ON_RECEIVE_FUNC) -> ON_RECEIVE_FUNC`
<details>
<summary>源代码</summary>
```python
def decorator(func: ON_RECEIVE_FUNC) -> ON_RECEIVE_FUNC:
async def wrapper(data: Any):
if is_coroutine_callable(func):
await func(data)
else:
func(data)
if IS_MAIN_PROCESS:
if channel_ not in _on_main_subscriber_receive_funcs:
_on_main_subscriber_receive_funcs[channel_] = []
_on_main_subscriber_receive_funcs[channel_].append(wrapper)
else:
if channel_ not in _on_sub_subscriber_receive_funcs:
_on_sub_subscriber_receive_funcs[channel_] = []
_on_sub_subscriber_receive_funcs[channel_].append(wrapper)
return wrapper
```
</details>
### ***async def*** `wrapper(data: Any) -> None`
<details>
<summary>源代码</summary>
```python
async def wrapper(data: Any):
if is_coroutine_callable(func):
await func(data)
else:
func(data)
```
</details>
### ***class*** `Subscriber`
### &emsp; ***def*** `__init__(self) -> None`
&emsp;
<details>
<summary>源代码</summary>
```python
def __init__(self):
self._subscribers = {}
```
</details>
### &emsp; ***def*** `receive(self) -> Any`
&emsp;
<details>
<summary>源代码</summary>
```python
def receive(self) -> Any:
pass
```
</details>
### &emsp; ***def*** `unsubscribe(self) -> None`
&emsp;
<details>
<summary>源代码</summary>
```python
def unsubscribe(self) -> None:
pass
```
</details>
### ***class*** `KeyValueStore`
### &emsp; ***def*** `__init__(self) -> None`
&emsp;
<details>
<summary>源代码</summary>
```python
def __init__(self):
self._store = {}
self.active_chan = Channel[tuple[str, Optional[dict[str, Any]]]](_id='shared_memory-active')
self.passive_chan = Channel[tuple[str, Optional[dict[str, Any]]]](_id='shared_memory-passive')
self.publish_channel = Channel[tuple[str, Any]](_id='shared_memory-publish')
self.is_main_receive_loop_running = False
self.is_sub_receive_loop_running = False
```
</details>
### &emsp; ***def*** `set(self, key: str, value: Any) -> None`
&emsp;设置键值对
Args:
key: 键
value: 值
<details>
<summary>源代码</summary>
```python
def set(self, key: str, value: Any) -> None:
"""
设置键值对
Args:
key: 键
value: 值
"""
if IS_MAIN_PROCESS:
lock = _get_lock(key)
with lock:
self._store[key] = value
else:
self.passive_chan.send(('set', {'key': key, 'value': value}))
```
</details>
### &emsp; ***def*** `get(self, key: str, default: Optional[Any]) -> Optional[Any]`
&emsp;获取键值对
Args:
key: 键
default: 默认值
Returns:
Any: 值
<details>
<summary>源代码</summary>
```python
def get(self, key: str, default: Optional[Any]=None) -> Optional[Any]:
"""
获取键值对
Args:
key: 键
default: 默认值
Returns:
Any: 值
"""
if IS_MAIN_PROCESS:
lock = _get_lock(key)
with lock:
return self._store.get(key, default)
else:
recv_chan = Channel[Optional[Any]]('recv_chan')
self.passive_chan.send(('get', {'key': key, 'default': default, 'recv_chan': recv_chan}))
return recv_chan.receive()
```
</details>
### &emsp; ***def*** `delete(self, key: str, ignore_key_error: bool) -> None`
&emsp;删除键值对
Args:
key: 键
ignore_key_error: 是否忽略键不存在的错误
Returns:
<details>
<summary>源代码</summary>
```python
def delete(self, key: str, ignore_key_error: bool=True) -> None:
"""
删除键值对
Args:
key: 键
ignore_key_error: 是否忽略键不存在的错误
Returns:
"""
if IS_MAIN_PROCESS:
lock = _get_lock(key)
with lock:
if key in self._store:
try:
del self._store[key]
del _locks[key]
except KeyError as e:
if not ignore_key_error:
raise e
else:
self.passive_chan.send(('delete', {'key': key}))
```
</details>
### &emsp; ***def*** `get_all(self) -> dict[str, Any]`
&emsp;获取所有键值对
Returns:
dict[str, Any]: 键值对
<details>
<summary>源代码</summary>
```python
def get_all(self) -> dict[str, Any]:
"""
获取所有键值对
Returns:
dict[str, Any]: 键值对
"""
if IS_MAIN_PROCESS:
return self._store
else:
recv_chan = Channel[dict[str, Any]]('recv_chan')
self.passive_chan.send(('get_all', {'recv_chan': recv_chan}))
return recv_chan.receive()
```
</details>
### &emsp; ***def*** `publish(self, channel_: str, data: Any) -> None`
&emsp;发布消息
Args:
channel_: 频道
data: 数据
Returns:
<details>
<summary>源代码</summary>
```python
def publish(self, channel_: str, data: Any) -> None:
"""
发布消息
Args:
channel_: 频道
data: 数据
Returns:
"""
self.active_chan.send(('publish', {'channel': channel_, 'data': data}))
```
</details>
### &emsp; ***def*** `on_subscriber_receive(self, channel_: str) -> Callable[[ON_RECEIVE_FUNC], ON_RECEIVE_FUNC]`
&emsp;订阅者接收消息时的回调
Args:
channel_: 频道
Returns:
装饰器
<details>
<summary>源代码</summary>
```python
def on_subscriber_receive(self, channel_: str) -> Callable[[ON_RECEIVE_FUNC], ON_RECEIVE_FUNC]:
"""
订阅者接收消息时的回调
Args:
channel_: 频道
Returns:
装饰器
"""
if IS_MAIN_PROCESS and (not self.is_main_receive_loop_running):
threading.Thread(target=self._start_receive_loop, daemon=True).start()
shared_memory.is_main_receive_loop_running = True
elif not IS_MAIN_PROCESS and (not self.is_sub_receive_loop_running):
threading.Thread(target=self._start_receive_loop, daemon=True).start()
shared_memory.is_sub_receive_loop_running = True
def decorator(func: ON_RECEIVE_FUNC) -> ON_RECEIVE_FUNC:
async def wrapper(data: Any):
if is_coroutine_callable(func):
await func(data)
else:
func(data)
if IS_MAIN_PROCESS:
if channel_ not in _on_main_subscriber_receive_funcs:
_on_main_subscriber_receive_funcs[channel_] = []
_on_main_subscriber_receive_funcs[channel_].append(wrapper)
else:
if channel_ not in _on_sub_subscriber_receive_funcs:
_on_sub_subscriber_receive_funcs[channel_] = []
_on_sub_subscriber_receive_funcs[channel_].append(wrapper)
return wrapper
return decorator
```
</details>
### &emsp; ***@staticmethod***
### &emsp; ***def*** `run_subscriber_receive_funcs(channel_: str, data: Any) -> None`
&emsp;运行订阅者接收函数
Args:
channel_: 频道
data: 数据
<details>
<summary>源代码</summary>
```python
@staticmethod
def run_subscriber_receive_funcs(channel_: str, data: Any):
"""
运行订阅者接收函数
Args:
channel_: 频道
data: 数据
"""
if IS_MAIN_PROCESS:
if channel_ in _on_main_subscriber_receive_funcs and _on_main_subscriber_receive_funcs[channel_]:
run_coroutine(*[func(data) for func in _on_main_subscriber_receive_funcs[channel_]])
elif channel_ in _on_sub_subscriber_receive_funcs and _on_sub_subscriber_receive_funcs[channel_]:
run_coroutine(*[func(data) for func in _on_sub_subscriber_receive_funcs[channel_]])
```
</details>
### ***class*** `GlobalKeyValueStore`
### &emsp; ***@classmethod***
### &emsp; ***def*** `get_instance(cls: Any) -> None`
&emsp;
<details>
<summary>源代码</summary>
```python
@classmethod
def get_instance(cls):
if cls._instance is None:
with cls._lock:
if cls._instance is None:
cls._instance = KeyValueStore()
return cls._instance
```
</details>
### &emsp; ***attr*** `_instance: None`
### &emsp; ***attr*** `_lock: threading.Lock()`
### ***var*** `key = data[1]['key']`
### ***var*** `default = data[1]['default']`
### ***var*** `recv_chan = data[1]['recv_chan']`
### ***var*** `key = data[1]['key']`
### ***var*** `value = data[1]['value']`
### ***var*** `key = data[1]['key']`
### ***var*** `recv_chan = data[1]['recv_chan']`
### ***var*** `lock = _get_lock(key)`
### ***var*** `lock = _get_lock(key)`
### ***var*** `recv_chan = Channel[Optional[Any]]('recv_chan')`
### ***var*** `lock = _get_lock(key)`
### ***var*** `recv_chan = Channel[dict[str, Any]]('recv_chan')`
### ***var*** `data = self.active_chan.receive()`
### ***var*** `data = self.publish_channel.receive()`

231
docs/dev/api/config.md
View File

@ -1,231 +0,0 @@
---
title: liteyuki.config
order: 1
icon: laptop-code
category: API
---
### ***def*** `flat_config(config: dict[str, Any]) -> dict[str, Any]`
扁平化配置文件
{a:{b:{c:1}}} -> {"a.b.c": 1}
Args:
config: 配置项目
Returns:
扁平化后的配置文件，但也包含原有的键值对
<details>
<summary>源代码</summary>
```python
def flat_config(config: dict[str, Any]) -> dict[str, Any]:
"""
扁平化配置文件
{a:{b:{c:1}}} -> {"a.b.c": 1}
Args:
config: 配置项目
Returns:
扁平化后的配置文件，但也包含原有的键值对
"""
new_config = copy.deepcopy(config)
for key, value in config.items():
if isinstance(value, dict):
for k, v in flat_config(value).items():
new_config[f'{key}.{k}'] = v
return new_config
```
</details>
### ***def*** `load_from_yaml(file: str) -> dict[str, Any]`
Load config from yaml file
<details>
<summary>源代码</summary>
```python
def load_from_yaml(file: str) -> dict[str, Any]:
"""
Load config from yaml file
"""
logger.debug(f'Loading YAML config from {file}')
config = yaml.safe_load(open(file, 'r', encoding='utf-8'))
return flat_config(config if config is not None else {})
```
</details>
### ***def*** `load_from_json(file: str) -> dict[str, Any]`
Load config from json file
<details>
<summary>源代码</summary>
```python
def load_from_json(file: str) -> dict[str, Any]:
"""
Load config from json file
"""
logger.debug(f'Loading JSON config from {file}')
config = json.load(open(file, 'r', encoding='utf-8'))
return flat_config(config if config is not None else {})
```
</details>
### ***def*** `load_from_toml(file: str) -> dict[str, Any]`
Load config from toml file
<details>
<summary>源代码</summary>
```python
def load_from_toml(file: str) -> dict[str, Any]:
"""
Load config from toml file
"""
logger.debug(f'Loading TOML config from {file}')
config = toml.load(open(file, 'r', encoding='utf-8'))
return flat_config(config if config is not None else {})
```
</details>
### ***def*** `load_from_files() -> dict[str, Any]`
从指定文件加载配置项，会自动识别文件格式
默认执行扁平化选项
<details>
<summary>源代码</summary>
```python
def load_from_files(*files: str, no_warning: bool=False) -> dict[str, Any]:
"""
从指定文件加载配置项，会自动识别文件格式
默认执行扁平化选项
"""
config = {}
for file in files:
if os.path.exists(file):
if file.endswith(('.yaml', 'yml')):
config.update(load_from_yaml(file))
elif file.endswith('.json'):
config.update(load_from_json(file))
elif file.endswith('.toml'):
config.update(load_from_toml(file))
elif not no_warning:
logger.warning(f'Unsupported config file format: {file}')
elif not no_warning:
logger.warning(f'Config file not found: {file}')
return config
```
</details>
### ***def*** `load_configs_from_dirs() -> dict[str, Any]`
从目录下加载配置文件，不递归
按照读取文件的优先级反向覆盖
默认执行扁平化选项
<details>
<summary>源代码</summary>
```python
def load_configs_from_dirs(*directories: str, no_waring: bool=False) -> dict[str, Any]:
"""
从目录下加载配置文件，不递归
按照读取文件的优先级反向覆盖
默认执行扁平化选项
"""
config = {}
for directory in directories:
if not os.path.exists(directory):
if not no_waring:
logger.warning(f'Directory not found: {directory}')
continue
for file in os.listdir(directory):
if file.endswith(_SUPPORTED_CONFIG_FORMATS):
config.update(load_from_files(os.path.join(directory, file), no_warning=no_waring))
return config
```
</details>
### ***def*** `load_config_in_default(no_waring: bool) -> dict[str, Any]`
从一个标准的轻雪项目加载配置文件
项目目录下的config.*和config目录下的所有配置文件
项目目录下的配置文件优先
<details>
<summary>源代码</summary>
```python
def load_config_in_default(no_waring: bool=False) -> dict[str, Any]:
"""
从一个标准的轻雪项目加载配置文件
项目目录下的config.*和config目录下的所有配置文件
项目目录下的配置文件优先
"""
config = load_configs_from_dirs('config', no_waring=no_waring)
config.update(load_from_files('config.yaml', 'config.toml', 'config.json', 'config.yml', no_warning=no_waring))
return config
```
</details>
### ***class*** `SatoriNodeConfig(BaseModel)`
### ***class*** `SatoriConfig(BaseModel)`
### ***class*** `BasicConfig(BaseModel)`
### ***var*** `new_config = copy.deepcopy(config)`
### ***var*** `config = yaml.safe_load(open(file, 'r', encoding='utf-8'))`
### ***var*** `config = json.load(open(file, 'r', encoding='utf-8'))`
### ***var*** `config = toml.load(open(file, 'r', encoding='utf-8'))`
### ***var*** `config = {}`
### ***var*** `config = {}`
### ***var*** `config = load_configs_from_dirs('config', no_waring=no_waring)`

7
docs/dev/api/core/README.md
View File

@ -1,7 +0,0 @@
---
title: liteyuki.core
index: true
icon: laptop-code
category: API
---

275
docs/dev/api/core/manager.md
View File

@ -1,275 +0,0 @@
---
title: liteyuki.core.manager
order: 1
icon: laptop-code
category: API
---
### ***class*** `ChannelDeliver`
### &emsp; ***def*** `__init__(self, active: Channel[Any], passive: Channel[Any], channel_deliver_active: Channel[Channel[Any]], channel_deliver_passive: Channel[tuple[str, dict]], publish: Channel[tuple[str, Any]]) -> None`
&emsp;
<details>
<summary>源代码</summary>
```python
def __init__(self, active: Channel[Any], passive: Channel[Any], channel_deliver_active: Channel[Channel[Any]], channel_deliver_passive: Channel[tuple[str, dict]], publish: Channel[tuple[str, Any]]):
self.active = active
self.passive = passive
self.channel_deliver_active = channel_deliver_active
self.channel_deliver_passive = channel_deliver_passive
self.publish = publish
```
</details>
### ***class*** `ProcessManager`
进程管理器
### &emsp; ***def*** `__init__(self, lifespan: 'Lifespan') -> None`
&emsp;
<details>
<summary>源代码</summary>
```python
def __init__(self, lifespan: 'Lifespan'):
self.lifespan = lifespan
self.targets: dict[str, tuple[Callable, tuple, dict]] = {}
self.processes: dict[str, Process] = {}
```
</details>
### &emsp; ***def*** `start(self, name: str) -> None`
&emsp;开启后自动监控进程，并添加到进程字典中
Args:
name:
Returns:
<details>
<summary>源代码</summary>
```python
def start(self, name: str):
"""
开启后自动监控进程，并添加到进程字典中
Args:
name:
Returns:
"""
if name not in self.targets:
raise KeyError(f'Process {name} not found.')
chan_active = get_channel(f'{name}-active')
def _start_process():
process = Process(target=self.targets[name][0], args=self.targets[name][1], kwargs=self.targets[name][2], daemon=True)
self.processes[name] = process
process.start()
_start_process()
while True:
data = chan_active.receive()
if data == 0:
logger.info(f'Stopping process {name}')
self.lifespan.before_process_shutdown()
self.terminate(name)
break
elif data == 1:
logger.info(f'Restarting process {name}')
self.lifespan.before_process_shutdown()
self.lifespan.before_process_restart()
self.terminate(name)
_start_process()
continue
else:
logger.warning('Unknown data received, ignored.')
```
</details>
### &emsp; ***def*** `start_all(self) -> None`
&emsp;启动所有进程
<details>
<summary>源代码</summary>
```python
def start_all(self):
"""
启动所有进程
"""
for name in self.targets:
threading.Thread(target=self.start, args=(name,), daemon=True).start()
```
</details>
### &emsp; ***def*** `add_target(self, name: str, target: TARGET_FUNC, args: tuple, kwargs: Any) -> None`
&emsp;添加进程
Args:
name: 进程名，用于获取和唯一标识
target: 进程函数
args: 进程函数参数
kwargs: 进程函数关键字参数，通常会默认传入chan_active和chan_passive
<details>
<summary>源代码</summary>
```python
def add_target(self, name: str, target: TARGET_FUNC, args: tuple=(), kwargs=None):
"""
添加进程
Args:
name: 进程名，用于获取和唯一标识
target: 进程函数
args: 进程函数参数
kwargs: 进程函数关键字参数，通常会默认传入chan_active和chan_passive
"""
if kwargs is None:
kwargs = {}
chan_active: Channel = Channel(_id=f'{name}-active')
chan_passive: Channel = Channel(_id=f'{name}-passive')
channel_deliver = ChannelDeliver(active=chan_active, passive=chan_passive, channel_deliver_active=channel_deliver_active_channel, channel_deliver_passive=channel_deliver_passive_channel, publish=publish_channel)
self.targets[name] = (_delivery_channel_wrapper, (target, channel_deliver, shared_memory, *args), kwargs)
set_channels({f'{name}-active': chan_active, f'{name}-passive': chan_passive})
```
</details>
### &emsp; ***def*** `join_all(self) -> None`
&emsp;
<details>
<summary>源代码</summary>
```python
def join_all(self):
for name, process in self.targets:
process.join()
```
</details>
### &emsp; ***def*** `terminate(self, name: str) -> None`
&emsp;终止进程并从进程字典中删除
Args:
name:
Returns:
<details>
<summary>源代码</summary>
```python
def terminate(self, name: str):
"""
终止进程并从进程字典中删除
Args:
name:
Returns:
"""
if name not in self.processes:
logger.warning(f'Process {name} not found.')
return
process = self.processes[name]
process.terminate()
process.join(TIMEOUT)
if process.is_alive():
process.kill()
logger.success(f'Process {name} terminated.')
```
</details>
### &emsp; ***def*** `terminate_all(self) -> None`
&emsp;
<details>
<summary>源代码</summary>
```python
def terminate_all(self):
for name in self.targets:
self.terminate(name)
```
</details>
### &emsp; ***def*** `is_process_alive(self, name: str) -> bool`
&emsp;检查进程是否存活
Args:
name:
Returns:
<details>
<summary>源代码</summary>
```python
def is_process_alive(self, name: str) -> bool:
"""
检查进程是否存活
Args:
name:
Returns:
"""
if name not in self.targets:
logger.warning(f'Process {name} not found.')
return self.processes[name].is_alive()
```
</details>
### ***var*** `TIMEOUT = 10`
### ***var*** `chan_active = get_channel(f'{name}-active')`
### ***var*** `channel_deliver = ChannelDeliver(active=chan_active, passive=chan_passive, channel_deliver_active=channel_deliver_active_channel, channel_deliver_passive=channel_deliver_passive_channel, publish=publish_channel)`
### ***var*** `process = self.processes[name]`
### ***var*** `process = Process(target=self.targets[name][0], args=self.targets[name][1], kwargs=self.targets[name][2], daemon=True)`
### ***var*** `data = chan_active.receive()`
### ***var*** `kwargs = {}`

7
docs/dev/api/dev/README.md
View File

@ -1,7 +0,0 @@
---
title: liteyuki.dev
index: true
icon: laptop-code
category: API
---

249
docs/dev/api/dev/observer.md
View File

@ -1,249 +0,0 @@
---
title: liteyuki.dev.observer
order: 1
icon: laptop-code
category: API
---
### ***def*** `debounce(wait: Any) -> None`
防抖函数
<details>
<summary>源代码</summary>
```python
def debounce(wait):
"""
防抖函数
"""
def decorator(func):
def wrapper(*args, **kwargs):
nonlocal last_call_time
current_time = time.time()
if current_time - last_call_time > wait:
last_call_time = current_time
return func(*args, **kwargs)
last_call_time = None
return wrapper
return decorator
```
</details>
### ***def*** `on_file_system_event(directories: tuple[str], recursive: bool, event_filter: FILTER_FUNC) -> Callable[[CALLBACK_FUNC], CALLBACK_FUNC]`
注册文件系统变化监听器
Args:
directories: 监听目录们
recursive: 是否递归监听子目录
event_filter: 事件过滤器, 返回True则执行回调函数
Returns:
装饰器，装饰一个函数在接收到数据后执行
<details>
<summary>源代码</summary>
```python
def on_file_system_event(directories: tuple[str], recursive: bool=True, event_filter: FILTER_FUNC=None) -> Callable[[CALLBACK_FUNC], CALLBACK_FUNC]:
"""
注册文件系统变化监听器
Args:
directories: 监听目录们
recursive: 是否递归监听子目录
event_filter: 事件过滤器, 返回True则执行回调函数
Returns:
装饰器，装饰一个函数在接收到数据后执行
"""
def decorator(func: CALLBACK_FUNC) -> CALLBACK_FUNC:
def wrapper(event: FileSystemEvent):
if event_filter is not None and (not event_filter(event)):
return
func(event)
code_modified_handler = CodeModifiedHandler()
code_modified_handler.on_modified = wrapper
for directory in directories:
observer.schedule(code_modified_handler, directory, recursive=recursive)
return func
return decorator
```
</details>
### ***def*** `decorator(func: Any) -> None`
<details>
<summary>源代码</summary>
```python
def decorator(func):
def wrapper(*args, **kwargs):
nonlocal last_call_time
current_time = time.time()
if current_time - last_call_time > wait:
last_call_time = current_time
return func(*args, **kwargs)
last_call_time = None
return wrapper
```
</details>
### ***def*** `decorator(func: CALLBACK_FUNC) -> CALLBACK_FUNC`
<details>
<summary>源代码</summary>
```python
def decorator(func: CALLBACK_FUNC) -> CALLBACK_FUNC:
def wrapper(event: FileSystemEvent):
if event_filter is not None and (not event_filter(event)):
return
func(event)
code_modified_handler = CodeModifiedHandler()
code_modified_handler.on_modified = wrapper
for directory in directories:
observer.schedule(code_modified_handler, directory, recursive=recursive)
return func
```
</details>
### ***def*** `wrapper() -> None`
<details>
<summary>源代码</summary>
```python
def wrapper(*args, **kwargs):
nonlocal last_call_time
current_time = time.time()
if current_time - last_call_time > wait:
last_call_time = current_time
return func(*args, **kwargs)
```
</details>
### ***def*** `wrapper(event: FileSystemEvent) -> None`
<details>
<summary>源代码</summary>
```python
def wrapper(event: FileSystemEvent):
if event_filter is not None and (not event_filter(event)):
return
func(event)
```
</details>
### ***class*** `CodeModifiedHandler(FileSystemEventHandler)`
Handler for code file changes
### &emsp; ***def*** `on_modified(self, event: Any) -> None`
&emsp;
<details>
<summary>源代码</summary>
```python
@debounce(1)
def on_modified(self, event):
raise NotImplementedError('on_modified must be implemented')
```
</details>
### &emsp; ***def*** `on_created(self, event: Any) -> None`
&emsp;
<details>
<summary>源代码</summary>
```python
def on_created(self, event):
self.on_modified(event)
```
</details>
### &emsp; ***def*** `on_deleted(self, event: Any) -> None`
&emsp;
<details>
<summary>源代码</summary>
```python
def on_deleted(self, event):
self.on_modified(event)
```
</details>
### &emsp; ***def*** `on_moved(self, event: Any) -> None`
&emsp;
<details>
<summary>源代码</summary>
```python
def on_moved(self, event):
self.on_modified(event)
```
</details>
### &emsp; ***def*** `on_any_event(self, event: Any) -> None`
&emsp;
<details>
<summary>源代码</summary>
```python
def on_any_event(self, event):
self.on_modified(event)
```
</details>
### ***var*** `liteyuki_bot = get_bot()`
### ***var*** `observer = Observer()`
### ***var*** `last_call_time = None`
### ***var*** `code_modified_handler = CodeModifiedHandler()`
### ***var*** `current_time = time.time()`
### ***var*** `last_call_time = current_time`

46
docs/dev/api/dev/plugin.md
View File

@ -1,46 +0,0 @@
---
title: liteyuki.dev.plugin
order: 1
icon: laptop-code
category: API
---
### ***def*** `run_plugins() -> None`
运行插件，无需手动初始化bot
Args:
module_path: 插件路径，参考`liteyuki.load_plugin`的函数签名
<details>
<summary>源代码</summary>
```python
def run_plugins(*module_path: str | Path):
"""
运行插件，无需手动初始化bot
Args:
module_path: 插件路径，参考`liteyuki.load_plugin`的函数签名
"""
cfg = load_config_in_default()
plugins = cfg.get('liteyuki.plugins', [])
plugins.extend(module_path)
cfg['liteyuki.plugins'] = plugins
bot = LiteyukiBot(**cfg)
bot.run()
```
</details>
### ***var*** `cfg = load_config_in_default()`
### ***var*** `plugins = cfg.get('liteyuki.plugins', [])`
### ***var*** `bot = LiteyukiBot(**cfg)`

11
docs/dev/api/exception.md
View File

@ -1,11 +0,0 @@
---
title: liteyuki.exception
order: 1
icon: laptop-code
category: API
---
### ***class*** `LiteyukiException(BaseException)`
Liteyuki的异常基类。

58
docs/dev/api/log.md
View File

@ -1,58 +0,0 @@
---
title: liteyuki.log
order: 1
icon: laptop-code
category: API
---
### ***def*** `get_format(level: str) -> str`
<details>
<summary>源代码</summary>
```python
def get_format(level: str) -> str:
if level == 'DEBUG':
return debug_format
else:
return default_format
```
</details>
### ***def*** `init_log(config: dict) -> None`
在语言加载完成后执行
Returns:
<details>
<summary>源代码</summary>
```python
def init_log(config: dict):
"""
在语言加载完成后执行
Returns:
"""
logger.remove()
logger.add(sys.stdout, level=0, diagnose=False, format=get_format(config.get('log_level', 'INFO')))
show_icon = config.get('log_icon', True)
logger.level('DEBUG', color='<blue>', icon=f"{('🐛' if show_icon else '')}DEBUG")
logger.level('INFO', color='<normal>', icon=f"{('ℹ️' if show_icon else '')}INFO")
logger.level('SUCCESS', color='<green>', icon=f"{('✅' if show_icon else '')}SUCCESS")
logger.level('WARNING', color='<yellow>', icon=f"{('⚠️' if show_icon else '')}WARNING")
logger.level('ERROR', color='<red>', icon=f"{('⭕' if show_icon else '')}ERROR")
```
</details>
### ***var*** `logger = loguru.logger`
### ***var*** `show_icon = config.get('log_icon', True)`

7
docs/dev/api/message/README.md
View File

@ -1,7 +0,0 @@
---
title: liteyuki.message
index: true
icon: laptop-code
category: API
---

106
docs/dev/api/message/event.md
View File

@ -1,106 +0,0 @@
---
title: liteyuki.message.event
order: 1
icon: laptop-code
category: API
---
### ***class*** `MessageEvent`
### &emsp; ***def*** `__init__(self, bot_id: str, message: list[dict[str, Any]] | str, message_type: str, raw_message: str, session_id: str, session_type: str, receive_channel: str, data: Optional[dict[str, Any]]) -> None`
&emsp;轻雪抽象消息事件
Args:
bot_id: 机器人ID
message: 消息，消息段数组[{type: str, data: dict[str, Any]}]
raw_message: 原始消息(通常为纯文本的格式)
message_type: 消息类型(private, group, other)
session_id: 会话ID(私聊通常为用户ID，群聊通常为群ID)
session_type: 会话类型(private, group)
receive_channel: 接收频道(用于回复消息)
data: 附加数据
<details>
<summary>源代码</summary>
```python
def __init__(self, bot_id: str, message: list[dict[str, Any]] | str, message_type: str, raw_message: str, session_id: str, session_type: str, receive_channel: str, data: Optional[dict[str, Any]]=None):
"""
轻雪抽象消息事件
Args:
bot_id: 机器人ID
message: 消息，消息段数组[{type: str, data: dict[str, Any]}]
raw_message: 原始消息(通常为纯文本的格式)
message_type: 消息类型(private, group, other)
session_id: 会话ID(私聊通常为用户ID，群聊通常为群ID)
session_type: 会话类型(private, group)
receive_channel: 接收频道(用于回复消息)
data: 附加数据
"""
if data is None:
data = {}
self.message_type = message_type
self.data = data
self.bot_id = bot_id
self.message = message
self.raw_message = raw_message
self.session_id = session_id
self.session_type = session_type
self.receive_channel = receive_channel
```
</details>
### &emsp; ***def*** `reply(self, message: str | dict[str, Any]) -> None`
&emsp;回复消息
Args:
message:
Returns:
<details>
<summary>源代码</summary>
```python
def reply(self, message: str | dict[str, Any]):
"""
回复消息
Args:
message:
Returns:
"""
reply_event = MessageEvent(message_type=self.session_type, message=message, raw_message='', data={'message': message}, bot_id=self.bot_id, session_id=self.session_id, session_type=self.session_type, receive_channel='_')
shared_memory.publish(self.receive_channel, reply_event)
```
</details>
### ***var*** `reply_event = MessageEvent(message_type=self.session_type, message=message, raw_message='', data={'message': message}, bot_id=self.bot_id, session_id=self.session_id, session_type=self.session_type, receive_channel='_')`
### ***var*** `data = {}`

71
docs/dev/api/message/matcher.md
View File

@ -1,71 +0,0 @@
---
title: liteyuki.message.matcher
order: 1
icon: laptop-code
category: API
---
### ***class*** `Matcher`
### &emsp; ***def*** `__init__(self, rule: Rule, priority: int, block: bool) -> None`
&emsp;匹配器
Args:
rule: 规则
priority: 优先级 >= 0
block: 是否阻断后续优先级更低的匹配器
<details>
<summary>源代码</summary>
```python
def __init__(self, rule: Rule, priority: int, block: bool):
"""
匹配器
Args:
rule: 规则
priority: 优先级 >= 0
block: 是否阻断后续优先级更低的匹配器
"""
self.rule = rule
self.priority = priority
self.block = block
self.handlers: list[EventHandler] = []
```
</details>
### &emsp; ***def*** `handle(self, handler: EventHandler) -> EventHandler`
&emsp;添加处理函数，装饰器
Args:
handler:
Returns:
EventHandler
<details>
<summary>源代码</summary>
```python
def handle(self, handler: EventHandler) -> EventHandler:
"""
添加处理函数，装饰器
Args:
handler:
Returns:
EventHandler
"""
self.handlers.append(handler)
return handler
```
</details>

39
docs/dev/api/message/on.md
View File

@ -1,39 +0,0 @@
---
title: liteyuki.message.on
order: 1
icon: laptop-code
category: API
---
### ***def*** `on_message(rule: Rule, priority: int, block: bool) -> Matcher`
<details>
<summary>源代码</summary>
```python
def on_message(rule: Rule=Rule(), priority: int=0, block: bool=True) -> Matcher:
matcher = Matcher(rule, priority, block)
for i, m in enumerate(_matcher_list):
if m.priority < matcher.priority:
_matcher_list.insert(i, matcher)
break
else:
_matcher_list.append(matcher)
return matcher
```
</details>
### ***var*** `current_priority = -1`
### ***var*** `matcher = Matcher(rule, priority, block)`
### ***var*** `current_priority = matcher.priority`

24
docs/dev/api/message/rule.md
View File

@ -1,24 +0,0 @@
---
title: liteyuki.message.rule
order: 1
icon: laptop-code
category: API
---
### ***class*** `Rule`
### &emsp; ***def*** `__init__(self, handler: Optional[RuleHandler]) -> None`
&emsp;
<details>
<summary>源代码</summary>
```python
def __init__(self, handler: Optional[RuleHandler]=None):
self.handler = handler
```
</details>

7
docs/dev/api/message/session.md
View File

@ -1,7 +0,0 @@
---
title: liteyuki.message.session
order: 1
icon: laptop-code
category: API
---

473
docs/dev/api/mkdoc.md
View File

@ -1,473 +0,0 @@
---
title: liteyuki.mkdoc
order: 1
icon: laptop-code
category: API
---
### ***def*** `get_relative_path(base_path: str, target_path: str) -> str`
获取相对路径
Args:
base_path: 基础路径
target_path: 目标路径
<details>
<summary>源代码</summary>
```python
def get_relative_path(base_path: str, target_path: str) -> str:
"""
获取相对路径
Args:
base_path: 基础路径
target_path: 目标路径
"""
return os.path.relpath(target_path, base_path)
```
</details>
### ***def*** `write_to_files(file_data: dict[str, str]) -> None`
输出文件
Args:
file_data: 文件数据 相对路径
<details>
<summary>源代码</summary>
```python
def write_to_files(file_data: dict[str, str]):
"""
输出文件
Args:
file_data: 文件数据 相对路径
"""
for rp, data in file_data.items():
if not os.path.exists(os.path.dirname(rp)):
os.makedirs(os.path.dirname(rp))
with open(rp, 'w', encoding='utf-8') as f:
f.write(data)
```
</details>
### ***def*** `get_file_list(module_folder: str) -> None`
<details>
<summary>源代码</summary>
```python
def get_file_list(module_folder: str):
file_list = []
for root, dirs, files in os.walk(module_folder):
for file in files:
if file.endswith(('.py', '.pyi')):
file_list.append(os.path.join(root, file))
return file_list
```
</details>
### ***def*** `get_module_info_normal(file_path: str, ignore_private: bool) -> ModuleInfo`
获取函数和类
Args:
file_path: Python 文件路径
ignore_private: 忽略私有函数和类
Returns:
模块信息
<details>
<summary>源代码</summary>
```python
def get_module_info_normal(file_path: str, ignore_private: bool=True) -> ModuleInfo:
"""
获取函数和类
Args:
file_path: Python 文件路径
ignore_private: 忽略私有函数和类
Returns:
模块信息
"""
with open(file_path, 'r', encoding='utf-8') as file:
file_content = file.read()
tree = ast.parse(file_content)
dot_sep_module_path = file_path.replace(os.sep, '.').replace('.py', '').replace('.pyi', '')
module_docstring = ast.get_docstring(tree)
module_info = ModuleInfo(module_path=dot_sep_module_path, functions=[], classes=[], attributes=[], docstring=module_docstring if module_docstring else '')
for node in ast.walk(tree):
if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
if not any((isinstance(parent, ast.ClassDef) for parent in ast.iter_child_nodes(node))) and (not ignore_private or not node.name.startswith('_')):
if node.args.args:
first_arg = node.args.args[0]
if first_arg.arg in ('self', 'cls'):
continue
function_docstring = ast.get_docstring(node)
func_info = FunctionInfo(name=node.name, args=[(arg.arg, ast.unparse(arg.annotation) if arg.annotation else NO_TYPE_ANY) for arg in node.args.args], return_type=ast.unparse(node.returns) if node.returns else 'None', docstring=function_docstring if function_docstring else '', type=DefType.FUNCTION, is_async=isinstance(node, ast.AsyncFunctionDef), source_code=ast.unparse(node))
module_info.functions.append(func_info)
elif isinstance(node, ast.ClassDef):
class_docstring = ast.get_docstring(node)
class_info = ClassInfo(name=node.name, docstring=class_docstring if class_docstring else '', methods=[], attributes=[], inherit=[ast.unparse(base) for base in node.bases])
for class_node in node.body:
if isinstance(class_node, ast.FunctionDef) and (not ignore_private or not class_node.name.startswith('_') or class_node.name == '__init__'):
method_docstring = ast.get_docstring(class_node)
def_type = DefType.METHOD
if class_node.decorator_list:
if any((isinstance(decorator, ast.Name) and decorator.id == 'staticmethod' for decorator in class_node.decorator_list)):
def_type = DefType.STATIC_METHOD
elif any((isinstance(decorator, ast.Name) and decorator.id == 'classmethod' for decorator in class_node.decorator_list)):
def_type = DefType.CLASS_METHOD
elif any((isinstance(decorator, ast.Name) and decorator.id == 'property' for decorator in class_node.decorator_list)):
def_type = DefType.PROPERTY
class_info.methods.append(FunctionInfo(name=class_node.name, args=[(arg.arg, ast.unparse(arg.annotation) if arg.annotation else NO_TYPE_ANY) for arg in class_node.args.args], return_type=ast.unparse(class_node.returns) if class_node.returns else 'None', docstring=method_docstring if method_docstring else '', type=def_type, is_async=isinstance(class_node, ast.AsyncFunctionDef), source_code=ast.unparse(class_node)))
elif isinstance(class_node, ast.Assign):
for target in class_node.targets:
if isinstance(target, ast.Name):
class_info.attributes.append(AttributeInfo(name=target.id, type=ast.unparse(class_node.value)))
module_info.classes.append(class_info)
elif isinstance(node, ast.Assign):
if not any((isinstance(parent, (ast.ClassDef, ast.FunctionDef)) for parent in ast.iter_child_nodes(node))):
for target in node.targets:
if isinstance(target, ast.Name) and (not ignore_private or not target.id.startswith('_')):
attr_type = NO_TYPE_HINT
if isinstance(node.value, ast.AnnAssign) and node.value.annotation:
attr_type = ast.unparse(node.value.annotation)
module_info.attributes.append(AttributeInfo(name=target.id, type=attr_type, value=ast.unparse(node.value) if node.value else None))
return module_info
```
</details>
### ***def*** `generate_markdown(module_info: ModuleInfo, front_matter: Any) -> str`
生成模块的Markdown
你可在此自定义生成的Markdown格式
Args:
module_info: 模块信息
front_matter: 自定义选项title, index, icon, category
Returns:
Markdown 字符串
<details>
<summary>源代码</summary>
```python
def generate_markdown(module_info: ModuleInfo, front_matter=None) -> str:
"""
生成模块的Markdown
你可在此自定义生成的Markdown格式
Args:
module_info: 模块信息
front_matter: 自定义选项title, index, icon, category
Returns:
Markdown 字符串
"""
content = ''
front_matter = '---\n' + '\n'.join([f'{k}: {v}' for k, v in front_matter.items()]) + '\n---\n\n'
content += front_matter
for func in module_info.functions:
args_with_type = [f'{arg[0]}: {arg[1]}' if arg[1] else arg[0] for arg in func.args]
content += f"### ***{('async ' if func.is_async else '')}def*** `{func.name}({', '.join(args_with_type)}) -> {func.return_type}`\n\n"
func.docstring = func.docstring.replace('\n', '\n\n')
content += f'{func.docstring}\n\n'
content += f'<details>\n<summary>源代码</summary>\n\n```python\n{func.source_code}\n```\n</details>\n\n'
for cls in module_info.classes:
if cls.inherit:
inherit = f"({', '.join(cls.inherit)})" if cls.inherit else ''
content += f'### ***class*** `{cls.name}{inherit}`\n\n'
else:
content += f'### ***class*** `{cls.name}`\n\n'
cls.docstring = cls.docstring.replace('\n', '\n\n')
content += f'{cls.docstring}\n\n'
for method in cls.methods:
if method.type != DefType.METHOD:
args_with_type = [f'{arg[0]}: {arg[1]}' if arg[1] else arg[0] for arg in method.args]
content += f'### &emsp; ***@{method.type.value}***\n'
else:
args_with_type = [f'{arg[0]}: {arg[1]}' if arg[1] and arg[0] != 'self' else arg[0] for arg in method.args]
content += f"### &emsp; ***{('async ' if method.is_async else '')}def*** `{method.name}({', '.join(args_with_type)}) -> {method.return_type}`\n\n"
method.docstring = method.docstring.replace('\n', '\n\n')
content += f'&emsp;{method.docstring}\n\n'
content += f'<details>\n<summary>源代码</summary>\n\n```python\n{method.source_code}\n```\n</details>\n\n'
for attr in cls.attributes:
content += f'### &emsp; ***attr*** `{attr.name}: {attr.type}`\n\n'
for attr in module_info.attributes:
if attr.type == NO_TYPE_HINT:
content += f'### ***var*** `{attr.name} = {attr.value}`\n\n'
else:
content += f'### ***var*** `{attr.name}: {attr.type} = {attr.value}`\n\n'
attr.docstring = attr.docstring.replace('\n', '\n\n')
content += f'{attr.docstring}\n\n'
return content
```
</details>
### ***def*** `generate_docs(module_folder: str, output_dir: str, with_top: bool, ignored_paths: Any) -> None`
生成文档
Args:
module_folder: 模块文件夹
output_dir: 输出文件夹
with_top: 是否包含顶层文件夹 False时例如docs/api/module_a, docs/api/module_b， True时例如docs/api/module/module_a.md， docs/api/module/module_b.md
ignored_paths: 忽略的路径
<details>
<summary>源代码</summary>
```python
def generate_docs(module_folder: str, output_dir: str, with_top: bool=False, ignored_paths=None):
"""
生成文档
Args:
module_folder: 模块文件夹
output_dir: 输出文件夹
with_top: 是否包含顶层文件夹 False时例如docs/api/module_a, docs/api/module_b， True时例如docs/api/module/module_a.md， docs/api/module/module_b.md
ignored_paths: 忽略的路径
"""
if ignored_paths is None:
ignored_paths = []
file_data: dict[str, str] = {}
file_list = get_file_list(module_folder)
shutil.rmtree(output_dir, ignore_errors=True)
os.mkdir(output_dir)
replace_data = {'__init__': 'README', '.py': '.md'}
for pyfile_path in file_list:
if any((ignored_path.replace('\\', '/') in pyfile_path.replace('\\', '/') for ignored_path in ignored_paths)):
continue
no_module_name_pyfile_path = get_relative_path(module_folder, pyfile_path)
rel_md_path = pyfile_path if with_top else no_module_name_pyfile_path
for rk, rv in replace_data.items():
rel_md_path = rel_md_path.replace(rk, rv)
abs_md_path = os.path.join(output_dir, rel_md_path)
module_info = get_module_info_normal(pyfile_path)
if 'README' in abs_md_path:
front_matter = {'title': module_info.module_path.replace('.__init__', '').replace('_', '\\n'), 'index': 'true', 'icon': 'laptop-code', 'category': 'API'}
else:
front_matter = {'title': module_info.module_path.replace('_', '\\n'), 'order': '1', 'icon': 'laptop-code', 'category': 'API'}
md_content = generate_markdown(module_info, front_matter)
print(f'Generate {pyfile_path} -> {abs_md_path}')
file_data[abs_md_path] = md_content
write_to_files(file_data)
```
</details>
### ***class*** `DefType(Enum)`
### &emsp; ***attr*** `FUNCTION: 'function'`
### &emsp; ***attr*** `METHOD: 'method'`
### &emsp; ***attr*** `STATIC_METHOD: 'staticmethod'`
### &emsp; ***attr*** `CLASS_METHOD: 'classmethod'`
### &emsp; ***attr*** `PROPERTY: 'property'`
### ***class*** `FunctionInfo(BaseModel)`
### ***class*** `AttributeInfo(BaseModel)`
### ***class*** `ClassInfo(BaseModel)`
### ***class*** `ModuleInfo(BaseModel)`
### ***var*** `NO_TYPE_ANY = 'Any'`
### ***var*** `NO_TYPE_HINT = 'NoTypeHint'`
### ***var*** `FUNCTION = 'function'`
### ***var*** `METHOD = 'method'`
### ***var*** `STATIC_METHOD = 'staticmethod'`
### ***var*** `CLASS_METHOD = 'classmethod'`
### ***var*** `PROPERTY = 'property'`
### ***var*** `file_list = []`
### ***var*** `dot_sep_module_path = file_path.replace(os.sep, '.').replace('.py', '').replace('.pyi', '')`
### ***var*** `module_docstring = ast.get_docstring(tree)`
### ***var*** `module_info = ModuleInfo(module_path=dot_sep_module_path, functions=[], classes=[], attributes=[], docstring=module_docstring if module_docstring else '')`
### ***var*** `content = ''`
### ***var*** `front_matter = '---\n' + '\n'.join([f'{k}: {v}' for k, v in front_matter.items()]) + '\n---\n\n'`
### ***var*** `file_list = get_file_list(module_folder)`
### ***var*** `replace_data = {'__init__': 'README', '.py': '.md'}`
### ***var*** `file_content = file.read()`
### ***var*** `tree = ast.parse(file_content)`
### ***var*** `args_with_type = [f'{arg[0]}: {arg[1]}' if arg[1] else arg[0] for arg in func.args]`
### ***var*** `ignored_paths = []`
### ***var*** `no_module_name_pyfile_path = get_relative_path(module_folder, pyfile_path)`
### ***var*** `rel_md_path = pyfile_path if with_top else no_module_name_pyfile_path`
### ***var*** `abs_md_path = os.path.join(output_dir, rel_md_path)`
### ***var*** `module_info = get_module_info_normal(pyfile_path)`
### ***var*** `md_content = generate_markdown(module_info, front_matter)`
### ***var*** `inherit = f"({', '.join(cls.inherit)})" if cls.inherit else ''`
### ***var*** `rel_md_path = rel_md_path.replace(rk, rv)`
### ***var*** `front_matter = {'title': module_info.module_path.replace('.__init__', '').replace('_', '\\n'), 'index': 'true', 'icon': 'laptop-code', 'category': 'API'}`
### ***var*** `front_matter = {'title': module_info.module_path.replace('_', '\\n'), 'order': '1', 'icon': 'laptop-code', 'category': 'API'}`
### ***var*** `function_docstring = ast.get_docstring(node)`
### ***var*** `func_info = FunctionInfo(name=node.name, args=[(arg.arg, ast.unparse(arg.annotation) if arg.annotation else NO_TYPE_ANY) for arg in node.args.args], return_type=ast.unparse(node.returns) if node.returns else 'None', docstring=function_docstring if function_docstring else '', type=DefType.FUNCTION, is_async=isinstance(node, ast.AsyncFunctionDef), source_code=ast.unparse(node))`
### ***var*** `class_docstring = ast.get_docstring(node)`
### ***var*** `class_info = ClassInfo(name=node.name, docstring=class_docstring if class_docstring else '', methods=[], attributes=[], inherit=[ast.unparse(base) for base in node.bases])`
### ***var*** `args_with_type = [f'{arg[0]}: {arg[1]}' if arg[1] else arg[0] for arg in method.args]`
### ***var*** `args_with_type = [f'{arg[0]}: {arg[1]}' if arg[1] and arg[0] != 'self' else arg[0] for arg in method.args]`
### ***var*** `first_arg = node.args.args[0]`
### ***var*** `method_docstring = ast.get_docstring(class_node)`
### ***var*** `def_type = DefType.METHOD`
### ***var*** `def_type = DefType.STATIC_METHOD`
### ***var*** `attr_type = NO_TYPE_HINT`
### ***var*** `def_type = DefType.CLASS_METHOD`
### ***var*** `attr_type = ast.unparse(node.value.annotation)`
### ***var*** `def_type = DefType.PROPERTY`

29
docs/dev/api/plugin/README.md
View File

@ -1,29 +0,0 @@
---
title: liteyuki.plugin
index: true
icon: laptop-code
category: API
---
### ***def*** `get_loaded_plugins() -> dict[str, Plugin]`
获取已加载的插件
Returns:
dict[str, Plugin]: 插件字典
<details>
<summary>源代码</summary>
```python
def get_loaded_plugins() -> dict[str, Plugin]:
"""
获取已加载的插件
Returns:
dict[str, Plugin]: 插件字典
"""
return _plugins
```
</details>

199
docs/dev/api/plugin/load.md
View File

@ -1,199 +0,0 @@
---
title: liteyuki.plugin.load
order: 1
icon: laptop-code
category: API
---
### ***def*** `load_plugin(module_path: str | Path) -> Optional[Plugin]`
加载单个插件，可以是本地插件或是通过 `pip` 安装的插件。
参数:
module_path: 插件名称 `path.to.your.plugin`
或插件路径 `pathlib.Path(path/to/your/plugin)`
<details>
<summary>源代码</summary>
```python
def load_plugin(module_path: str | Path) -> Optional[Plugin]:
"""加载单个插件，可以是本地插件或是通过 `pip` 安装的插件。
参数:
module_path: 插件名称 `path.to.your.plugin`
或插件路径 `pathlib.Path(path/to/your/plugin)`
"""
module_path = path_to_module_name(Path(module_path)) if isinstance(module_path, Path) else module_path
try:
module = import_module(module_path)
_plugins[module.__name__] = Plugin(name=module.__name__, module=module, module_name=module_path, metadata=module.__dict__.get('__plugin_metadata__', None))
display_name = module.__name__.split('.')[-1]
if module.__dict__.get('__plugin_meta__'):
metadata: 'PluginMetadata' = module.__dict__['__plugin_meta__']
display_name = format_display_name(f"{metadata.name}({module.__name__.split('.')[-1]})", metadata.type)
logger.opt(colors=True).success(f'Succeeded to load liteyuki plugin "{display_name}"')
return _plugins[module.__name__]
except Exception as e:
logger.opt(colors=True).success(f'Failed to load liteyuki plugin "<r>{module_path}</r>"')
traceback.print_exc()
return None
```
</details>
### ***def*** `load_plugins() -> set[Plugin]`
导入文件夹下多个插件
参数:
plugin_dir: 文件夹路径
ignore_warning: 是否忽略警告，通常是目录不存在或目录为空
<details>
<summary>源代码</summary>
```python
def load_plugins(*plugin_dir: str, ignore_warning: bool=True) -> set[Plugin]:
"""导入文件夹下多个插件
参数:
plugin_dir: 文件夹路径
ignore_warning: 是否忽略警告，通常是目录不存在或目录为空
"""
plugins = set()
for dir_path in plugin_dir:
if not os.path.exists(dir_path):
if not ignore_warning:
logger.warning(f"Plugins dir '{dir_path}' does not exist.")
continue
if not os.listdir(dir_path):
if not ignore_warning:
logger.warning(f"Plugins dir '{dir_path}' is empty.")
continue
if not os.path.isdir(dir_path):
if not ignore_warning:
logger.warning(f"Plugins dir '{dir_path}' is not a directory.")
continue
for f in os.listdir(dir_path):
path = Path(os.path.join(dir_path, f))
module_name = None
if os.path.isfile(path) and f.endswith('.py') and (f != '__init__.py'):
module_name = f'{path_to_module_name(Path(dir_path))}.{f[:-3]}'
elif os.path.isdir(path) and os.path.exists(os.path.join(path, '__init__.py')):
module_name = path_to_module_name(path)
if module_name:
load_plugin(module_name)
if _plugins.get(module_name):
plugins.add(_plugins[module_name])
return plugins
```
</details>
### ***def*** `format_display_name(display_name: str, plugin_type: PluginType) -> str`
设置插件名称颜色，根据不同类型插件设置颜色
Args:
display_name: 插件名称
plugin_type: 插件类型
Returns:
str: 设置后的插件名称 <y>name</y>
<details>
<summary>源代码</summary>
```python
def format_display_name(display_name: str, plugin_type: PluginType) -> str:
"""
设置插件名称颜色，根据不同类型插件设置颜色
Args:
display_name: 插件名称
plugin_type: 插件类型
Returns:
str: 设置后的插件名称 <y>name</y>
"""
color = 'y'
match plugin_type:
case PluginType.APPLICATION:
color = 'm'
case PluginType.TEST:
color = 'g'
case PluginType.MODULE:
color = 'e'
case PluginType.SERVICE:
color = 'c'
return f'<{color}>{display_name} [{plugin_type.name}]</{color}>'
```
</details>
### ***var*** `module_path = path_to_module_name(Path(module_path)) if isinstance(module_path, Path) else module_path`
### ***var*** `plugins = set()`
### ***var*** `color = 'y'`
### ***var*** `module = import_module(module_path)`
### ***var*** `display_name = module.__name__.split('.')[-1]`
### ***var*** `display_name = format_display_name(f"{metadata.name}({module.__name__.split('.')[-1]})", metadata.type)`
### ***var*** `path = Path(os.path.join(dir_path, f))`
### ***var*** `module_name = None`
### ***var*** `color = 'm'`
### ***var*** `color = 'g'`
### ***var*** `color = 'e'`
### ***var*** `color = 'c'`
### ***var*** `module_name = f'{path_to_module_name(Path(dir_path))}.{f[:-3]}'`
### ***var*** `module_name = path_to_module_name(path)`

7
docs/dev/api/plugin/manager.md
View File

@ -1,7 +0,0 @@
---
title: liteyuki.plugin.manager
order: 1
icon: laptop-code
category: API
---

89
docs/dev/api/plugin/model.md
View File

@ -1,89 +0,0 @@
---
title: liteyuki.plugin.model
order: 1
icon: laptop-code
category: API
---
### ***class*** `PluginType(Enum)`
插件类型枚举值
### &emsp; ***attr*** `APPLICATION: 'application'`
### &emsp; ***attr*** `SERVICE: 'service'`
### &emsp; ***attr*** `MODULE: 'module'`
### &emsp; ***attr*** `UNCLASSIFIED: 'unclassified'`
### &emsp; ***attr*** `TEST: 'test'`
### ***class*** `PluginMetadata(BaseModel)`
轻雪插件元数据，由插件编写者提供，name为必填项
Attributes:
----------
name: str
插件名称
description: str
插件描述
usage: str
插件使用方法
type: str
插件类型
author: str
插件作者
homepage: str
插件主页
extra: dict[str, Any]
额外信息
### ***class*** `Plugin(BaseModel)`
存储插件信息
### &emsp; ***attr*** `model_config: {'arbitrary_types_allowed': True}`
### ***var*** `APPLICATION = 'application'`
### ***var*** `SERVICE = 'service'`
### ***var*** `MODULE = 'module'`
### ***var*** `UNCLASSIFIED = 'unclassified'`
### ***var*** `TEST = 'test'`
### ***var*** `model_config = {'arbitrary_types_allowed': True}`

180
docs/dev/api/utils.md
View File

@ -1,180 +0,0 @@
---
title: liteyuki.utils
order: 1
icon: laptop-code
category: API
---
### ***def*** `is_coroutine_callable(call: Callable[..., Any]) -> bool`
判断是否为协程可调用对象
Args:
call: 可调用对象
Returns:
bool: 是否为协程可调用对象
<details>
<summary>源代码</summary>
```python
def is_coroutine_callable(call: Callable[..., Any]) -> bool:
"""
判断是否为协程可调用对象
Args:
call: 可调用对象
Returns:
bool: 是否为协程可调用对象
"""
if inspect.isroutine(call):
return inspect.iscoroutinefunction(call)
if inspect.isclass(call):
return False
func_ = getattr(call, '__call__', None)
return inspect.iscoroutinefunction(func_)
```
</details>
### ***def*** `run_coroutine() -> None`
运行协程
Args:
coro:
Returns:
<details>
<summary>源代码</summary>
```python
def run_coroutine(*coro: Coroutine):
"""
运行协程
Args:
coro:
Returns:
"""
try:
loop = asyncio.get_event_loop()
if loop.is_running():
for c in coro:
asyncio.ensure_future(c)
else:
for c in coro:
loop.run_until_complete(c)
except RuntimeError:
loop = asyncio.new_event_loop()
asyncio.set_event_loop(loop)
loop.run_until_complete(asyncio.gather(*coro))
loop.close()
except Exception as e:
logger.error(f'Exception occurred: {e}')
```
</details>
### ***def*** `path_to_module_name(path: Path) -> str`
转换路径为模块名
Args:
path: 路径a/b/c/d -> a.b.c.d
Returns:
str: 模块名
<details>
<summary>源代码</summary>
```python
def path_to_module_name(path: Path) -> str:
"""
转换路径为模块名
Args:
path: 路径a/b/c/d -> a.b.c.d
Returns:
str: 模块名
"""
rel_path = path.resolve().relative_to(Path.cwd().resolve())
if rel_path.stem == '__init__':
return '.'.join(rel_path.parts[:-1])
else:
return '.'.join(rel_path.parts[:-1] + (rel_path.stem,))
```
</details>
### ***def*** `async_wrapper(func: Callable[..., Any]) -> Callable[..., Coroutine]`
异步包装器
Args:
func: Sync Callable
Returns:
Coroutine: Asynchronous Callable
<details>
<summary>源代码</summary>
```python
def async_wrapper(func: Callable[..., Any]) -> Callable[..., Coroutine]:
"""
异步包装器
Args:
func: Sync Callable
Returns:
Coroutine: Asynchronous Callable
"""
async def wrapper(*args, **kwargs):
return func(*args, **kwargs)
wrapper.__signature__ = inspect.signature(func)
return wrapper
```
</details>
### ***async def*** `wrapper() -> None`
<details>
<summary>源代码</summary>
```python
async def wrapper(*args, **kwargs):
return func(*args, **kwargs)
```
</details>
### ***var*** `IS_MAIN_PROCESS = multiprocessing.current_process().name == 'MainProcess'`
### ***var*** `func_ = getattr(call, '__call__', None)`
### ***var*** `rel_path = path.resolve().relative_to(Path.cwd().resolve())`
### ***var*** `loop = asyncio.get_event_loop()`
### ***var*** `loop = asyncio.new_event_loop()`

99
docs/dev/dev_comm.md
View File

@ -1,99 +0,0 @@
---
title: 进程通信
icon: exchange-alt
order: 4
category: 开发
---
## **通道通信**
### 简介
轻雪运行在主进程 MainProcess 里，其他插件框架进程是伴随的子进程，因此无法通过内存共享和直接对象传递的方式进行通信，轻雪提供了一个通道`Channel`用于跨进程通信，你可以通过`Channel`发送消息给其他进程，也可以监听其他进程的消息。
例如子进程接收到用户信息需要重启机器人，这时可以通过通道对主进程发送消息，主进程接收到消息后重启对应子进程。
### 示例
通道是全双工的，有两种接收模式，但一个通道只能使用一种，即被动模式和主动模式，被动模式由`chan.on_receive()`装饰回调函数实现，主动模式需调用`chan.receive()`实现
- 创建子进程的同时会初始化一个被动通道和一个主动通道，且通道标识为`{process_name}-active`和`{process_name}-passive`，
- 主进程中通过`get_channel`函数获取通道对象
- 子进程中导入单例`active_channel`及`passive_channel`即可
> 在轻雪插件中(主进程中)
```python
import asyncio
from liteyuki.comm import get_channel, Channel
from liteyuki import get_bot
# get_channel函数获取通道对象，参数为调用set_channel时的通道标识
channel_passive = get_channel("nonebot-passive") # 获取被动通道
channel_active = get_channel("nonebot-active") # 获取主动通道
liteyuki_bot = get_bot()
# 注册一个函数在轻雪启动后运行
@liteyuki_bot.on_after_start
async def send_data():
while True:
channel_passive.send("I am liteyuki main process passive")
channel_active.send("I am liteyuki main process active")
await asyncio.sleep(3) # 每3秒发送一次消息
```
> 在子进程中（例如NoneBot插件中）
```python
from nonebot import get_driver
from liteyuki.comm import active_channel, passive_channel # 子进程中获取通道直接导入进程全局单例即可
from liteyuki.log import logger
driver = get_driver()
# 被动模式，通过装饰器注册一个函数在接收到消息时运行，每次接收到字符串数据时都会运行
@passive_channel.on_receive(filter_func=lambda data: isinstance(data, str))
async def on_passive_receive(data):
logger.info(f"Passive receive: {data}")
# 注册一个函数在NoneBot启动后运行
@driver.on_startup
def on_startup():
while True:
data = active_channel.receive()
logger.info(f"Active receive: {data}")
```
> 启动后控制台输出
```log
0000-00-00 00:00:00 [ℹ️信息] Passive receive: I am liteyuki main process passive
0000-00-00 00:00:00 [ℹ️信息] Active receive: I am liteyuki main process active
0000-00-00 00:00:03 [ℹ️信息] Passive receive: I am liteyuki main process passive
0000-00-00 00:00:03 [ℹ️信息] Active receive: I am liteyuki main process active
...
```
## **共享内存通信**
### 简介
- 相比于普通进程通信，内存共享使得代码编写更加简洁，轻雪框架提供了一个内存共享通信的接口，你可以通过`storage`模块实现内存共享通信，该模块封装通道实现
- 内存共享是线程安全的，你可以在多个线程中读写共享内存，线程锁会自动保护共享内存的读写操作
### 示例
> 在任意进程中均可使用
```python
from liteyuki.comm.storage import shared_memory
shared_memory.set("key", "value") # 设置共享内存
value = shared_memory.get("key") # 获取共享内存
```
源代码：[liteyuki/comm/storage.py](https://github.com/LiteyukiStudio/LiteyukiBot/blob/main/liteyuki/comm/storage.py)

74
docs/dev/dev_lyfunc.md
View File

@ -1,74 +0,0 @@
---
title: 轻雪函数
icon: code
order: 2
category: 开发
---
## **轻雪函数**
轻雪函数 Liteyuki Function 是轻雪的一个功能，它允许你在轻雪中运行一些自定义的由数据驱动的命令，类似于Minecraft的mcfunction，属于资源包的一部分，但需单独起篇幅.
### **函数文件**
函数文件放在资源包的`functions`目录下，文件名以`.mcfunction` `.lyfunction` `.lyf`结尾，例如`test.mcfunction`，文件内容为一系列的命令，每行一个命令，支持单行注释`#`(编辑时的语法高亮可采取`shell`格式)，例如：
```shell
# 在发信器输出"hello world"
cmd echo hello world
# 如果你想同时输出多行内容可以尝试换行符(Python格式)
cmd echo hello world\nLiteyuki bot
```
也支持句末注释，例如：
```shell
cmd echo hello world # 输出"hello world"
```
### **命令文档**
```shell
var <var1=value1> [var2=value2] ... # 定义变量
cmd <command> # 在设备上执行命令
api <api_name> [var=value...] # 调用Bot API
function <func_name> # 调用函数，可递归
sleep <time> # 异步等待，单位s
nohup <command> # 使用新的task执行命令，即不等待
end # 结束函数关键字，包括子task
await # 等待所有异步任务结束，若函数中启动了其他task，需要在最后调用，否则task对象会被销毁
```
#### **示例**
```shell
# 疯狂戳好友
# 使用 /function poke user_id=123456 执行
# 每隔0.2s戳两次，无限戳，会触发最大递归深度限制
# 若要戳20s后停止，则需要删除await，添加sleep 20和end
api friend_poke user_id=user_id
api friend_poke user_id=user_id
sleep 0.2
nohup function poke
await
```
### **API**
理论上所有基于onebotv11的api都可调用，不同Adapter api也有差别.
[Onebot v11 API文档](https://283375.github.io/onebot_v11_vitepress/api/index.html)
### **结束关键字**
由于LiteyukiBot基于异步运行, 所以在编写lyfunction时也要注意异步的调用，避免出现"单线程走到底"的情况是效率提升的关键.
`await` 异步任务结束关键字，用于结束当前已完成function的执行
> [!warning]
> 但若出现非单function的情况，有一个task任务没有完成而await被执行了，那么当前所有函数包的task都会被截停销毁
> [!tip]
> 编写轻雪函数推荐你使用VS Code插件[Liteyuki Function](https://github.com/LiteyukiStudio/lyfunctionTextmate)实现语法高亮

82
docs/dev/dev_lyplugin.md
View File

@ -1,82 +0,0 @@
---
title: 轻雪插件开发
icon: laptop-code
order: 3
category: 开发
---
## 简介
轻雪插件是轻雪内置的一部分功能，运行在主进程中，可以很高程度地扩展轻雪的功能
## 开始
### 创建插件
一个`.py`文件或一个包含`__init__.py`的文件夹即可被识别为插件
首先创建一个文件夹，例如`watchdog_plugin`，并在其中创建一个`__init__.py`文件，即可创建一个插件
`__init__.py`
```python
from liteyuki.plugin import PluginMetadata, PluginType
from .watch_dog import * # 导入逻辑部分
# 定义插件元数据
__plugin_meta__ = PluginMetadata(
name="NoneDog", # 插件名称
version="1.0.0", # 插件版本
description="A simple plugin for nonebot developer", # 插件描述
type=PluginType.SERVICE # 插件类型
)
# 你的插件代码
...
```
### 编写逻辑部分
轻雪主进程不涉及聊天部分，因此插件主要是一些后台任务或者与聊天机器人的通信
以下我们会编写一个简单的插件，用于开发NoneBot时进行文件系统变更重载
`watch_dog.py`
```python
import os
from liteyuki.dev import observer # 导入文件系统观察器
from liteyuki import get_bot, logger # 导入轻雪Bot和日志
from watchdog.events import FileSystemEvent # 导入文件系统事件
liteyuki = get_bot() # 获取唯一的轻雪Bot实例
exclude_extensions = (".pyc", ".pyo") # 排除的文件扩展名
# 用observer的on_file_system_event装饰器监听文件系统事件
@observer.on_file_system_event(
directories=("src/nonebot_plugins",),
event_filter=lambda event: not event.src_path.endswith(exclude_extensions) and ("__pycache__" not in event.src_path) and os.path.isfile(event.src_path)
)
def restart_nonebot_process(event: FileSystemEvent):
logger.debug(f"File {event.src_path} changed, reloading nonebot...")
liteyuki.restart_process("nonebot") # 调用重启进程方法
```
### 加载插件
#### 方法1
- 在配置文件中的`liteyuki.plugins`中添加你的插件路径，例如`watchdog_plugin`，重启轻雪即可加载插件。
#### 方法2
- 使用开发工具快速运行插件，无需手动创建实例
- 创建入口文件，例如`main.py`，并在其中写入以下代码
```python
from liteyuki.dev.plugin import run_plugins
run_plugins("watchdog_plugin")
```
然后运行`python main.py`即可启动插件
启用插件后，我们在src/nonebot_plugins下创建一个文件，例如`test.py`，并在其中写入一些代码，保存后轻雪会自动重载NoneBot进程

53
docs/dev/dev_resource_pack.md
View File

@ -1,53 +0,0 @@
---
title: 资源包开发
icon: box
order: 1
category: 开发
---
## 简介
资源包,亦可根据用途称为主题包、字体包、语言包等，它允许你一定程度上自定义轻雪的外观,并且不用修改源代码
- [资源/主题商店](/store/)提供了一些资源包供你选择，你也可以自己制作资源包
- 资源包的制作很简单，如果你接触过`Minecraft`的资源包，那么你能够很快就上手，仅需按照原有路径进行文件替换即可，讲起打包成一个新的资源包。
- 部分内容制作需要一点点前端基础,例如`html`，`css`
- 轻雪原版资源包请查看`LiteyukiBot/liteyuki/resources`，可以在此基础上进行修改
- 欢迎各位投稿资源包到轻雪资源商店
请注意，主题包中的html渲染使用Js来规定数据的渲染位置，请确保您所编写的html代码能被Bot解析，否则会导致渲染失败或渲染结果不理想/异常/错位等无法预料的事情发生。推荐在编写html时同时更改对应Js代码，以避免出现无法预料的问题。
---
## 加载资源包
- 资源包通常是以`.zip`格式压缩的，只需要将其解压到根目录`resources`目录下即可，注意不要嵌套文件夹,正常的路径应该是这样的
```shell
main.py
resources
└─resource_pack_1
├─metadata.yml
├─templates
└───...
└─resource_pack_2
├─metadata.yml
└─...
```
- 你自己制作的资源包也应该遵循这个规则,并且应该在`metadata.yml`中填写一些信息
- 若没有`metadata.yml`文件，则该文件夹不会被识别为资源包
```yaml
name: "资源包名称"
version: "1.0.0"
description: "资源包描述"
# 你可以自定义一些信息,但请保证以上三个字段
...
```
- 资源包加载遵循一个优先级，即后加载的资源包会覆盖前面的资源包，例如，你在A包中定义了一个`index.html`文件，B包也定义了一个`index.html`文件，那么加载B包后，A包中的`index.html`文件会被覆盖
- 对于不同资源包的不同文件，是可以相对引用的，例如你在A中定义了`templates/index.html`，在B中定义了`templates/style.css`，可以在A的`index.html`中用`./style.css`相对路径引用B中的css
> [!tip]
> 资源包的结构会随着轻雪的更新而有变动，第三方资源包开发者需要注意版本兼容性，同时用户也应该自行选择可用的资源包

8
docs/en/dev/README.md
View File

@ -1,8 +0,0 @@
---
title: Contribute
index: false
icon: laptop-code
category: 开发
---
<Catalog />

7
docs/en/dev/api/README.md
View File

@ -1,7 +0,0 @@
---
title: liteyuki
index: true
icon: laptop-code
category: API
---

581
docs/en/dev/api/bot/README.md
View File

@ -1,581 +0,0 @@
---
title: liteyuki.bot
index: true
icon: laptop-code
category: API
---
### ***def*** `get_bot() -> LiteyukiBot`
获取轻雪实例
Returns:
LiteyukiBot: 当前的轻雪实例
<details>
<summary>源代码</summary>
```python
def get_bot() -> LiteyukiBot:
"""
获取轻雪实例
Returns:
LiteyukiBot: 当前的轻雪实例
"""
if IS_MAIN_PROCESS:
if _BOT_INSTANCE is None:
raise RuntimeError('Liteyuki instance not initialized.')
return _BOT_INSTANCE
else:
raise RuntimeError("Can't get bot instance in sub process.")
```
</details>
### ***def*** `get_config(key: str, default: Any) -> Any`
获取配置
Args:
key: 配置键
default: 默认值
Returns:
Any: 配置值
<details>
<summary>源代码</summary>
```python
def get_config(key: str, default: Any=None) -> Any:
"""
获取配置
Args:
key: 配置键
default: 默认值
Returns:
Any: 配置值
"""
return get_bot().config.get(key, default)
```
</details>
### ***def*** `get_config_with_compat(key: str, compat_keys: tuple[str], default: Any) -> Any`
获取配置，兼容旧版本
Args:
key: 配置键
compat_keys: 兼容键
default: 默认值
Returns:
Any: 配置值
<details>
<summary>源代码</summary>
```python
def get_config_with_compat(key: str, compat_keys: tuple[str], default: Any=None) -> Any:
"""
获取配置，兼容旧版本
Args:
key: 配置键
compat_keys: 兼容键
default: 默认值
Returns:
Any: 配置值
"""
if key in get_bot().config:
return get_bot().config[key]
for compat_key in compat_keys:
if compat_key in get_bot().config:
logger.warning(f'Config key "{compat_key}" will be deprecated, use "{key}" instead.')
return get_bot().config[compat_key]
return default
```
</details>
### ***def*** `print_logo() -> None`
<details>
<summary>源代码</summary>
```python
def print_logo():
print('\x1b[34m' + '\n __ ______ ________ ________ __ __ __ __ __ __ ______ \n / | / |/ |/ |/ \\ / |/ | / |/ | / |/ |\n $$ | $$$$$$/ $$$$$$$$/ $$$$$$$$/ $$ \\ /$$/ $$ | $$ |$$ | /$$/ $$$$$$/ \n $$ | $$ | $$ | $$ |__ $$ \\/$$/ $$ | $$ |$$ |/$$/ $$ | \n $$ | $$ | $$ | $$ | $$ $$/ $$ | $$ |$$ $$< $$ | \n $$ | $$ | $$ | $$$$$/ $$$$/ $$ | $$ |$$$$$ \\ $$ | \n $$ |_____ _$$ |_ $$ | $$ |_____ $$ | $$ \\__$$ |$$ |$$ \\ _$$ |_ \n $$ |/ $$ | $$ | $$ | $$ | $$ $$/ $$ | $$ |/ $$ |\n $$$$$$$$/ $$$$$$/ $$/ $$$$$$$$/ $$/ $$$$$$/ $$/ $$/ $$$$$$/ \n ' + '\x1b[0m')
```
</details>
### ***class*** `LiteyukiBot`
### &emsp; ***def*** `__init__(self) -> None`
&emsp;初始化轻雪实例
Args:
*args:
**kwargs: 配置
<details>
<summary>源代码</summary>
```python
def __init__(self, *args, **kwargs) -> None:
"""
初始化轻雪实例
Args:
*args:
**kwargs: 配置
"""
'常规操作'
print_logo()
global _BOT_INSTANCE
_BOT_INSTANCE = self
'配置'
self.config: dict[str, Any] = kwargs
'初始化'
self.init(**self.config)
logger.info('Liteyuki is initializing...')
'生命周期管理'
self.lifespan = Lifespan()
self.process_manager: ProcessManager = ProcessManager(lifespan=self.lifespan)
'事件循环'
self.loop = asyncio.new_event_loop()
asyncio.set_event_loop(self.loop)
self.stop_event = threading.Event()
self.call_restart_count = 0
'加载插件加载器'
load_plugin('liteyuki.plugins.plugin_loader')
'信号处理'
signal.signal(signal.SIGINT, self._handle_exit)
signal.signal(signal.SIGTERM, self._handle_exit)
atexit.register(self.process_manager.terminate_all)
```
</details>
### &emsp; ***def*** `run(self) -> None`
&emsp;启动逻辑
<details>
<summary>源代码</summary>
```python
def run(self):
"""
启动逻辑
"""
self.lifespan.before_start()
self.process_manager.start_all()
self.lifespan.after_start()
self.keep_alive()
```
</details>
### &emsp; ***def*** `keep_alive(self) -> None`
&emsp;保持轻雪运行
Returns:
<details>
<summary>源代码</summary>
```python
def keep_alive(self):
"""
保持轻雪运行
Returns:
"""
try:
while not self.stop_event.is_set():
time.sleep(0.5)
except KeyboardInterrupt:
logger.info('Liteyuki is stopping...')
self.stop()
```
</details>
### &emsp; ***def*** `restart(self, delay: int) -> None`
&emsp;重启轻雪本体
Returns:
<details>
<summary>源代码</summary>
```python
def restart(self, delay: int=0):
"""
重启轻雪本体
Returns:
"""
if self.call_restart_count < 1:
executable = sys.executable
args = sys.argv
logger.info('Restarting LiteyukiBot...')
time.sleep(delay)
if platform.system() == 'Windows':
cmd = 'start'
elif platform.system() == 'Linux':
cmd = 'nohup'
elif platform.system() == 'Darwin':
cmd = 'open'
else:
cmd = 'nohup'
self.process_manager.terminate_all()
threading.Thread(target=os.system, args=(f"{cmd} {executable} {' '.join(args)}",)).start()
sys.exit(0)
self.call_restart_count += 1
```
</details>
### &emsp; ***def*** `restart_process(self, name: Optional[str]) -> None`
&emsp;停止轻雪
Args:
name: 进程名称, 默认为None, 所有进程
Returns:
<details>
<summary>源代码</summary>
```python
def restart_process(self, name: Optional[str]=None):
"""
停止轻雪
Args:
name: 进程名称, 默认为None, 所有进程
Returns:
"""
self.lifespan.before_process_shutdown()
self.lifespan.before_process_shutdown()
if name is not None:
chan_active = get_channel(f'{name}-active')
chan_active.send(1)
else:
for process_name in self.process_manager.processes:
chan_active = get_channel(f'{process_name}-active')
chan_active.send(1)
```
</details>
### &emsp; ***def*** `init(self) -> None`
&emsp;初始化轻雪, 自动调用
Returns:
<details>
<summary>源代码</summary>
```python
def init(self, *args, **kwargs):
"""
初始化轻雪, 自动调用
Returns:
"""
self.init_logger()
```
</details>
### &emsp; ***def*** `init_logger(self) -> None`
&emsp;
<details>
<summary>源代码</summary>
```python
def init_logger(self):
init_log(config=self.config)
```
</details>
### &emsp; ***def*** `stop(self) -> None`
&emsp;停止轻雪
Returns:
<details>
<summary>源代码</summary>
```python
def stop(self):
"""
停止轻雪
Returns:
"""
self.stop_event.set()
self.loop.stop()
```
</details>
### &emsp; ***def*** `on_before_start(self, func: LIFESPAN_FUNC) -> None`
&emsp;注册启动前的函数
Args:
func:
Returns:
<details>
<summary>源代码</summary>
```python
def on_before_start(self, func: LIFESPAN_FUNC):
"""
注册启动前的函数
Args:
func:
Returns:
"""
return self.lifespan.on_before_start(func)
```
</details>
### &emsp; ***def*** `on_after_start(self, func: LIFESPAN_FUNC) -> None`
&emsp;注册启动后的函数
Args:
func:
Returns:
<details>
<summary>源代码</summary>
```python
def on_after_start(self, func: LIFESPAN_FUNC):
"""
注册启动后的函数
Args:
func:
Returns:
"""
return self.lifespan.on_after_start(func)
```
</details>
### &emsp; ***def*** `on_after_shutdown(self, func: LIFESPAN_FUNC) -> None`
&emsp;注册停止后的函数：未实现
Args:
func:
Returns:
<details>
<summary>源代码</summary>
```python
def on_after_shutdown(self, func: LIFESPAN_FUNC):
"""
注册停止后的函数：未实现
Args:
func:
Returns:
"""
return self.lifespan.on_after_shutdown(func)
```
</details>
### &emsp; ***def*** `on_before_process_shutdown(self, func: LIFESPAN_FUNC) -> None`
&emsp;注册进程停止前的函数，为子进程停止时调用
Args:
func:
Returns:
<details>
<summary>源代码</summary>
```python
def on_before_process_shutdown(self, func: LIFESPAN_FUNC):
"""
注册进程停止前的函数，为子进程停止时调用
Args:
func:
Returns:
"""
return self.lifespan.on_before_process_shutdown(func)
```
</details>
### &emsp; ***def*** `on_before_process_restart(self, func: LIFESPAN_FUNC) -> None`
&emsp;注册进程重启前的函数，为子进程重启时调用
Args:
func:
Returns:
<details>
<summary>源代码</summary>
```python
def on_before_process_restart(self, func: LIFESPAN_FUNC):
"""
注册进程重启前的函数，为子进程重启时调用
Args:
func:
Returns:
"""
return self.lifespan.on_before_process_restart(func)
```
</details>
### &emsp; ***def*** `on_after_restart(self, func: LIFESPAN_FUNC) -> None`
&emsp;注册重启后的函数：未实现
Args:
func:
Returns:
<details>
<summary>源代码</summary>
```python
def on_after_restart(self, func: LIFESPAN_FUNC):
"""
注册重启后的函数：未实现
Args:
func:
Returns:
"""
return self.lifespan.on_after_restart(func)
```
</details>
### &emsp; ***def*** `on_after_nonebot_init(self, func: LIFESPAN_FUNC) -> None`
&emsp;注册nonebot初始化后的函数
Args:
func:
Returns:
<details>
<summary>源代码</summary>
```python
def on_after_nonebot_init(self, func: LIFESPAN_FUNC):
"""
注册nonebot初始化后的函数
Args:
func:
Returns:
"""
return self.lifespan.on_after_nonebot_init(func)
```
</details>
### ***var*** `executable = sys.executable`
### ***var*** `args = sys.argv`
### ***var*** `chan_active = get_channel(f'{name}-active')`
### ***var*** `cmd = 'start'`
### ***var*** `chan_active = get_channel(f'{process_name}-active')`
### ***var*** `cmd = 'nohup'`
### ***var*** `cmd = 'open'`
### ***var*** `cmd = 'nohup'`

450
docs/en/dev/api/bot/lifespan.md
View File

@ -1,450 +0,0 @@
---
title: liteyuki.bot.lifespan
order: 1
icon: laptop-code
category: API
---
### ***def*** `run_funcs(funcs: list[LIFESPAN_FUNC | PROCESS_LIFESPAN_FUNC]) -> None`
运行函数
Args:
funcs:
Returns:
<details>
<summary>源代码</summary>
```python
@staticmethod
def run_funcs(funcs: list[LIFESPAN_FUNC | PROCESS_LIFESPAN_FUNC], *args, **kwargs) -> None:
"""
运行函数
Args:
funcs:
Returns:
"""
try:
loop = asyncio.get_event_loop()
except RuntimeError:
loop = asyncio.new_event_loop()
asyncio.set_event_loop(loop)
tasks = []
for func in funcs:
if is_coroutine_callable(func):
tasks.append(func(*args, **kwargs))
else:
tasks.append(async_wrapper(func)(*args, **kwargs))
loop.run_until_complete(asyncio.gather(*tasks))
```
</details>
### ***class*** `Lifespan`
### &emsp; ***def*** `__init__(self) -> None`
&emsp;轻雪生命周期管理，启动、停止、重启
<details>
<summary>源代码</summary>
```python
def __init__(self) -> None:
"""
轻雪生命周期管理，启动、停止、重启
"""
self.life_flag: int = 0
self._before_start_funcs: list[LIFESPAN_FUNC] = []
self._after_start_funcs: list[LIFESPAN_FUNC] = []
self._before_process_shutdown_funcs: list[LIFESPAN_FUNC] = []
self._after_shutdown_funcs: list[LIFESPAN_FUNC] = []
self._before_process_restart_funcs: list[LIFESPAN_FUNC] = []
self._after_restart_funcs: list[LIFESPAN_FUNC] = []
self._after_nonebot_init_funcs: list[LIFESPAN_FUNC] = []
```
</details>
### &emsp; ***@staticmethod***
### &emsp; ***def*** `run_funcs(funcs: list[LIFESPAN_FUNC | PROCESS_LIFESPAN_FUNC]) -> None`
&emsp;运行函数
Args:
funcs:
Returns:
<details>
<summary>源代码</summary>
```python
@staticmethod
def run_funcs(funcs: list[LIFESPAN_FUNC | PROCESS_LIFESPAN_FUNC], *args, **kwargs) -> None:
"""
运行函数
Args:
funcs:
Returns:
"""
try:
loop = asyncio.get_event_loop()
except RuntimeError:
loop = asyncio.new_event_loop()
asyncio.set_event_loop(loop)
tasks = []
for func in funcs:
if is_coroutine_callable(func):
tasks.append(func(*args, **kwargs))
else:
tasks.append(async_wrapper(func)(*args, **kwargs))
loop.run_until_complete(asyncio.gather(*tasks))
```
</details>
### &emsp; ***def*** `on_before_start(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC`
&emsp;注册启动时的函数
Args:
func:
Returns:
LIFESPAN_FUNC:
<details>
<summary>源代码</summary>
```python
def on_before_start(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC:
"""
注册启动时的函数
Args:
func:
Returns:
LIFESPAN_FUNC:
"""
self._before_start_funcs.append(func)
return func
```
</details>
### &emsp; ***def*** `on_after_start(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC`
&emsp;注册启动时的函数
Args:
func:
Returns:
LIFESPAN_FUNC:
<details>
<summary>源代码</summary>
```python
def on_after_start(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC:
"""
注册启动时的函数
Args:
func:
Returns:
LIFESPAN_FUNC:
"""
self._after_start_funcs.append(func)
return func
```
</details>
### &emsp; ***def*** `on_before_process_shutdown(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC`
&emsp;注册停止前的函数
Args:
func:
Returns:
LIFESPAN_FUNC:
<details>
<summary>源代码</summary>
```python
def on_before_process_shutdown(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC:
"""
注册停止前的函数
Args:
func:
Returns:
LIFESPAN_FUNC:
"""
self._before_process_shutdown_funcs.append(func)
return func
```
</details>
### &emsp; ***def*** `on_after_shutdown(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC`
&emsp;注册停止后的函数
Args:
func:
Returns:
LIFESPAN_FUNC:
<details>
<summary>源代码</summary>
```python
def on_after_shutdown(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC:
"""
注册停止后的函数
Args:
func:
Returns:
LIFESPAN_FUNC:
"""
self._after_shutdown_funcs.append(func)
return func
```
</details>
### &emsp; ***def*** `on_before_process_restart(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC`
&emsp;注册重启时的函数
Args:
func:
Returns:
LIFESPAN_FUNC:
<details>
<summary>源代码</summary>
```python
def on_before_process_restart(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC:
"""
注册重启时的函数
Args:
func:
Returns:
LIFESPAN_FUNC:
"""
self._before_process_restart_funcs.append(func)
return func
```
</details>
### &emsp; ***def*** `on_after_restart(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC`
&emsp;注册重启后的函数
Args:
func:
Returns:
LIFESPAN_FUNC:
<details>
<summary>源代码</summary>
```python
def on_after_restart(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC:
"""
注册重启后的函数
Args:
func:
Returns:
LIFESPAN_FUNC:
"""
self._after_restart_funcs.append(func)
return func
```
</details>
### &emsp; ***def*** `on_after_nonebot_init(self, func: Any) -> None`
&emsp;注册 NoneBot 初始化后的函数
Args:
func:
Returns:
<details>
<summary>源代码</summary>
```python
def on_after_nonebot_init(self, func):
"""
注册 NoneBot 初始化后的函数
Args:
func:
Returns:
"""
self._after_nonebot_init_funcs.append(func)
return func
```
</details>
### &emsp; ***def*** `before_start(self) -> None`
&emsp;启动前
Returns:
<details>
<summary>源代码</summary>
```python
def before_start(self) -> None:
"""
启动前
Returns:
"""
logger.debug('Running before_start functions')
self.run_funcs(self._before_start_funcs)
```
</details>
### &emsp; ***def*** `after_start(self) -> None`
&emsp;启动后
Returns:
<details>
<summary>源代码</summary>
```python
def after_start(self) -> None:
"""
启动后
Returns:
"""
logger.debug('Running after_start functions')
self.run_funcs(self._after_start_funcs)
```
</details>
### &emsp; ***def*** `before_process_shutdown(self) -> None`
&emsp;停止前
Returns:
<details>
<summary>源代码</summary>
```python
def before_process_shutdown(self) -> None:
"""
停止前
Returns:
"""
logger.debug('Running before_shutdown functions')
self.run_funcs(self._before_process_shutdown_funcs)
```
</details>
### &emsp; ***def*** `after_shutdown(self) -> None`
&emsp;停止后
Returns:
<details>
<summary>源代码</summary>
```python
def after_shutdown(self) -> None:
"""
停止后
Returns:
"""
logger.debug('Running after_shutdown functions')
self.run_funcs(self._after_shutdown_funcs)
```
</details>
### &emsp; ***def*** `before_process_restart(self) -> None`
&emsp;重启前
Returns:
<details>
<summary>源代码</summary>
```python
def before_process_restart(self) -> None:
"""
重启前
Returns:
"""
logger.debug('Running before_restart functions')
self.run_funcs(self._before_process_restart_funcs)
```
</details>
### &emsp; ***def*** `after_restart(self) -> None`
&emsp;重启后
Returns:
<details>
<summary>源代码</summary>
```python
def after_restart(self) -> None:
"""
重启后
Returns:
"""
logger.debug('Running after_restart functions')
self.run_funcs(self._after_restart_funcs)
```
</details>
### ***var*** `tasks = []`
### ***var*** `loop = asyncio.get_event_loop()`
### ***var*** `loop = asyncio.new_event_loop()`

7
docs/en/dev/api/comm/README.md
View File

@ -1,7 +0,0 @@
---
title: liteyuki.comm
index: true
icon: laptop-code
category: API
---

427
docs/en/dev/api/comm/channel.md
View File

@ -1,427 +0,0 @@
---
title: liteyuki.comm.channel
order: 1
icon: laptop-code
category: API
---
### ***def*** `set_channel(name: str, channel: Channel) -> None`
设置通道实例
Args:
name: 通道名称
channel: 通道实例
<details>
<summary>源代码</summary>
```python
def set_channel(name: str, channel: Channel):
"""
设置通道实例
Args:
name: 通道名称
channel: 通道实例
"""
if not isinstance(channel, Channel):
raise TypeError(f'channel_ must be an instance of Channel, {type(channel)} found')
if IS_MAIN_PROCESS:
_channel[name] = channel
else:
channel_deliver_passive_channel.send(('set_channel', {'name': name, 'channel_': channel}))
```
</details>
### ***def*** `set_channels(channels: dict[str, Channel]) -> None`
设置通道实例
Args:
channels: 通道名称
<details>
<summary>源代码</summary>
```python
def set_channels(channels: dict[str, Channel]):
"""
设置通道实例
Args:
channels: 通道名称
"""
for name, channel in channels.items():
set_channel(name, channel)
```
</details>
### ***def*** `get_channel(name: str) -> Channel`
获取通道实例
Args:
name: 通道名称
Returns:
<details>
<summary>源代码</summary>
```python
def get_channel(name: str) -> Channel:
"""
获取通道实例
Args:
name: 通道名称
Returns:
"""
if IS_MAIN_PROCESS:
return _channel[name]
else:
recv_chan = Channel[Channel[Any]]('recv_chan')
channel_deliver_passive_channel.send(('get_channel', {'name': name, 'recv_chan': recv_chan}))
return recv_chan.receive()
```
</details>
### ***def*** `get_channels() -> dict[str, Channel]`
获取通道实例
Returns:
<details>
<summary>源代码</summary>
```python
def get_channels() -> dict[str, Channel]:
"""
获取通道实例
Returns:
"""
if IS_MAIN_PROCESS:
return _channel
else:
recv_chan = Channel[dict[str, Channel[Any]]]('recv_chan')
channel_deliver_passive_channel.send(('get_channels', {'recv_chan': recv_chan}))
return recv_chan.receive()
```
</details>
### ***def*** `on_set_channel(data: tuple[str, dict[str, Any]]) -> None`
<details>
<summary>源代码</summary>
```python
@channel_deliver_passive_channel.on_receive(filter_func=lambda data: data[0] == 'set_channel')
def on_set_channel(data: tuple[str, dict[str, Any]]):
name, channel = (data[1]['name'], data[1]['channel_'])
set_channel(name, channel)
```
</details>
### ***def*** `on_get_channel(data: tuple[str, dict[str, Any]]) -> None`
<details>
<summary>源代码</summary>
```python
@channel_deliver_passive_channel.on_receive(filter_func=lambda data: data[0] == 'get_channel')
def on_get_channel(data: tuple[str, dict[str, Any]]):
name, recv_chan = (data[1]['name'], data[1]['recv_chan'])
recv_chan.send(get_channel(name))
```
</details>
### ***def*** `on_get_channels(data: tuple[str, dict[str, Any]]) -> None`
<details>
<summary>源代码</summary>
```python
@channel_deliver_passive_channel.on_receive(filter_func=lambda data: data[0] == 'get_channels')
def on_get_channels(data: tuple[str, dict[str, Any]]):
recv_chan = data[1]['recv_chan']
recv_chan.send(get_channels())
```
</details>
### ***def*** `decorator(func: Callable[[T], Any]) -> Callable[[T], Any]`
<details>
<summary>源代码</summary>
```python
def decorator(func: Callable[[T], Any]) -> Callable[[T], Any]:
global _func_id
async def wrapper(data: T) -> Any:
if filter_func is not None:
if is_coroutine_callable(filter_func):
if not await filter_func(data):
return
elif not filter_func(data):
return
if is_coroutine_callable(func):
return await func(data)
else:
return func(data)
_callback_funcs[_func_id] = wrapper
if IS_MAIN_PROCESS:
self._on_main_receive_funcs.append(_func_id)
else:
self._on_sub_receive_funcs.append(_func_id)
_func_id += 1
return func
```
</details>
### ***async def*** `wrapper(data: T) -> Any`
<details>
<summary>源代码</summary>
```python
async def wrapper(data: T) -> Any:
if filter_func is not None:
if is_coroutine_callable(filter_func):
if not await filter_func(data):
return
elif not filter_func(data):
return
if is_coroutine_callable(func):
return await func(data)
else:
return func(data)
```
</details>
### ***class*** `Channel(Generic[T])`
通道类，可以在进程间和进程内通信，双向但同时只能有一个发送者和一个接收者
有两种接收工作方式，但是只能选择一种，主动接收和被动接收，主动接收使用 `receive` 方法，被动接收使用 `on_receive` 装饰器
### &emsp; ***def*** `__init__(self, _id: str, type_check: Optional[bool]) -> None`
&emsp;初始化通道
Args:
_id: 通道ID
type_check: 是否开启类型检查, 若为空，则传入泛型默认开启，否则默认关闭
<details>
<summary>源代码</summary>
```python
def __init__(self, _id: str, type_check: Optional[bool]=None):
"""
初始化通道
Args:
_id: 通道ID
type_check: 是否开启类型检查, 若为空，则传入泛型默认开启，否则默认关闭
"""
self.conn_send, self.conn_recv = Pipe()
self._closed = False
self._on_main_receive_funcs: list[int] = []
self._on_sub_receive_funcs: list[int] = []
self.name: str = _id
self.is_main_receive_loop_running = False
self.is_sub_receive_loop_running = False
if type_check is None:
type_check = self._get_generic_type() is not None
elif type_check:
if self._get_generic_type() is None:
raise TypeError('Type hint is required for enforcing type check.')
self.type_check = type_check
```
</details>
### &emsp; ***def*** `send(self, data: T) -> None`
&emsp;发送数据
Args:
data: 数据
<details>
<summary>源代码</summary>
```python
def send(self, data: T):
"""
发送数据
Args:
data: 数据
"""
if self.type_check:
_type = self._get_generic_type()
if _type is not None and (not self._validate_structure(data, _type)):
raise TypeError(f'Data must be an instance of {_type}, {type(data)} found')
if self._closed:
raise RuntimeError('Cannot send to a closed channel_')
self.conn_send.send(data)
```
</details>
### &emsp; ***def*** `receive(self) -> T`
&emsp;接收数据
Args:
<details>
<summary>源代码</summary>
```python
def receive(self) -> T:
"""
接收数据
Args:
"""
if self._closed:
raise RuntimeError('Cannot receive from a closed channel_')
while True:
data = self.conn_recv.recv()
return data
```
</details>
### &emsp; ***def*** `close(self) -> None`
&emsp;关闭通道
<details>
<summary>源代码</summary>
```python
def close(self):
"""
关闭通道
"""
self._closed = True
self.conn_send.close()
self.conn_recv.close()
```
</details>
### &emsp; ***def*** `on_receive(self, filter_func: Optional[FILTER_FUNC]) -> Callable[[Callable[[T], Any]], Callable[[T], Any]]`
&emsp;接收数据并执行函数
Args:
filter_func: 过滤函数，为None则不过滤
Returns:
装饰器，装饰一个函数在接收到数据后执行
<details>
<summary>源代码</summary>
```python
def on_receive(self, filter_func: Optional[FILTER_FUNC]=None) -> Callable[[Callable[[T], Any]], Callable[[T], Any]]:
"""
接收数据并执行函数
Args:
filter_func: 过滤函数，为None则不过滤
Returns:
装饰器，装饰一个函数在接收到数据后执行
"""
if not self.is_sub_receive_loop_running and (not IS_MAIN_PROCESS):
threading.Thread(target=self._start_sub_receive_loop, daemon=True).start()
if not self.is_main_receive_loop_running and IS_MAIN_PROCESS:
threading.Thread(target=self._start_main_receive_loop, daemon=True).start()
def decorator(func: Callable[[T], Any]) -> Callable[[T], Any]:
global _func_id
async def wrapper(data: T) -> Any:
if filter_func is not None:
if is_coroutine_callable(filter_func):
if not await filter_func(data):
return
elif not filter_func(data):
return
if is_coroutine_callable(func):
return await func(data)
else:
return func(data)
_callback_funcs[_func_id] = wrapper
if IS_MAIN_PROCESS:
self._on_main_receive_funcs.append(_func_id)
else:
self._on_sub_receive_funcs.append(_func_id)
_func_id += 1
return func
return decorator
```
</details>
### ***var*** `T = TypeVar('T')`
### ***var*** `channel_deliver_active_channel = Channel(_id='channel_deliver_active_channel')`
### ***var*** `channel_deliver_passive_channel = Channel(_id='channel_deliver_passive_channel')`
### ***var*** `recv_chan = data[1]['recv_chan']`
### ***var*** `recv_chan = Channel[Channel[Any]]('recv_chan')`
### ***var*** `recv_chan = Channel[dict[str, Channel[Any]]]('recv_chan')`
### ***var*** `type_check = self._get_generic_type() is not None`
### ***var*** `data = self.conn_recv.recv()`
### ***var*** `func = _callback_funcs[func_id]`
### ***var*** `func = _callback_funcs[func_id]`
### ***var*** `data = self.conn_recv.recv()`
### ***var*** `data = self.conn_recv.recv()`

25
docs/en/dev/api/comm/event.md
View File

@ -1,25 +0,0 @@
---
title: liteyuki.comm.event
order: 1
icon: laptop-code
category: API
---
### ***class*** `Event`
事件类
### &emsp; ***def*** `__init__(self, name: str, data: dict[str, Any]) -> None`
&emsp;
<details>
<summary>源代码</summary>
```python
def __init__(self, name: str, data: dict[str, Any]):
self.name = name
self.data = data
```
</details>

563
docs/en/dev/api/comm/storage.md
View File

@ -1,563 +0,0 @@
---
title: liteyuki.comm.storage
order: 1
icon: laptop-code
category: API
---
### ***def*** `run_subscriber_receive_funcs(channel_: str, data: Any) -> None`
运行订阅者接收函数
Args:
channel_: 频道
data: 数据
<details>
<summary>源代码</summary>
```python
@staticmethod
def run_subscriber_receive_funcs(channel_: str, data: Any):
"""
运行订阅者接收函数
Args:
channel_: 频道
data: 数据
"""
if IS_MAIN_PROCESS:
if channel_ in _on_main_subscriber_receive_funcs and _on_main_subscriber_receive_funcs[channel_]:
run_coroutine(*[func(data) for func in _on_main_subscriber_receive_funcs[channel_]])
elif channel_ in _on_sub_subscriber_receive_funcs and _on_sub_subscriber_receive_funcs[channel_]:
run_coroutine(*[func(data) for func in _on_sub_subscriber_receive_funcs[channel_]])
```
</details>
### ***def*** `on_get(data: tuple[str, dict[str, Any]]) -> None`
<details>
<summary>源代码</summary>
```python
@shared_memory.passive_chan.on_receive(lambda d: d[0] == 'get')
def on_get(data: tuple[str, dict[str, Any]]):
key = data[1]['key']
default = data[1]['default']
recv_chan = data[1]['recv_chan']
recv_chan.send(shared_memory.get(key, default))
```
</details>
### ***def*** `on_set(data: tuple[str, dict[str, Any]]) -> None`
<details>
<summary>源代码</summary>
```python
@shared_memory.passive_chan.on_receive(lambda d: d[0] == 'set')
def on_set(data: tuple[str, dict[str, Any]]):
key = data[1]['key']
value = data[1]['value']
shared_memory.set(key, value)
```
</details>
### ***def*** `on_delete(data: tuple[str, dict[str, Any]]) -> None`
<details>
<summary>源代码</summary>
```python
@shared_memory.passive_chan.on_receive(lambda d: d[0] == 'delete')
def on_delete(data: tuple[str, dict[str, Any]]):
key = data[1]['key']
shared_memory.delete(key)
```
</details>
### ***def*** `on_get_all(data: tuple[str, dict[str, Any]]) -> None`
<details>
<summary>源代码</summary>
```python
@shared_memory.passive_chan.on_receive(lambda d: d[0] == 'get_all')
def on_get_all(data: tuple[str, dict[str, Any]]):
recv_chan = data[1]['recv_chan']
recv_chan.send(shared_memory.get_all())
```
</details>
### ***def*** `on_publish(data: tuple[str, Any]) -> None`
<details>
<summary>源代码</summary>
```python
@channel.publish_channel.on_receive()
def on_publish(data: tuple[str, Any]):
channel_, data = data
shared_memory.run_subscriber_receive_funcs(channel_, data)
```
</details>
### ***def*** `decorator(func: ON_RECEIVE_FUNC) -> ON_RECEIVE_FUNC`
<details>
<summary>源代码</summary>
```python
def decorator(func: ON_RECEIVE_FUNC) -> ON_RECEIVE_FUNC:
async def wrapper(data: Any):
if is_coroutine_callable(func):
await func(data)
else:
func(data)
if IS_MAIN_PROCESS:
if channel_ not in _on_main_subscriber_receive_funcs:
_on_main_subscriber_receive_funcs[channel_] = []
_on_main_subscriber_receive_funcs[channel_].append(wrapper)
else:
if channel_ not in _on_sub_subscriber_receive_funcs:
_on_sub_subscriber_receive_funcs[channel_] = []
_on_sub_subscriber_receive_funcs[channel_].append(wrapper)
return wrapper
```
</details>
### ***async def*** `wrapper(data: Any) -> None`
<details>
<summary>源代码</summary>
```python
async def wrapper(data: Any):
if is_coroutine_callable(func):
await func(data)
else:
func(data)
```
</details>
### ***class*** `Subscriber`
### &emsp; ***def*** `__init__(self) -> None`
&emsp;
<details>
<summary>源代码</summary>
```python
def __init__(self):
self._subscribers = {}
```
</details>
### &emsp; ***def*** `receive(self) -> Any`
&emsp;
<details>
<summary>源代码</summary>
```python
def receive(self) -> Any:
pass
```
</details>
### &emsp; ***def*** `unsubscribe(self) -> None`
&emsp;
<details>
<summary>源代码</summary>
```python
def unsubscribe(self) -> None:
pass
```
</details>
### ***class*** `KeyValueStore`
### &emsp; ***def*** `__init__(self) -> None`
&emsp;
<details>
<summary>源代码</summary>
```python
def __init__(self):
self._store = {}
self.active_chan = Channel[tuple[str, Optional[dict[str, Any]]]](_id='shared_memory-active')
self.passive_chan = Channel[tuple[str, Optional[dict[str, Any]]]](_id='shared_memory-passive')
self.publish_channel = Channel[tuple[str, Any]](_id='shared_memory-publish')
self.is_main_receive_loop_running = False
self.is_sub_receive_loop_running = False
```
</details>
### &emsp; ***def*** `set(self, key: str, value: Any) -> None`
&emsp;设置键值对
Args:
key: 键
value: 值
<details>
<summary>源代码</summary>
```python
def set(self, key: str, value: Any) -> None:
"""
设置键值对
Args:
key: 键
value: 值
"""
if IS_MAIN_PROCESS:
lock = _get_lock(key)
with lock:
self._store[key] = value
else:
self.passive_chan.send(('set', {'key': key, 'value': value}))
```
</details>
### &emsp; ***def*** `get(self, key: str, default: Optional[Any]) -> Optional[Any]`
&emsp;获取键值对
Args:
key: 键
default: 默认值
Returns:
Any: 值
<details>
<summary>源代码</summary>
```python
def get(self, key: str, default: Optional[Any]=None) -> Optional[Any]:
"""
获取键值对
Args:
key: 键
default: 默认值
Returns:
Any: 值
"""
if IS_MAIN_PROCESS:
lock = _get_lock(key)
with lock:
return self._store.get(key, default)
else:
recv_chan = Channel[Optional[Any]]('recv_chan')
self.passive_chan.send(('get', {'key': key, 'default': default, 'recv_chan': recv_chan}))
return recv_chan.receive()
```
</details>
### &emsp; ***def*** `delete(self, key: str, ignore_key_error: bool) -> None`
&emsp;删除键值对
Args:
key: 键
ignore_key_error: 是否忽略键不存在的错误
Returns:
<details>
<summary>源代码</summary>
```python
def delete(self, key: str, ignore_key_error: bool=True) -> None:
"""
删除键值对
Args:
key: 键
ignore_key_error: 是否忽略键不存在的错误
Returns:
"""
if IS_MAIN_PROCESS:
lock = _get_lock(key)
with lock:
if key in self._store:
try:
del self._store[key]
del _locks[key]
except KeyError as e:
if not ignore_key_error:
raise e
else:
self.passive_chan.send(('delete', {'key': key}))
```
</details>
### &emsp; ***def*** `get_all(self) -> dict[str, Any]`
&emsp;获取所有键值对
Returns:
dict[str, Any]: 键值对
<details>
<summary>源代码</summary>
```python
def get_all(self) -> dict[str, Any]:
"""
获取所有键值对
Returns:
dict[str, Any]: 键值对
"""
if IS_MAIN_PROCESS:
return self._store
else:
recv_chan = Channel[dict[str, Any]]('recv_chan')
self.passive_chan.send(('get_all', {'recv_chan': recv_chan}))
return recv_chan.receive()
```
</details>
### &emsp; ***def*** `publish(self, channel_: str, data: Any) -> None`
&emsp;发布消息
Args:
channel_: 频道
data: 数据
Returns:
<details>
<summary>源代码</summary>
```python
def publish(self, channel_: str, data: Any) -> None:
"""
发布消息
Args:
channel_: 频道
data: 数据
Returns:
"""
self.active_chan.send(('publish', {'channel': channel_, 'data': data}))
```
</details>
### &emsp; ***def*** `on_subscriber_receive(self, channel_: str) -> Callable[[ON_RECEIVE_FUNC], ON_RECEIVE_FUNC]`
&emsp;订阅者接收消息时的回调
Args:
channel_: 频道
Returns:
装饰器
<details>
<summary>源代码</summary>
```python
def on_subscriber_receive(self, channel_: str) -> Callable[[ON_RECEIVE_FUNC], ON_RECEIVE_FUNC]:
"""
订阅者接收消息时的回调
Args:
channel_: 频道
Returns:
装饰器
"""
if IS_MAIN_PROCESS and (not self.is_main_receive_loop_running):
threading.Thread(target=self._start_receive_loop, daemon=True).start()
shared_memory.is_main_receive_loop_running = True
elif not IS_MAIN_PROCESS and (not self.is_sub_receive_loop_running):
threading.Thread(target=self._start_receive_loop, daemon=True).start()
shared_memory.is_sub_receive_loop_running = True
def decorator(func: ON_RECEIVE_FUNC) -> ON_RECEIVE_FUNC:
async def wrapper(data: Any):
if is_coroutine_callable(func):
await func(data)
else:
func(data)
if IS_MAIN_PROCESS:
if channel_ not in _on_main_subscriber_receive_funcs:
_on_main_subscriber_receive_funcs[channel_] = []
_on_main_subscriber_receive_funcs[channel_].append(wrapper)
else:
if channel_ not in _on_sub_subscriber_receive_funcs:
_on_sub_subscriber_receive_funcs[channel_] = []
_on_sub_subscriber_receive_funcs[channel_].append(wrapper)
return wrapper
return decorator
```
</details>
### &emsp; ***@staticmethod***
### &emsp; ***def*** `run_subscriber_receive_funcs(channel_: str, data: Any) -> None`
&emsp;运行订阅者接收函数
Args:
channel_: 频道
data: 数据
<details>
<summary>源代码</summary>
```python
@staticmethod
def run_subscriber_receive_funcs(channel_: str, data: Any):
"""
运行订阅者接收函数
Args:
channel_: 频道
data: 数据
"""
if IS_MAIN_PROCESS:
if channel_ in _on_main_subscriber_receive_funcs and _on_main_subscriber_receive_funcs[channel_]:
run_coroutine(*[func(data) for func in _on_main_subscriber_receive_funcs[channel_]])
elif channel_ in _on_sub_subscriber_receive_funcs and _on_sub_subscriber_receive_funcs[channel_]:
run_coroutine(*[func(data) for func in _on_sub_subscriber_receive_funcs[channel_]])
```
</details>
### ***class*** `GlobalKeyValueStore`
### &emsp; ***@classmethod***
### &emsp; ***def*** `get_instance(cls: Any) -> None`
&emsp;
<details>
<summary>源代码</summary>
```python
@classmethod
def get_instance(cls):
if cls._instance is None:
with cls._lock:
if cls._instance is None:
cls._instance = KeyValueStore()
return cls._instance
```
</details>
### &emsp; ***attr*** `_instance: None`
### &emsp; ***attr*** `_lock: threading.Lock()`
### ***var*** `key = data[1]['key']`
### ***var*** `default = data[1]['default']`
### ***var*** `recv_chan = data[1]['recv_chan']`
### ***var*** `key = data[1]['key']`
### ***var*** `value = data[1]['value']`
### ***var*** `key = data[1]['key']`
### ***var*** `recv_chan = data[1]['recv_chan']`
### ***var*** `lock = _get_lock(key)`
### ***var*** `lock = _get_lock(key)`
### ***var*** `recv_chan = Channel[Optional[Any]]('recv_chan')`
### ***var*** `lock = _get_lock(key)`
### ***var*** `recv_chan = Channel[dict[str, Any]]('recv_chan')`
### ***var*** `data = self.active_chan.receive()`
### ***var*** `data = self.publish_channel.receive()`

231
docs/en/dev/api/config.md
View File

@ -1,231 +0,0 @@
---
title: liteyuki.config
order: 1
icon: laptop-code
category: API
---
### ***def*** `flat_config(config: dict[str, Any]) -> dict[str, Any]`
扁平化配置文件
{a:{b:{c:1}}} -> {"a.b.c": 1}
Args:
config: 配置项目
Returns:
扁平化后的配置文件，但也包含原有的键值对
<details>
<summary>源代码</summary>
```python
def flat_config(config: dict[str, Any]) -> dict[str, Any]:
"""
扁平化配置文件
{a:{b:{c:1}}} -> {"a.b.c": 1}
Args:
config: 配置项目
Returns:
扁平化后的配置文件，但也包含原有的键值对
"""
new_config = copy.deepcopy(config)
for key, value in config.items():
if isinstance(value, dict):
for k, v in flat_config(value).items():
new_config[f'{key}.{k}'] = v
return new_config
```
</details>
### ***def*** `load_from_yaml(file: str) -> dict[str, Any]`
Load config from yaml file
<details>
<summary>源代码</summary>
```python
def load_from_yaml(file: str) -> dict[str, Any]:
"""
Load config from yaml file
"""
logger.debug(f'Loading YAML config from {file}')
config = yaml.safe_load(open(file, 'r', encoding='utf-8'))
return flat_config(config if config is not None else {})
```
</details>
### ***def*** `load_from_json(file: str) -> dict[str, Any]`
Load config from json file
<details>
<summary>源代码</summary>
```python
def load_from_json(file: str) -> dict[str, Any]:
"""
Load config from json file
"""
logger.debug(f'Loading JSON config from {file}')
config = json.load(open(file, 'r', encoding='utf-8'))
return flat_config(config if config is not None else {})
```
</details>
### ***def*** `load_from_toml(file: str) -> dict[str, Any]`
Load config from toml file
<details>
<summary>源代码</summary>
```python
def load_from_toml(file: str) -> dict[str, Any]:
"""
Load config from toml file
"""
logger.debug(f'Loading TOML config from {file}')
config = toml.load(open(file, 'r', encoding='utf-8'))
return flat_config(config if config is not None else {})
```
</details>
### ***def*** `load_from_files() -> dict[str, Any]`
从指定文件加载配置项，会自动识别文件格式
默认执行扁平化选项
<details>
<summary>源代码</summary>
```python
def load_from_files(*files: str, no_warning: bool=False) -> dict[str, Any]:
"""
从指定文件加载配置项，会自动识别文件格式
默认执行扁平化选项
"""
config = {}
for file in files:
if os.path.exists(file):
if file.endswith(('.yaml', 'yml')):
config.update(load_from_yaml(file))
elif file.endswith('.json'):
config.update(load_from_json(file))
elif file.endswith('.toml'):
config.update(load_from_toml(file))
elif not no_warning:
logger.warning(f'Unsupported config file format: {file}')
elif not no_warning:
logger.warning(f'Config file not found: {file}')
return config
```
</details>
### ***def*** `load_configs_from_dirs() -> dict[str, Any]`
从目录下加载配置文件，不递归
按照读取文件的优先级反向覆盖
默认执行扁平化选项
<details>
<summary>源代码</summary>
```python
def load_configs_from_dirs(*directories: str, no_waring: bool=False) -> dict[str, Any]:
"""
从目录下加载配置文件，不递归
按照读取文件的优先级反向覆盖
默认执行扁平化选项
"""
config = {}
for directory in directories:
if not os.path.exists(directory):
if not no_waring:
logger.warning(f'Directory not found: {directory}')
continue
for file in os.listdir(directory):
if file.endswith(_SUPPORTED_CONFIG_FORMATS):
config.update(load_from_files(os.path.join(directory, file), no_warning=no_waring))
return config
```
</details>
### ***def*** `load_config_in_default(no_waring: bool) -> dict[str, Any]`
从一个标准的轻雪项目加载配置文件
项目目录下的config.*和config目录下的所有配置文件
项目目录下的配置文件优先
<details>
<summary>源代码</summary>
```python
def load_config_in_default(no_waring: bool=False) -> dict[str, Any]:
"""
从一个标准的轻雪项目加载配置文件
项目目录下的config.*和config目录下的所有配置文件
项目目录下的配置文件优先
"""
config = load_configs_from_dirs('config', no_waring=no_waring)
config.update(load_from_files('config.yaml', 'config.toml', 'config.json', 'config.yml', no_warning=no_waring))
return config
```
</details>
### ***class*** `SatoriNodeConfig(BaseModel)`
### ***class*** `SatoriConfig(BaseModel)`
### ***class*** `BasicConfig(BaseModel)`
### ***var*** `new_config = copy.deepcopy(config)`
### ***var*** `config = yaml.safe_load(open(file, 'r', encoding='utf-8'))`
### ***var*** `config = json.load(open(file, 'r', encoding='utf-8'))`
### ***var*** `config = toml.load(open(file, 'r', encoding='utf-8'))`
### ***var*** `config = {}`
### ***var*** `config = {}`
### ***var*** `config = load_configs_from_dirs('config', no_waring=no_waring)`

7
docs/en/dev/api/core/README.md
View File

@ -1,7 +0,0 @@
---
title: liteyuki.core
index: true
icon: laptop-code
category: API
---

275
docs/en/dev/api/core/manager.md
View File

@ -1,275 +0,0 @@
---
title: liteyuki.core.manager
order: 1
icon: laptop-code
category: API
---
### ***class*** `ChannelDeliver`
### &emsp; ***def*** `__init__(self, active: Channel[Any], passive: Channel[Any], channel_deliver_active: Channel[Channel[Any]], channel_deliver_passive: Channel[tuple[str, dict]], publish: Channel[tuple[str, Any]]) -> None`
&emsp;
<details>
<summary>源代码</summary>
```python
def __init__(self, active: Channel[Any], passive: Channel[Any], channel_deliver_active: Channel[Channel[Any]], channel_deliver_passive: Channel[tuple[str, dict]], publish: Channel[tuple[str, Any]]):
self.active = active
self.passive = passive
self.channel_deliver_active = channel_deliver_active
self.channel_deliver_passive = channel_deliver_passive
self.publish = publish
```
</details>
### ***class*** `ProcessManager`
进程管理器
### &emsp; ***def*** `__init__(self, lifespan: 'Lifespan') -> None`
&emsp;
<details>
<summary>源代码</summary>
```python
def __init__(self, lifespan: 'Lifespan'):
self.lifespan = lifespan
self.targets: dict[str, tuple[Callable, tuple, dict]] = {}
self.processes: dict[str, Process] = {}
```
</details>
### &emsp; ***def*** `start(self, name: str) -> None`
&emsp;开启后自动监控进程，并添加到进程字典中
Args:
name:
Returns:
<details>
<summary>源代码</summary>
```python
def start(self, name: str):
"""
开启后自动监控进程，并添加到进程字典中
Args:
name:
Returns:
"""
if name not in self.targets:
raise KeyError(f'Process {name} not found.')
chan_active = get_channel(f'{name}-active')
def _start_process():
process = Process(target=self.targets[name][0], args=self.targets[name][1], kwargs=self.targets[name][2], daemon=True)
self.processes[name] = process
process.start()
_start_process()
while True:
data = chan_active.receive()
if data == 0:
logger.info(f'Stopping process {name}')
self.lifespan.before_process_shutdown()
self.terminate(name)
break
elif data == 1:
logger.info(f'Restarting process {name}')
self.lifespan.before_process_shutdown()
self.lifespan.before_process_restart()
self.terminate(name)
_start_process()
continue
else:
logger.warning('Unknown data received, ignored.')
```
</details>
### &emsp; ***def*** `start_all(self) -> None`
&emsp;启动所有进程
<details>
<summary>源代码</summary>
```python
def start_all(self):
"""
启动所有进程
"""
for name in self.targets:
threading.Thread(target=self.start, args=(name,), daemon=True).start()
```
</details>
### &emsp; ***def*** `add_target(self, name: str, target: TARGET_FUNC, args: tuple, kwargs: Any) -> None`
&emsp;添加进程
Args:
name: 进程名，用于获取和唯一标识
target: 进程函数
args: 进程函数参数
kwargs: 进程函数关键字参数，通常会默认传入chan_active和chan_passive
<details>
<summary>源代码</summary>
```python
def add_target(self, name: str, target: TARGET_FUNC, args: tuple=(), kwargs=None):
"""
添加进程
Args:
name: 进程名，用于获取和唯一标识
target: 进程函数
args: 进程函数参数
kwargs: 进程函数关键字参数，通常会默认传入chan_active和chan_passive
"""
if kwargs is None:
kwargs = {}
chan_active: Channel = Channel(_id=f'{name}-active')
chan_passive: Channel = Channel(_id=f'{name}-passive')
channel_deliver = ChannelDeliver(active=chan_active, passive=chan_passive, channel_deliver_active=channel_deliver_active_channel, channel_deliver_passive=channel_deliver_passive_channel, publish=publish_channel)
self.targets[name] = (_delivery_channel_wrapper, (target, channel_deliver, shared_memory, *args), kwargs)
set_channels({f'{name}-active': chan_active, f'{name}-passive': chan_passive})
```
</details>
### &emsp; ***def*** `join_all(self) -> None`
&emsp;
<details>
<summary>源代码</summary>
```python
def join_all(self):
for name, process in self.targets:
process.join()
```
</details>
### &emsp; ***def*** `terminate(self, name: str) -> None`
&emsp;终止进程并从进程字典中删除
Args:
name:
Returns:
<details>
<summary>源代码</summary>
```python
def terminate(self, name: str):
"""
终止进程并从进程字典中删除
Args:
name:
Returns:
"""
if name not in self.processes:
logger.warning(f'Process {name} not found.')
return
process = self.processes[name]
process.terminate()
process.join(TIMEOUT)
if process.is_alive():
process.kill()
logger.success(f'Process {name} terminated.')
```
</details>
### &emsp; ***def*** `terminate_all(self) -> None`
&emsp;
<details>
<summary>源代码</summary>
```python
def terminate_all(self):
for name in self.targets:
self.terminate(name)
```
</details>
### &emsp; ***def*** `is_process_alive(self, name: str) -> bool`
&emsp;检查进程是否存活
Args:
name:
Returns:
<details>
<summary>源代码</summary>
```python
def is_process_alive(self, name: str) -> bool:
"""
检查进程是否存活
Args:
name:
Returns:
"""
if name not in self.targets:
logger.warning(f'Process {name} not found.')
return self.processes[name].is_alive()
```
</details>
### ***var*** `TIMEOUT = 10`
### ***var*** `chan_active = get_channel(f'{name}-active')`
### ***var*** `channel_deliver = ChannelDeliver(active=chan_active, passive=chan_passive, channel_deliver_active=channel_deliver_active_channel, channel_deliver_passive=channel_deliver_passive_channel, publish=publish_channel)`
### ***var*** `process = self.processes[name]`
### ***var*** `process = Process(target=self.targets[name][0], args=self.targets[name][1], kwargs=self.targets[name][2], daemon=True)`
### ***var*** `data = chan_active.receive()`
### ***var*** `kwargs = {}`

7
docs/en/dev/api/dev/README.md
View File

@ -1,7 +0,0 @@
---
title: liteyuki.dev
index: true
icon: laptop-code
category: API
---

249
docs/en/dev/api/dev/observer.md
View File

@ -1,249 +0,0 @@
---
title: liteyuki.dev.observer
order: 1
icon: laptop-code
category: API
---
### ***def*** `debounce(wait: Any) -> None`
防抖函数
<details>
<summary>源代码</summary>
```python
def debounce(wait):
"""
防抖函数
"""
def decorator(func):
def wrapper(*args, **kwargs):
nonlocal last_call_time
current_time = time.time()
if current_time - last_call_time > wait:
last_call_time = current_time
return func(*args, **kwargs)
last_call_time = None
return wrapper
return decorator
```
</details>
### ***def*** `on_file_system_event(directories: tuple[str], recursive: bool, event_filter: FILTER_FUNC) -> Callable[[CALLBACK_FUNC], CALLBACK_FUNC]`
注册文件系统变化监听器
Args:
directories: 监听目录们
recursive: 是否递归监听子目录
event_filter: 事件过滤器, 返回True则执行回调函数
Returns:
装饰器，装饰一个函数在接收到数据后执行
<details>
<summary>源代码</summary>
```python
def on_file_system_event(directories: tuple[str], recursive: bool=True, event_filter: FILTER_FUNC=None) -> Callable[[CALLBACK_FUNC], CALLBACK_FUNC]:
"""
注册文件系统变化监听器
Args:
directories: 监听目录们
recursive: 是否递归监听子目录
event_filter: 事件过滤器, 返回True则执行回调函数
Returns:
装饰器，装饰一个函数在接收到数据后执行
"""
def decorator(func: CALLBACK_FUNC) -> CALLBACK_FUNC:
def wrapper(event: FileSystemEvent):
if event_filter is not None and (not event_filter(event)):
return
func(event)
code_modified_handler = CodeModifiedHandler()
code_modified_handler.on_modified = wrapper
for directory in directories:
observer.schedule(code_modified_handler, directory, recursive=recursive)
return func
return decorator
```
</details>
### ***def*** `decorator(func: Any) -> None`
<details>
<summary>源代码</summary>
```python
def decorator(func):
def wrapper(*args, **kwargs):
nonlocal last_call_time
current_time = time.time()
if current_time - last_call_time > wait:
last_call_time = current_time
return func(*args, **kwargs)
last_call_time = None
return wrapper
```
</details>
### ***def*** `decorator(func: CALLBACK_FUNC) -> CALLBACK_FUNC`
<details>
<summary>源代码</summary>
```python
def decorator(func: CALLBACK_FUNC) -> CALLBACK_FUNC:
def wrapper(event: FileSystemEvent):
if event_filter is not None and (not event_filter(event)):
return
func(event)
code_modified_handler = CodeModifiedHandler()
code_modified_handler.on_modified = wrapper
for directory in directories:
observer.schedule(code_modified_handler, directory, recursive=recursive)
return func
```
</details>
### ***def*** `wrapper() -> None`
<details>
<summary>源代码</summary>
```python
def wrapper(*args, **kwargs):
nonlocal last_call_time
current_time = time.time()
if current_time - last_call_time > wait:
last_call_time = current_time
return func(*args, **kwargs)
```
</details>
### ***def*** `wrapper(event: FileSystemEvent) -> None`
<details>
<summary>源代码</summary>
```python
def wrapper(event: FileSystemEvent):
if event_filter is not None and (not event_filter(event)):
return
func(event)
```
</details>
### ***class*** `CodeModifiedHandler(FileSystemEventHandler)`
Handler for code file changes
### &emsp; ***def*** `on_modified(self, event: Any) -> None`
&emsp;
<details>
<summary>源代码</summary>
```python
@debounce(1)
def on_modified(self, event):
raise NotImplementedError('on_modified must be implemented')
```
</details>
### &emsp; ***def*** `on_created(self, event: Any) -> None`
&emsp;
<details>
<summary>源代码</summary>
```python
def on_created(self, event):
self.on_modified(event)
```
</details>
### &emsp; ***def*** `on_deleted(self, event: Any) -> None`
&emsp;
<details>
<summary>源代码</summary>
```python
def on_deleted(self, event):
self.on_modified(event)
```
</details>
### &emsp; ***def*** `on_moved(self, event: Any) -> None`
&emsp;
<details>
<summary>源代码</summary>
```python
def on_moved(self, event):
self.on_modified(event)
```
</details>
### &emsp; ***def*** `on_any_event(self, event: Any) -> None`
&emsp;
<details>
<summary>源代码</summary>
```python
def on_any_event(self, event):
self.on_modified(event)
```
</details>
### ***var*** `liteyuki_bot = get_bot()`
### ***var*** `observer = Observer()`
### ***var*** `last_call_time = None`
### ***var*** `code_modified_handler = CodeModifiedHandler()`
### ***var*** `current_time = time.time()`
### ***var*** `last_call_time = current_time`

46
docs/en/dev/api/dev/plugin.md
View File

@ -1,46 +0,0 @@
---
title: liteyuki.dev.plugin
order: 1
icon: laptop-code
category: API
---
### ***def*** `run_plugins() -> None`
运行插件，无需手动初始化bot
Args:
module_path: 插件路径，参考`liteyuki.load_plugin`的函数签名
<details>
<summary>源代码</summary>
```python
def run_plugins(*module_path: str | Path):
"""
运行插件，无需手动初始化bot
Args:
module_path: 插件路径，参考`liteyuki.load_plugin`的函数签名
"""
cfg = load_config_in_default()
plugins = cfg.get('liteyuki.plugins', [])
plugins.extend(module_path)
cfg['liteyuki.plugins'] = plugins
bot = LiteyukiBot(**cfg)
bot.run()
```
</details>
### ***var*** `cfg = load_config_in_default()`
### ***var*** `plugins = cfg.get('liteyuki.plugins', [])`
### ***var*** `bot = LiteyukiBot(**cfg)`

11
docs/en/dev/api/exception.md
View File

@ -1,11 +0,0 @@
---
title: liteyuki.exception
order: 1
icon: laptop-code
category: API
---
### ***class*** `LiteyukiException(BaseException)`
Liteyuki的异常基类。

58
docs/en/dev/api/log.md
View File

@ -1,58 +0,0 @@
---
title: liteyuki.log
order: 1
icon: laptop-code
category: API
---
### ***def*** `get_format(level: str) -> str`
<details>
<summary>源代码</summary>
```python
def get_format(level: str) -> str:
if level == 'DEBUG':
return debug_format
else:
return default_format
```
</details>
### ***def*** `init_log(config: dict) -> None`
在语言加载完成后执行
Returns:
<details>
<summary>源代码</summary>
```python
def init_log(config: dict):
"""
在语言加载完成后执行
Returns:
"""
logger.remove()
logger.add(sys.stdout, level=0, diagnose=False, format=get_format(config.get('log_level', 'INFO')))
show_icon = config.get('log_icon', True)
logger.level('DEBUG', color='<blue>', icon=f"{('🐛' if show_icon else '')}DEBUG")
logger.level('INFO', color='<normal>', icon=f"{('ℹ️' if show_icon else '')}INFO")
logger.level('SUCCESS', color='<green>', icon=f"{('✅' if show_icon else '')}SUCCESS")
logger.level('WARNING', color='<yellow>', icon=f"{('⚠️' if show_icon else '')}WARNING")
logger.level('ERROR', color='<red>', icon=f"{('⭕' if show_icon else '')}ERROR")
```
</details>
### ***var*** `logger = loguru.logger`
### ***var*** `show_icon = config.get('log_icon', True)`

7
docs/en/dev/api/message/README.md
View File

@ -1,7 +0,0 @@
---
title: liteyuki.message
index: true
icon: laptop-code
category: API
---

106
docs/en/dev/api/message/event.md
View File

@ -1,106 +0,0 @@
---
title: liteyuki.message.event
order: 1
icon: laptop-code
category: API
---
### ***class*** `MessageEvent`
### &emsp; ***def*** `__init__(self, bot_id: str, message: list[dict[str, Any]] | str, message_type: str, raw_message: str, session_id: str, session_type: str, receive_channel: str, data: Optional[dict[str, Any]]) -> None`
&emsp;轻雪抽象消息事件
Args:
bot_id: 机器人ID
message: 消息，消息段数组[{type: str, data: dict[str, Any]}]
raw_message: 原始消息(通常为纯文本的格式)
message_type: 消息类型(private, group, other)
session_id: 会话ID(私聊通常为用户ID，群聊通常为群ID)
session_type: 会话类型(private, group)
receive_channel: 接收频道(用于回复消息)
data: 附加数据
<details>
<summary>源代码</summary>
```python
def __init__(self, bot_id: str, message: list[dict[str, Any]] | str, message_type: str, raw_message: str, session_id: str, session_type: str, receive_channel: str, data: Optional[dict[str, Any]]=None):
"""
轻雪抽象消息事件
Args:
bot_id: 机器人ID
message: 消息，消息段数组[{type: str, data: dict[str, Any]}]
raw_message: 原始消息(通常为纯文本的格式)
message_type: 消息类型(private, group, other)
session_id: 会话ID(私聊通常为用户ID，群聊通常为群ID)
session_type: 会话类型(private, group)
receive_channel: 接收频道(用于回复消息)
data: 附加数据
"""
if data is None:
data = {}
self.message_type = message_type
self.data = data
self.bot_id = bot_id
self.message = message
self.raw_message = raw_message
self.session_id = session_id
self.session_type = session_type
self.receive_channel = receive_channel
```
</details>
### &emsp; ***def*** `reply(self, message: str | dict[str, Any]) -> None`
&emsp;回复消息
Args:
message:
Returns:
<details>
<summary>源代码</summary>
```python
def reply(self, message: str | dict[str, Any]):
"""
回复消息
Args:
message:
Returns:
"""
reply_event = MessageEvent(message_type=self.session_type, message=message, raw_message='', data={'message': message}, bot_id=self.bot_id, session_id=self.session_id, session_type=self.session_type, receive_channel='_')
shared_memory.publish(self.receive_channel, reply_event)
```
</details>
### ***var*** `reply_event = MessageEvent(message_type=self.session_type, message=message, raw_message='', data={'message': message}, bot_id=self.bot_id, session_id=self.session_id, session_type=self.session_type, receive_channel='_')`
### ***var*** `data = {}`

71
docs/en/dev/api/message/matcher.md
View File

@ -1,71 +0,0 @@
---
title: liteyuki.message.matcher
order: 1
icon: laptop-code
category: API
---
### ***class*** `Matcher`
### &emsp; ***def*** `__init__(self, rule: Rule, priority: int, block: bool) -> None`
&emsp;匹配器
Args:
rule: 规则
priority: 优先级 >= 0
block: 是否阻断后续优先级更低的匹配器
<details>
<summary>源代码</summary>
```python
def __init__(self, rule: Rule, priority: int, block: bool):
"""
匹配器
Args:
rule: 规则
priority: 优先级 >= 0
block: 是否阻断后续优先级更低的匹配器
"""
self.rule = rule
self.priority = priority
self.block = block
self.handlers: list[EventHandler] = []
```
</details>
### &emsp; ***def*** `handle(self, handler: EventHandler) -> EventHandler`
&emsp;添加处理函数，装饰器
Args:
handler:
Returns:
EventHandler
<details>
<summary>源代码</summary>
```python
def handle(self, handler: EventHandler) -> EventHandler:
"""
添加处理函数，装饰器
Args:
handler:
Returns:
EventHandler
"""
self.handlers.append(handler)
return handler
```
</details>

39
docs/en/dev/api/message/on.md
View File

@ -1,39 +0,0 @@
---
title: liteyuki.message.on
order: 1
icon: laptop-code
category: API
---
### ***def*** `on_message(rule: Rule, priority: int, block: bool) -> Matcher`
<details>
<summary>源代码</summary>
```python
def on_message(rule: Rule=Rule(), priority: int=0, block: bool=True) -> Matcher:
matcher = Matcher(rule, priority, block)
for i, m in enumerate(_matcher_list):
if m.priority < matcher.priority:
_matcher_list.insert(i, matcher)
break
else:
_matcher_list.append(matcher)
return matcher
```
</details>
### ***var*** `current_priority = -1`
### ***var*** `matcher = Matcher(rule, priority, block)`
### ***var*** `current_priority = matcher.priority`

24
docs/en/dev/api/message/rule.md
View File

@ -1,24 +0,0 @@
---
title: liteyuki.message.rule
order: 1
icon: laptop-code
category: API
---
### ***class*** `Rule`
### &emsp; ***def*** `__init__(self, handler: Optional[RuleHandler]) -> None`
&emsp;
<details>
<summary>源代码</summary>
```python
def __init__(self, handler: Optional[RuleHandler]=None):
self.handler = handler
```
</details>

7
docs/en/dev/api/message/session.md
View File

@ -1,7 +0,0 @@
---
title: liteyuki.message.session
order: 1
icon: laptop-code
category: API
---

473
docs/en/dev/api/mkdoc.md
View File

@ -1,473 +0,0 @@
---
title: liteyuki.mkdoc
order: 1
icon: laptop-code
category: API
---
### ***def*** `get_relative_path(base_path: str, target_path: str) -> str`
获取相对路径
Args:
base_path: 基础路径
target_path: 目标路径
<details>
<summary>源代码</summary>
```python
def get_relative_path(base_path: str, target_path: str) -> str:
"""
获取相对路径
Args:
base_path: 基础路径
target_path: 目标路径
"""
return os.path.relpath(target_path, base_path)
```
</details>
### ***def*** `write_to_files(file_data: dict[str, str]) -> None`
输出文件
Args:
file_data: 文件数据 相对路径
<details>
<summary>源代码</summary>
```python
def write_to_files(file_data: dict[str, str]):
"""
输出文件
Args:
file_data: 文件数据 相对路径
"""
for rp, data in file_data.items():
if not os.path.exists(os.path.dirname(rp)):
os.makedirs(os.path.dirname(rp))
with open(rp, 'w', encoding='utf-8') as f:
f.write(data)
```
</details>
### ***def*** `get_file_list(module_folder: str) -> None`
<details>
<summary>源代码</summary>
```python
def get_file_list(module_folder: str):
file_list = []
for root, dirs, files in os.walk(module_folder):
for file in files:
if file.endswith(('.py', '.pyi')):
file_list.append(os.path.join(root, file))
return file_list
```
</details>
### ***def*** `get_module_info_normal(file_path: str, ignore_private: bool) -> ModuleInfo`
获取函数和类
Args:
file_path: Python 文件路径
ignore_private: 忽略私有函数和类
Returns:
模块信息
<details>
<summary>源代码</summary>
```python
def get_module_info_normal(file_path: str, ignore_private: bool=True) -> ModuleInfo:
"""
获取函数和类
Args:
file_path: Python 文件路径
ignore_private: 忽略私有函数和类
Returns:
模块信息
"""
with open(file_path, 'r', encoding='utf-8') as file:
file_content = file.read()
tree = ast.parse(file_content)
dot_sep_module_path = file_path.replace(os.sep, '.').replace('.py', '').replace('.pyi', '')
module_docstring = ast.get_docstring(tree)
module_info = ModuleInfo(module_path=dot_sep_module_path, functions=[], classes=[], attributes=[], docstring=module_docstring if module_docstring else '')
for node in ast.walk(tree):
if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
if not any((isinstance(parent, ast.ClassDef) for parent in ast.iter_child_nodes(node))) and (not ignore_private or not node.name.startswith('_')):
if node.args.args:
first_arg = node.args.args[0]
if first_arg.arg in ('self', 'cls'):
continue
function_docstring = ast.get_docstring(node)
func_info = FunctionInfo(name=node.name, args=[(arg.arg, ast.unparse(arg.annotation) if arg.annotation else NO_TYPE_ANY) for arg in node.args.args], return_type=ast.unparse(node.returns) if node.returns else 'None', docstring=function_docstring if function_docstring else '', type=DefType.FUNCTION, is_async=isinstance(node, ast.AsyncFunctionDef), source_code=ast.unparse(node))
module_info.functions.append(func_info)
elif isinstance(node, ast.ClassDef):
class_docstring = ast.get_docstring(node)
class_info = ClassInfo(name=node.name, docstring=class_docstring if class_docstring else '', methods=[], attributes=[], inherit=[ast.unparse(base) for base in node.bases])
for class_node in node.body:
if isinstance(class_node, ast.FunctionDef) and (not ignore_private or not class_node.name.startswith('_') or class_node.name == '__init__'):
method_docstring = ast.get_docstring(class_node)
def_type = DefType.METHOD
if class_node.decorator_list:
if any((isinstance(decorator, ast.Name) and decorator.id == 'staticmethod' for decorator in class_node.decorator_list)):
def_type = DefType.STATIC_METHOD
elif any((isinstance(decorator, ast.Name) and decorator.id == 'classmethod' for decorator in class_node.decorator_list)):
def_type = DefType.CLASS_METHOD
elif any((isinstance(decorator, ast.Name) and decorator.id == 'property' for decorator in class_node.decorator_list)):
def_type = DefType.PROPERTY
class_info.methods.append(FunctionInfo(name=class_node.name, args=[(arg.arg, ast.unparse(arg.annotation) if arg.annotation else NO_TYPE_ANY) for arg in class_node.args.args], return_type=ast.unparse(class_node.returns) if class_node.returns else 'None', docstring=method_docstring if method_docstring else '', type=def_type, is_async=isinstance(class_node, ast.AsyncFunctionDef), source_code=ast.unparse(class_node)))
elif isinstance(class_node, ast.Assign):
for target in class_node.targets:
if isinstance(target, ast.Name):
class_info.attributes.append(AttributeInfo(name=target.id, type=ast.unparse(class_node.value)))
module_info.classes.append(class_info)
elif isinstance(node, ast.Assign):
if not any((isinstance(parent, (ast.ClassDef, ast.FunctionDef)) for parent in ast.iter_child_nodes(node))):
for target in node.targets:
if isinstance(target, ast.Name) and (not ignore_private or not target.id.startswith('_')):
attr_type = NO_TYPE_HINT
if isinstance(node.value, ast.AnnAssign) and node.value.annotation:
attr_type = ast.unparse(node.value.annotation)
module_info.attributes.append(AttributeInfo(name=target.id, type=attr_type, value=ast.unparse(node.value) if node.value else None))
return module_info
```
</details>
### ***def*** `generate_markdown(module_info: ModuleInfo, front_matter: Any) -> str`
生成模块的Markdown
你可在此自定义生成的Markdown格式
Args:
module_info: 模块信息
front_matter: 自定义选项title, index, icon, category
Returns:
Markdown 字符串
<details>
<summary>源代码</summary>
```python
def generate_markdown(module_info: ModuleInfo, front_matter=None) -> str:
"""
生成模块的Markdown
你可在此自定义生成的Markdown格式
Args:
module_info: 模块信息
front_matter: 自定义选项title, index, icon, category
Returns:
Markdown 字符串
"""
content = ''
front_matter = '---\n' + '\n'.join([f'{k}: {v}' for k, v in front_matter.items()]) + '\n---\n\n'
content += front_matter
for func in module_info.functions:
args_with_type = [f'{arg[0]}: {arg[1]}' if arg[1] else arg[0] for arg in func.args]
content += f"### ***{('async ' if func.is_async else '')}def*** `{func.name}({', '.join(args_with_type)}) -> {func.return_type}`\n\n"
func.docstring = func.docstring.replace('\n', '\n\n')
content += f'{func.docstring}\n\n'
content += f'<details>\n<summary>源代码</summary>\n\n```python\n{func.source_code}\n```\n</details>\n\n'
for cls in module_info.classes:
if cls.inherit:
inherit = f"({', '.join(cls.inherit)})" if cls.inherit else ''
content += f'### ***class*** `{cls.name}{inherit}`\n\n'
else:
content += f'### ***class*** `{cls.name}`\n\n'
cls.docstring = cls.docstring.replace('\n', '\n\n')
content += f'{cls.docstring}\n\n'
for method in cls.methods:
if method.type != DefType.METHOD:
args_with_type = [f'{arg[0]}: {arg[1]}' if arg[1] else arg[0] for arg in method.args]
content += f'### &emsp; ***@{method.type.value}***\n'
else:
args_with_type = [f'{arg[0]}: {arg[1]}' if arg[1] and arg[0] != 'self' else arg[0] for arg in method.args]
content += f"### &emsp; ***{('async ' if method.is_async else '')}def*** `{method.name}({', '.join(args_with_type)}) -> {method.return_type}`\n\n"
method.docstring = method.docstring.replace('\n', '\n\n')
content += f'&emsp;{method.docstring}\n\n'
content += f'<details>\n<summary>源代码</summary>\n\n```python\n{method.source_code}\n```\n</details>\n\n'
for attr in cls.attributes:
content += f'### &emsp; ***attr*** `{attr.name}: {attr.type}`\n\n'
for attr in module_info.attributes:
if attr.type == NO_TYPE_HINT:
content += f'### ***var*** `{attr.name} = {attr.value}`\n\n'
else:
content += f'### ***var*** `{attr.name}: {attr.type} = {attr.value}`\n\n'
attr.docstring = attr.docstring.replace('\n', '\n\n')
content += f'{attr.docstring}\n\n'
return content
```
</details>
### ***def*** `generate_docs(module_folder: str, output_dir: str, with_top: bool, ignored_paths: Any) -> None`
生成文档
Args:
module_folder: 模块文件夹
output_dir: 输出文件夹
with_top: 是否包含顶层文件夹 False时例如docs/api/module_a, docs/api/module_b， True时例如docs/api/module/module_a.md， docs/api/module/module_b.md
ignored_paths: 忽略的路径
<details>
<summary>源代码</summary>
```python
def generate_docs(module_folder: str, output_dir: str, with_top: bool=False, ignored_paths=None):
"""
生成文档
Args:
module_folder: 模块文件夹
output_dir: 输出文件夹
with_top: 是否包含顶层文件夹 False时例如docs/api/module_a, docs/api/module_b， True时例如docs/api/module/module_a.md， docs/api/module/module_b.md
ignored_paths: 忽略的路径
"""
if ignored_paths is None:
ignored_paths = []
file_data: dict[str, str] = {}
file_list = get_file_list(module_folder)
shutil.rmtree(output_dir, ignore_errors=True)
os.mkdir(output_dir)
replace_data = {'__init__': 'README', '.py': '.md'}
for pyfile_path in file_list:
if any((ignored_path.replace('\\', '/') in pyfile_path.replace('\\', '/') for ignored_path in ignored_paths)):
continue
no_module_name_pyfile_path = get_relative_path(module_folder, pyfile_path)
rel_md_path = pyfile_path if with_top else no_module_name_pyfile_path
for rk, rv in replace_data.items():
rel_md_path = rel_md_path.replace(rk, rv)
abs_md_path = os.path.join(output_dir, rel_md_path)
module_info = get_module_info_normal(pyfile_path)
if 'README' in abs_md_path:
front_matter = {'title': module_info.module_path.replace('.__init__', '').replace('_', '\\n'), 'index': 'true', 'icon': 'laptop-code', 'category': 'API'}
else:
front_matter = {'title': module_info.module_path.replace('_', '\\n'), 'order': '1', 'icon': 'laptop-code', 'category': 'API'}
md_content = generate_markdown(module_info, front_matter)
print(f'Generate {pyfile_path} -> {abs_md_path}')
file_data[abs_md_path] = md_content
write_to_files(file_data)
```
</details>
### ***class*** `DefType(Enum)`
### &emsp; ***attr*** `FUNCTION: 'function'`
### &emsp; ***attr*** `METHOD: 'method'`
### &emsp; ***attr*** `STATIC_METHOD: 'staticmethod'`
### &emsp; ***attr*** `CLASS_METHOD: 'classmethod'`
### &emsp; ***attr*** `PROPERTY: 'property'`
### ***class*** `FunctionInfo(BaseModel)`
### ***class*** `AttributeInfo(BaseModel)`
### ***class*** `ClassInfo(BaseModel)`
### ***class*** `ModuleInfo(BaseModel)`
### ***var*** `NO_TYPE_ANY = 'Any'`
### ***var*** `NO_TYPE_HINT = 'NoTypeHint'`
### ***var*** `FUNCTION = 'function'`
### ***var*** `METHOD = 'method'`
### ***var*** `STATIC_METHOD = 'staticmethod'`
### ***var*** `CLASS_METHOD = 'classmethod'`
### ***var*** `PROPERTY = 'property'`
### ***var*** `file_list = []`
### ***var*** `dot_sep_module_path = file_path.replace(os.sep, '.').replace('.py', '').replace('.pyi', '')`
### ***var*** `module_docstring = ast.get_docstring(tree)`
### ***var*** `module_info = ModuleInfo(module_path=dot_sep_module_path, functions=[], classes=[], attributes=[], docstring=module_docstring if module_docstring else '')`
### ***var*** `content = ''`
### ***var*** `front_matter = '---\n' + '\n'.join([f'{k}: {v}' for k, v in front_matter.items()]) + '\n---\n\n'`
### ***var*** `file_list = get_file_list(module_folder)`
### ***var*** `replace_data = {'__init__': 'README', '.py': '.md'}`
### ***var*** `file_content = file.read()`
### ***var*** `tree = ast.parse(file_content)`
### ***var*** `args_with_type = [f'{arg[0]}: {arg[1]}' if arg[1] else arg[0] for arg in func.args]`
### ***var*** `ignored_paths = []`
### ***var*** `no_module_name_pyfile_path = get_relative_path(module_folder, pyfile_path)`
### ***var*** `rel_md_path = pyfile_path if with_top else no_module_name_pyfile_path`
### ***var*** `abs_md_path = os.path.join(output_dir, rel_md_path)`
### ***var*** `module_info = get_module_info_normal(pyfile_path)`
### ***var*** `md_content = generate_markdown(module_info, front_matter)`
### ***var*** `inherit = f"({', '.join(cls.inherit)})" if cls.inherit else ''`
### ***var*** `rel_md_path = rel_md_path.replace(rk, rv)`
### ***var*** `front_matter = {'title': module_info.module_path.replace('.__init__', '').replace('_', '\\n'), 'index': 'true', 'icon': 'laptop-code', 'category': 'API'}`
### ***var*** `front_matter = {'title': module_info.module_path.replace('_', '\\n'), 'order': '1', 'icon': 'laptop-code', 'category': 'API'}`
### ***var*** `function_docstring = ast.get_docstring(node)`
### ***var*** `func_info = FunctionInfo(name=node.name, args=[(arg.arg, ast.unparse(arg.annotation) if arg.annotation else NO_TYPE_ANY) for arg in node.args.args], return_type=ast.unparse(node.returns) if node.returns else 'None', docstring=function_docstring if function_docstring else '', type=DefType.FUNCTION, is_async=isinstance(node, ast.AsyncFunctionDef), source_code=ast.unparse(node))`
### ***var*** `class_docstring = ast.get_docstring(node)`
### ***var*** `class_info = ClassInfo(name=node.name, docstring=class_docstring if class_docstring else '', methods=[], attributes=[], inherit=[ast.unparse(base) for base in node.bases])`
### ***var*** `args_with_type = [f'{arg[0]}: {arg[1]}' if arg[1] else arg[0] for arg in method.args]`
### ***var*** `args_with_type = [f'{arg[0]}: {arg[1]}' if arg[1] and arg[0] != 'self' else arg[0] for arg in method.args]`
### ***var*** `first_arg = node.args.args[0]`
### ***var*** `method_docstring = ast.get_docstring(class_node)`
### ***var*** `def_type = DefType.METHOD`
### ***var*** `def_type = DefType.STATIC_METHOD`
### ***var*** `attr_type = NO_TYPE_HINT`
### ***var*** `def_type = DefType.CLASS_METHOD`
### ***var*** `attr_type = ast.unparse(node.value.annotation)`
### ***var*** `def_type = DefType.PROPERTY`

29
docs/en/dev/api/plugin/README.md
View File

@ -1,29 +0,0 @@
---
title: liteyuki.plugin
index: true
icon: laptop-code
category: API
---
### ***def*** `get_loaded_plugins() -> dict[str, Plugin]`
获取已加载的插件
Returns:
dict[str, Plugin]: 插件字典
<details>
<summary>源代码</summary>
```python
def get_loaded_plugins() -> dict[str, Plugin]:
"""
获取已加载的插件
Returns:
dict[str, Plugin]: 插件字典
"""
return _plugins
```
</details>

199
docs/en/dev/api/plugin/load.md
View File

@ -1,199 +0,0 @@
---
title: liteyuki.plugin.load
order: 1
icon: laptop-code
category: API
---
### ***def*** `load_plugin(module_path: str | Path) -> Optional[Plugin]`
加载单个插件，可以是本地插件或是通过 `pip` 安装的插件。
参数:
module_path: 插件名称 `path.to.your.plugin`
或插件路径 `pathlib.Path(path/to/your/plugin)`
<details>
<summary>源代码</summary>
```python
def load_plugin(module_path: str | Path) -> Optional[Plugin]:
"""加载单个插件，可以是本地插件或是通过 `pip` 安装的插件。
参数:
module_path: 插件名称 `path.to.your.plugin`
或插件路径 `pathlib.Path(path/to/your/plugin)`
"""
module_path = path_to_module_name(Path(module_path)) if isinstance(module_path, Path) else module_path
try:
module = import_module(module_path)
_plugins[module.__name__] = Plugin(name=module.__name__, module=module, module_name=module_path, metadata=module.__dict__.get('__plugin_metadata__', None))
display_name = module.__name__.split('.')[-1]
if module.__dict__.get('__plugin_meta__'):
metadata: 'PluginMetadata' = module.__dict__['__plugin_meta__']
display_name = format_display_name(f"{metadata.name}({module.__name__.split('.')[-1]})", metadata.type)
logger.opt(colors=True).success(f'Succeeded to load liteyuki plugin "{display_name}"')
return _plugins[module.__name__]
except Exception as e:
logger.opt(colors=True).success(f'Failed to load liteyuki plugin "<r>{module_path}</r>"')
traceback.print_exc()
return None
```
</details>
### ***def*** `load_plugins() -> set[Plugin]`
导入文件夹下多个插件
参数:
plugin_dir: 文件夹路径
ignore_warning: 是否忽略警告，通常是目录不存在或目录为空
<details>
<summary>源代码</summary>
```python
def load_plugins(*plugin_dir: str, ignore_warning: bool=True) -> set[Plugin]:
"""导入文件夹下多个插件
参数:
plugin_dir: 文件夹路径
ignore_warning: 是否忽略警告，通常是目录不存在或目录为空
"""
plugins = set()
for dir_path in plugin_dir:
if not os.path.exists(dir_path):
if not ignore_warning:
logger.warning(f"Plugins dir '{dir_path}' does not exist.")
continue
if not os.listdir(dir_path):
if not ignore_warning:
logger.warning(f"Plugins dir '{dir_path}' is empty.")
continue
if not os.path.isdir(dir_path):
if not ignore_warning:
logger.warning(f"Plugins dir '{dir_path}' is not a directory.")
continue
for f in os.listdir(dir_path):
path = Path(os.path.join(dir_path, f))
module_name = None
if os.path.isfile(path) and f.endswith('.py') and (f != '__init__.py'):
module_name = f'{path_to_module_name(Path(dir_path))}.{f[:-3]}'
elif os.path.isdir(path) and os.path.exists(os.path.join(path, '__init__.py')):
module_name = path_to_module_name(path)
if module_name:
load_plugin(module_name)
if _plugins.get(module_name):
plugins.add(_plugins[module_name])
return plugins
```
</details>
### ***def*** `format_display_name(display_name: str, plugin_type: PluginType) -> str`
设置插件名称颜色，根据不同类型插件设置颜色
Args:
display_name: 插件名称
plugin_type: 插件类型
Returns:
str: 设置后的插件名称 <y>name</y>
<details>
<summary>源代码</summary>
```python
def format_display_name(display_name: str, plugin_type: PluginType) -> str:
"""
设置插件名称颜色，根据不同类型插件设置颜色
Args:
display_name: 插件名称
plugin_type: 插件类型
Returns:
str: 设置后的插件名称 <y>name</y>
"""
color = 'y'
match plugin_type:
case PluginType.APPLICATION:
color = 'm'
case PluginType.TEST:
color = 'g'
case PluginType.MODULE:
color = 'e'
case PluginType.SERVICE:
color = 'c'
return f'<{color}>{display_name} [{plugin_type.name}]</{color}>'
```
</details>
### ***var*** `module_path = path_to_module_name(Path(module_path)) if isinstance(module_path, Path) else module_path`
### ***var*** `plugins = set()`
### ***var*** `color = 'y'`
### ***var*** `module = import_module(module_path)`
### ***var*** `display_name = module.__name__.split('.')[-1]`
### ***var*** `display_name = format_display_name(f"{metadata.name}({module.__name__.split('.')[-1]})", metadata.type)`
### ***var*** `path = Path(os.path.join(dir_path, f))`
### ***var*** `module_name = None`
### ***var*** `color = 'm'`
### ***var*** `color = 'g'`
### ***var*** `color = 'e'`
### ***var*** `color = 'c'`
### ***var*** `module_name = f'{path_to_module_name(Path(dir_path))}.{f[:-3]}'`
### ***var*** `module_name = path_to_module_name(path)`

7
docs/en/dev/api/plugin/manager.md
View File

@ -1,7 +0,0 @@
---
title: liteyuki.plugin.manager
order: 1
icon: laptop-code
category: API
---

89
docs/en/dev/api/plugin/model.md
View File

@ -1,89 +0,0 @@
---
title: liteyuki.plugin.model
order: 1
icon: laptop-code
category: API
---
### ***class*** `PluginType(Enum)`
插件类型枚举值
### &emsp; ***attr*** `APPLICATION: 'application'`
### &emsp; ***attr*** `SERVICE: 'service'`
### &emsp; ***attr*** `MODULE: 'module'`
### &emsp; ***attr*** `UNCLASSIFIED: 'unclassified'`
### &emsp; ***attr*** `TEST: 'test'`
### ***class*** `PluginMetadata(BaseModel)`
轻雪插件元数据，由插件编写者提供，name为必填项
Attributes:
----------
name: str
插件名称
description: str
插件描述
usage: str
插件使用方法
type: str
插件类型
author: str
插件作者
homepage: str
插件主页
extra: dict[str, Any]
额外信息
### ***class*** `Plugin(BaseModel)`
存储插件信息
### &emsp; ***attr*** `model_config: {'arbitrary_types_allowed': True}`
### ***var*** `APPLICATION = 'application'`
### ***var*** `SERVICE = 'service'`
### ***var*** `MODULE = 'module'`
### ***var*** `UNCLASSIFIED = 'unclassified'`
### ***var*** `TEST = 'test'`
### ***var*** `model_config = {'arbitrary_types_allowed': True}`

180
docs/en/dev/api/utils.md
View File

@ -1,180 +0,0 @@
---
title: liteyuki.utils
order: 1
icon: laptop-code
category: API
---
### ***def*** `is_coroutine_callable(call: Callable[..., Any]) -> bool`
判断是否为协程可调用对象
Args:
call: 可调用对象
Returns:
bool: 是否为协程可调用对象
<details>
<summary>源代码</summary>
```python
def is_coroutine_callable(call: Callable[..., Any]) -> bool:
"""
判断是否为协程可调用对象
Args:
call: 可调用对象
Returns:
bool: 是否为协程可调用对象
"""
if inspect.isroutine(call):
return inspect.iscoroutinefunction(call)
if inspect.isclass(call):
return False
func_ = getattr(call, '__call__', None)
return inspect.iscoroutinefunction(func_)
```
</details>
### ***def*** `run_coroutine() -> None`
运行协程
Args:
coro:
Returns:
<details>
<summary>源代码</summary>
```python
def run_coroutine(*coro: Coroutine):
"""
运行协程
Args:
coro:
Returns:
"""
try:
loop = asyncio.get_event_loop()
if loop.is_running():
for c in coro:
asyncio.ensure_future(c)
else:
for c in coro:
loop.run_until_complete(c)
except RuntimeError:
loop = asyncio.new_event_loop()
asyncio.set_event_loop(loop)
loop.run_until_complete(asyncio.gather(*coro))
loop.close()
except Exception as e:
logger.error(f'Exception occurred: {e}')
```
</details>
### ***def*** `path_to_module_name(path: Path) -> str`
转换路径为模块名
Args:
path: 路径a/b/c/d -> a.b.c.d
Returns:
str: 模块名
<details>
<summary>源代码</summary>
```python
def path_to_module_name(path: Path) -> str:
"""
转换路径为模块名
Args:
path: 路径a/b/c/d -> a.b.c.d
Returns:
str: 模块名
"""
rel_path = path.resolve().relative_to(Path.cwd().resolve())
if rel_path.stem == '__init__':
return '.'.join(rel_path.parts[:-1])
else:
return '.'.join(rel_path.parts[:-1] + (rel_path.stem,))
```
</details>
### ***def*** `async_wrapper(func: Callable[..., Any]) -> Callable[..., Coroutine]`
异步包装器
Args:
func: Sync Callable
Returns:
Coroutine: Asynchronous Callable
<details>
<summary>源代码</summary>
```python
def async_wrapper(func: Callable[..., Any]) -> Callable[..., Coroutine]:
"""
异步包装器
Args:
func: Sync Callable
Returns:
Coroutine: Asynchronous Callable
"""
async def wrapper(*args, **kwargs):
return func(*args, **kwargs)
wrapper.__signature__ = inspect.signature(func)
return wrapper
```
</details>
### ***async def*** `wrapper() -> None`
<details>
<summary>源代码</summary>
```python
async def wrapper(*args, **kwargs):
return func(*args, **kwargs)
```
</details>
### ***var*** `IS_MAIN_PROCESS = multiprocessing.current_process().name == 'MainProcess'`
### ***var*** `func_ = getattr(call, '__call__', None)`
### ***var*** `rel_path = path.resolve().relative_to(Path.cwd().resolve())`
### ***var*** `loop = asyncio.get_event_loop()`
### ***var*** `loop = asyncio.new_event_loop()`

99
docs/en/dev/dev_comm.md
View File

@ -1,99 +0,0 @@
---
title: Communication
icon: exchange-alt
order: 4
category: development
---
## **通道通信**
### 简介
轻雪运行在主进程 MainProcess 里，其他插件框架进程是伴随的子进程，因此无法通过内存共享和直接对象传递的方式进行通信，轻雪提供了一个通道`Channel`用于跨进程通信，你可以通过`Channel`发送消息给其他进程，也可以监听其他进程的消息。
例如子进程接收到用户信息需要重启机器人，这时可以通过通道对主进程发送消息，主进程接收到消息后重启对应子进程。
### 示例
通道是全双工的，有两种接收模式，但一个通道只能使用一种，即被动模式和主动模式，被动模式由`chan.on_receive()`装饰回调函数实现，主动模式需调用`chan.receive()`实现
- 创建子进程的同时会初始化一个被动通道和一个主动通道，且通道标识为`{process_name}-active`和`{process_name}-passive`，
- 主进程中通过`get_channel`函数获取通道对象
- 子进程中导入单例`active_channel`及`passive_channel`即可
> 在轻雪插件中(主进程中)
```python
import asyncio
from liteyuki.comm import get_channel, Channel
from liteyuki import get_bot
# get_channel函数获取通道对象，参数为调用set_channel时的通道标识
channel_passive = get_channel("nonebot-passive") # 获取被动通道
channel_active = get_channel("nonebot-active") # 获取主动通道
liteyuki_bot = get_bot()
# 注册一个函数在轻雪启动后运行
@liteyuki_bot.on_after_start
async def send_data():
while True:
channel_passive.send("I am liteyuki main process passive")
channel_active.send("I am liteyuki main process active")
await asyncio.sleep(3) # 每3秒发送一次消息
```
> 在子进程中（例如NoneBot插件中）
```python
from nonebot import get_driver
from liteyuki.comm import active_channel, passive_channel # 子进程中获取通道直接导入进程全局单例即可
from liteyuki.log import logger
driver = get_driver()
# 被动模式，通过装饰器注册一个函数在接收到消息时运行，每次接收到字符串数据时都会运行
@passive_channel.on_receive(filter_func=lambda data: isinstance(data, str))
async def on_passive_receive(data):
logger.info(f"Passive receive: {data}")
# 注册一个函数在NoneBot启动后运行
@driver.on_startup
def on_startup():
while True:
data = active_channel.receive()
logger.info(f"Active receive: {data}")
```
> 启动后控制台输出
```log
0000-00-00 00:00:00 [ℹ️信息] Passive receive: I am liteyuki main process passive
0000-00-00 00:00:00 [ℹ️信息] Active receive: I am liteyuki main process active
0000-00-00 00:00:03 [ℹ️信息] Passive receive: I am liteyuki main process passive
0000-00-00 00:00:03 [ℹ️信息] Active receive: I am liteyuki main process active
...
```
## **共享内存通信**
### 简介
- 相比于普通进程通信，内存共享使得代码编写更加简洁，轻雪框架提供了一个内存共享通信的接口，你可以通过`storage`模块实现内存共享通信，该模块封装通道实现
- 内存共享是线程安全的，你可以在多个线程中读写共享内存，线程锁会自动保护共享内存的读写操作
### 示例
> 在任意进程中均可使用
```python
from liteyuki.comm.storage import shared_memory
shared_memory.set("key", "value") # 设置共享内存
value = shared_memory.get("key") # 获取共享内存
```
- 源代码：[liteyuki/comm/storage.py](https://github.com/LiteyukiStudio/LiteyukiBot/blob/main/liteyuki/comm/storage.py)

74
docs/en/dev/dev_lyfunc.md
View File

@ -1,74 +0,0 @@
---
title: Liteyuki Function
icon: code
order: 2
category: development
---
## **轻雪函数**
轻雪函数 Liteyuki Function 是轻雪的一个功能，它允许你在轻雪中运行一些自定义的由数据驱动的命令，类似于Minecraft的mcfunction，属于资源包的一部分，但需单独起篇幅.
### **函数文件**
函数文件放在资源包的`functions`目录下，文件名以`.mcfunction` `.lyfunction` `.lyf`结尾，例如`test.mcfunction`，文件内容为一系列的命令，每行一个命令，支持单行注释`#`(编辑时的语法高亮可采取`shell`格式)，例如：
```shell
# 在发信器输出"hello world"
cmd echo hello world
# 如果你想同时输出多行内容可以尝试换行符(Python格式)
cmd echo hello world\nLiteyuki bot
```
也支持句末注释，例如：
```shell
cmd echo hello world # 输出"hello world"
```
### **命令文档**
```shell
var <var1=value1> [var2=value2] ... # 定义变量
cmd <command> # 在设备上执行命令
api <api_name> [var=value...] # 调用Bot API
function <func_name> # 调用函数，可递归
sleep <time> # 异步等待，单位s
nohup <command> # 使用新的task执行命令，即不等待
end # 结束函数关键字，包括子task
await # 等待所有异步任务结束，若函数中启动了其他task，需要在最后调用，否则task对象会被销毁
```
#### **示例**
```shell
# 疯狂戳好友
# 使用 /function poke user_id=123456 执行
# 每隔0.2s戳两次，无限戳，会触发最大递归深度限制
# 若要戳20s后停止，则需要删除await，添加sleep 20和end
api friend_poke user_id=user_id
api friend_poke user_id=user_id
sleep 0.2
nohup function poke
await
```
### **API**
理论上所有基于onebotv11的api都可调用，不同Adapter api也有差别.
[Onebot v11 API文档](https://283375.github.io/onebot_v11_vitepress/api/index.html)
### **结束关键字**
由于LiteyukiBot基于异步运行, 所以在编写lyfunction时也要注意异步的调用，避免出现"单线程走到底"的情况是效率提升的关键.
`await` 异步任务结束关键字，用于结束当前已完成function的执行
> [!warning]
> 但若出现非单function的情况，有一个task任务没有完成而await被执行了，那么当前所有函数包的task都会被截停销毁
> [!tip]
> 编写轻雪函数推荐你使用VS Code插件[Liteyuki Function](https://github.com/LiteyukiStudio/lyfunctionTextmate)实现语法高亮

63
docs/en/dev/dev_lyplugin.md
View File

@ -1,63 +0,0 @@
---
title: Liteyuki Plugin
icon: laptop-code
order: 3
category: development
---
## 简介
轻雪插件是轻雪内置的一部分功能，运行在主进程中，可以很高程度地扩展轻雪的功能
## 开始
### 创建插件
在标准项目中，位于liteyuki/plugins和src/liteyuki_plugins下的Python modules均会被当作插件加载，你可自行添加配置文件以指定插件的加载路径
一个`.py`文件或一个包含`__init__.py`的文件夹即可被识别为插件
创建一个文件夹，例如`watchdog_plugin`，并在其中创建一个`__init__.py`文件，即可创建一个插件
```python
from liteyuki.plugin import PluginMetadata
# 定义插件元数据，推荐填写
__plugin_meta__ = PluginMetadata(
name="NoneDog", # 插件名称
version="1.0.0", # 插件版本
description="A simple plugin for nonebot developer" # 插件描述
)
# 你的插件代码
...
```
### 编写逻辑部分
轻雪主进程不涉及聊天部分，因此插件主要是一些后台任务或者与聊天机器人的通信
以下我们会编写一个简单的插件，用于开发NoneBot时进行文件系统变更重载
```python
import os
from liteyuki.dev import observer # 导入文件系统观察器
from liteyuki import get_bot, logger # 导入轻雪Bot和日志
from watchdog.events import FileSystemEvent # 导入文件系统事件
liteyuki = get_bot() # 获取唯一的轻雪Bot实例
exclude_extensions = (".pyc", ".pyo") # 排除的文件扩展名
# 用observer的on_file_system_event装饰器监听文件系统事件
@observer.on_file_system_event(
directories=("src/nonebot_plugins",),
event_filter=lambda event: not event.src_path.endswith(exclude_extensions) and ("__pycache__" not in event.src_path) and os.path.isfile(event.src_path)
)
def restart_nonebot_process(event: FileSystemEvent):
logger.debug(f"File {event.src_path} changed, reloading nonebot...")
liteyuki.restart_process("nonebot") # 调用重启进程方法
```
### 加载插件
在配置文件中的`liteyuki.plugins`中添加你的插件路径，例如`watchdog_plugin`，重启轻雪即可加载插件。然后我们在src/nonebot_plugins下创建一个文件，例如`test.py`，并在其中写入一些代码，保存后轻雪会自动重载NoneBot进程

53
docs/en/dev/dev_resource_pack.md
View File

@ -1,53 +0,0 @@
---
title: Resource Pack
icon: box
order: 1
category: development
---
## 简介
资源包,亦可根据用途称为主题包、字体包、语言包等，它允许你一定程度上自定义轻雪的外观,并且不用修改源代码
- [资源/主题商店](/store/)提供了一些资源包供你选择，你也可以自己制作资源包
- 资源包的制作很简单，如果你接触过`Minecraft`的资源包，那么你能够很快就上手，仅需按照原有路径进行文件替换即可，讲起打包成一个新的资源包。
- 部分内容制作需要一点点前端基础,例如`html`，`css`
- 轻雪原版资源包请查看`LiteyukiBot/liteyuki/resources`，可以在此基础上进行修改
- 欢迎各位投稿资源包到轻雪资源商店
请注意，主题包中的html渲染使用Js来规定数据的渲染位置，请确保您所编写的html代码能被Bot解析，否则会导致渲染失败或渲染结果不理想/异常/错位等无法预料的事情发生。推荐在编写html时同时更改对应Js代码，以避免出现无法预料的问题。
---
## 加载资源包
- 资源包通常是以`.zip`格式压缩的，只需要将其解压到根目录`resources`目录下即可，注意不要嵌套文件夹,正常的路径应该是这样的
```shell
main.py
resources
└─resource_pack_1
├─metadata.yml
├─templates
└───...
└─resource_pack_2
├─metadata.yml
└─...
```
- 你自己制作的资源包也应该遵循这个规则,并且应该在`metadata.yml`中填写一些信息
- 若没有`metadata.yml`文件，则该文件夹不会被识别为资源包
```yaml
name: "资源包名称"
version: "1.0.0"
description: "资源包描述"
# 你可以自定义一些信息,但请保证以上三个字段
...
```
- 资源包加载遵循一个优先级，即后加载的资源包会覆盖前面的资源包，例如，你在A包中定义了一个`index.html`文件，B包也定义了一个`index.html`文件，那么加载B包后，A包中的`index.html`文件会被覆盖
- 对于不同资源包的不同文件，是可以相对引用的，例如你在A中定义了`templates/index.html`，在B中定义了`templates/style.css`，可以在A的`index.html`中用`./style.css`相对路径引用B中的css
> [!tip]
> 资源包的结构会随着轻雪的更新而有变动，第三方资源包开发者需要注意版本兼容性，同时用户也应该自行选择可用的资源包

10
docs/litedoc/__init__.py Normal file
View File

@ -0,0 +1,10 @@
# -*- coding: utf-8 -*-
"""
Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
@Time : 2024/8/28 下午12:52
@Author : snowykami
@Email : snowykami@outlook.com
@File : __init__.py.py
@Software: PyCharm
"""

46
docs/litedoc/__main__.py Normal file
View File

@ -0,0 +1,46 @@
# -*- coding: utf-8 -*-
"""
Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
@Time : 2024/8/28 下午4:08
@Author : snowykami
@Email : snowykami@outlook.com
@File : __main__.py
@Software: PyCharm
"""
# command line tool
# args[0] path
# -o|--output output path
# -l|--lang zh-Hans en jp default zh-Hans
import argparse
import os
import sys
from litedoc.output import generate_from_module
def main():
parser = argparse.ArgumentParser(description="Generate documentation from Python modules.")
parser.add_argument("path", type=str, help="Path to the Python module or package.")
parser.add_argument("-o", "--output", default="doc-output", type=str, help="Output directory.")
parser.add_argument("-c", "--contain-top", action="store_true", help="Whether to contain top-level dir in output dir.")
parser.add_argument("-l", "--lang", nargs='+', default=["zh-Hans"], type=str, help="Languages of the document.")
args = parser.parse_args()
if not os.path.exists(args.path):
print(f"Error: The path {args.path} does not exist.")
sys.exit(1)
if not os.path.exists(args.output):
os.makedirs(args.output)
langs = args.lang
for lang in langs:
generate_from_module(args.path, args.output, with_top=args.contain_top, lang=lang)
if __name__ == '__main__':
main()

10
docs/litedoc/docstring/__init__.py Normal file
View File

@ -0,0 +1,10 @@
# -*- coding: utf-8 -*-
"""
Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
@Time : 2024/8/28 下午1:46
@Author : snowykami
@Email : snowykami@outlook.com
@File : __init__.py.py
@Software: PyCharm
"""

154
docs/litedoc/docstring/docstring.py Normal file
View File

@ -0,0 +1,154 @@
# -*- coding: utf-8 -*-
"""
Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
@Time : 2024/8/28 下午1:46
@Author : snowykami
@Email : snowykami@outlook.com
@File : docstring.py
@Software: PyCharm
"""
from typing import Optional
from pydantic import BaseModel, Field
from litedoc.i18n import get_text
class Attr(BaseModel):
name: str
type: str = ""
desc: str = ""
class Args(BaseModel):
name: str
type: str = ""
desc: str = ""
class Return(BaseModel):
desc: str = ""
class Exception_(BaseModel):
name: str
desc: str = ""
class Raise(BaseModel):
exceptions: list[Exception_] = []
class Example(BaseModel):
desc: str = ""
input: str = ""
output: str = ""
class Docstring(BaseModel):
desc: str = ""
args: list[Args] = []
attrs: list[Attr] = []
return_: Optional[Return] = None
raise_: list[Exception_] = []
example: list[Example] = []
def add_desc(self, desc: str):
if self.desc == "":
self.desc = desc
else:
self.desc += "\n" + desc
def add_arg(self, name: str, type_: str = "", desc: str = ""):
self.args.append(Args(name=name, type=type_, desc=desc))
def add_attrs(self, name: str, type_: str = "", desc: str = ""):
self.attrs.append(Attr(name=name, type=type_, desc=desc))
def add_return(self, desc: str = ""):
self.return_ = Return(desc=desc)
def add_raise(self, name: str, desc: str = ""):
self.raise_.append(Exception_(name=name, desc=desc))
def add_example(self, desc: str = "", input_: str = "", output: str = ""):
self.example.append(Example(desc=desc, input=input_, output=output))
def reduction(self) -> str:
"""
通过解析结果还原docstring
Args:
Returns:
"""
ret = ""
ret += self.desc + "\n"
if self.args:
ret += "Args:\n"
for arg in self.args:
ret += f" {arg.name}: {arg.type}\n {arg.desc}\n"
if self.attrs:
ret += "Attributes:\n"
for attr in self.attrs:
ret += f" {attr.name}: {attr.type}\n {attr.desc}\n"
if self.return_:
ret += "Returns:\n"
ret += f" {self.return_.desc}\n"
if self.raise_:
ret += "Raises:\n"
for exception in self.raise_:
ret += f" {exception.name}\n {exception.desc}\n"
if self.example:
ret += "Examples:\n"
for example in self.example:
ret += f" {example.desc}\n Input: {example.input}\n Output: {example.output}\n"
return ret
def markdown(self, lang: str, indent: int = 4, is_classmethod: bool = False) -> str:
"""
生成markdown文档
Args:
is_classmethod:
lang:
indent:
Returns:
"""
PREFIX = "" * indent
ret = ""
# ret += self.desc + "\n\n"
# print(self.reduction())
# print(self.desc, self.return_)
# 单数属性
if self.desc:
ret += PREFIX + f"\n**{get_text(lang, 'desc')}**: {self.desc}\n"
if self.return_ is not None:
ret += PREFIX + f"\n**{get_text(lang, 'docstring.return')}**: {self.return_.desc}\n"
# 复数属性
if self.args:
ret += PREFIX + f"\n**{get_text(lang, 'docstring.args')}**:\n"
for arg in self.args:
ret += PREFIX + f"> - {arg.name}: {arg.type} {arg.desc}\n"
if self.attrs:
ret += PREFIX + f"\n**{get_text(lang, 'docstring.attrs')}**:\n"
for attr in self.attrs:
ret += PREFIX + f"> - {attr.name}: {attr.type} {attr.desc}\n"
if self.raise_:
ret += PREFIX + f"\n**{get_text(lang, 'docstring.raises')}**:\n"
for exception in self.raise_:
ret += PREFIX + f"> - {exception.name} {exception.desc}\n"
if self.example:
ret += PREFIX + f"\n**{get_text(lang, 'docstring.example')}**:\n"
for example in self.example:
ret += PREFIX + f" - {example.desc}\n> **{get_text(lang, 'docs.input')}**: {example.input}\n> **{get_text(lang, 'docs.output')}**: {example.output}\n"
return ret
def __str__(self):
return self.desc

192
docs/litedoc/docstring/parser.py Normal file
View File

@ -0,0 +1,192 @@
"""
Google docstring parser for Python.
"""
from typing import Optional
from litedoc.docstring.docstring import Docstring
class Parser:
...
class GoogleDocstringParser(Parser):
_tokens = {
"Args" : "args",
"Arguments" : "args",
"参数" : "args",
"Return" : "return",
"Returns" : "return",
"返回" : "return",
"Attribute" : "attribute",
"Attributes" : "attribute",
"属性" : "attribute",
"Raises" : "raises",
"Raise" : "raises",
"引发" : "raises",
"Example" : "example",
"Examples" : "example",
"示例" : "example",
"Yields" : "yields",
"Yield" : "yields",
"产出" : "yields",
"Requires" : "requires",
"Require" : "requires",
"需要" : "requires",
"FrontMatter": "front_matter",
"前言" : "front_matter",
}
def __init__(self, docstring: str, indent: int = 4):
self.lines = docstring.splitlines()
self.indent = indent
self.lineno = 0 # Current line number
self.char = 0 # Current character position
self.docstring = Docstring()
def read_line(self, move: bool = True) -> str:
"""
每次读取一行
Args:
move: 是否移动指针
Returns:
"""
if self.lineno >= len(self.lines):
return ""
line = self.lines[self.lineno]
if move:
self.lineno += 1
return line
def match_token(self) -> Optional[str]:
"""
解析下一行的token
Returns:
"""
for token in self._tokens:
line = self.read_line(move=False)
if line.strip().startswith(token):
self.lineno += 1
return self._tokens[token]
return None
def parse_args(self):
"""
依次解析后面的参数行，直到缩进小于等于当前行的缩进
"""
while line := self.match_next_line():
if ":" in line:
name, desc = line.split(":", 1)
self.docstring.add_arg(name.strip(), desc.strip())
else:
self.docstring.add_arg(line.strip())
def parse_return(self):
"""
解析返回值行
"""
if line := self.match_next_line():
self.docstring.add_return(line.strip())
def parse_raises(self):
"""
解析异常行
"""
while line := self.match_next_line():
if ":" in line:
name, desc = line.split(":", 1)
self.docstring.add_raise(name.strip(), desc.strip())
else:
self.docstring.add_raise(line.strip())
def parse_example(self):
"""
解析示例行
"""
while line := self.match_next_line():
if ":" in line:
name, desc = line.split(":", 1)
self.docstring.add_example(name.strip(), desc.strip())
else:
self.docstring.add_example(line.strip())
def parse_attrs(self):
"""
解析属性行
"""
while line := self.match_next_line():
if ":" in line:
name, desc = line.split(":", 1)
self.docstring.add_attrs(name.strip(), desc.strip())
else:
self.docstring.add_attrs(line.strip())
def match_next_line(self) -> Optional[str]:
"""
在一个子解析器中，解析下一行，直到缩进小于等于当前行的缩进
Returns:
"""
line = self.read_line(move=False)
if line.startswith(" " * self.indent):
self.lineno += 1
return line[self.indent:]
else:
return None
def parse(self) -> Docstring:
"""
逐行解析，直到遇到EOS
最开始未解析到的内容全部加入desc
Returns:
"""
add_desc = True
while self.lineno < len(self.lines):
token = self.match_token()
if token is None and add_desc:
self.docstring.add_desc(self.lines[self.lineno].strip())
if token is not None:
add_desc = False
match token:
case "args":
self.parse_args()
case "return":
self.parse_return()
case "attribute":
self.parse_attrs()
case "raises":
self.parse_raises()
case "example":
self.parse_example()
case _:
self.lineno += 1
return self.docstring
class NumpyDocstringParser(Parser):
...
class ReStructuredParser(Parser):
...
def parse(docstring: str, parser: str = "google", indent: int = 4) -> Docstring:
if parser == "google":
return GoogleDocstringParser(docstring, indent).parse()
else:
raise ValueError(f"Unknown parser: {parser}")

131
docs/litedoc/i18n.py Normal file
View File

@ -0,0 +1,131 @@
# -*- coding: utf-8 -*-
"""
Internationalization module.
"""
from typing import Optional, TypeAlias
NestedDict: TypeAlias = dict[str, 'str | NestedDict']
i18n_dict: dict[str, NestedDict] = {
"en" : {
"docstring": {
"args" : "Arguments",
"return" : "Return",
"attribute": "Attribute",
"raises" : "Raises",
"example" : "Examples",
"yields" : "Yields",
},
"src": "Source code",
"desc": "Description",
"type": "Type",
},
"zh-Hans": {
"docstring": {
"args" : "参数",
"return" : "返回",
"attribute": "属性",
"raises" : "引发",
"example" : "示例",
"yields" : "产出",
},
"src": "源代码",
"desc": "说明",
"type": "类型",
},
"zh-Hant": {
"docstring": {
"args" : "變數説明",
"return" : "返回",
"attribute": "屬性",
"raises" : "抛出",
"example" : "範例",
"yields" : "產出",
},
"src": "源碼",
"desc": "説明",
"type": "類型",
},
"ja" : {
"docstring": {
"args" : "引数",
"return" : "戻り値",
"attribute": "属性",
"raises" : "例外",
"example" : "例",
"yields" : "生成",
},
"src": "ソースコード",
"desc": "説明",
"type": "タイプ",
},
}
def flat_i18n_dict(data: dict[str, NestedDict]) -> dict[str, dict[str, str]]:
"""
Flatten i18n_dict.
Examples:
```python
{
"en": {
"docs": {
"key1": "val1",
"key2": "val2",
}
}
}
```
to
```python
{
"en": {
"docs.key1": "val1",
"docs.key2": "val2",
}
}
```
Returns:
"""
ret: dict[str, dict[str, str]] = {}
def _flat(_lang_data: NestedDict) -> dict[str, str]:
res = {}
for k, v in _lang_data.items():
if isinstance(v, dict):
for kk, vv in _flat(v).items():
res[f"{k}.{kk}"] = vv
else:
res[k] = v
return res
for lang, lang_data in data.items():
ret[lang] = _flat(lang_data)
return ret
i18n_flat_dict = flat_i18n_dict(i18n_dict)
def get_text(lang: str, key: str, default: Optional[str] = None, fallback: Optional[str] = "en") -> str:
"""
Get text from i18n_dict.
Args:
lang: language name
key: text key
default: default text, if None return fallback language or key
fallback: fallback language, priority is higher than default
Returns:
str: text
"""
if lang in i18n_flat_dict:
if key in i18n_flat_dict[lang]:
return i18n_flat_dict[lang][key]
if fallback is not None:
return i18n_flat_dict.get(fallback, {}).get(key, default or key)
else:
return default or key

107
docs/litedoc/output.py Normal file
View File

@ -0,0 +1,107 @@
# -*- coding: utf-8 -*-
"""
Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
@Time : 2024/8/28 下午3:59
@Author : snowykami
@Email : snowykami@outlook.com
@File : output.py
@Software: PyCharm
"""
import os.path
from litedoc.style.markdown import generate
from litedoc.syntax.astparser import AstParser
def write_to_file(content: str, output: str) -> None:
"""
Write content to file.
Args:
content: str, content to write.
output: str, path to output file.
"""
if not os.path.exists(os.path.dirname(output)):
os.makedirs(os.path.dirname(output))
with open(output, "w", encoding="utf-8") as f:
f.write(content)
def get_file_list(module_folder: str):
file_list = []
for root, dirs, files in os.walk(module_folder):
for file in files:
if file.endswith((".py", ".pyi")):
file_list.append(os.path.join(root, file))
return file_list
def get_relative_path(base_path: str, target_path: str) -> str:
"""
获取相对路径
Args:
base_path: 基础路径
target_path: 目标路径
"""
return os.path.relpath(target_path, base_path)
def generate_from_module(module_folder: str, output_dir: str, with_top: bool = False, lang: str = "zh-Hans", ignored_paths=None):
"""
生成文档
Args:
module_folder: 模块文件夹
output_dir: 输出文件夹
with_top: 是否包含顶层文件夹 False时例如docs/api/module_a, docs/api/module_b， True时例如docs/api/module/module_a.md， docs/api/module/module_b.md
ignored_paths: 忽略的路径
lang: 语言
"""
if ignored_paths is None:
ignored_paths = []
file_data: dict[str, str] = {} # 路径 -> 字串
file_list = get_file_list(module_folder)
# 清理输出目录
if not os.path.exists(output_dir):
os.makedirs(output_dir)
replace_data = {
"__init__": "index",
".py" : ".md",
}
for pyfile_path in file_list:
if any(ignored_path.replace("\\", "/") in pyfile_path.replace("\\", "/") for ignored_path in ignored_paths):
continue
no_module_name_pyfile_path = get_relative_path(module_folder, pyfile_path) # 去头路径
# markdown相对路径
rel_md_path = pyfile_path if with_top else no_module_name_pyfile_path
for rk, rv in replace_data.items():
rel_md_path = rel_md_path.replace(rk, rv)
abs_md_path = os.path.join(output_dir, rel_md_path)
# 获取模块信息
ast_parser = AstParser(open(pyfile_path, "r", encoding="utf-8").read())
# 生成markdown
front_matter = {
"title" : pyfile_path.replace("\\", "/").
replace("/", ".").
replace(".py", "").
replace(".__init__", ""),
}
md_content = generate(ast_parser, lang=lang, frontmatter=front_matter)
print(f"Generate {pyfile_path} -> {abs_md_path}")
file_data[abs_md_path] = md_content
for fn, content in file_data.items():
write_to_file(content, fn)

10
docs/litedoc/style/__init__.py Normal file
View File

@ -0,0 +1,10 @@
# -*- coding: utf-8 -*-
"""
Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
@Time : 2024/8/28 下午3:39
@Author : snowykami
@Email : snowykami@outlook.com
@File : __init__.py.py
@Software: PyCharm
"""

59
docs/litedoc/style/markdown.py Normal file
View File

@ -0,0 +1,59 @@
# -*- coding: utf-8 -*-
"""
Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
@Time : 2024/8/28 下午3:39
@Author : snowykami
@Email : snowykami@outlook.com
@File : markdown.py
@Software: PyCharm
"""
from typing import Optional
from litedoc.syntax.astparser import AstParser
from litedoc.syntax.node import *
from litedoc.i18n import get_text
def generate(parser: AstParser, lang: str, frontmatter: Optional[dict] = None) -> str:
"""
Generate markdown style document from ast
You can modify this function to generate markdown style that enjoys you
Args:
parser:
lang: language
frontmatter:
Returns:
markdown style document
"""
if frontmatter is not None:
md = "---\n"
for k, v in frontmatter.items():
md += f"{k}: {v}\n"
md += "---\n"
else:
md = ""
# var > func > class
"""遍历函数"""
for func in parser.functions:
if func.name.startswith("_"):
continue
md += func.markdown(lang)
"""遍历类"""
for cls in parser.classes:
md += cls.markdown(lang)
"""遍历变量"""
for var in parser.variables:
md += f"### ***var*** `{var.name} = {var.value}`\n\n"
if var.type != TypeHint.NO_TYPEHINT:
md += f"- **{get_text(lang, 'type')}**: `{var.type}`\n\n"
if var.docs is not None:
md += f"- **{get_text(lang, 'desc')}**: {var.docs}\n\n"
return md

293
docs/litedoc/syntax/astparser.py Normal file
View File

@ -0,0 +1,293 @@
# -*- coding: utf-8 -*-
"""
Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
@Time : 2024/8/28 下午2:13
@Author : snowykami
@Email : snowykami@outlook.com
@File : astparser.py
@Software: PyCharm
"""
import ast
import inspect
from .node import *
from ..docstring.parser import parse
class AstParser:
def __init__(self, code: str):
self.code = code
self.tree = ast.parse(code)
self.classes: list[ClassNode] = []
self.functions: list[FunctionNode] = []
self.variables: list[AssignNode] = []
self.parse()
@staticmethod
def clear_quotes(s: str) -> str:
"""
去除类型注解中的引号
Args:
s:
Returns:
"""
return s.replace("'", "").replace('"', "")
def get_line_content(self, lineno: int, ignore_index_out: bool = True) -> str:
"""获取代码行内容
Args:
lineno: 行号
ignore_index_out: 是否忽略索引越界
Returns:
代码行内容
"""
if ignore_index_out:
if lineno < 1 or lineno > len(self.code.split("\n")):
return ""
return self.code.split("\n")[lineno - 1]
@staticmethod
def match_line_docs(linecontent: str) -> str:
"""匹配行内注释
Args:
linecontent: 行内容
Returns:
文档字符串
"""
in_string = False
string_char = ''
for i, char in enumerate(linecontent):
if char in ('"', "'"):
if in_string:
if char == string_char:
in_string = False
else:
in_string = True
string_char = char
elif char == '#' and not in_string:
return linecontent[i + 1:].strip()
return ""
def parse(self):
for node in ast.walk(self.tree):
if isinstance(node, ast.ClassDef):
if not self._is_module_level_class(node):
continue
class_node = ClassNode(
name=node.name,
docs=parse(ast.get_docstring(node)) if ast.get_docstring(node) else None,
inherits=[ast.unparse(base) for base in node.bases]
)
self.classes.append(class_node)
# 继续遍历类内部的函数
for sub_node in node.body:
if isinstance(sub_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
class_node.methods.append(FunctionNode(
name=sub_node.name,
docs=parse(ast.get_docstring(sub_node)) if ast.get_docstring(sub_node) else None,
posonlyargs=[
ArgNode(
name=arg.arg,
type=self.clear_quotes(ast.unparse(arg.annotation).strip()) if arg.annotation else TypeHint.NO_TYPEHINT,
)
for arg in sub_node.args.posonlyargs
],
args=[
ArgNode(
name=arg.arg,
type=self.clear_quotes(ast.unparse(arg.annotation).strip()) if arg.annotation else TypeHint.NO_TYPEHINT,
)
for arg in sub_node.args.args
],
kwonlyargs=[
ArgNode(
name=arg.arg,
type=self.clear_quotes(ast.unparse(arg.annotation).strip()) if arg.annotation else TypeHint.NO_TYPEHINT,
)
for arg in sub_node.args.kwonlyargs
],
kw_defaults=[
ConstantNode(
value=ast.unparse(default).strip() if default else TypeHint.NO_DEFAULT
)
for default in sub_node.args.kw_defaults
],
defaults=[
ConstantNode(
value=ast.unparse(default).strip() if default else TypeHint.NO_DEFAULT
)
for default in sub_node.args.defaults
],
return_=self.clear_quotes(ast.unparse(sub_node.returns).strip()) if sub_node.returns else TypeHint.NO_RETURN,
decorators=[ast.unparse(decorator).strip() for decorator in sub_node.decorator_list],
is_async=isinstance(sub_node, ast.AsyncFunctionDef),
src=ast.unparse(sub_node).strip(),
is_classmethod=True
))
# elif isinstance(sub_node, (ast.Assign, ast.AnnAssign)):
# if isinstance(sub_node, ast.Assign):
# class_node.attrs.append(AttrNode(
# name=sub_node.targets[0].id, # type: ignore
# type=TypeHint.NO_TYPEHINT,
# value=ast.unparse(sub_node.value).strip()
# ))
# elif isinstance(sub_node, ast.AnnAssign):
# class_node.attrs.append(AttrNode(
# name=sub_node.target.id,
# type=ast.unparse(sub_node.annotation).strip(),
# value=ast.unparse(sub_node.value).strip() if sub_node.value else TypeHint.NO_DEFAULT
# ))
# else:
# raise ValueError(f"Unsupported node type: {type(sub_node)}")
elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
# 仅打印模块级别的函数
if not self._is_module_level_function(node):
continue
self.functions.append(FunctionNode(
name=node.name,
docs=parse(ast.get_docstring(node)) if ast.get_docstring(node) else None,
posonlyargs=[
ArgNode(
name=arg.arg,
type=self.clear_quotes(ast.unparse(arg.annotation).strip()) if arg.annotation else TypeHint.NO_TYPEHINT,
)
for arg in node.args.posonlyargs
],
args=[
ArgNode(
name=arg.arg,
type=self.clear_quotes(ast.unparse(arg.annotation).strip()) if arg.annotation else TypeHint.NO_TYPEHINT,
)
for arg, default in zip(node.args.args, node.args.defaults)
],
kwonlyargs=[
ArgNode(
name=arg.arg,
type=self.clear_quotes(ast.unparse(arg.annotation).strip()) if arg.annotation else TypeHint.NO_TYPEHINT,
)
for arg in node.args.kwonlyargs
],
kw_defaults=[
ConstantNode(
value=ast.unparse(default).strip() if default else TypeHint.NO_DEFAULT
)
for default in node.args.kw_defaults
],
defaults=[
ConstantNode(
value=ast.unparse(default).strip() if default else TypeHint.NO_DEFAULT
)
for default in node.args.defaults
],
return_=self.clear_quotes(ast.unparse(node.returns).strip()) if node.returns else TypeHint.NO_RETURN,
decorators=[ast.unparse(decorator).strip() for decorator in node.decorator_list],
is_async=isinstance(node, ast.AsyncFunctionDef),
src=ast.unparse(node).strip()
))
elif isinstance(node, (ast.Assign, ast.AnnAssign)):
if not self._is_module_level_variable2(node):
continue
else:
pass
lineno = node.lineno
prev_line = self.get_line_content(lineno - 1).strip()
curr_line = self.get_line_content(lineno).strip()
next_line = self.get_line_content(lineno + 1).strip()
# 获取文档字符串，优先检测下行"""
if next_line.startswith('"""'):
docs = next_line[3:-3]
elif prev_line.startswith('"""'):
docs = prev_line[3:-3]
else:
curr_docs = self.match_line_docs(curr_line)
if curr_docs:
docs = curr_docs
else:
docs = None
# if isinstance(node, ast.Assign):
# for target in node.targets:
# if isinstance(target, ast.Name):
# self.variables.append(AssignNode(
# name=target.id,
# value=ast.unparse(node.value).strip(),
# type=ast.unparse(node.annotation).strip() if isinstance(node, ast.AnnAssign) else TypeHint.NO_TYPEHINT
# ))
if isinstance(node, ast.AnnAssign):
self.variables.append(AssignNode(
name=node.target.id,
value=ast.unparse(node.value).strip() if node.value else TypeHint.NO_DEFAULT,
type=ast.unparse(node.annotation).strip(),
docs=docs
))
def _is_module_level_function(self, node: ast.FunctionDef | ast.AsyncFunctionDef):
for parent in ast.walk(self.tree):
if isinstance(parent, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)):
if node in parent.body:
return False
return True
def _is_module_level_class(self, node: ast.ClassDef):
for parent in ast.walk(self.tree):
if isinstance(parent, ast.ClassDef):
if node in parent.body:
return False
return True
def _is_module_level_variable(self, node: ast.Assign | ast.AnnAssign):
"""在类方法或函数内部的变量不会被记录"""
# for parent in ast.walk(self.tree):
# if isinstance(parent, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)):
# if node in parent.body:
# return False
# else:
# for sub_node in parent.body:
# if isinstance(sub_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
# if node in sub_node.body:
# return False
# return True
# 递归检查
def _check(_node, _parent):
if isinstance(_parent, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)):
if _node in _parent.body:
return False
else:
for sub_node in _parent.body:
if isinstance(sub_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
return _check(_node, sub_node)
return True
for parent in ast.walk(self.tree):
if not _check(node, parent):
return False
return True
def _is_module_level_variable2(self, node: ast.Assign | ast.AnnAssign) -> bool:
"""
检查变量是否在模块级别定义。
"""
for parent in ast.walk(self.tree):
if isinstance(parent, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)):
if node in parent.body:
return False
return True
def __str__(self):
s = ""
for cls in self.classes:
s += f"class {cls.name}:\n"
for func in self.functions:
s += f"def {func.name}:\n"
for var in self.variables:
s += f"{var.name} = {var.value}\n"
return s

314
docs/litedoc/syntax/node.py Normal file
View File

@ -0,0 +1,314 @@
# -*- coding: utf-8 -*-
"""
Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
@Time : 2024/8/28 下午2:14
@Author : snowykami
@Email : snowykami@outlook.com
@File : node.py
@Software: PyCharm
"""
from typing import Literal, Optional
from enum import Enum
from pydantic import BaseModel, Field
from litedoc.docstring.docstring import Docstring
from litedoc.i18n import get_text
class TypeHint:
NO_TYPEHINT = "NO_TYPE_HINT"
NO_DEFAULT = "NO_DEFAULT"
NO_RETURN = "NO_RETURN"
class AssignNode(BaseModel):
"""
AssignNode is a pydantic model that represents an assignment.
Attributes:
name: str
The name of the assignment.
type: str = ""
The type of the assignment.
value: str
The value of the assignment.
"""
name: str
type: str = ""
value: str
docs: Optional[str] = ""
class ArgNode(BaseModel):
"""
ArgNode is a pydantic model that represents an argument.
Attributes:
name: str
The name of the argument.
type: str = ""
The type of the argument.
default: str = ""
The default value of the argument.
"""
name: str
type: str = TypeHint.NO_TYPEHINT
class AttrNode(BaseModel):
"""
AttrNode is a pydantic model that represents an attribute.
Attributes:
name: str
The name of the attribute.
type: str = ""
The type of the attribute.
value: str = ""
The value of the attribute
"""
name: str
type: str = ""
value: str = ""
class ImportNode(BaseModel):
"""
ImportNode is a pydantic model that represents an import statement.
Attributes:
name: str
The name of the import statement.
as_: str = ""
The alias of the import
"""
name: str
as_: str = ""
class ConstantNode(BaseModel):
"""
ConstantNode is a pydantic model that represents a constant.
Attributes:
value: str
The value of the constant.
"""
value: str
class FunctionNode(BaseModel):
"""
FunctionNode is a pydantic model that represents a function.
Attributes:
name: str
The name of the function.
docs: str = ""
The docstring of the function.
args: list[ArgNode] = []
The arguments of the function.
return_: ReturnNode = None
The return value of the function.
decorators: list[str] = []
The decorators of the function.
is_async: bool = False
Whether the function is asynchronous.
"""
name: str
docs: Optional[Docstring] = None
posonlyargs: list[ArgNode] = []
args: list[ArgNode] = []
kwonlyargs: list[ArgNode] = []
kw_defaults: list[ConstantNode] = []
defaults: list[ConstantNode] = []
return_: str = TypeHint.NO_RETURN
decorators: list[str] = []
src: str
is_async: bool = False
is_classmethod: bool = False
magic_methods: dict[str, str] = {
"__add__" : "+",
"__radd__" : "+",
"__sub__" : "-",
"__rsub__" : "-",
"__mul__" : "*",
"__rmul__" : "*",
"__matmul__" : "@",
"__rmatmul__": "@",
"__mod__" : "%",
"__truediv__": "/",
"__rtruediv__": "/",
"__neg__" : "-",
} # 魔术方法, 例如运算符
def is_private(self):
"""
Check if the function or method is private.
Returns:
bool: True if the function or method is private, False otherwise.
"""
return self.name.startswith("_")
def is_builtin(self):
"""
Check if the function or method is a builtin function or method.
Returns:
bool: True if the function or method is a builtin function or method, False otherwise.
"""
return self.name.startswith("__") and self.name.endswith("__")
def markdown(self, lang: str, indent: int = 0) -> str:
"""
Args:
indent: int
The number of spaces to indent the markdown.
lang: str
The language of the
Returns:
markdown style document
"""
self.complete_default_args()
PREFIX = "" * indent
# if is_classmethod:
# PREFIX = "- #"
func_type = "func" if not self.is_classmethod else "method"
md = ""
# 装饰器部分
if len(self.decorators) > 0:
for decorator in self.decorators:
md += PREFIX + f"### `@{decorator}`\n"
if self.is_async:
md += PREFIX + f"### *async {func_type}* "
else:
md += PREFIX + f"### *{func_type}* "
# code start
# 配对位置参数和位置参数默认值，无默认值用TypeHint.NO_DEFAULT
args: list[str] = [] # 可直接", ".join(args)得到位置参数部分
arg_i = 0
if len(self.posonlyargs) > 0:
for arg in self.posonlyargs:
arg_text = f"{arg.name}"
if arg.type != TypeHint.NO_TYPEHINT:
arg_text += f": {arg.type}"
arg_default = self.defaults[arg_i].value
if arg_default != TypeHint.NO_DEFAULT:
arg_text += f" = {arg_default}"
args.append(arg_text)
arg_i += 1
# 加位置参数分割符 /
args.append("/")
for arg in self.args:
arg_text = f"{arg.name}"
if arg.type != TypeHint.NO_TYPEHINT:
arg_text += f": {arg.type}"
arg_default = self.defaults[arg_i].value
if arg_default != TypeHint.NO_DEFAULT:
arg_text += f" = {arg_default}"
args.append(arg_text)
arg_i += 1
if len(self.kwonlyargs) > 0:
# 加关键字参数分割符 *
args.append("*")
for arg, kw_default in zip(self.kwonlyargs, self.kw_defaults):
arg_text = f"{arg.name}"
if arg.type != TypeHint.NO_TYPEHINT:
arg_text += f": {arg.type}"
if kw_default.value != TypeHint.NO_DEFAULT:
arg_text += f" = {kw_default.value}"
args.append(arg_text)
"""魔法方法"""
if self.name in self.magic_methods:
if len(args) == 2:
md += f"`{args[0]} {self.magic_methods[self.name]} {args[1]}"
elif len(args) == 1:
md += f"`{self.magic_methods[self.name]} {args[0]}"
if self.return_ != TypeHint.NO_RETURN:
md += f" => {self.return_}"
else:
md += f"`{self.name}(" # code start
md += ", ".join(args) + ")"
if self.return_ != TypeHint.NO_RETURN:
md += f" -> {self.return_}"
md += "`\n\n" # code end
"""此处预留docstring"""
if self.docs is not None:
md += f"\n{self.docs.markdown(lang, indent)}\n"
else:
pass
# 源码展示
md += PREFIX + f"\n<details>\n<summary> <b>{get_text(lang, 'src')}</b> </summary>\n\n```python\n{self.src}\n```\n</details>\n\n"
return md
def complete_default_args(self):
"""
补全位置参数默认值，用无默认值插入
Returns:
"""
num = len(self.args) + len(self.posonlyargs) - len(self.defaults)
self.defaults = [ConstantNode(value=TypeHint.NO_DEFAULT) for _ in range(num)] + self.defaults
def __str__(self):
return f"def {self.name}({', '.join([f'{arg.name}: {arg.type} = {arg.default}' for arg in self.args])}) -> {self.return_}"
class ClassNode(BaseModel):
"""
ClassNode is a pydantic model that represents a class.
Attributes:
name: str
The name of the class.
docs: str = ""
The docstring of the class.
attrs: list[AttrNode] = []
The attributes of the class.
methods: list[MethodNode] = []
The methods of the class.
inherits: list["ClassNode"] = []
The classes that the class inherits from
"""
name: str
docs: Optional[Docstring] = None
attrs: list[AttrNode] = []
methods: list[FunctionNode] = []
inherits: list[str] = []
def markdown(self, lang: str) -> str:
"""
返回类的markdown文档
Args:
lang: str
The language of the
Returns:
markdown style document
"""
hidden_methods = [
"__str__",
"__repr__",
]
md = ""
md += f"### **class** `{self.name}"
if len(self.inherits) > 0:
md += f"({', '.join([cls for cls in self.inherits])})"
md += "`\n"
for method in self.methods:
if method.name in hidden_methods:
continue
md += method.markdown(lang, 2)
for attr in self.attrs:
if attr.type == TypeHint.NO_TYPEHINT:
md += f"#### ***attr*** `{attr.name} = {attr.value}`\n\n"
else:
md += f"#### ***attr*** `{attr.name}: {attr.type} = {attr.value}`\n\n"
return md

47
docs/litedoc/translator.py Normal file
View File

@ -0,0 +1,47 @@
# -*- coding: utf-8 -*-
"""
Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
@Time : 2024/8/29 下午12:02
@Author : snowykami
@Email : snowykami@outlook.com
@File : translator.py
@Software: PyCharm
"""
from typing import Optional
from translate import Translator # type: ignore
# 特殊映射语言
i18n_lang2googletrans_lang = {
"zh-Hans": "zh-cn",
"zh-Hant": "zh-tw",
"en" : "en",
}
def get_google_lang(lang: str) -> str:
"""
Get google translate language
Args:
lang: language
Returns:
google translate language
"""
return i18n_lang2googletrans_lang.get(lang, lang)
def translate(text: str, lang: str, source_lang: str) -> str:
"""
Translate text to target language
Args:
source_lang:
text: text
lang: target language
Returns:
translated text
"""
if lang == source_lang:
return text
google_lang = get_google_lang(lang)
return Translator(to_lang=google_lang, from_lang=source_lang).translate(text)

36
liteyuki/bot/__init__.py
View File

@ -10,7 +10,6 @@ from typing import Any, Optional
from liteyuki.bot.lifespan import (LIFESPAN_FUNC, Lifespan)
from liteyuki.comm.channel import get_channel
from liteyuki.comm.storage import shared_memory
from liteyuki.core.manager import ProcessManager
from liteyuki.log import init_log, logger
from liteyuki.plugin import load_plugin
@ -63,16 +62,25 @@ class LiteyukiBot:
signal.signal(signal.SIGTERM, self._handle_exit)
atexit.register(self.process_manager.terminate_all) # 注册退出时的函数
def run(self):
async def _run(self):
"""
启动逻辑
"""
self.lifespan.before_start() # 启动前钩子
self.process_manager.start_all()
self.lifespan.after_start() # 启动后钩子
self.keep_alive()
await self.lifespan.before_start() # 启动前钩子
await self.process_manager.start_all()
await self.lifespan.after_start() # 启动后钩子
await self.keep_alive()
def keep_alive(self):
def run(self):
"""
外部启动接口
"""
try:
asyncio.run(self._run())
except KeyboardInterrupt:
logger.info("Liteyuki is stopping...")
async def keep_alive(self):
"""
保持轻雪运行
Returns:
@ -131,9 +139,6 @@ class LiteyukiBot:
name: 进程名称, 默认为None, 所有进程
Returns:
"""
self.lifespan.before_process_shutdown() # 重启前钩子
self.lifespan.before_process_shutdown() # 停止前钩子
if name is not None:
chan_active = get_channel(f"{name}-active")
chan_active.send(1)
@ -230,17 +235,6 @@ class LiteyukiBot:
"""
return self.lifespan.on_after_restart(func)
def on_after_nonebot_init(self, func: LIFESPAN_FUNC):
"""
注册nonebot初始化后的函数
Args:
func:
Returns:
"""
return self.lifespan.on_after_nonebot_init(func)
_BOT_INSTANCE: LiteyukiBot

58
liteyuki/bot/lifespan.py
View File

@ -39,29 +39,17 @@ class Lifespan:
self._before_process_restart_funcs: list[LIFESPAN_FUNC] = []
self._after_restart_funcs: list[LIFESPAN_FUNC] = []
self._after_nonebot_init_funcs: list[LIFESPAN_FUNC] = []
@staticmethod
def run_funcs(funcs: list[LIFESPAN_FUNC | PROCESS_LIFESPAN_FUNC], *args, **kwargs) -> None:
async def run_funcs(funcs: list[ASYNC_LIFESPAN_FUNC | PROCESS_LIFESPAN_FUNC], *args, **kwargs) -> None:
"""
运行函数
并发运行异步函数
Args:
funcs:
Returns:
"""
try:
loop = asyncio.get_event_loop()
except RuntimeError:
loop = asyncio.new_event_loop()
asyncio.set_event_loop(loop)
tasks = []
for func in funcs:
if is_coroutine_callable(func):
tasks.append(func(*args, **kwargs))
else:
tasks.append(async_wrapper(func)(*args, **kwargs))
loop.run_until_complete(asyncio.gather(*tasks))
loop = asyncio.get_running_loop()
tasks = [func(*args, **kwargs) if is_coroutine_callable(func) else async_wrapper(func)(*args, **kwargs) for func in funcs]
await asyncio.gather(*tasks)
def on_before_start(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC:
"""
@ -131,63 +119,51 @@ class Lifespan:
self._after_restart_funcs.append(func)
return func
def on_after_nonebot_init(self, func):
"""
注册 NoneBot 初始化后的函数
Args:
func:
Returns:
"""
self._after_nonebot_init_funcs.append(func)
return func
def before_start(self) -> None:
async def before_start(self) -> None:
"""
启动前
Returns:
"""
logger.debug("Running before_start functions")
self.run_funcs(self._before_start_funcs)
await self.run_funcs(self._before_start_funcs)
def after_start(self) -> None:
async def after_start(self) -> None:
"""
启动后
Returns:
"""
logger.debug("Running after_start functions")
self.run_funcs(self._after_start_funcs)
await self.run_funcs(self._after_start_funcs)
def before_process_shutdown(self) -> None:
async def before_process_shutdown(self) -> None:
"""
停止前
Returns:
"""
logger.debug("Running before_shutdown functions")
self.run_funcs(self._before_process_shutdown_funcs)
await self.run_funcs(self._before_process_shutdown_funcs)
def after_shutdown(self) -> None:
async def after_shutdown(self) -> None:
"""
停止后
Returns:
"""
logger.debug("Running after_shutdown functions")
self.run_funcs(self._after_shutdown_funcs)
await self.run_funcs(self._after_shutdown_funcs)
def before_process_restart(self) -> None:
async def before_process_restart(self) -> None:
"""
重启前
Returns:
"""
logger.debug("Running before_restart functions")
self.run_funcs(self._before_process_restart_funcs)
await self.run_funcs(self._before_process_restart_funcs)
def after_restart(self) -> None:
async def after_restart(self) -> None:
"""
重启后
Returns:
"""
logger.debug("Running after_restart functions")
self.run_funcs(self._after_restart_funcs)
await self.run_funcs(self._after_restart_funcs)

123
liteyuki/comm/channel.py
View File

@ -10,12 +10,12 @@ Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
本模块定义了一个通用的通道类，用于进程间通信
"""
import threading
import asyncio
from multiprocessing import Pipe
from typing import Any, Callable, Coroutine, Generic, Optional, TypeAlias, TypeVar, get_args
from liteyuki.utils import IS_MAIN_PROCESS, is_coroutine_callable, run_coroutine
from liteyuki.log import logger
from liteyuki.utils import IS_MAIN_PROCESS, is_coroutine_callable
T = TypeVar("T")
@ -38,21 +38,22 @@ class Channel(Generic[T]):
有两种接收工作方式，但是只能选择一种，主动接收和被动接收，主动接收使用 `receive` 方法，被动接收使用 `on_receive` 装饰器
"""
def __init__(self, _id: str = "", type_check: Optional[bool] = None):
def __init__(self, name: str, type_check: Optional[bool] = None):
"""
初始化通道
Args:
_id: 通道ID
name: 通道ID
type_check: 是否开启类型检查, 若为空，则传入泛型默认开启，否则默认关闭
"""
self.conn_send, self.conn_recv = Pipe()
self._closed = False
self._on_main_receive_funcs: list[int] = []
self._on_sub_receive_funcs: list[int] = []
self.name: str = _id
self.is_main_receive_loop_running = False
self.is_sub_receive_loop_running = False
self.conn_send, self.conn_recv = Pipe()
self._conn_send_inner, self._conn_recv_inner = Pipe() # 内部通道，用于子进程通信
self._closed = False
self._on_main_receive_func_ids: list[int] = []
self._on_sub_receive_func_ids: list[int] = []
self.name: str = name
self.is_receive_loop_running = False
if type_check is None:
# 若传入泛型则默认开启类型检查
@ -62,6 +63,16 @@ class Channel(Generic[T]):
if self._get_generic_type() is None:
raise TypeError("Type hint is required for enforcing type check.")
self.type_check = type_check
if name in _channel:
raise ValueError(f"Channel {name} already exists")
if IS_MAIN_PROCESS:
if name in _channel:
raise ValueError(f"Channel {name} already exists")
_channel[name] = self
logger.debug(f"Channel {name} initialized in main process")
else:
logger.debug(f"Channel {name} initialized in sub process, should manually set in main process")
def _get_generic_type(self) -> Optional[type]:
"""
@ -105,7 +116,7 @@ class Channel(Generic[T]):
def send(self, data: T):
"""
发送数据
发送数据，发送函数为同步函数，没有异步的必要
Args:
data: 数据
"""
@ -120,7 +131,7 @@ class Channel(Generic[T]):
def receive(self) -> T:
"""
接收数据
同步接收数据，会阻塞线程
Args:
"""
if self._closed:
@ -130,13 +141,15 @@ class Channel(Generic[T]):
data = self.conn_recv.recv()
return data
def close(self):
async def async_receive(self) -> T:
"""
关闭通道
异步接收数据，会挂起等待
"""
self._closed = True
self.conn_send.close()
self.conn_recv.close()
print("等待接收数据")
loop = asyncio.get_running_loop()
data = await loop.run_in_executor(None, self.receive)
print("接收到数据")
return data
def on_receive(self, filter_func: Optional[FILTER_FUNC] = None) -> Callable[[Callable[[T], Any]], Callable[[T], Any]]:
"""
@ -146,11 +159,8 @@ class Channel(Generic[T]):
Returns:
装饰器，装饰一个函数在接收到数据后执行
"""
if (not self.is_sub_receive_loop_running) and not IS_MAIN_PROCESS:
threading.Thread(target=self._start_sub_receive_loop, daemon=True).start()
if (not self.is_main_receive_loop_running) and IS_MAIN_PROCESS:
threading.Thread(target=self._start_main_receive_loop, daemon=True).start()
if not IS_MAIN_PROCESS:
raise RuntimeError("on_receive can only be used in main process")
def decorator(func: Callable[[T], Any]) -> Callable[[T], Any]:
global _func_id
@ -171,65 +181,52 @@ class Channel(Generic[T]):
_callback_funcs[_func_id] = wrapper
if IS_MAIN_PROCESS:
self._on_main_receive_funcs.append(_func_id)
self._on_main_receive_func_ids.append(_func_id)
else:
self._on_sub_receive_funcs.append(_func_id)
self._on_sub_receive_func_ids.append(_func_id)
_func_id += 1
return func
return decorator
def _run_on_main_receive_funcs(self, data: Any):
async def _run_on_receive_funcs(self, data: Any):
"""
运行接收函数
Args:
data: 数据
"""
for func_id in self._on_main_receive_funcs:
func = _callback_funcs[func_id]
run_coroutine(func(data))
if IS_MAIN_PROCESS:
[asyncio.create_task(_callback_funcs[func_id](data)) for func_id in self._on_main_receive_func_ids]
else:
[asyncio.create_task(_callback_funcs[func_id](data)) for func_id in self._on_sub_receive_func_ids]
def _run_on_sub_receive_funcs(self, data: Any):
"""
运行接收函数
Args:
data: 数据
"""
for func_id in self._on_sub_receive_funcs:
func = _callback_funcs[func_id]
run_coroutine(func(data))
def _start_main_receive_loop(self):
async def start_receive_loop(self):
"""
开始接收数据
会自动判断主进程和子进程，需要在对应进程都调度一次
"""
self.is_main_receive_loop_running = True
while not self._closed:
data = self.conn_recv.recv()
self._run_on_main_receive_funcs(data)
if len(self._on_main_receive_func_ids) == 0:
logger.warning(f"No on_receive function registered for {self.name}")
return
def _start_sub_receive_loop(self):
"""
开始接收数据
"""
self.is_sub_receive_loop_running = True
self.is_receive_loop_running = True
logger.debug(f"Starting receive loop for {self.name}")
while not self._closed:
data = self.conn_recv.recv()
self._run_on_sub_receive_funcs(data)
data = await self.async_receive()
await self._run_on_receive_funcs(data)
"""子进程可用的主动和被动通道"""
active_channel: Optional["Channel"] = None
passive_channel: Optional["Channel"] = None
publish_channel: Channel[tuple[str, dict[str, Any]]] = Channel(_id="publish_channel")
active_channel: Channel = Channel(name="active_channel")
passive_channel: Channel = Channel(name="passive_channel")
publish_channel: Channel[tuple[str, dict[str, Any]]] = Channel(name="publish_channel")
"""通道传递通道，主进程创建单例，子进程初始化时实例化"""
channel_deliver_active_channel: Channel[Channel[Any]]
channel_deliver_passive_channel: Channel[tuple[str, dict[str, Any]]]
if IS_MAIN_PROCESS:
channel_deliver_active_channel = Channel(_id="channel_deliver_active_channel")
channel_deliver_passive_channel = Channel(_id="channel_deliver_passive_channel")
channel_deliver_active_channel = Channel(name="channel_deliver_active_channel")
channel_deliver_passive_channel = Channel(name="channel_deliver_passive_channel")
@channel_deliver_passive_channel.on_receive(filter_func=lambda data: data[0] == "set_channel")
@ -250,7 +247,7 @@ if IS_MAIN_PROCESS:
recv_chan.send(get_channels())
def set_channel(name: str, channel: Channel):
def set_channel(name: str, channel: "Channel"):
"""
设置通道实例
Args:
@ -261,20 +258,22 @@ def set_channel(name: str, channel: Channel):
raise TypeError(f"channel_ must be an instance of Channel, {type(channel)} found")
if IS_MAIN_PROCESS:
if name in _channel:
raise ValueError(f"Channel {name} already exists")
_channel[name] = channel
else:
# 请求主进程设置通道
channel_deliver_passive_channel.send(
(
"set_channel", {
"name" : name,
"name" : name,
"channel_": channel,
}
)
)
def set_channels(channels: dict[str, Channel]):
def set_channels(channels: dict[str, "Channel"]):
"""
设置通道实例
Args:
@ -284,7 +283,7 @@ def set_channels(channels: dict[str, Channel]):
set_channel(name, channel)
def get_channel(name: str) -> Channel:
def get_channel(name: str) -> "Channel":
"""
获取通道实例
Args:
@ -308,7 +307,7 @@ def get_channel(name: str) -> Channel:
return recv_chan.receive()
def get_channels() -> dict[str, Channel]:
def get_channels() -> dict[str, "Channel"]:
"""
获取通道实例
Returns:

26
liteyuki/comm/rpc.py Normal file
View File

@ -0,0 +1,26 @@
# -*- coding: utf-8 -*-
"""
本模块用于实现RPC(基于IPC)通信
"""
from typing import TypeAlias, Callable, Any
from liteyuki.comm.channel import Channel
ON_CALLING_FUNC: TypeAlias = Callable[[tuple, dict], Any]
class RPC:
"""
RPC类
"""
def __init__(self, on_calling: ON_CALLING_FUNC) -> None:
self.on_calling = on_calling
def call(self, args: tuple, kwargs: dict) -> Any:
"""
调用
"""
# 获取self.calling函数名
return self.on_calling(args, kwargs)

54
liteyuki/comm/socks_channel.py Normal file
View File

@ -0,0 +1,54 @@
# -*- coding: utf-8 -*-
"""
Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
@Time : 2024/8/25 下午3:54
@Author : snowykami
@Email : snowykami@outlook.com
@File : channelv2.py
@Software: PyCharm
"""
class SocksChannel:
"""
通道类，可以在进程间和进程内通信，双向但同时只能有一个发送者和一个接收者
有两种接收工作方式，但是只能选择一种，主动接收和被动接收，主动接收使用 `receive` 方法，被动接收使用 `on_receive` 装饰器
"""
def __init__(self, name: str):
"""
初始化通道
Args:
name: 通道ID
"""
self._name = name
self._conn_send = None
self._conn_recv = None
self._closed = False
def send(self, data):
"""
发送数据
Args:
data: 数据
"""
pass
def receive(self):
"""
接收数据
Returns:
data: 数据
"""
pass
def close(self):
"""
关闭通道
"""
pass

79
liteyuki/comm/storage.py
View File

@ -2,13 +2,13 @@
"""
共享内存模块。类似于redis，但是更加轻量级并且线程安全
"""
import asyncio
import threading
from typing import Any, Coroutine, Optional, TypeAlias, Callable
from typing import Any, Callable, Optional
from liteyuki.comm import channel
from liteyuki.comm.channel import Channel, ON_RECEIVE_FUNC, ASYNC_ON_RECEIVE_FUNC
from liteyuki.utils import IS_MAIN_PROCESS, is_coroutine_callable, run_coroutine, run_coroutine_in_thread
from liteyuki.comm.channel import ASYNC_ON_RECEIVE_FUNC, Channel, ON_RECEIVE_FUNC
from liteyuki.utils import IS_MAIN_PROCESS, is_coroutine_callable, run_coroutine_in_thread
if IS_MAIN_PROCESS:
_locks = {}
@ -31,24 +31,13 @@ def _get_lock(key) -> threading.Lock:
raise RuntimeError("Cannot get lock in sub process.")
class Subscriber:
def __init__(self):
self._subscribers = {}
def receive(self) -> Any:
pass
def unsubscribe(self) -> None:
pass
class KeyValueStore:
def __init__(self):
self._store = {}
self.active_chan = Channel[tuple[str, Optional[dict[str, Any]]]](_id="shared_memory-active")
self.passive_chan = Channel[tuple[str, Optional[dict[str, Any]]]](_id="shared_memory-passive")
self.active_chan = Channel[tuple[str, Optional[dict[str, Any]]]](name="shared_memory-active")
self.passive_chan = Channel[tuple[str, Optional[dict[str, Any]]]](name="shared_memory-passive")
self.publish_channel = Channel[tuple[str, Any]](_id="shared_memory-publish")
self.publish_channel = Channel[tuple[str, Any]](name="shared_memory-publish")
self.is_main_receive_loop_running = False
self.is_sub_receive_loop_running = False
@ -170,7 +159,7 @@ class KeyValueStore:
"publish",
{
"channel": channel_,
"data" : data
"data" : data
}
)
)
@ -184,12 +173,8 @@ class KeyValueStore:
Returns:
装饰器
"""
if IS_MAIN_PROCESS and not self.is_main_receive_loop_running:
threading.Thread(target=self._start_receive_loop, daemon=True).start()
shared_memory.is_main_receive_loop_running = True
elif not IS_MAIN_PROCESS and not self.is_sub_receive_loop_running:
threading.Thread(target=self._start_receive_loop, daemon=True).start()
shared_memory.is_sub_receive_loop_running = True
if not IS_MAIN_PROCESS:
raise RuntimeError("Cannot subscribe in sub process.")
def decorator(func: ON_RECEIVE_FUNC) -> ON_RECEIVE_FUNC:
async def wrapper(data: Any):
@ -211,38 +196,29 @@ class KeyValueStore:
return decorator
@staticmethod
def run_subscriber_receive_funcs(channel_: str, data: Any):
async def run_subscriber_receive_funcs(channel_: str, data: Any):
"""
运行订阅者接收函数
Args:
channel_: 频道
data: 数据
"""
if IS_MAIN_PROCESS:
if channel_ in _on_main_subscriber_receive_funcs and _on_main_subscriber_receive_funcs[channel_]:
run_coroutine_in_thread(*[func(data) for func in _on_main_subscriber_receive_funcs[channel_]])
else:
if channel_ in _on_sub_subscriber_receive_funcs and _on_sub_subscriber_receive_funcs[channel_]:
run_coroutine_in_thread(*[func(data) for func in _on_sub_subscriber_receive_funcs[channel_]])
[asyncio.create_task(func(data)) for func in _on_main_subscriber_receive_funcs[channel_]]
def _start_receive_loop(self):
async def start_receive_loop(self):
"""
启动发布订阅接收器循环，在主进程中运行，若有子进程订阅则推送给子进程
"""
if IS_MAIN_PROCESS:
while True:
data = self.active_chan.receive()
if data[0] == "publish":
# 运行主进程订阅函数
self.run_subscriber_receive_funcs(data[1]["channel"], data[1]["data"])
# 推送给子进程
self.publish_channel.send(data)
else:
while True:
data = self.publish_channel.receive()
if data[0] == "publish":
# 运行子进程订阅函数
self.run_subscriber_receive_funcs(data[1]["channel"], data[1]["data"])
if not IS_MAIN_PROCESS:
raise RuntimeError("Cannot start receive loop in sub process.")
while True:
data = await self.active_chan.async_receive()
if data[0] == "publish":
# 运行主进程订阅函数
await self.run_subscriber_receive_funcs(data[1]["channel"], data[1]["data"])
# 推送给子进程
self.publish_channel.send(data)
class GlobalKeyValueStore:
@ -262,7 +238,6 @@ shared_memory: KeyValueStore = GlobalKeyValueStore.get_instance()
# 全局单例访问点
if IS_MAIN_PROCESS:
@shared_memory.passive_chan.on_receive(lambda d: d[0] == "get")
def on_get(data: tuple[str, dict[str, Any]]):
key = data[1]["key"]
@ -289,14 +264,6 @@ if IS_MAIN_PROCESS:
recv_chan = data[1]["recv_chan"]
recv_chan.send(shared_memory.get_all())
else:
# 子进程在入口函数中对shared_memory进行初始化
@channel.publish_channel.on_receive()
def on_publish(data: tuple[str, Any]):
channel_, data = data
shared_memory.run_subscriber_receive_funcs(channel_, data)
_ref_count = 0 # import 引用计数, 防止获取空指针
if not IS_MAIN_PROCESS:
if (shared_memory is None) and _ref_count > 1:

2
liteyuki/core/__init__.py
View File

@ -1,4 +1,2 @@
import multiprocessing
from .manager import *

43
liteyuki/core/manager.py
View File

@ -8,13 +8,11 @@ Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
@File : manager.py
@Software: PyCharm
"""
import asyncio
import multiprocessing
import threading
from multiprocessing import Process
from typing import Any, Callable, TYPE_CHECKING, TypeAlias
from liteyuki.comm.channel import Channel, get_channel, set_channels, publish_channel
from liteyuki.comm.storage import shared_memory
from liteyuki.log import logger
from liteyuki.utils import IS_MAIN_PROCESS
@ -22,10 +20,15 @@ if TYPE_CHECKING:
from liteyuki.bot.lifespan import Lifespan
from liteyuki.comm.storage import KeyValueStore
from liteyuki.comm import Channel
if IS_MAIN_PROCESS:
from liteyuki.comm.channel import get_channel, publish_channel, get_channels
from liteyuki.comm.storage import shared_memory
from liteyuki.comm.channel import channel_deliver_active_channel, channel_deliver_passive_channel
else:
from liteyuki.comm import channel
from liteyuki.comm import storage
TARGET_FUNC: TypeAlias = Callable[..., Any]
TIMEOUT = 10
@ -69,7 +72,7 @@ def _delivery_channel_wrapper(func: TARGET_FUNC, cd: ChannelDeliver, sm: "KeyVal
channel.publish_channel = cd.publish # 子进程发布通道
# 给子进程创建共享内存实例
from liteyuki.comm import storage
storage.shared_memory = sm
func(*args, **kwargs)
@ -85,13 +88,12 @@ class ProcessManager:
self.targets: dict[str, tuple[Callable, tuple, dict]] = {}
self.processes: dict[str, Process] = {}
def start(self, name: str):
async def _run_process(self, name: str):
"""
开启后自动监控进程，并添加到进程字典中
开启后自动监控进程，并添加到进程字典中，会阻塞，请创建task
Args:
name:
Returns:
"""
if name not in self.targets:
raise KeyError(f"Process {name} not found.")
@ -108,30 +110,31 @@ class ProcessManager:
_start_process()
while True:
data = chan_active.receive()
data = await chan_active.async_receive()
if data == 0:
# 停止
logger.info(f"Stopping process {name}")
self.lifespan.before_process_shutdown()
await self.lifespan.before_process_shutdown()
self.terminate(name)
break
elif data == 1:
# 重启
logger.info(f"Restarting process {name}")
self.lifespan.before_process_shutdown()
self.lifespan.before_process_restart()
await self.lifespan.before_process_shutdown()
await self.lifespan.before_process_restart()
self.terminate(name)
_start_process()
continue
else:
logger.warning("Unknown data received, ignored.")
def start_all(self):
async def start_all(self):
"""
启动所有进程
对外启动方法，启动所有进程，创建asyncio task
"""
for name in self.targets:
threading.Thread(target=self.start, args=(name,), daemon=True).start()
[asyncio.create_task(chan.start_receive_loop()) for chan in get_channels().values()]
[asyncio.create_task(sm.start_receive_loop()) for sm in [shared_memory]]
[asyncio.create_task(self._run_process(name)) for name in self.targets]
def add_target(self, name: str, target: TARGET_FUNC, args: tuple = (), kwargs=None):
"""
@ -144,8 +147,8 @@ class ProcessManager:
"""
if kwargs is None:
kwargs = {}
chan_active: Channel = Channel(_id=f"{name}-active")
chan_passive: Channel = Channel(_id=f"{name}-passive")
chan_active: Channel = Channel(name=f"{name}-active")
chan_passive: Channel = Channel(name=f"{name}-passive")
channel_deliver = ChannelDeliver(
active=chan_active,
@ -157,12 +160,6 @@ class ProcessManager:
self.targets[name] = (_delivery_channel_wrapper, (target, channel_deliver, shared_memory, *args), kwargs)
# 主进程通道
set_channels(
{
f"{name}-active" : chan_active,
f"{name}-passive": chan_passive
}
)
def join_all(self):
for name, process in self.targets:

10
liteyuki/message/event.py
View File

@ -10,6 +10,7 @@ Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
"""
from typing import Any, Optional
from liteyuki import Channel
from liteyuki.comm.storage import shared_memory
@ -24,7 +25,7 @@ class MessageEvent:
session_id: str,
user_id: str,
session_type: str,
receive_channel: str,
receive_channel: Optional[Channel["MessageEvent"]] = None,
data: Optional[dict[str, Any]] = None,
):
"""
@ -78,7 +79,10 @@ class MessageEvent:
},
bot_id=self.bot_id,
session_id=self.session_id,
user_id=self.user_id,
session_type=self.session_type,
receive_channel="_"
receive_channel=None
)
shared_memory.publish(self.receive_channel, reply_event)
# shared_memory.publish(self.receive_channel, reply_event)
if self.receive_channel:
self.receive_channel.send(reply_event)

15
liteyuki/message/on.py
View File

@ -23,6 +23,7 @@ _queue: Queue = Queue()
@shared_memory.on_subscriber_receive("event_to_liteyuki")
async def _(event: MessageEvent):
print("AA")
current_priority = -1
for i, matcher in enumerate(_matcher_list):
logger.info(f"Running matcher {matcher} for event: {event}")
@ -32,17 +33,24 @@ async def _(event: MessageEvent):
current_priority = matcher.priority
if matcher.block:
break
else:
logger.info(f"No matcher matched for event: {event}")
print("BB")
def on_message(rule: Rule = empty_rule, priority: int = 0, block: bool = False) -> Matcher:
matcher = Matcher(rule, priority, block)
# 按照优先级插入
def add_matcher(matcher: Matcher):
for i, m in enumerate(_matcher_list):
if m.priority < matcher.priority:
_matcher_list.insert(i, matcher)
break
else:
_matcher_list.append(matcher)
def on_message(rule: Rule = empty_rule, priority: int = 0, block: bool = False) -> Matcher:
matcher = Matcher(rule, priority, block)
# 按照优先级插入
add_matcher(matcher)
return matcher
@ -50,4 +58,5 @@ def on_keywords(keywords: list[str], rule=empty_rule, priority: int = 0, block:
@Rule
async def on_keywords_rule(event: MessageEvent):
return any(keyword in event.raw_message for keyword in keywords)
return on_message(on_keywords_rule & rule, priority, block)

4
liteyuki/utils.py
View File

@ -43,7 +43,7 @@ def run_coroutine(*coro: Coroutine):
# 检测是否有现有的事件循环
try:
loop = asyncio.get_event_loop()
loop = asyncio.get_running_loop()
if loop.is_running():
# 如果事件循环正在运行，创建任务
for c in coro:
@ -62,6 +62,7 @@ def run_coroutine(*coro: Coroutine):
# 捕获其他异常，防止协程被重复等待
logger.error(f"Exception occurred: {e}")
def run_coroutine_in_thread(*coro: Coroutine):
"""
在新线程中运行协程
@ -73,6 +74,7 @@ def run_coroutine_in_thread(*coro: Coroutine):
"""
threading.Thread(target=run_coroutine, args=coro, daemon=True).start()
def path_to_module_name(path: Path) -> str:
"""
转换路径为模块名

1
main.py
View File

@ -4,6 +4,7 @@
from liteyuki import LiteyukiBot
from liteyuki.config import load_config_in_default
if __name__ == "__main__":
bot = LiteyukiBot(**load_config_in_default(no_waring=True))
bot.run()

24
src/liteyuki_plugins/anti_dislink.py
View File

@ -1,24 +0,0 @@
# -*- coding: utf-8 -*-
"""
Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
@Time : 2024/8/22 上午9:06
@Author : snowykami
@Email : snowykami@outlook.com
@File : anti_dislink.py
@Software: PyCharm
"""
import random
from liteyuki.plugin import PluginMetadata, PluginType
from liteyuki.message.on import on_keywords
__plugin_meta__ = PluginMetadata(
name="严禁断联化",
type=PluginType.APPLICATION
)
@on_keywords(["看看你的", "看看j", "给我看看"]).handle()
async def _(event):
event.reply(random.choice(["No dislink", "严禁断联化"]))

26
src/liteyuki_plugins/ts_chan_main.py
View File

@ -1,26 +0,0 @@
# -*- coding: utf-8 -*-
"""
Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
@Time : 2024/8/22 上午8:37
@Author : snowykami
@Email : snowykami@outlook.com
@File : ts_chan_main.py
@Software: PyCharm
"""
import asyncio
from liteyuki.comm import Channel, set_channel, get_channel
from liteyuki import get_bot
set_channel("chan-main", Channel("chan-main"))
set_channel("chan-sub", Channel("chan-sub"))
chan_main = get_channel("chan-main")
# @get_bot().on_after_start
# async def _():
# while True:
# chan_main.send("Hello, World!")
# await asyncio.sleep(5)

27
src/nonebot_plugins/to_liteyuki.py
View File

@ -10,18 +10,23 @@ Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
"""
import asyncio
from nonebot import Bot, get_bot, on_message
from nonebot import Bot, get_bot, on_message, get_driver
from nonebot.plugin import PluginMetadata
from nonebot.adapters.onebot.v11 import MessageEvent, Bot
from liteyuki import Channel
from liteyuki.comm import get_channel
from liteyuki.comm.storage import shared_memory
from liteyuki.message.event import MessageEvent as LiteyukiMessageEvent
__plugin_meta__ = PluginMetadata(
name="轻雪物流",
name="轻雪push",
description="把消息事件传递给轻雪框架进行处理",
usage="用户无需使用",
)
recv_channel = Channel[LiteyukiMessageEvent](name="event_to_nonebot")
@on_message().handle()
async def _(bot: Bot, event: MessageEvent):
@ -34,15 +39,17 @@ async def _(bot: Bot, event: MessageEvent):
user_id=str(event.user_id),
session_id=str(event.user_id if event.message_type == "private" else event.group_id),
session_type=event.message_type,
receive_channel="event_to_nonebot"
receive_channel=recv_channel,
)
shared_memory.publish("event_to_liteyuki", liteyuki_event)
@shared_memory.on_subscriber_receive("event_to_nonebot")
async def _(event: LiteyukiMessageEvent):
bot: Bot = get_bot(event.bot_id)
if event.message_type == "private":
await bot.send_private_msg(user_id=int(event.session_id), message=event.data["message"])
elif event.message_type == "group":
await bot.send_group_msg(group_id=int(event.session_id), message=event.data["message"])
@get_driver().on_bot_connect
async def _():
while True:
event = await recv_channel.async_receive()
bot: Bot = get_bot(event.bot_id) # type: ignore
if event.message_type == "private":
await bot.send_private_msg(user_id=int(event.session_id), message=event.data["message"])
elif event.message_type == "group":
await bot.send_group_msg(group_id=int(event.session_id), message=event.data["message"])

35
src/nonebot_plugins/ts_chan_sub.py
View File

@ -1,35 +0,0 @@
# -*- coding: utf-8 -*-
"""
Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
@Time : 2024/8/22 上午8:39
@Author : snowykami
@Email : snowykami@outlook.com
@File : ts_chan_sub.py
@Software: PyCharm
"""
import asyncio
from liteyuki.comm import Channel, get_channel
from nonebot import get_bot
from nonebot.adapters.onebot.v11 import Bot
chan_main = get_channel("chan-main")
# @chan_main.on_receive()
# async def _(data: str):
# print("Received data from chan-main:", data)
# try:
# bot: Bot = get_bot("2443429204") # type: ignore
#
# def send_msg():
#
# bot.send_msg(message_type="private", user_id=2443429204, message=data)
#
# print("tsA")
# print("tsA1")
# await asyncio.ensure_future(c)
# print("tsB")
# except Exception as e:
# print(e)
# pass