[Refactoring] Landmark version 1.0.0-alpha.5

[GreyElaina]

概要

本次重构的 Landmark 版本被设定为 1.0.0-alpha.5.

本次主要对各种用名进行修改, 对 Relationship 模型进行重构, 以及分割 core 部件内的框架抽象到 avilla.core.abstract 处, 这将会不可避免的带来 API 的破坏性改动和用户体验的变化.

• Rename Components
  • Context
  • Metadata
• Context
  • Implements ContextSelector #65
    • ContextClientSelector
    • ContextSceneSelector
    • ContextEndpointSelector
      • ContextRequestSelector
        • context.endpoint.expects_request() -> ContextRequestSelector
        • context.request (property)
  • Implement Context.wrap #63
    • Context.wrap(bound: Selector) -> ContextSelector
    • Context.wrap(bound: MetadataOf) -> ContextWrappedMetadataOf
      • note: Generic omitted.
    • Context.wrap(bound: Selector, trait: type[T extends Trait]) -> T
    • Context.wrap(bound: MetadataOf, trait: type[T extends Trait]) -> T
    • ContextSelector.wrap(trait: type[T extends Trait]) -> T
    • ContextWrappedMetadata.wrap(trait: type[T extends Trait]) -> T
  • Implement Context.pull #64
    • ContextSelector.pull(metadata: type[T extends Metadata] | MetadataRoute[..._L, T]) -> T
    • ContextWrappedMetadataOf[T].pull() -> T
      • note: not required for otherwise arguments.
  • Implements checker utilities on Context #66
    • Design Completed
• Refactor defination of implement & bound #67
  • bound(...)
  • Modifies on record impl and others.
• Event
  • Core

用名修改

以下更改同时会影响到 Filter 等内置组件上的方法命名, 请尤其是该提案的实现编写者注意.

Relationship => Context
Relationship.ctx => Context.client & Context.endpoint
Relationship.mainline => Context.scene
Relationship.via => Context.mediums (type: list[ContextMedium])
Relationship.cast =>
    | Context.wrap(bound: Selector, trait: type[T extends Trait]) -> T
    | Context.wrap(bound: Selector) -> ContextSelector

Cell => Metadata
CellOf => MetadataRoute

API 变动概览

ContextSelector

该 Selector 同时包装了一个 Context, 使得可以配合其完成更多的操作, 这也导致了一些代码风格上的变化.

Context.{client, endpoint, scene, mediums[number].selector} 的类型都为 ContextSelector.

await context.scene.send_message(...)
await context.scene.pull(...) # equals to context.pull(scene, ...)
await context.scene.wrap(trait) # equals to context.wrap(scene, trait)

目前正在考虑实现例如 ContextClientSelector, ContextSceneSelector 等派生类, 用于进一步的提供高效的 API 实现.

Selector 相关

新加入 Selector.expects 方法, 用于对 Selector 的内容进行断言. 在语法上使用 follows-style, 同时 follows-style 作为优雅的模式表达方式将得到进一步的推广.

selector = Selector().group("123").member("456")
selector.expects("group.member")  # pass
selector.expects("group(123).member")  # pass
selector.expects("friend") # error with ValueError

Metadata.of & MetadataRoute.of

需要注意的是, 这里的 MetadataOf 与先前版本中的 CellOf 完全不同.

MetadataOf 的声明:

@dataclass
class MetadataOf(Generic[T]):  # T bounds type[Metadata] | MetadataRoute
    target: Selector
    describe: T

可以这样创建:

Summary.of(context.scene)  # Metadata.of
(Privilege >> Summary).of(context.self)  # MetadataRoute.of

Context.wrap

该 API 不仅用于替代 Relationship.cast, 还用于简单的包装 Selector 为 ContextSelector.
该方法会自动运行 Context.complete, 且自动忽略 land 字段.

# 以下几种调用方法等价.
ctx.wrap(Selector().group(...)).wrap(MessageSend).send(...)
ctx.wrap(Selector().group(...), MessageSend).send(...)

对于 Metadata 上的 bound, 这里有一个简单的草案, 但未经验证:

x = ctx.wrap(bound=Metadata.of(selector))  # -> ContextWrappedMetadataOf
x.wrap(...) # -> Trait

