[All] Bumped to 3.1 (#35)

Updated 3.1 docs & bumped to 3.1

docs/source/api/index.rst

@@ -15,10 +15,11 @@ melobot API
 - :class:`~melobot.adapter.base.Adapter`, :class:`~melobot.adapter.model.Event`, :class:`~melobot.adapter.model.Action`, :class:`~melobot.adapter.model.Echo`
 - :func:`.send_text`, :func:`.send_image`
 - :class:`.Flow`, :class:`.FlowStore`, :func:`.node`, :func:`.rewind`, :func:`.stop`
+- :class:`.FlowDecorator`, :func:`~melobot.handle.on_event`, :func:`.on_text`, :func:`.on_start_match`, :func:`.on_contain_match`, :func:`.on_full_match`, :func:`.on_end_match`, :func:`.on_regex_match`, :func:`.on_command`
 - :class:`.Depends`
-- :class:`.Rule`, :func:`.enter_session`, :class:`.SessionStore`, :func:`.suspend`
+- :class:`.Session`, :class:`.Rule`, :class:`.DefaultRule`, :func:`.enter_session`, :class:`.SessionStore`, :func:`.suspend`
 - :class:`.GenericLogger`, :class:`.Logger`, :class:`.LogLevel`, :func:`.get_logger`
-- :class:`.HandleLevel`, :class:`.LogicMode`
+- :class:`.LogicMode`
 - :class:`.Context`
 
 各模块 API 文档索引：
@@ -40,3 +41,4 @@ melobot API
     melobot.typ
     melobot.exceptions
     melobot.ctx
+    melobot.mixin

docs/source/api/melobot.adapter.rst

@@ -28,6 +28,10 @@ melobot.adapter
     :members:
     :exclude-members: __init__
 
+.. autoclass:: melobot.adapter.TextEvent
+    :members:
+    :exclude-members: __init__
+
 .. autoclass:: melobot.adapter.Action
     :members:
     :exclude-members: __init__

docs/source/api/melobot.handle.rst

@@ -20,6 +20,32 @@ melobot.handle
 
 .. autofunction:: melobot.handle.no_deps_node
 
+流装饰器
+----------
+
+流装饰相关的组件，可以将一个普通函数装饰为一个处理流。
+
+这些组件，在 melobot 的教程中，早期我们称它们为“事件绑定方法”或“事件绑定函数”。
+
+.. autoclass:: melobot.handle.FlowDecorator
+    :exclude-members: auto_flow_wrapped
+
+.. autofunction:: melobot.handle.on_event
+
+.. autofunction:: melobot.handle.on_text
+
+.. autofunction:: melobot.handle.on_start_match
+
+.. autofunction:: melobot.handle.on_contain_match
+
+.. autofunction:: melobot.handle.on_end_match
+
+.. autofunction:: melobot.handle.on_full_match
+
+.. autofunction:: melobot.handle.on_regex_match
+
+.. autofunction:: melobot.handle.on_command
+
 处理流控制
 -------------
 
@@ -55,3 +81,8 @@ melobot.handle
 .. autofunction:: melobot.handle.get_event
 
 .. autofunction:: melobot.handle.try_get_event
+
+弃用项，临时存在
+----------------
+
+.. autofunction:: melobot.handle.GetParseArgs

docs/source/api/melobot.io.rst

@@ -37,3 +37,34 @@ melobot.io
 .. autoclass:: melobot.io.EchoPacket
     :members:
     :exclude-members: __init__, ok, status, prompt, noecho
+
+泛型
+------
+
+.. data:: melobot.io.InPacketT
+
+    输入包泛型
+
+.. data:: melobot.io.OutPacketT
+
+    输出包泛型
+
+.. data:: melobot.io.EchoPacketT
+
+    回应包泛型
+
+.. data:: melobot.io.InSourceT
+
+    输入源泛型
+
+.. data:: melobot.io.OutSourceT
+
+    输出源泛型
+
+.. data:: melobot.io.InOrOutSourceT
+
+    输入或输出源泛型
+
+.. data:: melobot.io.IOSourceT
+
+    输入输出源泛型

docs/source/api/melobot.mixin.rst

@@ -0,0 +1,14 @@
+melobot.mixin
+=============
+
+.. autoclass:: melobot.mixin.LogMixin
+    :members:
+
+.. autoclass:: melobot.mixin.FlagMixin
+    :members:
+
+.. autoclass:: melobot.mixin.AttrReprMixin
+    :members:
+
+.. autoclass:: melobot.mixin.HookMixin
+    :members:

docs/source/api/melobot.session.rst

@@ -14,13 +14,22 @@ melobot.session
 .. autoclass:: melobot.session.Rule
     :members:
 
+.. autoclass:: melobot.session.CompareInfo
+    :members:
+    :exclude-members: __init__
+
+.. autoclass:: melobot.session.DefaultRule
+    :members:
+
 .. autofunction:: melobot.session.enter_session
 
 会话状态
 -----------------
 
 .. autofunction:: melobot.session.suspend
 
+.. autofunction:: melobot.session.get_session
+
 .. autofunction:: melobot.session.get_rule
 
 .. autofunction:: melobot.session.get_session_store

docs/source/api/melobot.typ.rst

@@ -3,37 +3,35 @@
 melobot.typ
 ===========
 
-.. autoclass:: melobot.typ.HandleLevel
-    :members:
-    :exclude-members: __new__
-
 .. autoclass:: melobot.typ.LogicMode
     :members:
 
 .. autofunction:: melobot.typ.is_type
 
-.. autofunction:: melobot.typ.abstractattr
-
 .. autoclass:: melobot.typ.BetterABCMeta
     :members:
     :exclude-members: __call__, DummyAttribute
 
 .. autoclass:: melobot.typ.BetterABC
     :members:
 
+.. autofunction:: melobot.typ.abstractattr
+
 .. autoclass:: melobot.typ.SingletonMeta
     :exclude-members: __call__
 
 .. autoclass:: melobot.typ.SingletonBetterABCMeta
     :exclude-members: __call__
 
-.. autoclass:: melobot.typ.Markable
-    :members:
-    :exclude-members: __init__
-
 .. autoclass:: melobot.typ.VoidType
     :members:
 
+.. autoclass:: melobot.typ.AsyncCallable
+    :exclude-members: __call__, __init__
+
+.. autoclass:: melobot.typ.SyncOrAsyncCallable
+    :exclude-members: __call__, __init__
+
 .. data:: melobot.typ.T
 
     泛型 T，无约束
@@ -45,6 +43,3 @@ melobot.typ
 .. data:: melobot.typ.P
 
    :obj:`~typing.ParamSpec` 泛型 P，无约束
-
-.. autoclass:: melobot.typ.AsyncCallable
-    :exclude-members: __call__, __init__

docs/source/api/melobot.utils.rst

@@ -1,6 +1,9 @@
 melobot.utils
 =============
 
+基础工具
+----------
+
 .. autofunction:: melobot.utils.get_obj_name
 
 .. autofunction:: melobot.utils.singleton
@@ -14,6 +17,8 @@ melobot.utils
 
 .. autofunction:: melobot.utils.to_coro
 
+.. autofunction:: melobot.utils.to_sync
+
 .. autofunction:: melobot.utils.if_not
 
 .. autofunction:: melobot.utils.unfold_ctx
@@ -37,3 +42,68 @@ melobot.utils
 .. autofunction:: melobot.utils.async_at
 
 .. autofunction:: melobot.utils.async_interval
+
+检查/验证
+-----------
+
+.. autoclass:: melobot.utils.check.Checker
+    :exclude-members: __init__
+
+.. autoclass:: melobot.utils.check.WrappedChecker
+    :exclude-members: __init__, check
+
+基础检查/验证工具
+------------------
+
+.. autofunction:: melobot.utils.check.checker_join
+
+.. _melobot_match:
+
+匹配
+------
+
+.. autoclass:: melobot.utils.match.Matcher
+    :exclude-members: __init__
+
+.. autoclass:: melobot.utils.match.WrappedMatcher
+    :exclude-members: __init__, match
+
+基础匹配工具
+-------------
+
+.. autoclass:: melobot.utils.match.StartMatcher
+
+.. autoclass:: melobot.utils.match.ContainMatcher
+
+.. autoclass:: melobot.utils.match.EndMatcher
+
+.. autoclass:: melobot.utils.match.FullMatcher
+
+.. autoclass:: melobot.utils.match.RegexMatcher
+
+.. _melobot_parse:
+
+解析
+-------
+
+.. autoclass:: melobot.utils.parse.Parser
+    :exclude-members: __init__
+
+.. autoclass:: melobot.utils.parse.AbstractParseArgs
+    :exclude-members: __init__
+
+基础解析工具
+-------------
+
+.. autoclass:: melobot.utils.parse.CmdParser
+    :exclude-members: format
+
+.. autoclass:: melobot.utils.parse.CmdArgs
+    :exclude-members: __init__, vals
+
+.. autoclass:: melobot.utils.parse.CmdParserFactory
+
+.. autoclass:: melobot.utils.parse.CmdArgFormatter
+
+.. autoclass:: melobot.utils.parse.CmdArgFormatInfo
+    :exclude-members: __init__

docs/source/index.md

@@ -31,6 +31,7 @@ ob_api/index
 :caption: 更多
 :hidden:
 
+update-log
 melobot-prev
 ```
 

docs/source/intro/action-echo.md

@@ -11,7 +11,7 @@
 
 ## 行为句柄
 
-当直接使用行为方法时，默认是尽快完成的。即不等待也不关心 OneBot 实现端是否成功完成了行为：
+当直接使用 OneBot 的行为方法时，默认是尽快完成的。即不等待也不关心 OneBot 实现端是否成功完成了行为：
 
 ```python
 # 发送消息而不等待，也不关心是否成功
@@ -64,7 +64,7 @@ async def _(adapter: Adapter):
         await adapter.send("我一定是第二条消息")
 ```
 
-一整个函数都需要等待时，可以使用 {func}`.unfold_ctx` 装饰器：
+一整个事件处理函数都需要等待时，可以使用 {func}`.unfold_ctx` 装饰器：
 
 ```python
 from melobot.protocols.onebot.v11 import Adapter, on_message, EchoRequireCtx
@@ -78,6 +78,12 @@ async def _(adapter: Adapter):
     await adapter.send("我一定是第二条消息")
 ```
 
+注意：melobot 的所有行为操作，包括刚才提及的协议特定操作，或通用的操作（例如 {func}`.send_text`），都会返回行为句柄。
+
+但这里提及的 {meth}`~.v11.Adapter.with_echo` 以及 {class}`.EchoRequireCtx` 等操作，只对 OneBot 协议特有行为操作有效。
+
+**其他协议的行为句柄，是否需要类似的操作，取决于它们的实现。但不变的是：使用行为句柄，可以获知行为的执行情况。**
+
 ```{admonition} 提示
 :class: tip
 **不建议频繁等待行为操作**。等待总是需要更多时间，大量使用会降低运行效率。
@@ -97,7 +103,7 @@ async def _(adapter: Adapter):
 和自定义消息段类似，有时候我们总是会需要自定义的 OneBot 行为类型的。一般这样构造：
 
 ```python
-from melobot.protocols.onebot.v11.adapter.action import Action
+from melobot.protocols.onebot.v11 import Action
 
 # 临时构造一个自定义行为
 action = Action(type="action_type", params={"param1": 123456})
@@ -117,9 +123,9 @@ action.set_echo(True)
 handles = await adapter.call_output(action)
 ```
 
-实际上，适配器所有行为操作，都是先在内部构建 {class}`~.v11.adapter.action.Action` 对象，再通过 {meth}`~.v11.Adapter.call_output` 输出。
+实际上，适配器所有行为操作，都是先在内部构建 {class}`~melobot.adapter.model.Action` 对象，再通过 {meth}`~melobot.adapter.base.Adapter.call_output` 输出。
 
-而所有内置行为对象，也可以在文档 [OneBot v11 行为类型](onebot_v11_action) 中找到。你完全可以手动构造，再使用 {meth}`~.v11.Adapter.call_output` 输出，这适用于更精细的控制需求。
+而所有 OneBot v11 的行为对象，也可以在文档 [OneBot v11 行为类型](onebot_v11_action) 中找到。你完全可以手动构造，再使用 {meth}`~.v11.Adapter.call_output` 输出，这适用于更精细的控制需求。
 
 ## 总结
 

docs/source/intro/async-callable.md

@@ -79,3 +79,8 @@ aprint = to_async(print)
 {func}`.to_async` 只是将原对象包裹在一个异步函数中，从而满足异步可调用的接口。
 
 **即：{func}`.to_async` 不做接口兼容外的处理，因此也就不会提供并发/并行的能力。**
+
+另外，有的接口支持 {class}`.SyncOrAsyncCallable` 类型的参数，这表明它是**同时支持同步可调用、异步可调用**的。{class}`.SyncOrAsyncCallable` 有以下特性：
+
+{class}`.SyncOrAsyncCallable`\[{data}`.P`, {data}`.T`\] {math}`\iff`
+{external:class}`~collections.abc.Callable`\[{data}`.P`, {external:class}`~collections.abc.Awaitable`\[{data}`.T` | {external:class}`~typing.Awaitable`\[{data}`.T`\]\]\]