nonebot-plugin-htmlrender 0.6.7__py3-none-any.whl → 0.7.0__py3-none-any.whl

nonebot_plugin_htmlrender/__init__.py

@@ -1,55 +1,180 @@
+from typing_extensions import Unpack
+
 import nonebot
+from nonebot import require
 from nonebot.log import logger
 from nonebot.plugin import PluginMetadata
 
-from nonebot_plugin_htmlrender.browser import get_browser as get_browser
-from nonebot_plugin_htmlrender.browser import get_new_page as get_new_page
-from nonebot_plugin_htmlrender.browser import init_browser as init_browser
-from nonebot_plugin_htmlrender.browser import shutdown_browser as shutdown_browser
-from nonebot_plugin_htmlrender.browser import start_browser as start_browser
-from nonebot_plugin_htmlrender.config import Config
-from nonebot_plugin_htmlrender.data_source import capture_element as capture_element
-from nonebot_plugin_htmlrender.data_source import html_to_pic as html_to_pic
-from nonebot_plugin_htmlrender.data_source import md_to_pic as md_to_pic
-from nonebot_plugin_htmlrender.data_source import template_to_html as template_to_html
-from nonebot_plugin_htmlrender.data_source import template_to_pic as template_to_pic
-from nonebot_plugin_htmlrender.data_source import text_to_pic as text_to_pic
+require("nonebot_plugin_localstore")
+
+from nonebot_plugin_htmlrender._bootstrap import (
+    _bootstrap_filehost_guard_on_import,
+    _bootstrap_optional_plugins_on_import,
+)
+from nonebot_plugin_htmlrender._bootstrap import (
+    _patch_filehost_request_headers_validator as _patch_filehost_request_headers_validator,
+)
+
+_bootstrap_optional_plugins_on_import()
+
+from nonebot_plugin_htmlrender._compat import (
+    capture_element as capture_element,
+)
+from nonebot_plugin_htmlrender._compat import (
+    get_new_page as get_new_page,
+)
+from nonebot_plugin_htmlrender._compat import (
+    html_to_pic as html_to_pic,
+)
+from nonebot_plugin_htmlrender._compat import (
+    md_to_pic as md_to_pic,
+)
+from nonebot_plugin_htmlrender._compat import (
+    shutdown_htmlrender as shutdown_htmlrender,
+)
+from nonebot_plugin_htmlrender._compat import (
+    startup_htmlrender as startup_htmlrender,
+)
+from nonebot_plugin_htmlrender._compat import (
+    template_to_html as template_to_html,
+)
+from nonebot_plugin_htmlrender._compat import (
+    template_to_pic as template_to_pic,
+)
+from nonebot_plugin_htmlrender._compat import (
+    text_to_pic as text_to_pic,
+)
+
+# Wire the render context provider so that backend operations can obtain
+# pages without importing the render module directly (avoids circular coupling).
+from nonebot_plugin_htmlrender.backend.playwright._page import (
+    register_render_context_provider as _register_ctx_provider,
+)
+from nonebot_plugin_htmlrender.backend.playwright.runtime import (
+    clear_playwright_env_vars,
+)
+from nonebot_plugin_htmlrender.backend.playwright.types import BrowserSessionKwargs
+from nonebot_plugin_htmlrender.config import Config, plugin_config
+from nonebot_plugin_htmlrender.consts import RenderBackend, RenderStartupMode
+from nonebot_plugin_htmlrender.render import (
+    available_render_backends,
+    capture_html_element,
+    get_default_render,
+    get_render,
+    get_render_backend_status,
+    get_render_context,
+    is_render_backend_available,
+    is_render_backend_registered,
+    list_render_backend_statuses,
+    probe_render,
+    registered_render_backends,
+    render_html,
+    render_markdown,
+    render_template,
+    render_template_html,
+    render_text,
+    shutdown_render,
+    startup_render,
+    unavailable_render_backends,
+)
+from nonebot_plugin_htmlrender.resources import (
+    ResourceResolveError,
+    resolve_template_vars,
+    to_resource_url,
+)
+from nonebot_plugin_htmlrender.resources.filehost import ensure_filehost_runtime_ready
+
+_register_ctx_provider(get_render_context)
+del _register_ctx_provider
 
 __plugin_meta__ = PluginMetadata(
     name="nonebot-plugin-htmlrender",
     description="通过浏览器渲染图片",
-    usage="",
+    usage=(
+        "提供 HTML/Markdown/模板渲染为图片的能力，作为库插件供其他插件调用。\n"
+        "主要接口：render_html, render_text, render_markdown, render_template 等。"
+    ),
     type="library",
     config=Config,
     homepage="https://github.com/kexue-z/nonebot-plugin-htmlrender",
-    extra={},
+    supported_adapters=None,
 )
 
 driver = nonebot.get_driver()
 
 
