tenko-api 0.2.0__tar.gz → 0.3.0__tar.gz

{tenko_api-0.2.0 → tenko_api-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tenko-api
-Version: 0.2.0
+Version: 0.3.0
 Summary: Tenko 第三方插件的稳定宿主接口（运行时转发到 Tenko 宿主）
 Project-URL: Homepage, https://github.com/g1331/tenko
 Project-URL: Issues, https://github.com/g1331/tenko/issues
@@ -21,7 +21,7 @@ Description-Content-Type: text/markdown
 
 插件依赖它，而不是依赖 `tenko` 本体：`tenko-api` 没有任何运行时依赖，
 只是转发到正在运行的 Tenko 宿主，因此不会影响插件自己的依赖解析。插件声明
-`tenko-api>=0.2,<0.3` 这样的范围；宿主加载插件前按自己提供的 `tenko-api` 版本检查
+`tenko-api>=0.3,<0.4` 这样的范围；宿主加载插件前按自己提供的 `tenko-api` 版本检查
 这个范围，不兼容的插件不加载并在日志中说明原因，插件不需要另写兼容检查。
 
 > 当前为预览版（0.x）。1.0 之前接口可能调整，请把上限写到次版本。
@@ -36,7 +36,7 @@ Description-Content-Type: text/markdown
 [project]
 name = "tenko-plugin-hello"
 version = "0.1.0"
-dependencies = ["tenko-api>=0.2,<0.3"]
+dependencies = ["tenko-api>=0.3,<0.4"]
 
 [project.entry-points."tenko.plugins"]
 hello = "tenko_plugin_hello"   # 入口名 = 插件 ID
@@ -65,9 +65,8 @@ async def hello(session: Session):
 ## 返回消息
 
 命令处理函数直接返回 `str`，Entari 原样发送；图片等混合内容返回 `MessageChain`。
-`tenko_api.messages.text_message` 自 0.2.0 起弃用（调用时发出 `DeprecationWarning`），
-将在 1.0 前移除，请改为直接返回字符串。宿主强制关闭 Entari 的 `str_as_message`，
-返回的 `str` 一律按纯文本发送；需要 @、图片等元素时返回 `MessageChain`。
+宿主强制关闭 Entari 的 `str_as_message`，返回的 `str` 一律按纯文本发送，需要 @、图片等元素时
+返回 `MessageChain`。
 
 ## 权限与功能开关
 
@@ -82,7 +81,7 @@ async def hello(session: Session):
 - 装饰器放在 `@command.on(...)` 之下，放在之上也同样生效；同一种装饰器在一个函数上只能用一次。
   它们在命令匹配之后执行，所以只有命中命令的消息才会收到拒绝回复。
 - 声明的要求登记在处理函数上，`/帮助 <编号>` 会显示每条命令的“权限”。
-- 只有权限取决于运行时数据时（例如按参数区分的权限）才在函数体里调用 `require_perm`。
+- 只有权限取决于运行时数据时（例如按参数区分的权限）才在函数体里调用 `require_perm(session, level)`。
 - `declare(level=Permission.X)` 声明整个插件要求的群等级，默认 `ActiveGroup`：群等级更低的群里，
   该插件的所有命令都被宿主静默忽略。
 - 不走命令的监听器（例如响应 @bot 的消息监听）没有宿主的命令策略保护，用
@@ -104,13 +103,12 @@ async def on_message(event: MessageCreatedEvent): ...
 
 | 模块 | 内容 |
 |---|---|
-| `tenko_api.context` | `MessageContext`、`context_from_session` |
 | `tenko_api.perm` | `Permission`；装饰器 `require`、`require_group`、`group_only`、`private_only`；函数体内的 `require_perm`、`get_user_perm`、`get_group_perm` |
 | `tenko_api.actions` | 发消息、禁言、踢人、撤回、查询群成员等宿主动作，以及 `ActionServiceError` 系列异常 |
 | `tenko_api.accounts` | 只读账号信息：在线账号、某群可响应的账号 |
 | `tenko_api.features` | `feature_enabled` 只读查询；`declare` 声明范围、默认开关、限流权重和群等级；`feature_required` 装饰非命令监听器 |
 | `tenko_api.render` | `RenderService`、`try_render`（浏览器不可用时得到 `None`，回退文本；`render_or_none` 是按方法名分发的旧写法） |
-| `tenko_api.messages` | `report_error`；`text_message` 已弃用（见上文“返回消息”） |
+| `tenko_api.messages` | `report_error` |
 | `tenko_api.storage` | 插件独立数据目录 `data_dir()`、带版本号并自动备份迁移的 JSON `Store`、插件自己的 SQLite 库 `Model` 与 `get_session()` |
 
 ## 插件的 SQLite 库
@@ -135,7 +133,8 @@ async def latest() -> str | None:
         return await db.scalar(select(Note.text).order_by(Note.id.desc()).limit(1))
 ```
 
-- 模型要在插件模块里定义（导入期间），并在 Tenko 启动时随插件加载；已经在运行的 Tenko 里不能新增模型，需要重启。
+- 模型要在插件模块里定义（导入期间），并在 Tenko 启动时随插件加载；已经在运行的 Tenko 里不能新增模型，
+  所以用了模型的插件首次启用后需要重启，没有模型的插件启用即可加载。
 - 启动时自动建表，并自动执行新增表、新增可空列和新增索引。删除表、删除列、修改列类型会被拒绝
   （日志报错、数据保持原样）；确需这类变更时用官方的 `register_custom_migration` 写显式迁移脚本。
 - 插件版本变化后的第一次启动，宿主先备份插件库（`backups/`，保留最近 3 份）再迁移。
@@ -149,7 +148,8 @@ async def latest() -> str | None:
 
 ## 版本承诺
 
-版本号独立于 Tenko 本体，遵循语义化版本（1.0 起生效）：
+版本号独立于 Tenko 本体，遵循语义化版本（1.0 起生效）。1.0 之前删除或改变语义时次版本号 +1，
+例如 0.3.0 移除了 `tenko_api.context` 和 `text_message`，权限函数改为接收 `Session`。
 
 | 变更 | 版本号 |
 |---|---|

{tenko_api-0.2.0 → tenko_api-0.3.0}/README.md

@@ -4,7 +4,7 @@
 
 插件依赖它，而不是依赖 `tenko` 本体：`tenko-api` 没有任何运行时依赖，
 只是转发到正在运行的 Tenko 宿主，因此不会影响插件自己的依赖解析。插件声明
-`tenko-api>=0.2,<0.3` 这样的范围；宿主加载插件前按自己提供的 `tenko-api` 版本检查
+`tenko-api>=0.3,<0.4` 这样的范围；宿主加载插件前按自己提供的 `tenko-api` 版本检查
 这个范围，不兼容的插件不加载并在日志中说明原因，插件不需要另写兼容检查。
 
 > 当前为预览版（0.x）。1.0 之前接口可能调整，请把上限写到次版本。
@@ -19,7 +19,7 @@
 [project]
 name = "tenko-plugin-hello"
 version = "0.1.0"
-dependencies = ["tenko-api>=0.2,<0.3"]
+dependencies = ["tenko-api>=0.3,<0.4"]
 
 [project.entry-points."tenko.plugins"]
 hello = "tenko_plugin_hello"   # 入口名 = 插件 ID
@@ -48,9 +48,8 @@ async def hello(session: Session):
 ## 返回消息
 
 命令处理函数直接返回 `str`，Entari 原样发送；图片等混合内容返回 `MessageChain`。
-`tenko_api.messages.text_message` 自 0.2.0 起弃用（调用时发出 `DeprecationWarning`），
-将在 1.0 前移除，请改为直接返回字符串。宿主强制关闭 Entari 的 `str_as_message`，
-返回的 `str` 一律按纯文本发送；需要 @、图片等元素时返回 `MessageChain`。
+宿主强制关闭 Entari 的 `str_as_message`，返回的 `str` 一律按纯文本发送，需要 @、图片等元素时
+返回 `MessageChain`。
 
 ## 权限与功能开关
 
@@ -65,7 +64,7 @@ async def hello(session: Session):
 - 装饰器放在 `@command.on(...)` 之下，放在之上也同样生效；同一种装饰器在一个函数上只能用一次。
   它们在命令匹配之后执行，所以只有命中命令的消息才会收到拒绝回复。
 - 声明的要求登记在处理函数上，`/帮助 <编号>` 会显示每条命令的“权限”。
-- 只有权限取决于运行时数据时（例如按参数区分的权限）才在函数体里调用 `require_perm`。
+- 只有权限取决于运行时数据时（例如按参数区分的权限）才在函数体里调用 `require_perm(session, level)`。
 - `declare(level=Permission.X)` 声明整个插件要求的群等级，默认 `ActiveGroup`：群等级更低的群里，
   该插件的所有命令都被宿主静默忽略。
 - 不走命令的监听器（例如响应 @bot 的消息监听）没有宿主的命令策略保护，用
@@ -87,13 +86,12 @@ async def on_message(event: MessageCreatedEvent): ...
 
 | 模块 | 内容 |
 |---|---|
-| `tenko_api.context` | `MessageContext`、`context_from_session` |
 | `tenko_api.perm` | `Permission`；装饰器 `require`、`require_group`、`group_only`、`private_only`；函数体内的 `require_perm`、`get_user_perm`、`get_group_perm` |
 | `tenko_api.actions` | 发消息、禁言、踢人、撤回、查询群成员等宿主动作，以及 `ActionServiceError` 系列异常 |
 | `tenko_api.accounts` | 只读账号信息：在线账号、某群可响应的账号 |
 | `tenko_api.features` | `feature_enabled` 只读查询；`declare` 声明范围、默认开关、限流权重和群等级；`feature_required` 装饰非命令监听器 |
 | `tenko_api.render` | `RenderService`、`try_render`（浏览器不可用时得到 `None`，回退文本；`render_or_none` 是按方法名分发的旧写法） |
-| `tenko_api.messages` | `report_error`；`text_message` 已弃用（见上文“返回消息”） |
+| `tenko_api.messages` | `report_error` |
 | `tenko_api.storage` | 插件独立数据目录 `data_dir()`、带版本号并自动备份迁移的 JSON `Store`、插件自己的 SQLite 库 `Model` 与 `get_session()` |
 
 ## 插件的 SQLite 库
@@ -118,7 +116,8 @@ async def latest() -> str | None:
         return await db.scalar(select(Note.text).order_by(Note.id.desc()).limit(1))
 ```
 
-- 模型要在插件模块里定义（导入期间），并在 Tenko 启动时随插件加载；已经在运行的 Tenko 里不能新增模型，需要重启。
+- 模型要在插件模块里定义（导入期间），并在 Tenko 启动时随插件加载；已经在运行的 Tenko 里不能新增模型，
+  所以用了模型的插件首次启用后需要重启，没有模型的插件启用即可加载。
 - 启动时自动建表，并自动执行新增表、新增可空列和新增索引。删除表、删除列、修改列类型会被拒绝
   （日志报错、数据保持原样）；确需这类变更时用官方的 `register_custom_migration` 写显式迁移脚本。
 - 插件版本变化后的第一次启动，宿主先备份插件库（`backups/`，保留最近 3 份）再迁移。
@@ -132,7 +131,8 @@ async def latest() -> str | None:
 
 ## 版本承诺
 
-版本号独立于 Tenko 本体，遵循语义化版本（1.0 起生效）：
+版本号独立于 Tenko 本体，遵循语义化版本（1.0 起生效）。1.0 之前删除或改变语义时次版本号 +1，
+例如 0.3.0 移除了 `tenko_api.context` 和 `text_message`，权限函数改为接收 `Session`。
 
 | 变更 | 版本号 |
 |---|---|

{tenko_api-0.2.0 → tenko_api-0.3.0}/src/tenko_api/__init__.py

@@ -4,13 +4,13 @@
 Tenko 宿主（``tenko.*``），所以 ``import tenko_api`` 本身不要求宿主已安装。
 插件只应从 ``tenko_api.*`` 导入宿主能力，不要导入 ``tenko.*`` 内部模块。
 
-版本遵循语义化版本，且 1.0 之前（预览期）接口可能调整：
+版本遵循语义化版本。1.0 之前（预览期）删除或改变语义时次版本号 +1；1.0 起：
 
 - 新增能力：次版本号 +1；
 - 删除或改变语义：主版本号 +1，废弃的接口至少保留一个次版本并给出
   ``DeprecationWarning``。
 """
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 __all__ = ["__version__"]

{tenko_api-0.2.0 → tenko_api-0.3.0}/src/tenko_api/actions.py

@@ -25,7 +25,7 @@ kick_member = action_service.kick_member
 delete_message = action_service.delete_message
 get_group_member = action_service.get_group_member
 list_group_members = action_service.list_group_members
-list_groups = action_service.list_groups
+list_groups = action_service.get_group_list
 
 __all__ = [
     "ActionAccountUnavailable",

tenko_api-0.3.0/src/tenko_api/messages.py

@@ -0,0 +1,13 @@
+"""稳定插件 API：错误上报。
+
+命令处理函数直接返回 ``str`` 即可，Entari 会原样发送；混合内容（图片等）返回
+``MessageChain``。
+"""
+
+from tenko.host.action_errors import action_error_message, report_action_error
+
+# 把异常连同消息来源报告给 Master；投递失败只记日志，不会再抛出。
+report_error = report_action_error
+
+
+__all__ = ["action_error_message", "report_error"]

{tenko_api-0.2.0 → tenko_api-0.3.0}/src/tenko_api/perm.py

@@ -6,7 +6,9 @@
 （例如按参数区分的权限）时才在函数体里用 :func:`require_perm`。
 """
 
-from tenko.context import MessageContext
+from arclet.entari import Session
+
+from tenko.context import context_from_session
 from tenko.host import perm as _perm
 from tenko.host.guards import group_only, private_only, require_group
 from tenko.host.guards import require as _require
@@ -24,22 +26,22 @@ __all__ = [
 ]
 
 
-async def get_user_perm(ctx: MessageContext) -> int:
+async def get_user_perm(session: Session) -> int:
     """返回消息发送者在当前群（私聊为全局）的权限数值。"""
 
-    return await _perm.get_user_perm(ctx)
+    return await _perm.get_user_perm(context_from_session(session))
 
 
-async def get_group_perm(ctx: MessageContext) -> int:
+async def get_group_perm(session: Session) -> int:
     """返回当前群的群等级数值。"""
 
-    return await _perm.get_group_perm(ctx)
+    return await _perm.get_group_perm(context_from_session(session))
 
 
-async def require_perm(ctx: MessageContext, level: int) -> bool:
+async def require_perm(session: Session, level: int) -> bool:
     """发送者权限不低于 ``level``（可用 :class:`Permission`）时返回 ``True``。"""
 
-    return await _perm.require_perm(ctx, level)
+    return await _perm.require_perm(context_from_session(session), level)
 
 
 def require(level: Permission):

{tenko_api-0.2.0 → tenko_api-0.3.0}/src/tenko_api/render.py

@@ -5,6 +5,6 @@
 ``None``，请回退到文本。:func:`render_or_none` 是按方法名分发的旧写法，保留兼容。
 """
 
-from tenko.render import RenderService, render_or_none, try_render
+from tenko.host.render import RenderService, render_or_none, try_render
 
 __all__ = ["RenderService", "render_or_none", "try_render"]

{tenko_api-0.2.0 → tenko_api-0.3.0}/src/tenko_api/storage.py

@@ -14,7 +14,7 @@
 
 from typing import TYPE_CHECKING, Any
 
-from tenko.host.plugin_storage import (
+from tenko.host.plugins.storage import (
     PluginStorageError,
     Store,
     StoreVersionError,
@@ -22,7 +22,7 @@ from tenko.host.plugin_storage import (
 )
 
 if TYPE_CHECKING:
-    from tenko.db.plugin_models import Model, get_session
+    from tenko.host.plugins.database import Model, get_session
 
 __all__ = [
     "Model",
@@ -36,7 +36,7 @@ __all__ = [
 
 def __getattr__(name: str) -> Any:
     if name in ("Model", "get_session"):
-        from tenko.db import plugin_models
+        from tenko.host.plugins import database as plugin_models
 
         return getattr(plugin_models, name)
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

tenko_api-0.2.0/src/tenko_api/context.py

@@ -1,6 +0,0 @@
-"""稳定插件 API：消息上下文。"""
-
-from tenko.context import MessageContext
-from tenko.plugins._common import context_from_session
-
-__all__ = ["MessageContext", "context_from_session"]

tenko_api-0.2.0/src/tenko_api/messages.py

@@ -1,34 +0,0 @@
-"""稳定插件 API：错误上报。
-
-命令处理函数直接返回 ``str`` 即可，Entari 会原样发送；混合内容（图片等）返回
-``MessageChain``。``text_message`` 自 0.2.0 起弃用，将在 1.0 前移除。
-"""
-
-import warnings
-
-from tenko.plugins._common import action_error_message, report_action_error
-
-# 把异常连同消息来源报告给 Master；投递失败只记日志，不会再抛出。
-report_error = report_action_error
-
-
-def text_message(content: str):
-    """返回只含一段文本的 ``MessageChain``。
-
-    .. deprecated:: 0.2.0
-        直接返回 ``str``；将在 1.0 前移除。
-    """
-
-    from arclet.entari import MessageChain
-    from satori import Text
-
-    warnings.warn(
-        "tenko_api.messages.text_message 自 0.2.0 起弃用，将在 1.0 前移除；"
-        "命令处理函数请直接返回 str",
-        DeprecationWarning,
-        stacklevel=2,
-    )
-    return MessageChain(Text(content))
-
-
-__all__ = ["action_error_message", "report_error", "text_message"]