mirror of
https://github.com/nonebot/nonebot2.git
synced 2024-11-24 00:55:07 +08:00
Update docs
This commit is contained in:
Richard Chien
parent
f669558050
commit
6dad545a38
111
docs/api.md
111
docs/api.md
@ -983,7 +983,7 @@ sidebar: auto
|
||||
|
||||
## `none.command` 模块
|
||||
|
||||
### _decorator_ `on_command(name, *, aliases=(), permission=perm.EVERYBODY, only_to_me=True, privileged=False)`
|
||||
### _decorator_ `on_command(name, *, aliases=(), permission=perm.EVERYBODY, only_to_me=True, privileged=False, shell_like=False )`
|
||||
|
||||
- **说明:**
|
||||
|
||||
@ -998,6 +998,7 @@ sidebar: auto
|
||||
- `permission: int`: 命令所需要的权限，不满足权限的用户将无法触发该命令
|
||||
- `only_to_me: bool`: 是否只响应确定是在和「我」（机器人）说话的命令
|
||||
- `privileged: bool`: 是否特权命令，若是，则无论当前是否有命令会话正在运行，都会运行该命令，但运行不会覆盖已有会话，也不会保留新创建的会话
|
||||
- `shell_like: bool`: 是否使用类 shell 语法，若是，则会自动使用 `shlex` 模块进行分割（无需手动编写参数解析器），分割后的参数列表放入 `session.args['argv']`
|
||||
|
||||
- **要求:**
|
||||
|
||||
@ -1024,6 +1025,8 @@ sidebar: auto
|
||||
|
||||
将函数装饰为命令参数解析器。
|
||||
|
||||
如果已经在 `on_command` 装饰器中使用了 `shell_like=True`，则无需手动使用编写参数解析器。
|
||||
|
||||
- **要求:**
|
||||
|
||||
对被装饰函数的要求同 `on_command` 装饰器。
|
||||
@ -1077,7 +1080,15 @@ sidebar: auto
|
||||
|
||||
命令组内命令的默认 `privileged` 属性。
|
||||
|
||||
#### `__init__(name, permission=None, *, only_to_me=None, privileged=None)`
|
||||
#### `shell_like`
|
||||
|
||||
- **类型:** `Optional[bool]`
|
||||
|
||||
- **说明:**
|
||||
|
||||
命令组内命令的默认 `shell_like` 属性。
|
||||
|
||||
#### `__init__(name, permission=None, *, only_to_me=None, privileged=None, shell_like=None)`
|
||||
|
||||
- **说明:**
|
||||
|
||||
@ -1089,8 +1100,9 @@ sidebar: auto
|
||||
- `permission: Optional[int]`: 对应 `permission` 属性
|
||||
- `only_to_me: Optional[bool]`: 对应 `only_to_me` 属性
|
||||
- `privileged: Optional[bool]`: 对应 `privileged` 属性
|
||||
- `shell_like: Optional[bool]`: 对应 `shell_like` 属性
|
||||
|
||||
#### _decorator_ `command(name, *, aliases=None, permission=None, only_to_me=None, privileged=None)`
|
||||
#### _decorator_ `command(name, *, aliases=None, permission=None, only_to_me=None, privileged=None, shell_like=None)`
|
||||
|
||||
- **说明:**
|
||||
|
||||
@ -1103,6 +1115,7 @@ sidebar: auto
|
||||
- `permission: Optional[int]`: 同上
|
||||
- `only_to_me: Optional[bool]`: 同上
|
||||
- `privileged: Optional[bool]`: 同上
|
||||
- `shell_like: Optional[bool]`: 同上
|
||||
|
||||
- **用法:**
|
||||
|
||||
@ -1160,7 +1173,7 @@ sidebar: auto
|
||||
|
||||
命令会话已获得的所有参数。
|
||||
|
||||
#### _property_ `is_first_run`
|
||||
#### _readonly property_ `is_first_run`
|
||||
|
||||
- **类型:** `bool`
|
||||
|
||||
@ -1168,6 +1181,22 @@ sidebar: auto
|
||||
|
||||
命令会话是否第一次运行。
|
||||
|
||||
#### _readonly property_ `argv`
|
||||
|
||||
- **类型:** `List[str]`
|
||||
|
||||
- **说明:**
|
||||
|
||||
命令参数列表，本质上是 `session.get_optional('argv', [])`，通常搭配 `on_command(..., shell_like=True)` 使用。
|
||||
|
||||
- **用法:**
|
||||
|
||||
```python
|
||||
@on_command('some_cmd', shell_like=True)
|
||||
async def _(session: CommandSession):
|
||||
argv = session.argv
|
||||
```
|
||||
|
||||
#### `get(key, *, prompt=None)`
|
||||
|
||||
- **说明:**
|
||||
@ -1774,52 +1803,66 @@ async def _(session):
|
||||
|
||||
### _class_ `ArgumentParser`
|
||||
|
||||
继承自 `argparse.ArgumentParser` 类，修改部分函数实现使其不再打印文本到标准输出、并且不再在参数错误时直接退出程序。
|
||||
继承自 `argparse.ArgumentParser` 类，修改部分函数实现使其适用于命令型聊天机器人。
|
||||
|
||||
此类可用于命令参数的解析。基本用法和 Python 内置的 `argparse.ArgumentParser` 类一致，区别是当它需要导致程序退出时，行为改变为抛出 `none.argparse.ParserExit` 异常。
|
||||
此类可用于命令参数的解析。基本用法和 Python 内置的 `argparse.ArgumentParser` 类一致，下面主要列出与 Python 原生含义和行为不同的属性和方法。
|
||||
|
||||
- **用法:**
|
||||
|
||||
```python
|
||||
parser = ArgumentParser()
|
||||
parser.add_argument('-S', '--second')
|
||||
parser.add_argument('-M', '--minute')
|
||||
parser.add_argument('-H', '--hour')
|
||||
parser.add_argument('-d', '--day')
|
||||
parser.add_argument('-m', '--month')
|
||||
parser.add_argument('-w', '--day-of-week')
|
||||
parser.add_argument('-f', '--force', action='store_true', default=False)
|
||||
parser.add_argument('-v', '--verbose', action='store_true', default=False)
|
||||
parser.add_argument('--name', required=True)
|
||||
parser.add_argument('commands', nargs='+')
|
||||
USAGE = r"""
|
||||
创建计划任务
|
||||
|
||||
argv = ['-S', '*/10', '-v', '--force', '--name', 'test', 'echo wow']
|
||||
使用方法：
|
||||
XXXXXX
|
||||
""".strip()
|
||||
|
||||
try:
|
||||
return parser.parse_args(argv)
|
||||
except ParserExit as e:
|
||||
if e.status == 0:
|
||||
# --help
|
||||
await session.send(help_msg)
|
||||
else:
|
||||
await session.send('参数不足或不正确，请使用 --help 参数查询使用帮助')
|
||||
@on_command('schedule', shell_like=True)
|
||||
async def _(session: CommandSession):
|
||||
parser = ArgumentParser(session=session, usage=USAGE)
|
||||
parser.add_argument('-S', '--second')
|
||||
parser.add_argument('-M', '--minute')
|
||||
parser.add_argument('-H', '--hour')
|
||||
parser.add_argument('-d', '--day')
|
||||
parser.add_argument('-m', '--month')
|
||||
parser.add_argument('-w', '--day-of-week')
|
||||
parser.add_argument('-f', '--force', action='store_true', default=False)
|
||||
parser.add_argument('-v', '--verbose', action='store_true', default=False)
|
||||
parser.add_argument('--name', required=True)
|
||||
parser.add_argument('commands', nargs='+')
|
||||
|
||||
args = parser.parse_args(session.argv)
|
||||
name = args.name
|
||||
# ...
|
||||
```
|
||||
|
||||
### _class_ `ParserExit`
|
||||
|
||||
继承自 `RuntimeError` 类，在 `ArgumentParser` 解析出错时抛出。
|
||||
|
||||
#### `status`
|
||||
#### `__init__(session=None, usage=None, **kwargs)`
|
||||
|
||||
- **说明:**
|
||||
|
||||
`argparse.ArgumentParser` 类的 `exit()` 方法的 `status` 参数。
|
||||
初始化 `ArgumentParser` 对象。
|
||||
|
||||
#### `message`
|
||||
- **参数:**
|
||||
|
||||
- `session: CommandSession`: 当前需要解析参数的命令会话，用于解析失败或遇到 `--help` 时发送提示消息
|
||||
- `usage: str`: 命令的使用帮助，在参数为空或遇到 `--help` 时发送
|
||||
- `**kwargs: Any`: 和 Python `argparse.ArgumentParser` 类一致
|
||||
|
||||
#### `parse_args(args=None, namespace=None)`
|
||||
|
||||
- **说明:**
|
||||
|
||||
`argparse.ArgumentParser` 类的 `exit()` 方法的 `message` 参数。
|
||||
解析参数。
|
||||
|
||||
Python 原生的「打印到控制台」行为变为「发送消息到用户」，「退出程序」变为「结束当前命令会话」。
|
||||
|
||||
- **参数:**
|
||||
|
||||
和 Python `argparse.ArgumentParser` 类一致。
|
||||
|
||||
- **异常:**
|
||||
|
||||
无。
|
||||
|
||||
## `none.sched` 模块
|
||||
|
||||
|
||||
@ -8,6 +8,9 @@ sidebar: auto
|
||||
|
||||
- 修复调用不存在的多级命令（例如 `/echo/nonexist`）时，抛出异常导致 WebSocket 连接断开的问题
|
||||
- 调整 Expression 相关接口：移除了所有 `send_expr()` 函数和方法，移除了 `CommandSession.get()` 方法的 `prompt_expr` 参数，移除了 `none.expression` 模块，原 `render()` 函数移动到 `none.helpers` 模块并改名为 `render_expression()`
|
||||
- 修改 `none.argparse.ArgumentParser` 类的构造方法和 `parse_args()` 方法：构造方法新增 `session` 参数，可传入 `CommandSession` 对象；`parse_args()` 方法可直接用于解析参数，用户输入的参数错误，会发送错误提示或使用帮助
|
||||
- `on_command` 装饰器新增 `shell_like` 参数，设为 `True`（默认 `False`）将自动以类 shell 语法分割命令参数 `current_arg`（不再需要自行编写 args parser），并将分割后的参数列表放入 `session.args['argv']`
|
||||
- `CommandSession` 类新增 `argv` 只读属性，用于获取 `session.args['argv']`，如不存在，则返回空列表
|
||||
|
||||
## v0.4.3
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user