+_bootstrap_filehost_guard_on_import()
+
+
 @driver.on_startup
-async def init(**kwargs):
+async def init(**kwargs: Unpack[BrowserSessionKwargs]) -> None:
+    """插件启动时初始化渲染后端。"""
     logger.info("HTMLRender Starting...")
-    await init_browser(**kwargs)
-    logger.info("HTMLRender Started.")
+    if plugin_config.render_backend is None:
+        logger.info("No render backend selected; startup skipped.")
+        return
+
+    if plugin_config.render_backend == RenderBackend.PLAYWRIGHT:
+        await ensure_filehost_runtime_ready(reason="plugin_startup")
+
+    try:
+        startup_mode = plugin_config.render_startup_mode
+        if startup_mode == RenderStartupMode.OFF:
+            logger.info("Render startup skipped by configuration.")
+            return
+        if startup_mode == RenderStartupMode.WARMUP:
+            await startup_render(**kwargs)
+        else:
+            await startup_render(**kwargs)
+            await probe_render()
+    except Exception as e:
+        logger.exception("Failed to start render runtime.")
+        raise RuntimeError("Render runtime startup failed.") from e
+
+    logger.opt(colors=True).info(
+        f"HTMLRender Started with backend <cyan>{plugin_config.render_backend}</cyan>."
+    )
 
 
 @driver.on_shutdown
-async def shutdown():
+async def shutdown() -> None:
+    """插件关闭时清理渲染资源。"""
     logger.info("HTMLRender Shutting down...")
-    await shutdown_browser()
+    await shutdown_render()
+    clear_playwright_env_vars()
     logger.info("HTMLRender Shut down.")
 
 
 __all__ = [
+    "ResourceResolveError",
+    "available_render_backends",
     "capture_element",
+    "capture_html_element",
+    "get_default_render",
     "get_new_page",
+    "get_render",
+    "get_render_backend_status",
+    "get_render_context",
     "html_to_pic",
+    "is_render_backend_available",
+    "is_render_backend_registered",
+    "list_render_backend_statuses",
     "md_to_pic",
-    "shutdown_browser",
-    "start_browser",
+    "probe_render",
+    "registered_render_backends",
+    "render_html",
+    "render_markdown",
+    "render_template",
+    "render_template_html",
+    "render_text",
+    "resolve_template_vars",
+    "shutdown_htmlrender",
+    "shutdown_render",
+    "startup_htmlrender",
+    "startup_render",
     "template_to_html",
     "template_to_pic",
     "text_to_pic",
+    "to_resource_url",
+    "unavailable_render_backends",
 ]

nonebot_plugin_htmlrender/_bootstrap.py

