diff --git a/docs/.vuepress/public/images/add-cookie-target.png b/docs/.vuepress/public/images/add-cookie-target.png index 88d244c..4ea5fd3 100644 Binary files a/docs/.vuepress/public/images/add-cookie-target.png and b/docs/.vuepress/public/images/add-cookie-target.png differ diff --git a/docs/dev/cookie.md b/docs/dev/cookie.md index 94f47eb..93378d6 100644 --- a/docs/dev/cookie.md +++ b/docs/dev/cookie.md @@ -5,7 +5,7 @@ prev: /usage/ # Cookie 开发须知 -本项目将大部分 Cookie 相关逻辑提出到了 Site 及 ClientManger 模块中,你只需要继承相关类即可获得使用 Cookie 的能力。 +本项目将大部分 Cookie 相关逻辑提出到了 Site 及 ClientManger 模块中,只需要继承相关类即可获得使用 Cookie 的能力。 ::: tip @@ -21,7 +21,7 @@ prev: /usage/ ## 快速上手 -例如,你现在有一个这样子的 Site 类: +例如,现在有一个这样子的 Site 类: ```python class WeiboSite(Site): @@ -30,30 +30,30 @@ class WeiboSite(Site): schedule_setting = {"seconds": 3} ``` -简而言之,要让你的站点获得 Cookie 能力,只需要: +简而言之,要让站点获得 Cookie 能力,只需要: -为你的 Site 类添加一个`client_mgr`属性,值为`create_cookie_client_manager(name)`,其中`name`为你的站点名称,这是默认的 Cookie 管理器。 +为 Site 类添加一个`client_mgr`字段,值为`CookieClientManager.from_name(name)`,其中`name`为站点名称,这是默认的 Cookie 管理器。 ```python {5} class WeiboSite(Site): name = "weibo.com" schedule_type = "interval" schedule_setting = {"seconds": 3} - client_mgr = create_cookie_client_manager(name) + client_mgr = CookieClientManager.from_name(name) ``` -至此,你的站点就可以使用 Cookie 了! +至此,站点就可以使用 Cookie 了! ## 更好的体验 -为了给用户提供更好的体验,你还可以创建自己的 `ClientManager`:继承 `CookieClientManager` 并重写`validate_cookie`和`get_target_name`方法。 +为了给用户提供更好的体验,还可以创建自己的 `ClientManager`:继承 `CookieClientManager` 并重写`validate_cookie`和`get_target_name`方法。 -- `async def validate_cookie(cls, content: str) -> bool`该方法将会在 Cookie 添加时被调用,你可以在这里验证 Cookie 的有效性 -- `async def get_cookie_name(cls, content: str) -> str`该方法将会在验证 Cookie 成功后被调用,你可以在这里设置 Cookie 的名字并展示给用户 +- `async def validate_cookie(cls, content: str) -> bool`该方法将会在 Cookie 添加时被调用,可以在这里验证 Cookie 的有效性 +- `async def get_cookie_name(cls, content: str) -> str`该方法将会在验证 Cookie 成功后被调用,可以在这里设置 Cookie 的名字并展示给用户 -## 我要自己调度 Cookie +## 自定义 Cookie 调度策略 -当默认的 Cookie 调度逻辑无法满足你的需求时,你可以重写`CookieClientManager`的`_choose_cookie`方法。 +当默认的 Cookie 调度逻辑无法满足需求时,可以重写`CookieClientManager`的`_choose_cookie`方法。 目前整体的调度逻辑是: @@ -84,7 +84,7 @@ sequenceDiagram - `refresh_anonymous_cookie(cls)` 移除已有的匿名 cookie,添加一个新的匿名 cookie,应该在 CCM 初始化时调用 - `add_user_cookie(cls, content: str)` 添加用户 cookie,在这里对 Cookie 进行检查并获取 cookie_name,写入数据库 -- `_generate_hook(self, cookie: Cookie) -> callable` hook 函数生成器,用于回写请求状态到数据库 +- `_generate_hook(self, cookie: Cookie) -> Callable` hook 函数生成器,用于回写请求状态到数据库 - `_choose_cookie(self, target: Target) -> Cookie` 选择 cookie 的具体算法 - `add_user_cookie(cls, content: str, cookie_name: str | None = None) -> Cookie` 对外的接口,添加用户 cookie,内部会调用 Site 的方法进行检查 - `get_client(self, target: Target | None) -> AsyncClient` 对外的接口,获取 client,根据 target 选择 cookie @@ -100,19 +100,19 @@ sequenceDiagram 简单来说: -- 如果你需要修改 Cookie 的默认参数,可以重写`add_user_cookie`方法,这里设置你需要的属性 -- 如果你需要修改选择 Cookie 的逻辑,可以重写`_choose_cookie`方法,使用你自己的算法选择合适的 Cookie 并返回 -- 如果你需要自定义 Cookie 的格式,可以重写`valid_cookie`方法,自定义验证 Cookie 的逻辑,并重写`_assemble_client`方法,自定义将 Cookie 装配到 Client 中的逻辑 -- 如果你要在请求结束后做一些操作(例如保存此次请求的结果/状态),可以重写`_response_hook`方法,自定义请求结束后的行为 -- 如果你需要跳过一次请求,可以在 `get_client` 方法中抛出 `SkipRequestException` 异常,调度器会捕获该异常并跳过此次请求 +- 如果需要修改 Cookie 的默认参数,可以重写`add_user_cookie`方法,这里设置需要的字段 +- 如果需要修改选择 Cookie 的逻辑,可以重写`_choose_cookie`方法,使用自己的算法选择合适的 Cookie 并返回 +- 如果需要自定义 Cookie 的格式,可以重写`valid_cookie`方法,自定义验证 Cookie 的逻辑,并重写`_assemble_client`方法,自定义将 Cookie 装配到 Client 中的逻辑 +- 如果要在请求结束后做一些操作(例如保存此次请求的结果/状态),可以重写`_response_hook`方法,自定义请求结束后的行为 +- 如果需要跳过一次请求,可以在 `get_client` 方法中抛出 `SkipRequestException` 异常,调度器会捕获该异常并跳过此次请求 ## 实名 Cookie 和匿名 Cookie -部分站点所有接口都需要携带 Cookie,对于匿名用户(未登录)也会发放一个临时 Cookie,我们称为匿名 Cookie。 +部分站点所有接口都需要携带 Cookie,对于匿名用户(未登录)也会发放一个临时 Cookie,本项目称为匿名 Cookie。 -在此基础上,我们添加了用户上传 Cookie 的功能,这种 Cookie 我们称为实名 Cookie。 +在此基础上,我们添加了用户上传 Cookie 的功能,这种 Cookie 本项目称为实名 Cookie。 -匿名 Cookie 和实名 Cookie 在同一个框架下统一调度,实名 Cookie 优先级高于匿名 Cookie。为了调度,Cookie 对象有以下属性: +匿名 Cookie 和实名 Cookie 在同一个框架下统一调度,实名 Cookie 优先级高于匿名 Cookie。为了调度,Cookie 对象有以下字段: ```python # 最后使用的时刻 @@ -137,7 +137,7 @@ sequenceDiagram - **无 Target 平台的 Cookie 处理方式** - 对于不存在 Target 的平台,如小刻食堂,可以重写 add_user_cookie 方法,为用户 Cookie 设置 is_universal 属性。这样,在获取 Client 时,由于传入的 Target 为空,就只会选择 is_universal 的 cookie。实现了无 Target 平台的用户 Cookie 调度。 + 对于不存在 Target 的平台,如小刻食堂,可以重写 add_user_cookie 方法,为用户 Cookie 设置 is_universal 字段。这样,在获取 Client 时,由于传入的 Target 为空,就只会选择 is_universal 的 cookie。实现了无 Target 平台的用户 Cookie 调度。 ## 默认的调度策略 diff --git a/nonebot_bison/platform/rss.py b/nonebot_bison/platform/rss.py index 8be0867..1437965 100644 --- a/nonebot_bison/platform/rss.py +++ b/nonebot_bison/platform/rss.py @@ -10,14 +10,14 @@ from ..post import Post from .platform import NewMessage from ..types import Target, RawPost from ..utils import text_similarity -from ..utils.site import Site, create_cookie_client_manager +from ..utils.site import Site, CookieClientManager class RssSite(Site): name = "rss" schedule_type = "interval" schedule_setting = {"seconds": 30} - client_mgr = create_cookie_client_manager(name) + client_mgr = CookieClientManager.from_name(name) class RssPost(Post): diff --git a/nonebot_bison/utils/site.py b/nonebot_bison/utils/site.py index 95a5b85..82395e6 100644 --- a/nonebot_bison/utils/site.py +++ b/nonebot_bison/utils/site.py @@ -147,6 +147,15 @@ class CookieClientManager(ClientManager): client.event_hooks = {"response": [self._generate_hook(cookie)]} return client + @classmethod + def from_name(cls, site_name: str) -> type["CookieClientManager"]: + """创建一个平台特化的 CookieClientManger""" + return type( + "CookieClientManager", + (CookieClientManager,), + {"_site_name": site_name}, + ) + async def get_client_for_static(self) -> AsyncClient: return http_client() @@ -183,15 +192,6 @@ class Site(metaclass=SiteMeta): return f"[{self.name}]-{self.name}-{self.schedule_setting}" -def create_cookie_client_manager(site_name: str) -> type[CookieClientManager]: - """创建一个平台特化的 CookieClientManger""" - return type( - "CookieClientManager", - (CookieClientManager,), - {"_site_name": site_name}, - ) - - def anonymous_site(schedule_type: Literal["date", "interval", "cron"], schedule_setting: dict) -> type[Site]: return type( "AnonymousSite",