From 6dad545a3860f799439ebc5a228e62ff7c29c99b Mon Sep 17 00:00:00 2001 From: Richard Chien Date: Sat, 22 Dec 2018 23:07:48 +0800 Subject: [PATCH] Update docs --- docs/api.md | 111 ++++++++++++++++++++++++++++++++-------------- docs/changelog.md | 3 ++ 2 files changed, 80 insertions(+), 34 deletions(-) diff --git a/docs/api.md b/docs/api.md index c86c4261..dbfeadd2 100644 --- a/docs/api.md +++ b/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` 模块 diff --git a/docs/changelog.md b/docs/changelog.md index 7da91195..8ff01723 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -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