@@ -0,0 +1,81 @@
+"""Bootstrap helpers executed at plugin import time."""
+
+from importlib import import_module
+from importlib.util import find_spec
+
+from nonebot import require
+from nonebot.log import logger
+
+from nonebot_plugin_htmlrender.config import plugin_config
+from nonebot_plugin_htmlrender.consts import RenderBackend
+from nonebot_plugin_htmlrender.resources.filehost import (
+    ensure_filehost_request_guard_installed,
+)
+
+_OPTIONAL_PLUGIN_IDS = (
+    "nonebot_plugin_filehost",
+    "nonebot_plugin_sentry",
+    "nonebot_plugin_prometheus",
+)
+
+
+def _patch_filehost_request_headers_validator() -> None:
+    """修补 filehost 请求头验证器以兼容 pydantic。"""
+    try:
+        filehost_models = import_module("nonebot_plugin_filehost.models")
+        request_headers = getattr(filehost_models, "RequestHeaders", None)
+        request_scope_info = getattr(filehost_models, "RequestScopeInfo", None)
+        if request_headers is None or request_scope_info is None:
+            return
+        if bool(getattr(request_headers, "__htmlrender_validator_patched__", False)):
+            return
+
+        raw_validate = request_headers.__dict__.get("validate")
+        if not isinstance(raw_validate, classmethod):
+            return
+
+        validate_func = raw_validate.__func__
+
+        def _compat_validate(cls, value, *args, **kwargs):  # type: ignore[no-untyped-def]
+            """兼容性验证包装器。"""
+            del args, kwargs
+            return validate_func(cls, value)
+
+        request_headers.validate = classmethod(_compat_validate)
+        request_headers.__htmlrender_validator_patched__ = True
+        model_rebuild = getattr(request_scope_info, "model_rebuild", None)
+        if callable(model_rebuild):
+            model_rebuild(force=True)
+        logger.opt(colors=True).info(
+            "Patched <c>nonebot_plugin_filehost</c> websocket scope validator for pydantic compatibility."
+        )
+    except Exception as e:
+        logger.opt(colors=True).warning(
+            "Failed to patch <c>nonebot_plugin_filehost</c> validator compatibility: <r>{e}</r>",
+            e=e,
+        )
+
+
+def _bootstrap_optional_plugins_on_import() -> None:
+    """在导入时引导可选插件。"""
+    for plugin_name in _OPTIONAL_PLUGIN_IDS:
+        if find_spec(plugin_name) is None:
+            logger.opt(colors=True).info(
+                "Optional plugin <d>{plugin_name}</d> not installed, skip bootstrap.",
+                plugin_name=plugin_name,
+            )
+            continue
+        require(plugin_name)
+        if plugin_name == "nonebot_plugin_filehost":
+            _patch_filehost_request_headers_validator()
+        logger.opt(colors=True).info(
+            "Optional plugin <c>{plugin_name}</c> bootstrapped on import.",
+            plugin_name=plugin_name,
+        )
+
+
+def _bootstrap_filehost_guard_on_import() -> None:
+    """在导入时安装 filehost 请求守卫。"""
+    if plugin_config.render_backend != RenderBackend.PLAYWRIGHT:
+        return
+    ensure_filehost_request_guard_installed(reason="plugin_import")

nonebot_plugin_htmlrender/_compat.py

