🎉 major part of 0.7.0

.github/workflows/api-docs.yml

@@ -28,3 +28,12 @@ jobs:
         with:
           branch: gh-pages
           folder: site
+
+      - name: Deploy to Cloudflare Pages
+        uses: cloudflare/pages-action@1
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CF_ACCOUNT_ID }}
+          projectName: graia-ariadne
+          directory: site
+          gitHubToken: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/cf-preview-deploy.yml

@@ -0,0 +1,33 @@
+name: Preview Deployment to Cloudflare Pages
+on:
+  push:
+    branches:
+      - "!dev"
+jobs:
+  deploy-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Setup Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.9
+
+      - name: Setup Document Dependencies
+        run: |
+          pip install -r ./docs/requirements.txt
+
+      - name: Build with MKDocs
+        run: |
+          PYTHONPATH=src mkdocs build
+
+      - name: Deploy to Cloudflare Pages
+        uses: cloudflare/pages-action@1
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CF_ACCOUNT_ID }}
+          projectName: graia-ariadne-preview
+          directory: site
+          gitHubToken: ${{ secrets.GITHUB_TOKEN }}

.readthedocs.yaml

@@ -1,12 +1,9 @@
 version: 2
 
 build:
-  os: ubuntu-20.04
+  os: ubuntu-22.04
   tools:
-    python: "3.9"
-  jobs:
-    pre_build:
-      - export PYTHONPATH="./src"
+    python: "3.10"
 
 python:
   install:

.vscode/settings.json

@@ -7,41 +7,69 @@
     "alconna",
     "arithmatex",
     "asgi",
+    "Behaviour",
     "behaviours",
     "betterem",
     "cheatsheet",
     "codehilite",
     "cooldown",
+    "crontabify",
+    "dataclass",
     "Disp",
+    "Dispatchable",
     "disqus",
     "docformat",
+    "DOTALL",
+    "exectarget",
     "favicon",
     "fontawesome",
+    "fullmatch",
+    "HRTX",
     "inlinehilite",
     "isawaitable",
     "Kugou",
     "kuriyama",
     "Kuwo",
+    "Launart",
+    "Launchable",
+    "launchables",
     "levelno",
     "linenums",
+    "maintask",
     "Migu",
     "miraijvm",
+    "MISRO",
     "mkdocstrings",
+    "Netease",
     "pycon",
     "pymdownx",
     "pypi",
+    "qualname",
     "quickstart",
+    "removeprefix",
+    "removesuffix",
+    "RESTGET",
+    "RESTPOST",
+    "richuru",
+    "Shutdowned",
+    "sigexit",
     "smartsymbols",
+    "sourcery",
+    "starlette",
+    "statv",
+    "subchain",
     "superfences",
     "tasklist",
+    "Throwed",
     "ujson",
     "unmatch",
+    "unsync",
     "uvicorn"
   ],
   "python.analysis.completeFunctionParens": true,
   "python.analysis.diagnosticMode": "workspace",
   "editor.fontLigatures": false,
   "python.linting.flake8Enabled": true,
   "python.analysis.typeCheckingMode": "basic",
-  "sourcery.ruleType.comments": false
+  "jupyter.jupyterServerType": "local",
 }

CHANGELOG.md

@@ -0,0 +1 @@
+参见 [`CHANGELOG.md`](./docs/appendix/CHANGELOG.md)

README.md