Context.check

!> 该项仍然处于设计中(In-Design)阶段.

在 1.0.0rc4 中, Relationship.check 尚未被实现, 1.0.0rc5 将着手相关工程.

await ctx.check_existence(...) # 确认其存在, 因例如权限原因无法确认就抛出 CheckFailed (lint: 流程控制问题警告)
await ctx.check_accessible(...) # 确认其可操作性, 包括权限等
...

由于要确认的包括且不限于 Metadata, Selector, Trait 之类的交互形式, 所以该项仍然处于设计中阶段.

impl 相关

鉴于 bound 在 Context.wrap -> Trait 中的强制要求, 协议实现中 impl 的方式亦有所改变.

with bound("group.member"):
    @impl(MessageSend.send)
    ...

事件结构体变动

鉴于现在的自动从 AvillaEvent 生成 Context/Relationship 和注入 Metadata 的方式实在是不堪入目,
从 1.0.0-alpha.5 开始, 事件的实例化强制要求 Context 作为第一个参数的传入.
这不会影响事件本身描述的完整性, 也就是说, MessageReceived.scene 等不会被删除.

包组织结构改动

Trait, Fn 以及各式 recorder, AvillaEvent 事件基类, Resource 基类等部件将被移动至 avilla.core.abstract 处.
由 avilla-core 所提供的事件, 元信息类, 内建 Trait 等都被移动至 avilla.core.standards 下.

其他改动

• Relationship.send_message 等缩写形式不再受到支持, 其职权将由 ContextSelector 及其派生完成, 而不需要实现默认求值 (default_target).
• 鉴于上一条的影响, 实现记录器 default_target 不再提供.
• 鉴于 bound 参数的强制要求, 追加声明方法 ImplRecorder.pin, 实现签名类型 OrientFn 与 DirectFn 将不再提供.
• 鉴于 bound 辅助型上下文管理器的出现, prefix 被标记为弃用.
• MessageSend.send_message 等实现签名 Fn 的方法名现已被改为仅包含谓词的形式, 如 MessageSend.send, 这将减少语义杂糅.
• Message 派生为多个消息类型, 如 ChatMessage, NoticeMessage, PlatformMessage 等.
• MetadataModified.modifies 的表述方式现已如下呈现, 因为引入 Context.endpoint, 这一切都变得更简单了:

Modify(
    bound: Selector | MetadataOf,
    field: str,
    action: str,
    past: Any,
    present: Any # use generic ?
)

设计中事项

• 考虑在下一个版本中重构 avilla.core.exceptions, 现阶段其大部分设计都来自于 OneBot 的错误类型.
• 考虑将 BaseProtocol 使用单个 ProtocolManifest 实例表述, 并使用一套 Credential 机制或是 kayaku 描述账号及其鉴权信息.
  • 该项设计仍处于极度早期的阶段.

login = (
    MatrixLogin("elaina", "https://matrix.org")\
        .auth_with_credential_file("session_credential.json")\
        .auth_with_token(...)\
        .auth_with_password(...)\
        .auth_interactive()
)

[GreyElaina]

@BlueGlassBlock @ProgramRipper @RF-Tar-Railt

[GreyElaina]

另附一份 Readme 中的 Example 在 1.0.0rc5 的呈现:

from creart import create
from graia.amnesia.builtins.aiohttp import AiohttpService
from graia.broadcast import Broadcast

from avilla.core import Avilla, Context, MessageReceived, Selector
from avilla.elizabeth.connection.config import WebsocketClientConfig
from avilla.elizabeth.protocol import ElizabethProtocol

broadcast = create(Broadcast)
avilla = Avilla(broadcast, [
    ElizabethProtocol(
        WebsocketClientConfig("bot-account", "mah-verify-code")
    )
], [AiohttpService()])

@broadcast.receiver(MessageReceived)
async def on_message_received(ctx: Context, event: MessageReceived):
    if ctx.client.follows("group.member(<master-account>)"):
        await ctx.scene.send_message("Hello, Avilla!")

avilla.launch_manager.launch_blocking(loop=broadcast.loop)

[GreyElaina]

Trait & Fn 可能需要让我再摸一会.

[GreyElaina]

Trait & Fn 可能需要让我再摸一会.

我摸完了