mirror of
https://github.com/LiteyukiStudio/nonebot-plugin-marshoai.git
synced 2025-08-02 08:29:51 +00:00
✨ 添加开发文档和 API 文档的初始结构；更新 .gitignore 以排除生成的文档目录
This commit is contained in:
9
docs/zh/dev/api/plugin/index.md
Normal file
9
docs/zh/dev/api/plugin/index.md
Normal file
@ -0,0 +1,9 @@
|
||||
---
|
||||
title: index
|
||||
collapsed: true
|
||||
---
|
||||
# **模块** `nonebot_plugin_marshoai.plugin`
|
||||
|
||||
该功能目前正在开发中，暂时不可用，受影响的文件夹 `plugin`, `plugins`
|
||||
|
||||
|
||||
138
docs/zh/dev/api/plugin/load.md
Normal file
138
docs/zh/dev/api/plugin/load.md
Normal file
@ -0,0 +1,138 @@
|
||||
---
|
||||
title: load
|
||||
---
|
||||
# **模块** `nonebot_plugin_marshoai.plugin.load`
|
||||
|
||||
Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
|
||||
本模块为工具加载模块
|
||||
|
||||
|
||||
---
|
||||
### ***func*** `get_plugin(name: str) -> Plugin | None`
|
||||
|
||||
**说明**: 获取插件对象
|
||||
|
||||
|
||||
**参数**:
|
||||
> - name: 插件名称
|
||||
|
||||
**返回**: Optional[Plugin]: 插件对象
|
||||
|
||||
|
||||
<details>
|
||||
<summary> <b>源代码</b> 或 <a href='https://github.com/LiteyukiStudio/nonebot-plugin-marshoai/tree/main/nonebot_plugin_marshoai/plugin/load.py#L26' target='_blank'>在GitHub上查看</a></summary>
|
||||
|
||||
```python
|
||||
def get_plugin(name: str) -> Plugin | None:
|
||||
return _plugins.get(name)
|
||||
```
|
||||
</details>
|
||||
|
||||
---
|
||||
### ***func*** `get_plugins() -> dict[str, Plugin]`
|
||||
|
||||
**说明**: 获取所有插件
|
||||
|
||||
|
||||
**返回**: dict[str, Plugin]: 插件集合
|
||||
|
||||
|
||||
<details>
|
||||
<summary> <b>源代码</b> 或 <a href='https://github.com/LiteyukiStudio/nonebot-plugin-marshoai/tree/main/nonebot_plugin_marshoai/plugin/load.py#L37' target='_blank'>在GitHub上查看</a></summary>
|
||||
|
||||
```python
|
||||
def get_plugins() -> dict[str, Plugin]:
|
||||
return _plugins
|
||||
```
|
||||
</details>
|
||||
|
||||
---
|
||||
### ***func*** `load_plugin(module_path: str | Path) -> Optional[Plugin]`
|
||||
|
||||
**说明**: 加载单个插件，可以是本地插件或是通过 `pip` 安装的插件。
|
||||
该函数产生的副作用在于将插件加载到 `_plugins` 中。
|
||||
|
||||
|
||||
**参数**:
|
||||
> - module_path: 插件名称 `path.to.your.plugin`
|
||||
> - 或插件路径 `pathlib.Path(path/to/your/plugin)`:
|
||||
|
||||
**返回**: Optional[Plugin]: 插件对象
|
||||
|
||||
|
||||
<details>
|
||||
<summary> <b>源代码</b> 或 <a href='https://github.com/LiteyukiStudio/nonebot-plugin-marshoai/tree/main/nonebot_plugin_marshoai/plugin/load.py#L46' target='_blank'>在GitHub上查看</a></summary>
|
||||
|
||||
```python
|
||||
def load_plugin(module_path: str | Path) -> Optional[Plugin]:
|
||||
module_path = path_to_module_name(Path(module_path)) if isinstance(module_path, Path) else module_path
|
||||
try:
|
||||
module = import_module(module_path)
|
||||
plugin = Plugin(name=module.__name__, module=module, module_name=module_path)
|
||||
_plugins[plugin.name] = plugin
|
||||
plugin.metadata = getattr(module, '__marsho_meta__', None)
|
||||
if plugin.metadata is None:
|
||||
logger.opt(colors=True).warning(f'成功加载小棉插件 <y>{plugin.name}</y>, 但是没有定义元数据')
|
||||
else:
|
||||
logger.opt(colors=True).success(f'成功加载小棉插件 <c>"{plugin.metadata.name}"</c>')
|
||||
return plugin
|
||||
except Exception as e:
|
||||
logger.opt(colors=True).success(f'加载小棉插件失败 "<r>{module_path}</r>"')
|
||||
traceback.print_exc()
|
||||
return None
|
||||
```
|
||||
</details>
|
||||
|
||||
---
|
||||
### ***func*** `load_plugins(*plugin_dirs: str) -> set[Plugin]`
|
||||
|
||||
**说明**: 导入文件夹下多个插件
|
||||
|
||||
|
||||
**参数**:
|
||||
> - plugin_dir: 文件夹路径
|
||||
> - ignore_warning: 是否忽略警告，通常是目录不存在或目录为空
|
||||
|
||||
**返回**: set[Plugin]: 插件集合
|
||||
|
||||
|
||||
<details>
|
||||
<summary> <b>源代码</b> 或 <a href='https://github.com/LiteyukiStudio/nonebot-plugin-marshoai/tree/main/nonebot_plugin_marshoai/plugin/load.py#L89' target='_blank'>在GitHub上查看</a></summary>
|
||||
|
||||
```python
|
||||
def load_plugins(*plugin_dirs: str) -> set[Plugin]:
|
||||
plugins = set()
|
||||
for plugin_dir in plugin_dirs:
|
||||
for f in os.listdir(plugin_dir):
|
||||
path = Path(os.path.join(plugin_dir, f))
|
||||
module_name = None
|
||||
if os.path.isfile(path) and f.endswith('.py'):
|
||||
'单文件加载'
|
||||
module_name = f'{path_to_module_name(Path(plugin_dir))}.{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 and (plugin := load_plugin(module_name)):
|
||||
plugins.add(plugin)
|
||||
return plugins
|
||||
```
|
||||
</details>
|
||||
|
||||
### var `module`
|
||||
|
||||
- **说明**: 导入模块对象
|
||||
|
||||
- **默认值**: `import_module(module_path)`
|
||||
|
||||
### var `module_name`
|
||||
|
||||
- **说明**: 单文件加载
|
||||
|
||||
- **默认值**: `f'{path_to_module_name(Path(plugin_dir))}.{f[:-3]}'`
|
||||
|
||||
### var `module_name`
|
||||
|
||||
- **说明**: 包加载
|
||||
|
||||
- **默认值**: `path_to_module_name(path)`
|
||||
|
||||
113
docs/zh/dev/api/plugin/models.md
Normal file
113
docs/zh/dev/api/plugin/models.md
Normal file
@ -0,0 +1,113 @@
|
||||
---
|
||||
title: models
|
||||
---
|
||||
# **模块** `nonebot_plugin_marshoai.plugin.models`
|
||||
|
||||
### ***class*** `PluginMetadata(BaseModel)`
|
||||
#### ***attr*** `name: str = NO_DEFAULT`
|
||||
|
||||
#### ***attr*** `description: str = ''`
|
||||
|
||||
#### ***attr*** `usage: str = ''`
|
||||
|
||||
#### ***attr*** `author: str = ''`
|
||||
|
||||
#### ***attr*** `homepage: str = ''`
|
||||
|
||||
#### ***attr*** `extra: dict[str, Any] = {}`
|
||||
|
||||
### ***class*** `Plugin(BaseModel)`
|
||||
---
|
||||
#### ***func*** `hash self => int`
|
||||
|
||||
|
||||
<details>
|
||||
<summary> <b>源代码</b> 或 <a href='https://github.com/LiteyukiStudio/nonebot-plugin-marshoai/tree/main/nonebot_plugin_marshoai/plugin/models.py#L67' target='_blank'>在GitHub上查看</a></summary>
|
||||
|
||||
```python
|
||||
def __hash__(self) -> int:
|
||||
return hash(self.name)
|
||||
```
|
||||
</details>
|
||||
|
||||
---
|
||||
#### ***func*** `self == other: Any => bool`
|
||||
|
||||
|
||||
<details>
|
||||
<summary> <b>源代码</b> 或 <a href='https://github.com/LiteyukiStudio/nonebot-plugin-marshoai/tree/main/nonebot_plugin_marshoai/plugin/models.py#L70' target='_blank'>在GitHub上查看</a></summary>
|
||||
|
||||
```python
|
||||
def __eq__(self, other: Any) -> bool:
|
||||
return self.name == other.name
|
||||
```
|
||||
</details>
|
||||
|
||||
#### ***attr*** `name: str = NO_DEFAULT`
|
||||
|
||||
#### ***attr*** `module: ModuleType = NO_DEFAULT`
|
||||
|
||||
#### ***attr*** `module_name: str = NO_DEFAULT`
|
||||
|
||||
#### ***attr*** `metadata: PluginMetadata | None = None`
|
||||
|
||||
### ***class*** `FunctionCallArgument(BaseModel)`
|
||||
---
|
||||
#### ***func*** `data(self) -> dict[str, Any]`
|
||||
|
||||
|
||||
<details>
|
||||
<summary> <b>源代码</b> 或 <a href='https://github.com/LiteyukiStudio/nonebot-plugin-marshoai/tree/main/nonebot_plugin_marshoai/plugin/models.py#L95' target='_blank'>在GitHub上查看</a></summary>
|
||||
|
||||
```python
|
||||
def data(self) -> dict[str, Any]:
|
||||
return {'type': self.type_, 'description': self.description}
|
||||
```
|
||||
</details>
|
||||
|
||||
#### ***attr*** `type_: str = NO_DEFAULT`
|
||||
|
||||
#### ***attr*** `description: str = NO_DEFAULT`
|
||||
|
||||
#### ***attr*** `default: Any = None`
|
||||
|
||||
### ***class*** `FunctionCall(BaseModel)`
|
||||
---
|
||||
#### ***func*** `hash self => int`
|
||||
|
||||
|
||||
<details>
|
||||
<summary> <b>源代码</b> 或 <a href='https://github.com/LiteyukiStudio/nonebot-plugin-marshoai/tree/main/nonebot_plugin_marshoai/plugin/models.py#L123' target='_blank'>在GitHub上查看</a></summary>
|
||||
|
||||
```python
|
||||
def __hash__(self) -> int:
|
||||
return hash(self.name)
|
||||
```
|
||||
</details>
|
||||
|
||||
---
|
||||
#### ***func*** `data(self) -> dict[str, Any]`
|
||||
|
||||
**说明**: 生成函数描述信息
|
||||
|
||||
|
||||
**返回**: dict[str, Any]: 函数描述信息 字典
|
||||
|
||||
|
||||
<details>
|
||||
<summary> <b>源代码</b> 或 <a href='https://github.com/LiteyukiStudio/nonebot-plugin-marshoai/tree/main/nonebot_plugin_marshoai/plugin/models.py#L126' target='_blank'>在GitHub上查看</a></summary>
|
||||
|
||||
```python
|
||||
def data(self) -> dict[str, Any]:
|
||||
return {'type': 'function', 'function': {'name': self.name, 'description': self.description, 'parameters': {'type': 'object', 'properties': {k: v.data() for k, v in self.arguments.items()}}, 'required': [k for k, v in self.arguments.items() if v.default is None]}}
|
||||
```
|
||||
</details>
|
||||
|
||||
#### ***attr*** `name: str = NO_DEFAULT`
|
||||
|
||||
#### ***attr*** `description: str = NO_DEFAULT`
|
||||
|
||||
#### ***attr*** `arguments: dict[str, FunctionCallArgument] = NO_DEFAULT`
|
||||
|
||||
#### ***attr*** `function: ASYNC_FUNCTION_CALL_FUNC = NO_DEFAULT`
|
||||
|
||||
75
docs/zh/dev/api/plugin/register.md
Normal file
75
docs/zh/dev/api/plugin/register.md
Normal file
@ -0,0 +1,75 @@
|
||||
---
|
||||
title: register
|
||||
---
|
||||
# **模块** `nonebot_plugin_marshoai.plugin.register`
|
||||
|
||||
此模块用于获取function call中函数定义信息以及注册函数
|
||||
|
||||
|
||||
---
|
||||
### ***func*** `async_wrapper(func: SYNC_FUNCTION_CALL_FUNC) -> ASYNC_FUNCTION_CALL_FUNC`
|
||||
|
||||
**说明**: 将同步函数包装为异步函数，但是不会真正异步执行，仅用于统一调用及函数签名
|
||||
|
||||
|
||||
**参数**:
|
||||
> - func: 同步函数
|
||||
|
||||
**返回**: ASYNC_FUNCTION_CALL: 异步函数
|
||||
|
||||
|
||||
<details>
|
||||
<summary> <b>源代码</b> 或 <a href='https://github.com/LiteyukiStudio/nonebot-plugin-marshoai/tree/main/nonebot_plugin_marshoai/plugin/register.py#L20' target='_blank'>在GitHub上查看</a></summary>
|
||||
|
||||
```python
|
||||
def async_wrapper(func: SYNC_FUNCTION_CALL_FUNC) -> ASYNC_FUNCTION_CALL_FUNC:
|
||||
|
||||
async def wrapper(*args, **kwargs) -> str:
|
||||
return func(*args, **kwargs)
|
||||
return wrapper
|
||||
```
|
||||
</details>
|
||||
|
||||
---
|
||||
### ***func*** `function_call(*funcs: FUNCTION_CALL_FUNC) -> None`
|
||||
|
||||
|
||||
**参数**:
|
||||
> - func: 函数对象，要有完整的 Google Style Docstring
|
||||
|
||||
**返回**: str: 函数定义信息
|
||||
|
||||
|
||||
<details>
|
||||
<summary> <b>源代码</b> 或 <a href='https://github.com/LiteyukiStudio/nonebot-plugin-marshoai/tree/main/nonebot_plugin_marshoai/plugin/register.py#L36' target='_blank'>在GitHub上查看</a></summary>
|
||||
|
||||
```python
|
||||
def function_call(*funcs: FUNCTION_CALL_FUNC) -> None:
|
||||
for func in funcs:
|
||||
function_call = get_function_info(func)
|
||||
```
|
||||
</details>
|
||||
|
||||
---
|
||||
### ***func*** `get_function_info(func: FUNCTION_CALL_FUNC)`
|
||||
|
||||
**说明**: 获取函数信息
|
||||
|
||||
|
||||
**参数**:
|
||||
> - func: 函数对象
|
||||
|
||||
**返回**: FunctionCall: 函数信息对象模型
|
||||
|
||||
|
||||
<details>
|
||||
<summary> <b>源代码</b> 或 <a href='https://github.com/LiteyukiStudio/nonebot-plugin-marshoai/tree/main/nonebot_plugin_marshoai/plugin/register.py#L50' target='_blank'>在GitHub上查看</a></summary>
|
||||
|
||||
```python
|
||||
def get_function_info(func: FUNCTION_CALL_FUNC):
|
||||
name = func.__name__
|
||||
description = func.__doc__
|
||||
logger.info(f'注册函数: {name} {description}')
|
||||
```
|
||||
</details>
|
||||
|
||||
5
docs/zh/dev/api/plugin/typing.md
Normal file
5
docs/zh/dev/api/plugin/typing.md
Normal file
@ -0,0 +1,5 @@
|
||||
---
|
||||
title: typing
|
||||
---
|
||||
# **模块** `nonebot_plugin_marshoai.plugin.typing`
|
||||
|
||||
54
docs/zh/dev/api/plugin/utils.md
Normal file
54
docs/zh/dev/api/plugin/utils.md
Normal file
@ -0,0 +1,54 @@
|
||||
---
|
||||
title: utils
|
||||
---
|
||||
# **模块** `nonebot_plugin_marshoai.plugin.utils`
|
||||
|
||||
---
|
||||
### ***func*** `path_to_module_name(path: Path) -> str`
|
||||
|
||||
**说明**: 转换路径为模块名
|
||||
|
||||
**参数**:
|
||||
> - path: 路径a/b/c/d -> a.b.c.d
|
||||
|
||||
**返回**: str: 模块名
|
||||
|
||||
|
||||
<details>
|
||||
<summary> <b>源代码</b> 或 <a href='https://github.com/LiteyukiStudio/nonebot-plugin-marshoai/tree/main/nonebot_plugin_marshoai/plugin/utils.py#L6' target='_blank'>在GitHub上查看</a></summary>
|
||||
|
||||
```python
|
||||
def path_to_module_name(path: Path) -> 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>
|
||||
|
||||
---
|
||||
### ***func*** `is_coroutine_callable(call: Callable[..., Any]) -> bool`
|
||||
|
||||
**说明**: 判断是否为async def 函数
|
||||
|
||||
**参数**:
|
||||
> - call: 可调用对象
|
||||
|
||||
**返回**: bool: 是否为协程可调用对象
|
||||
|
||||
|
||||
<details>
|
||||
<summary> <b>源代码</b> 或 <a href='https://github.com/LiteyukiStudio/nonebot-plugin-marshoai/tree/main/nonebot_plugin_marshoai/plugin/utils.py#L21' target='_blank'>在GitHub上查看</a></summary>
|
||||
|
||||
```python
|
||||
def is_coroutine_callable(call: Callable[..., Any]) -> 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>
|
||||
|
||||
Reference in New Issue
Block a user