💥 [Breaking] Deprecate get_interface method (#3)

* 🎨 Friendly to type checking
* 🩺 Require a higher version of Python
* 💥 [Breaking] Deprecate `get_interface` method
* 🐛 Fix the issue of Black going on strike

Author: Redlnn

README.md

@@ -2,7 +2,7 @@
 
 # GraiaX Playwright
 
-*适用于 Graia Project 的 Playwright 管理器*
+_适用于 Graia Project 的 Playwright 管理器_
 
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/)
@@ -53,20 +53,15 @@ launart.launch_blocking()
 from creart import create
 from launart import Launart
 from graia.ariadne.util.saya import listen
-from graiax.playwright import PlaywrightBrowser
-
-# 此处代码为没有使用 Persistent Context 的示例
-# 若使用 Persistent Context 请使用 `context = launart.get_interface(PlaywrightContext)`
-# 该方法获得的对象与 playwright.async_api.BrowserContext 兼容
+from graiax.playwright import PlaywrightService
 
 
 @listen(...)
 async def function(app: Ariadne):
     launart = create(Launart)
-    browser = launart.get_interface(PlaywrightBrowser)
-    # 此处的 browser 之用法与 playwright.async_api.Browser 无异，但要注意的是下方代码的返回值为 False。
-    # `isinstance(browser, playwright.async_api.Browser)`
-    async with browser.page(  # 此 API 启用了自动上下文管理
+    pw_service = launart.get_component(PlaywrightService)
+
+    async with pw_service.page(  # 此 API 启用了自动上下文管理
         viewport={"width": 800, "height": 10},
         device_scale_factor=1.5,
     ) as page:
@@ -77,20 +72,26 @@ async def function(app: Ariadne):
 
 ### 高级用法之一
 
-上面配合 Saya 使用的例子展示了创建一个页面的例子，但假如我们需要一个与其他页面**隔离**的新页面（例如 cookie
-等），那么我们可以使用 `browser.page(context=True)` 在创建页面时使用一个新的上下文，如下所示：
+上面配合 Saya 使用的例子展示了创建一个页面的例子，但该页面默认与其他页面互相**隔离**（例如 cookie
+等），假如我们需要一个与其他页面**隔离**的新页面，那么我们可以使用
+`page(use_global_context=False)` 在创建页面时使用一个新的上下文，如下所示：
 
 > [!NOTE]  
-> 该种用法不支持持久性上下文（Persistent Context）
+> 该种用法中的新上下文，仍受到 Playwright 启动参数的影响
+>
+> 如果你传入了例如 `viewport` 之类的只有新创建上下文或者新页面才支持的参数时，则会忽略
+> `use_global_context` 参数。此时若 `without_new_context`
+> 为 `True`（默认行为），则将会直接使用浏览器实例创建新页面。
+> 反之则会先创建新上下文再用新的上下文创建新页面，但是结束时新的页面和上下文都会被关闭。
 >
 > 更多信息详见：<https://playwright.dev/python/docs/browser-contexts>
 
 ```python
 @listen(...)
 async def function(app: Ariadne):
     launart = create(Launart)
-    browser = launart.get_interface(PlaywrightBrowser)
-    async with browser.page(new_context=True) as page:  # 此 API 启用了自动上下文管理
+    pw_service = launart.get_component(PlaywrightService)
+    async with pw_service.page(use_global_context=False) as page:  # 此 API 启用了自动上下文管理
         await page.set_content("Hello World!")
         img = await page.screenshot(type="jpeg", quality=80, full_page=True, scale="device")
     ...
@@ -102,9 +103,6 @@ async def function(app: Ariadne):
 版本起，可以在创建 PlaywrightService 时为全局的 Browser Context 指定 viewport，然后在截图时使用全局
 Browser Context 截图，如下所示：
 
-> [!NOTE]  
-> 该种用法不支持持久性上下文（Persistent Context）
-
 **机器人入口文件：**
 
 ```python
@@ -114,19 +112,68 @@ launart.add_service(PlaywrightService("chromium"))
 **Saya 模块中：**
 
 ```python
-from graiax.playwright import PlaywrightContext
+from graiax.playwright import PlaywrightService
 
 
 @listen(...)
 async def function(app: Ariadne):
     launart = create(Launart)
-    context = launart.get_interface(PlaywrightContext)
-    async with context.page() as page:  # 此 API 启用了自动上下文管理
-        await page.set_content("Hello World!")
-        img = await page.screenshot(type="jpeg", quality=80, full_page=True, scale="device")
+    pw_service = manager.get_component(PlaywrightService)
+    async with pw_service.context(...) as context:  # 此 API 启用了自动上下文管理
+        page = context.new_page()
+        try:
+            await page.set_content("Hello World!")
+            img = await page.screenshot(type="jpeg", quality=80, full_page=True, scale='device')
+        finally:
+            page.stop()
     ...
 ```
 
+### 高级用法之三
+
+通过依赖注入来获取 `PlaywrightService`，前面的代码中获取 `PlaywrightService` 都需要通过 Launart
+的 `get_component()` 方法，你也可以通过自定义一个 BCC 的 `Dispatcher` 来实现依赖注入。
+
+编写一个 `Dispatcher`：
+
+```python
+from graia.broadcast.entities.dispatcher import BaseDispatcher
+from graia.broadcast.interfaces.dispatcher import DispatcherInterface
+
+class CustomDispatcher(BaseDispatcher):
+    @classmethod
+    async def catch(cls, interface: DispatcherInterface):
+        with contextlib.suppress(TypeError):
+            if generic_isinstance(interface.event, Service):
+                manager = Launart.current()
+                return manager.get_component(interface.annotation)
+```
+
+在启动 Launart 之前获取一个 BCC 实例并对其应用这个 `Dispatcher`：
+
+```python
+from creart import it
+from graia.broadcast import Broadcast
+
+bcc = it(Broadcast)
+bcc.finale_dispatchers.append(RedbotDispatcher)
+
+...
+
+launart.launch_blocking() # 或者是 avilla.launch()
+```
+
+之后用起来就很简单了，你可以对比一下有什么不同：
+
+```python
+from graiax.playwright import PlaywrightService
+
+@listen(...)
+async def function(app: Ariadne, pw_service: PlaywrightService):
+    async with pw_service.page(...) as page:
+        ...
+```
+
 ## 许可证
 
 本项目使用 [`MIT`](./LICENSE) 许可证进行许可。