ProjectHentai/nonebot2
6
0
Fork 0
mirror of https://github.com/nonebot/nonebot2.git synced 2025-07-26 15:51:26 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

💡 add docstrings

Browse Source
This commit is contained in:
yanyongyu
2022-01-22 15:23:07 +08:00
parent f9674da6ea
commit c4e204001e
22 changed files with 342 additions and 191 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
nonebot/plugin/__init__.py
View File

@ -1,7 +1,37 @@
"""
## 插件
"""本模块为 NoneBot 插件开发提供便携的定义函数。
为 NoneBot 插件开发提供便携的定义函数。
## 快捷导入
为方便使用，本模块从子模块导入了部分内容，以下内容可以直接通过本模块导入:
- `on` => {ref}``on` <nonebot.plugin.on.on>`
- `on_metaevent` => {ref}``on_metaevent` <nonebot.plugin.on.on_metaevent>`
- `on_message` => {ref}``on_message` <nonebot.plugin.on.on_message>`
- `on_notice` => {ref}``on_notice` <nonebot.plugin.on.on_notice>`
- `on_request` => {ref}``on_request` <nonebot.plugin.on.on_request>`
- `on_startswith` => {ref}``on_startswith` <nonebot.plugin.on.on_startswith>`
- `on_endswith` => {ref}``on_endswith` <nonebot.plugin.on.on_endswith>`
- `on_keyword` => {ref}``on_keyword` <nonebot.plugin.on.on_keyword>`
- `on_command` => {ref}``on_command` <nonebot.plugin.on.on_command>`
- `on_shell_command` => {ref}``on_shell_command` <nonebot.plugin.on.on_shell_command>`
- `on_regex` => {ref}``on_regex` <nonebot.plugin.on.on_regex>`
- `CommandGroup` => {ref}``CommandGroup` <nonebot.plugin.on.CommandGroup>`
- `Matchergroup` => {ref}``MatcherGroup` <nonebot.plugin.on.MatcherGroup>`
- `load_plugin` => {ref}``load_plugin` <nonebot.plugin.load.load_plugin>`
- `load_plugins` => {ref}``load_plugins` <nonebot.plugin.load.load_plugins>`
- `load_all_plugins` => {ref}``load_all_plugins` <nonebot.plugin.load.load_all_plugins>`
- `load_from_json` => {ref}``load_from_json` <nonebot.plugin.load.load_from_json>`
- `load_from_toml` => {ref}``load_from_toml` <nonebot.plugin.load.load_from_toml>`
- `load_builtin_plugin` => {ref}``load_builtin_plugin` <nonebot.plugin.load.load_builtin_plugin>`
- `load_builtin_plugins` => {ref}``load_builtin_plugins` <nonebot.plugin.load.load_builtin_plugins>`
- `get_plugin` => {ref}``get_plugin` <nonebot.plugin.plugin.get_plugin>`
- `get_loaded_plugins` => {ref}``get_loaded_plugins` <nonebot.plugin.plugin.get_loaded_plugins>`
- `export` => {ref}``export` <nonebot.plugin.export.export>`
- `require` => {ref}``require` <nonebot.plugin.load.require>`
FrontMatter:
sidebar_position: 0
description: nonebot.plugin 模块
"""
from typing import List, Optional

16
nonebot/plugin/export.py
View File

@ -1,9 +1,17 @@
"""本模块定义了插件导出的内容对象。
在新版插件系统中，推荐优先使用直接 import 所需要的插件内容。
FrontMatter:
sidebar_position: 4
description: nonebot.plugin.export 模块
"""
from . import _current_plugin
class Export(dict):
"""
插件导出内容以使得其他插件可以获得。
"""插件导出内容以使得其他插件可以获得。
用法:
```python
@ -42,9 +50,7 @@ class Export(dict):
def export() -> Export:
"""
获取插件的导出内容对象
"""
"""获取当前插件的导出内容对象"""
plugin = _current_plugin.get()
if not plugin:
raise RuntimeError("Export outside of the plugin!")

68
nonebot/plugin/load.py
View File

@ -1,3 +1,9 @@
"""本模块定义插件加载接口。
FrontMatter:
sidebar_position: 1
description: nonebot.plugin.load 模块
"""
import json
import warnings
from typing import Set, Iterable, Optional
@ -11,8 +17,7 @@ from .plugin import Plugin, get_plugin
def load_plugin(module_path: str) -> Optional[Plugin]:
"""
使用 `PluginManager` 加载单个插件，可以是本地插件或是通过 `pip` 安装的插件。
"""加载单个插件，可以是本地插件或是通过 `pip` 安装的插件。
参数:
module_path: 插件名称 `path.to.your.plugin`
@ -24,11 +29,10 @@ def load_plugin(module_path: str) -> Optional[Plugin]:
def load_plugins(*plugin_dir: str) -> Set[Plugin]:
"""
导入目录下多个插件，以 `_` 开头的插件不会被导入！
"""导入文件夹下多个插件，以 `_` 开头的插件不会被导入!
参数:
plugin_dir: 插件路径
plugin_dir: 文件夹路径
"""
manager = PluginManager(search_path=plugin_dir)
_managers.append(manager)
@ -38,12 +42,11 @@ def load_plugins(*plugin_dir: str) -> Set[Plugin]:
def load_all_plugins(
module_path: Iterable[str], plugin_dir: Iterable[str]
) -> Set[Plugin]:
"""
导入指定列表中的插件以及指定目录下多个插件，以 `_` 开头的插件不会被导入！
"""导入指定列表中的插件以及指定目录下多个插件，以 `_` 开头的插件不会被导入!
参数:
module_path: 指定插件集合
plugin_dir: 指定插件路径集合
plugin_dir: 指定文件夹路径集合
"""
manager = PluginManager(module_path, plugin_dir)
_managers.append(manager)
@ -51,12 +54,23 @@ def load_all_plugins(
def load_from_json(file_path: str, encoding: str = "utf-8") -> Set[Plugin]:
"""
导入指定 json 文件中的 `plugins` 以及 `plugin_dirs` 下多个插件，以 `_` 开头的插件不会被导入！
"""导入指定 json 文件中的 `plugins` 以及 `plugin_dirs` 下多个插件，以 `_` 开头的插件不会被导入!
参数:
file_path: 指定 json 文件路径
encoding: 指定 json 文件编码
用法:
```json title=plugins.json
{
"plugins": ["some_plugin"],
"plugin_dirs": ["some_dir"]
}
```
```python
nonebot.load_from_json("plugins.json")
```
"""
with open(file_path, "r", encoding=encoding) as f:
data = json.load(f)
@ -68,13 +82,22 @@ def load_from_json(file_path: str, encoding: str = "utf-8") -> Set[Plugin]:
def load_from_toml(file_path: str, encoding: str = "utf-8") -> Set[Plugin]:
"""
导入指定 toml 文件 `[tool.nonebot]` 中的 `plugins` 以及 `plugin_dirs` 下多个插件，
以 `_` 开头的插件不会被导入！
"""导入指定 toml 文件 `[tool.nonebot]` 中的 `plugins` 以及 `plugin_dirs` 下多个插件，以 `_` 开头的插件不会被导入!
参数:
file_path: 指定 toml 文件路径
encoding: 指定 toml 文件编码
用法:
```toml title=pyproject.toml
[tool.nonebot]
plugins = ["some_plugin"]
plugin_dirs = ["some_dir"]
```
```python
nonebot.load_from_toml("pyproject.toml")
```
"""
with open(file_path, "r", encoding=encoding) as f:
data = tomlkit.parse(f.read()) # type: ignore
@ -97,25 +120,30 @@ def load_from_toml(file_path: str, encoding: str = "utf-8") -> Set[Plugin]:
def load_builtin_plugin(name: str) -> Optional[Plugin]:
"""
导入 NoneBot 内置插件
"""导入 NoneBot 内置插件。
参数:
name: 插件名称
"""
return load_plugin(f"nonebot.plugins.{name}")
def load_builtin_plugins(*plugins) -> Set[Plugin]:
"""
导入多个 NoneBot 内置插件
"""导入多个 NoneBot 内置插件。
参数:
plugins: 插件名称列表
"""
return load_all_plugins([f"nonebot.plugins.{p}" for p in plugins], [])
def require(name: str) -> Export:
"""
获取一个插件的导出内容
"""获取一个插件的导出内容。
如果为 `load_plugins` 文件夹导入的插件，则为文件(夹)名。
参数:
name: 插件名，与 `load_plugin` 参数一致。如果为 `load_plugins` 导入的插件，则为文件(夹)名。
name: 插件名，即 {ref}`nonebot.plugin.plugin.Plugin.name`。
异常:
RuntimeError: 插件无法加载

8
nonebot/plugin/manager.py
View File

@ -1,3 +1,11 @@
"""本模块实现插件加载流程。
参考: [import hooks](https://docs.python.org/3/reference/import.html#import-hooks), [PEP302](https://www.python.org/dev/peps/pep-0302/)
FrontMatter:
sidebar_position: 5
description: nonebot.plugin.manager 模块
"""
import sys
import pkgutil
import importlib

6
nonebot/plugin/on.py
View File

@ -1,3 +1,9 @@
"""本模块定义事件响应器便携定义函数。
FrontMatter:
sidebar_position: 2
description: nonebot.plugin.on 模块
"""
import re
import sys
import inspect

53
nonebot/plugin/plugin.py
View File

@ -1,3 +1,9 @@
"""本模块定义插件对象。
FrontMatter:
sidebar_position: 3
description: nonebot.plugin.plugin 模块
"""
from types import ModuleType
from dataclasses import field, dataclass
from typing import TYPE_CHECKING, Set, Dict, Type, Optional
@ -10,9 +16,7 @@ if TYPE_CHECKING:
from .manager import PluginManager
plugins: Dict[str, "Plugin"] = {}
"""
已加载的插件
"""
"""已加载的插件"""
@dataclass(eq=False)
@ -20,53 +24,36 @@ class Plugin(object):
"""存储插件信息"""
name: str
"""
插件名称，使用 文件/文件夹 名称作为插件名
"""
"""插件名称，使用 文件/文件夹 名称作为插件名"""
module: ModuleType
"""
插件模块对象
"""
"""插件模块对象"""
module_name: str
"""
点分割模块路径
"""
"""点分割模块路径"""
manager: "PluginManager"
"""
导入该插件的插件管理器
"""
"""导入该插件的插件管理器"""
export: Export = field(default_factory=Export)
"""
插件内定义的导出内容
"""
"""插件内定义的导出内容"""
matcher: Set[Type[Matcher]] = field(default_factory=set)
"""
插件内定义的 `Matcher`
"""
"""插件内定义的 `Matcher`"""
parent_plugin: Optional["Plugin"] = None
"""
父插件
"""
"""父插件"""
sub_plugins: Set["Plugin"] = field(default_factory=set)
"""
子插件集合
"""
"""子插件集合"""
def get_plugin(name: str) -> Optional[Plugin]:
"""
获取当前导入的某个插件。
"""获取已经导入的某个插件。
如果为 `load_plugins` 文件夹导入的插件，则为文件(夹)名。
参数:
name: 插件名，与 `load_plugin` 参数一致。如果为 `load_plugins` 导入的插件，则为文件(夹)名。
name: 插件名，即 {ref}`nonebot.plugin.plugin.Plugin.name`。
"""
return plugins.get(name)
def get_loaded_plugins() -> Set[Plugin]:
"""
获取当前已导入的所有插件。
"""
"""获取当前已导入的所有插件。"""
return set(plugins.values())