@@ -40,19 +40,18 @@ Ariadne 是 `Graia Project` 继承了 [`Application`](https://github.com/GraiaPr
 
 ```python
 from graia.ariadne.app import Ariadne
-from graia.ariadne.message.chain import MessageChain
-from graia.ariadne.message.element import Plain
-from graia.ariadne.model import Friend, MiraiSession
+from graia.ariadne.connection.config import config
+from graia.ariadne.model import Friend
 
-app = Ariadne(MiraiSession(host="http://localhost:8080", verify_key="ServiceVerifyKey", account=123456789))
+app = Ariadne(config(verify_key="ServiceVerifyKey", account=123456789))
 
 
 @app.broadcast.receiver("FriendMessage")
 async def friend_message_listener(app: Ariadne, friend: Friend):
-    await app.sendMessage(friend, MessageChain.create([Plain("Hello, World!")]))
+    await app.send_message("Hello, World!")
 
 
-app.launch_blocking()
+Ariadne.launch_blocking()
 ```
 
 更多信息请看

docs/advance/NAV.md

@@ -4,7 +4,5 @@
 - [消息链](./msg-chain.md)
 - [Commander](./commander.md)
 - [Twilight](./twilight.md)
-- [Twilight 旧版文档](./twilight-old.md)
-- [Adapter](./adapter.md)
 - [Alconna](./alconna/quickstart.md)
     - [官方文档](https://arcletproject.github.io/docs/alconna/tutorial)

docs/advance/alconna/quickstart.md

@@ -19,9 +19,9 @@ music = AlconnaString(
 )
 @app.broadcast.receiver(FriendMessage, dispatchers=[AlconnaDispatcher(alconna=music, help_flag='reply')])
 async def friend_message_listener(app: Ariadne, friend: Friend, result: Arpamar):
-    await app.sendFriendMessage(friend, MessageChain.create("歌名是 ", result.song_name))
+    await app.send_message(friend, f"歌名是 {result.song_name}")
     if result.singer_name:
-        await app.sendFriendMessage(friend, MessageChain.create("歌手是 ", result.singer_name))
+        await app.send_message(friend, f"歌名是 {result.singer_name}")
 ```
 
 执行这段代码后，向你的 bot 发送 `!点歌 大地 -s Beyond` 试试.
@@ -188,7 +188,7 @@ alc = Alconna("test", Args.foo[int]) + Option("my_option", Args.bar[str])
 @app.broadcast.receiver(FriendMessage, dispatchers=[AlconnaDispatcher(alconna=alc)])
 async def friend_message_listener(app: Ariadne, friend: Friend, dup: Test):
     print(dup.my_args.first_arg)
-    await app.sendFriendMessage(friend, MessageChain.create(dup.my_option.name))
+    await app.send_message(friend, dup.my_option.name)
     ...
 ```
 
@@ -197,7 +197,7 @@ async def friend_message_listener(app: Ariadne, friend: Friend, dup: Test):
 ...
 async def friend_message_listener(app: Ariadne, friend: Friend, my_args: ArgsStub, my_option: OptionStub):
     print(my_args.first_arg)
-    await app.sendFriendMessage(friend, MessageChain.create(my_option.name))
+    await app.send_message(friend, my_option.name)
     ...
 ```
 

docs/advance/broadcast/derive.md

@@ -0,0 +1,50 @@
+# 派生修饰 - Derive
+
+如果你看到这里, 相信你大概通过 [基础消息链处理器](./../../basic/base-parser.md) 接触过 `Derive` 了.
+
+它利用了 [`typing.Annotated`][typing.Annotated] 的特性, 为 `BroadcastControl` 提供了 `Decorator` 外的另一种参数修饰方式.
+
+这个特性已被默认在 `BroadcastControl` 中启用.
+
+## 使用
+
+在声明参数时，使用这样的语法：
+
+```py
+arg: Annotated[OriginType, Derive1, Derive2, ...]
+```
+
+`Broadcast` 会获取 `OriginType` 作为初始值，之后 **逐个** 对剩下的 Derive **串行调用**，
+如果没有失败，就返回最后的修饰值.
+
+例如：
+
+```py
+chain: Annotated[MessageChain, MentionMe(name=False), StartsWith(".command")]
+```
+
+就会将 `MessageChain([At(123), ".command arg"])` 转换为 `MessageChain(["arg"])` 传回来.
+
+!!! tip "跨版本兼容性"
+
+    Python 3.8 用户请 `#!py from typing_extensions import Annotated`
+
+## 自定义 Derive
+
+`Derive` 应该是一个可调用对象, 签名为 `(T_Value, DispatcherInterface) -> T_Value`.
+
+调用过程中引发的 `ExecutionStop` 异常会导致整个执行过程的终止, 就和 Decorator 一样.
+
+例如:
+
+```py
+async def derive_chain(chain: MessageChain, interface: DispatcherInterface) -> MessageChain: # 注意 async
+    ...
+
+async def parse(chain: Annotated[MessageChain, derive_chain]):
+    ...
+```
+
+你会注意到 `Derive` 的局限在于它不应用于改变返回值的类型, 比如从 MessageChain 变为 dict 之类的.
+
+因此, 它是一个和 `Decorator` 同级的特性.

docs/advance/commander.md

@@ -224,7 +224,7 @@ Arg("--option {value}", default=MessageChain(["default"])) # 默认 type 为 Mes
 ```py title="示例"
 def cast_to_list(value: MessageChain, field: ModelField):
     if field.outer_type_ is List[str]:
-        return value.asDisplay().split(".")
+        return value.display.split(".")
     if field.outer_type_ is List[MessageChain]:
         return value.split(".")
     return value

docs/advance/msg-chain.md

@@ -1,31 +1,5 @@
 # 消息链: 进阶
 
-### subchain 方法
-
-`MessageChain.subchain` 是这样使用的:
-
-传入一个 `slice` 切片对象, 其 `start` 与 `stop` (可选) 均为 **二元组**, 为 `(int, Optional[int]` 格式.
-
-切片对象 `start` 与 `stop` 的第一个整数指示元素起止位置. (含义同在序列上切片)
-
-若有第二个整数, 则分别指示 **开头文本起始下标** 与 **末尾文本结束下标**. (含义同在字符串上切片)
-
-示例:
-
-```python
-assert (MessageChain.create("hello world"))[(0,3):(1,7)] == MessageChain([Plain(text='lo w')])
-```
-
-!!! warning "注意"
-
-    若提供第二个整数时 首/尾 元素不为文本则会引发 `ValueError`.
-
-???+ note "提示"
-
-    在消息链对象上使用 `[]` 符号并使用 `MessageChain[(a1, a2):(b1, b2)]`
-
-    相当于调用 `MessageChain.subchain(slice((a1, a2), (b1, b2)))`
-
 ### 筛选元素
 
 使用 `include` 与 `exclude` 方法可以筛选消息链中的元素.
@@ -77,10 +51,10 @@ assert not msg_chain.endswith("world!")
 
 `MessageChain` 的 `replace` 方法与 `str` 的 `replace` 方法有异曲同工之妙.
 
-在其表面下, `findSubChain` 承担了大部分工作, 找出所有符合 `old` 的部分, 之后由简单的循环完成替换.
+在其表面下, `find_sub_chain` 承担了大部分工作, 找出所有符合 `old` 的部分, 之后由简单的循环完成替换.
 
 ```pycon
->>> MessageChain(["Hello World!Hello World!""How are you?", At(1), "yo"]).replace(
+>>> MessageChain(["Hello World!Hello World!How are you?", At(1), "yo"]).replace(
 ...     MessageChain(["Hello World!"]),
 ...     MessageChain(["No!"])
 ... )
@@ -147,5 +121,5 @@ MessageChain([Plain(text='test'), At(target=12345)])
 
 原因很简单, `Ariadne` 的 `MessageChain` 是支持链式调用的, 所以 **所有对消息链的操作都会返回一个消息链引用** .
 
-自 `0.5.1` 起, 所有消息链的修改操作都支持布尔参数 `copy` (可能为仅关键字参数), `copy = True` 时会返回消息链的 **副本** (相当于在 `chain.copy()` 上操作),
+自 `0.5.1` 起, 消息链的大部分修改操作都支持参数 `copy` (可能为仅关键字参数), `copy = True` 时会返回消息链的 **副本** (相当于在 `chain.copy()` 上操作),
 否则会返回自身的引用.