@@ -0,0 +1,286 @@
+# ruff: noqa: A002, FBT001, FBT002, PTH109
+"""Backward-compatible deprecated API surface.
+
+All deprecated top-level functions are defined here. Other modules
+(``data_source``, ``browser``, ``__init__``) re-export from this
+module so that old import paths keep working.
+"""
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from os import getcwd
+from typing import Any, Literal
+from typing_extensions import Unpack, deprecated
+
+from playwright.async_api import Browser
+
+from nonebot_plugin_htmlrender.backend.playwright.operations import (
+    read_file as read_file,
+)
+from nonebot_plugin_htmlrender.backend.playwright.operations import (
+    read_tpl as read_tpl,
+)
+from nonebot_plugin_htmlrender.backend.playwright.runtime import (
+    clean_playwright_cache as _clean_playwright_cache,
+)
+from nonebot_plugin_htmlrender.backend.playwright.runtime import (
+    reconcile_legacy_playwright_cache as _reconcile_legacy_playwright_cache,
+)
+from nonebot_plugin_htmlrender.backend.playwright.types import (
+    BrowserSessionKwargs,
+    GotoKwargs,
+    HtmlPageKwargs,
+    LocatorScreenshotKwargs,
+    PageContextKwargs,
+    TemplatePageKwargs,
+)
+from nonebot_plugin_htmlrender.render import (
+    capture_html_element,
+    get_render,
+    get_render_context,
+    render_html,
+    render_markdown,
+    render_template,
+    render_template_html,
+    render_text,
+    shutdown_render,
+    startup_render,
+)
+
+
+def _require_browser(session: object) -> Browser:
+    """从渲染会话中提取 Browser 实例。
+
+    Args:
+        session: 渲染会话对象，需包含 ``handle`` 属性。
+
+    Returns:
+        会话中的 :class:`Browser` 实例。
+
+    Raises:
+        RuntimeError: 当前渲染目标不是 Browser 实例时抛出。
+    """
+    browser = getattr(session, "handle", None)
+    if isinstance(browser, Browser):
+        return browser
+    raise RuntimeError("Current render target is not a Browser instance.")
+
+
+@deprecated("`text_to_pic` is deprecated. Use `render_text` instead.")
+async def text_to_pic(
+    text: str,
+    css_path: str = "",
+    width: int = 500,
+    type: Literal["jpeg", "png"] = "png",
+    quality: int | None = None,
+    device_scale_factor: float = 2,
+    screenshot_timeout: float | None = 30_000,
+) -> bytes:
+    """已弃用：将文本渲染为图片，请使用 ``render_text``。"""
+    return await render_text(
+        text,
+        css_path=css_path,
+        width=width,
+        image_type=type,
+        quality=quality,
+        device_scale_factor=device_scale_factor,
+        screenshot_timeout=screenshot_timeout,
+    )
+
+
+@deprecated("`md_to_pic` is deprecated. Use `render_markdown` instead.")
+async def md_to_pic(
+    md: str = "",
+    md_path: str = "",
+    css_path: str = "",
+    width: int = 500,
+    type: Literal["jpeg", "png"] = "png",
+    quality: int | None = None,
+    device_scale_factor: float = 2,
+    screenshot_timeout: float | None = 30_000,
+) -> bytes:
+    """已弃用：将 Markdown 渲染为图片，请使用 ``render_markdown``。"""
+    return await render_markdown(
+        md,
+        md_path=md_path,
+        css_path=css_path,
+        width=width,
+        image_type=type,
+        quality=quality,
+        device_scale_factor=device_scale_factor,
+        screenshot_timeout=screenshot_timeout,
+    )
+
+
+@deprecated("`template_to_html` is deprecated. Use `render_template_html` instead.")
+async def template_to_html(
+    template_path: str,
+    template_name: str,
+    filters: dict[str, Any] | None = None,
+    **kwargs: Any,
+) -> str:
+    """已弃用：将模板渲染为 HTML，请使用 ``render_template_html``。"""
+    return await render_template_html(
+        template_path,
+        template_name=template_name,
+        filters=filters,
+        **kwargs,
+    )
+
+
+@deprecated("`html_to_pic` is deprecated. Use `render_html` instead.")
+async def html_to_pic(
+    html: str,
+    wait: int = 0,
+    template_path: str | None = None,
+    type: Literal["jpeg", "png"] = "png",
+    quality: int | None = None,
+    device_scale_factor: float = 2,
+    screenshot_timeout: float | None = 30_000,
+    full_page: bool = True,
+    **kwargs: Unpack[HtmlPageKwargs],
+) -> bytes:
+    """已弃用：将 HTML 渲染为图片，请使用 ``render_html``。"""
+    return await render_html(
+        html,
+        wait=wait,
+        template_path=template_path,
+        image_type=type,
+        quality=quality,
+        device_scale_factor=device_scale_factor,
+        screenshot_timeout=screenshot_timeout,
+        full_page=full_page,
+        **kwargs,
+    )
+
+
+@deprecated("`template_to_pic` is deprecated. Use `render_template` instead.")
+async def template_to_pic(
+    template_path: str,
+    template_name: str,
+    templates: dict[str, Any],
+    filters: dict[str, Any] | None = None,
+    pages: TemplatePageKwargs | None = None,
+    wait: int = 0,
+    type: Literal["jpeg", "png"] = "png",
+    quality: int | None = None,
+    device_scale_factor: float = 2,
+    screenshot_timeout: float | None = 30_000,
+) -> bytes:
+    """已弃用：将模板渲染为图片，请使用 ``render_template``。"""
+    default_pages: TemplatePageKwargs = {
+        "viewport": {"width": 500, "height": 10},
+        "base_url": f"file://{getcwd()}",
+    }
+    return await render_template(
+        template_path,
+        template_name=template_name,
+        templates=templates,
+        filters=filters,
+        pages=pages or default_pages,
+        wait=wait,
+        image_type=type,
+        quality=quality,
+        device_scale_factor=device_scale_factor,
+        screenshot_timeout=screenshot_timeout,
+    )
+
+
+@deprecated("`capture_element` is deprecated. Use `capture_html_element` instead.")
+async def capture_element(
+    url: str,
+    element: str,
+    page_kwargs: PageContextKwargs | None = None,
+    goto_kwargs: GotoKwargs | None = None,
+    screenshot_kwargs: LocatorScreenshotKwargs | None = None,
+) -> bytes:
+    """已弃用：捕获页面元素截图，请使用 ``capture_html_element``。"""
+    return await capture_html_element(
+        url,
+        element,
+        page_kwargs=page_kwargs,
+        goto_kwargs=goto_kwargs,
+        screenshot_kwargs=screenshot_kwargs,
+    )
+
+
+@deprecated("`get_new_page` is deprecated. Use `get_render_context` instead.")
+@asynccontextmanager
+async def get_new_page(
+    device_scale_factor: float = 2,
+    **kwargs: Unpack[HtmlPageKwargs],
+) -> AsyncIterator[object]:
+    """已弃用：获取新的浏览器页面，请使用 ``get_render_context``。"""
+    async with get_render_context(
+        device_scale_factor=device_scale_factor,
+        **kwargs,
+    ) as page:
+        yield page
+
+
+@deprecated("`get_browser` is deprecated. Use `get_render` instead.")
+async def get_browser(**kwargs: Unpack[BrowserSessionKwargs]) -> Browser:
+    """已弃用：获取浏览器实例，请使用 ``get_render``。"""
+    session = await get_render(**kwargs)
+    return _require_browser(session)
+
+
+@deprecated("`startup_htmlrender` is deprecated. Use `startup_render` instead.")
+async def startup_htmlrender(**kwargs: Unpack[BrowserSessionKwargs]) -> Browser:
+    """已弃用：启动 HTML 渲染引擎，请使用 ``startup_render``。"""
+    session = await startup_render(**kwargs)
+    return _require_browser(session)
+
+
+@deprecated("`shutdown_htmlrender` is deprecated. Use `shutdown_render` instead.")
+async def shutdown_htmlrender() -> None:
+    """已弃用：关闭 HTML 渲染引擎，请使用 ``shutdown_render``。"""
+    await shutdown_render()
+
+
+@deprecated("`_launch` is deprecated. Use `startup_render` instead.")
+async def _launch(
+    browser_type: str,
+    **kwargs: Unpack[BrowserSessionKwargs],
+) -> Browser:
+    """已弃用：启动浏览器，请使用 ``startup_render``。"""
+    _ = browser_type
+    return await startup_htmlrender(**kwargs)
+
+
+@deprecated(
+    "`clean_playwright_cache` from `nonebot_plugin_htmlrender.browser` is deprecated. "
+    "Use `nonebot_plugin_htmlrender.backend.playwright.runtime.reconcile_legacy_playwright_cache` instead."
+)
+def clean_playwright_cache(*, cleanup: bool) -> None:
+    """已弃用：清理 Playwright 缓存。"""
+    _clean_playwright_cache(cleanup=cleanup)
+
+
+@deprecated(
+    "`reconcile_legacy_playwright_cache` from `nonebot_plugin_htmlrender.browser` "
+    "is deprecated. Use "
+    "`nonebot_plugin_htmlrender.backend.playwright.runtime.reconcile_legacy_playwright_cache` instead."
+)
+def reconcile_legacy_playwright_cache(*, cleanup: bool) -> None:
+    """已弃用：协调旧版 Playwright 缓存目录。"""
+    _reconcile_legacy_playwright_cache(cleanup=cleanup)
+
+
+__all__ = [
+    "_launch",
+    "capture_element",
+    "clean_playwright_cache",
+    "get_browser",
+    "get_new_page",
+    "html_to_pic",
+    "md_to_pic",
+    "read_file",
+    "read_tpl",
+    "reconcile_legacy_playwright_cache",
+    "shutdown_htmlrender",
+    "startup_htmlrender",
+    "template_to_html",
+    "template_to_pic",
+    "text_to_pic",
+]

nonebot_plugin_htmlrender/backend/__init__.py

@@ -0,0 +1,42 @@
+from .base import (
+    Backend,
+    BackendCapability,
+    RenderRuntime,
+    RenderSession,
+    SupportsHtmlRenderBackend,
+)
+from .factory import (
+    BackendAvailability,
+    BackendStatus,
+    available_backends,
+    backend_statuses,
+    build_backend,
+    get_backend_status,
+    is_backend_available,
+    is_backend_registered,
+    register_backend,
+    registered_backends,
+    unavailable_backends,
+)
+from .playwright import PlaywrightBackend, PlaywrightMode
+
+__all__ = [
+    "Backend",
+    "BackendAvailability",
+    "BackendCapability",
+    "BackendStatus",
+    "PlaywrightBackend",
+    "PlaywrightMode",
+    "RenderRuntime",
+    "RenderSession",
+    "SupportsHtmlRenderBackend",
+    "available_backends",
+    "backend_statuses",
+    "build_backend",
+    "get_backend_status",
+    "is_backend_available",
+    "is_backend_registered",
+    "register_backend",
+    "registered_backends",
+    "unavailable_backends",
+]