⬆️ auto update by pre-commit hooks (#4181)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

website/versioned_docs/version-2.4.3/best-practice/alconna/command.md

@@ -20,7 +20,7 @@ alc = Alconna(
         Args["package", str],
         Option("-r|--requirement", Args["file", str]),
         Option("-i|--index-url", Args["url", str]),
-    )
+    ),
 )
 
 res = alc.parse("pip install nonebot2 -i URL")
@@ -113,8 +113,8 @@ from arclet.alconna import Alconna, Args
 
 
 alc = Alconna("test", Args["foo", str])
-alc.parse("test --foo abc") # 错误
-alc.parse("test abc") # 正确
+alc.parse("test --foo abc")  # 错误
+alc.parse("test abc")  # 正确
 ```
 
 若需要 `test --foo abc`，你应该使用 `Option`：
@@ -383,20 +383,33 @@ alc = Alconna(..., meta=CommandMeta("foo", example="bar"))
 from arclet.alconna import Alconna, namespace, Namespace, Subcommand, Args, config
 
 
-ns = Namespace("foo", prefixes=["/"])  # 创建 "foo"命名空间配置, 它要求创建的Alconna的主命令前缀必须是/
+ns = Namespace(
+    "foo", prefixes=["/"]
+)  # 创建 "foo"命名空间配置, 它要求创建的Alconna的主命令前缀必须是/
 
-alc = Alconna("pip", Subcommand("install", Args["package", str]), namespace=ns) # 在创建Alconna时候传入命名空间以替换默认命名空间
+alc = Alconna(
+    "pip", Subcommand("install", Args["package", str]), namespace=ns
+)  # 在创建Alconna时候传入命名空间以替换默认命名空间
 
 # 可以通过with方式创建命名空间
 with namespace("bar") as np1:
-    np1.prefixes = ["!"]    # 以上下文管理器方式配置命名空间，此时配置会自动注入上下文内创建的命令
+    np1.prefixes = [
+        "!"
+    ]  # 以上下文管理器方式配置命名空间，此时配置会自动注入上下文内创建的命令
     np1.formatter_type = ShellTextFormatter  # 设置此命名空间下的命令的 formatter 默认为 ShellTextFormatter
-    np1.builtin_option_name["help"] = {"帮助", "-h"}  # 设置此命名空间下的命令的帮助选项名称
+    np1.builtin_option_name["help"] = {
+        "帮助",
+        "-h",
+    }  # 设置此命名空间下的命令的帮助选项名称
 
 # 你还可以使用config来管理所有命名空间并切换至任意命名空间
 config.namespaces["foo"] = ns  # 将命名空间挂载到 config 上
 
-alc = Alconna("pip", Subcommand("install", Args["package", str]), namespace=config.namespaces["foo"]) # 也是同样可以切换到"foo"命名空间
+alc = Alconna(
+    "pip",
+    Subcommand("install", Args["package", str]),
+    namespace=config.namespaces["foo"],
+)  # 也是同样可以切换到"foo"命名空间
 ```
 
 ### 修改默认的命名空间
@@ -466,13 +479,15 @@ alc = Alconna("eval", Args["content", str])
 alc.shortcut("echo", {"command": "eval print(\\'{*}\\')"})
 # 'Alconna::eval 的快捷指令: "echo" 添加成功'
 
-alc.shortcut("echo", delete=True) # 删除快捷指令
+alc.shortcut("echo", delete=True)  # 删除快捷指令
 # 'Alconna::eval 的快捷指令: "echo" 删除成功'
 
-@alc.bind() # 绑定一个命令执行器, 若匹配成功则会传入参数, 自动执行命令执行器
+
+@alc.bind()  # 绑定一个命令执行器, 若匹配成功则会传入参数, 自动执行命令执行器
 def cb(content: str):
     eval(content, {}, {})
 
+
 alc.parse('eval print(\\"hello world\\")')
 # hello world
 
@@ -523,7 +538,12 @@ alc.parse("eval --shortcut list")
 from arclet.alconna import Alconna, Option, CommandMeta, Args
 
 
-alc = Alconna("test", Args["foo", int], Option("BAR", Args["baz", str], compact=True), meta=CommandMeta(compact=True))
+alc = Alconna(
+    "test",
+    Args["foo", int],
+    Option("BAR", Args["baz", str], compact=True),
+    meta=CommandMeta(compact=True),
+)
 
 assert alc.parse("test123 BARabc").matched
 ```
@@ -534,7 +554,9 @@ assert alc.parse("test123 BARabc").matched
 from arclet.alconna import Alconna, Option, Args, append
 
 
-alc = Alconna("gcc", Option("--flag|-F", Args["content", str], action=append, compact=True))
+alc = Alconna(
+    "gcc", Option("--flag|-F", Args["content", str], action=append, compact=True)
+)
 print(alc.parse("gcc -Fabc -Fdef -Fxyz").query[list]("flag.content"))
 # ['abc', 'def', 'xyz']
 ```
@@ -577,7 +599,7 @@ from arclet.alconna import Alconna, Args, Option
 alc = Alconna("test", Args["abc", int]) + Option("foo") + Option("bar")
 alc.parse("test --comp")
 
-'''
+"""
 output
 
 以下是建议的输入：
@@ -588,7 +610,7 @@ output
 * --shortcut
 * foo
 * bar
-'''
+"""
 ```
 
 ## Duplication
@@ -600,7 +622,16 @@ output
 以pip为例，其对应的 Duplication 应如下构造:
 
 ```python
-from arclet.alconna import Alconna, Args, Option, OptionResult, Duplication, SubcommandStub, Subcommand, count
+from arclet.alconna import (
+    Alconna,
+    Args,
+    Option,
+    OptionResult,
+    Duplication,
+    SubcommandStub,
+    Subcommand,
+    count,
+)
 
 
 class MyDup(Duplication):
@@ -620,7 +651,7 @@ alc = Alconna(
     Option("-v|--verbose", action=count),
 )
 
-res = alc.parse("pip -v install ...") # 不使用duplication获得的提示较少
+res = alc.parse("pip -v install ...")  # 不使用duplication获得的提示较少
 print(res.query("install"))
 # (value=Ellipsis args={'package': '...'} options={} subcommands={})
 

website/versioned_docs/version-2.4.3/best-practice/alconna/shortcut.md

@@ -29,10 +29,10 @@ from nonebot_plugin_alconna import on_alconna, AlconnaMatch, Match
 
 echo = on_alconna(Alconna("echo", Args["msg", str]))
 
+
 @echo.handle()
 async def echo_exit(msg: Match[str] = AlconnaMatch("msg")):
     await echo.finish(msg.result)
-
 ```
 
 相比于 `on_alconna`， `funcommand` 增加了三个参数 `name`, `prefixes` 和 `description`。
@@ -54,6 +54,7 @@ book = (
     .build()
 )
 
+
 @book.handle()
 async def _(arp: Arparma):
     await book.send(str(arp.options))

website/versioned_docs/version-2.4.3/best-practice/alconna/uniseg/README.md

@@ -45,14 +45,11 @@ message = UniMessage(
 ```python
 from nonebot_plugin_alconna import Button, UniMessage
 
-message = (
-    UniMessage.text("hello world")
-    .keyboard(
-        Button("link1", url="https://example.com/1"),
-        Button("link2", url="https://example.com/2"),
-        Button("link3", url="https://example.com/3"),
-        row=3,
-    )
+message = UniMessage.text("hello world").keyboard(
+    Button("link1", url="https://example.com/1"),
+    Button("link2", url="https://example.com/2"),
+    Button("link3", url="https://example.com/3"),
+    row=3,
 )
 ```
 
@@ -94,6 +91,7 @@ async def _():
 ```python
 from nonebot_plugin_alconna import message_recall, message_edit, message_reaction
 
+
 @matcher.handle()
 async def _():
     await message_edit(UniMessage.text("hello world"))
@@ -120,9 +118,9 @@ async def _():
 ```python
 from nonebot_plugin_alconna import UniMsg
 
+
 @matcher.handle()
-async def _(msg: UniMsg):
-    ...
+async def _(msg: UniMsg): ...
 ```
 
 然后你可以通过 `UniMessage` 的方法来处理消息.
@@ -182,6 +180,7 @@ async def _(msg: UniMsg):
 ```python
 from nonebot_plugin_alconna import UniMsg
 
+
 @matcher.handle()
 async def _(msg: UniMsg):
     data: list[dict] = msg.dump()
@@ -193,6 +192,7 @@ async def _(msg: UniMsg):
 ```python
 from nonebot_plugin_alconna import UniMessage
 
+
 @matcher.handle()
 async def _():
     data = [

website/versioned_docs/version-2.4.3/best-practice/alconna/uniseg/segment.md

@@ -12,9 +12,9 @@ from nonebot_plugin_alconna import Alconna, Args, Image, on_alconna
 
 meme = on_alconna(Alconna("make_meme", Args["name", str]["img", Image]))
 
+
 @meme.handle()
-async def _(img: Image):
-    ...
+async def _(img: Image): ...
 ```
 
 ## 模型定义
@@ -24,6 +24,7 @@ async def _(img: Image):
 ```python
 class Segment:
     """基类标注"""
+
     @property
     def type(self) -> str: ...
     @property
@@ -31,29 +32,40 @@ class Segment:
     @property
     def children(self) -> list["Segment"]: ...
 
+
 class Text(Segment):
     """Text对象, 表示一类文本元素"""
+
     text: str
     styles: dict[tuple[int, int], list[str]]
 
     def cover(self, text: str): ...
-    def mark(self, start: Optional[int] = None, end: Optional[int] = None, *styles: str): ...
+    def mark(
+        self, start: Optional[int] = None, end: Optional[int] = None, *styles: str
+    ): ...
+
 
 class At(Segment):
     """At对象, 表示一类提醒某用户的元素"""
+
     flag: Literal["user", "role", "channel"]
     target: str
     display: Optional[str]
 
+
 class AtAll(Segment):
     """AtAll对象, 表示一类提醒所有人的元素"""
+
     here: bool
 
+
 class Emoji(Segment):
     """Emoji对象, 表示一类表情元素"""
+
     id: str
     name: Optional[str]
 
+
 class Media(Segment):
     id: Optional[str]
     url: Optional[str]
@@ -64,53 +76,72 @@ class Media(Segment):
 
     to_url: ClassVar[Optional[MediaToUrl]]
 
+
 class Image(Media):
     """Image对象, 表示一类图片元素"""
+
     width: Optional[int]
     height: Optional[int]
 
+
 class Audio(Media):
     """Audio对象, 表示一类音频元素"""
+
     duration: Optional[float]
 
+
 class Voice(Media):
     """Voice对象, 表示一类语音元素"""
+
     duration: Optional[float]
 
+
 class Video(Media):
     """Video对象, 表示一类视频元素"""
+
     thumbnail: Optional[Image]
     duration: Optional[float]
 
+
 class File(Media):
     """File对象, 表示一类文件元素"""
 
+
 class Reply(Segment):
     """Reply对象，表示一类回复消息"""
+
     id: str
     """此处不一定是消息ID，可能是其他ID，如消息序号等"""
     msg: Optional[Union[Message, str]]
     origin: Optional[Any]
 
+
 class Reference(Segment):
     """Reference对象，表示一类引用消息。转发消息 (Forward) 也属于此类"""
+
     id: Optional[str]
     """此处不一定是消息ID，可能是其他ID，如消息序号等"""
     children: List[Union[RefNode, CustomNode]]
 
+
 class Hyper(Segment):
     """Hyper对象，表示一类超级消息。如卡片消息、ark消息、小程序等"""
+
     format: Literal["xml", "json"]
     raw: Optional[str]
     content: Optional[Union[dict, list]]
 
+
 class Reference(Segment):
     """Reference对象，表示一类引用消息。转发消息 (Forward) 也属于此类"""
+
     id: Optional[str]
     nodes: Sequence[Union[RefNode, CustomNode]]
 
+
 class Button(Segment):
     """Button对象，表示一类按钮消息"""
+
     flag: Literal["action", "link", "input", "enter"]
     """
     - 点击 action 类型的按钮时会触发一个关于 按钮回调 事件，该事件的 button 资源会包含上述 id
@@ -138,20 +169,26 @@ class Button(Segment):
     - list[At]: 指定用户/身份组可操作
     """
 
+
 class Keyboard(Segment):
     """Keyboard对象，表示一行按钮元素"""
+
     id: Optional[str]
     """此处一般用来表示模板id，特殊情况下可能表示例如 bot_appid 等"""
     buttons: Optional[list[Button]]
     row: Optional[int]
     """当消息中只写有一个 Keyboard 时可根据此参数约定按钮组的列数"""
 
+
 class Other(Segment):
     """其他 Segment"""
+
     origin: MessageSegment
 
+
 class I18n(Segment):
     """特殊的 Segment，用于 i18n 消息"""
+
     item_or_scope: Union[LangItem, str]
     type_: Optional[str] = None
 
@@ -172,10 +209,14 @@ from nonebot_plugin_alconna import Args, Image, Alconna, select
 from nonebot_plugin_alconna.builtins.uniseg.market_face import MarketFace
 
 # 表示这个指令需要的图片会在目标元素下进行搜索，将所有符合 Image 的元素选出来并将第一个作为结果
-alc1 = Alconna("make_meme", Args["name", str]["img", select(Image).first])  # 也可以使用 select(Image).nth(0)
+alc1 = Alconna(
+    "make_meme", Args["name", str]["img", select(Image).first]
+)  # 也可以使用 select(Image).nth(0)
 
 # 表示这个指令需要的图片要么直接是 Image 要么是在 MarketFace 元素内的 Image
-alc2 = Alconna("make_meme", Args["name", str]["img", [Image, select(Image).from_(MarketFace)]])
+alc2 = Alconna(
+    "make_meme", Args["name", str]["img", [Image, select(Image).from_(MarketFace)]]
+)
 ```
 
 也可以参考通用消息的 [`嵌套提取`](./message.mdx#嵌套提取)
@@ -213,10 +254,13 @@ def mfbuild(builder: MessageBuilder, seg: BaseMessageSegment):
 
 
 @custom_handler(MarketFace)
-async def mfexport(exporter: MessageExporter, seg: MarketFace, bot: Bot, fallback: bool):
+async def mfexport(
+    exporter: MessageExporter, seg: MarketFace, bot: Bot, fallback: bool
+):
     if exporter.get_message_type() is Message:
-        return MessageSegment("chronocat:marketface", seg.data)(await exporter.export(seg.children, bot, fallback))
-
+        return MessageSegment("chronocat:marketface", seg.data)(
+            await exporter.export(seg.children, bot, fallback)
+        )
 ```
 
 具体而言，你可以使用 `custom_register` 来增加一个从 MessageSegment 到 Segment 的处理方法；使用 `custom_handler` 来增加一个从 Segment 到 MessageSegment 的处理方法。