nonebot-plugin-htmlrender 0.7.0a3__py3-none-any.whl → 0.7.2__py3-none-any.whl

nonebot_plugin_htmlrender/__init__.py

@@ -1,64 +1,188 @@
+from importlib import import_module
+from typing import Any
+
 import nonebot
 from nonebot import require
-
-require("nonebot_plugin_localstore")
 from nonebot.log import logger
 from nonebot.plugin import PluginMetadata
 
-from nonebot_plugin_htmlrender.browser import (
-    get_new_page,
-    shutdown_htmlrender,
-    startup_htmlrender,
+require("nonebot_plugin_localstore")
+
+from nonebot_plugin_htmlrender._bootstrap import (
+    _bootstrap_filehost_guard_on_import as _bootstrap_filehost_guard_on_import,
+)
+from nonebot_plugin_htmlrender._bootstrap import (
+    _bootstrap_optional_plugins_on_import as _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()
+_bootstrap_filehost_guard_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,
+)
+from nonebot_plugin_htmlrender.backend.factory import ensure_backend_loaded
 from nonebot_plugin_htmlrender.config import Config, plugin_config
-from nonebot_plugin_htmlrender.data_source import (
-    capture_element,
-    html_to_pic,
-    md_to_pic,
-    template_to_html,
-    template_to_pic,
-    text_to_pic,
+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.utils import _clear_playwright_env_vars
 
 __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()
 
 
+def _prepare_playwright_startup() -> None:
+    ensure_backend_loaded(RenderBackend.PLAYWRIGHT)
+    page_module = import_module("nonebot_plugin_htmlrender.backend.playwright._page")
+    register_render_context_provider = page_module.register_render_context_provider
+    register_render_context_provider(get_render_context)
+
+
 @driver.on_startup
-async def init(**kwargs):
+async def init(**kwargs: Any) -> None:
+    """插件启动时初始化渲染后端。"""
     logger.info("HTMLRender Starting...")
-    await startup_htmlrender(**kwargs)
+    if plugin_config.render_backend is None:
+        logger.info("No render backend selected; startup skipped.")
+        return
+
+    try:
+        startup_mode = plugin_config.render_startup_mode
+        if startup_mode == RenderStartupMode.OFF:
+            logger.info("Render startup skipped by configuration.")
+            return
+        if plugin_config.render_backend == RenderBackend.PLAYWRIGHT:
+            filehost_module = import_module(
+                "nonebot_plugin_htmlrender.resources.filehost"
+            )
+            ensure_filehost_runtime_ready = (
+                filehost_module.ensure_filehost_runtime_ready
+            )
+
+            _prepare_playwright_startup()
+            await ensure_filehost_runtime_ready(reason="plugin_startup")
+        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 <cyan>{plugin_config.htmlrender_browser}</cyan>."
+        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_htmlrender()
-    _clear_playwright_env_vars()
+    await shutdown_render()
+    if plugin_config.render_backend == RenderBackend.PLAYWRIGHT:
+        runtime_module = import_module(
+            "nonebot_plugin_htmlrender.backend.playwright.runtime"
+        )
+        clear_playwright_env_vars = runtime_module.clear_playwright_env_vars
+
+        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",
+    "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,122 @@
+"""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 (
+    LocalLocalResourcePolicy,
+    RemoteLocalResourcePolicy,
+    RenderBackend,
+    ResourceResolveMode,
+)
+
+_OPTIONAL_PLUGIN_IDS = (
+    "nonebot_plugin_sentry",
+    "nonebot_plugin_prometheus",
+)
+
+
+def _enum_value(raw: object) -> str:
+    """Return the string value for enum-like configuration entries."""
+    return getattr(raw, "value", str(raw))
+
+
+def _playwright_filehost_policy_enabled() -> bool:
+    """Check whether Playwright config explicitly needs filehost bootstrap."""
+    try:
+        config_module = import_module(
+            "nonebot_plugin_htmlrender.backend.playwright.config"
+        )
+        get_playwright_config = config_module.get_playwright_config
+        cfg = get_playwright_config()
+    except Exception as e:
+        logger.warning(f"Skipping filehost import bootstrap: invalid config: {e}")
+        return False
+
+    if _enum_value(cfg.resource_resolve_mode) == ResourceResolveMode.OFF.value:
+        return False
+
+    return (
+        _enum_value(cfg.remote_local_resource_policy)
+        == RemoteLocalResourcePolicy.FILEHOST.value
+        or _enum_value(cfg.local_local_resource_policy)
+        == LocalLocalResourcePolicy.FILEHOST.value
+    )
+
+
+def _patch_filehost_request_headers_validator() -> None:
+    """修补 filehost 请求头验证器以兼容 pydantic。"""
+    try:
+        # TODO: Open an upstream issue for nonebot-plugin-filehost to replace
+        # __get_validators__ with __get_pydantic_core_schema__.
+        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)
+        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
+    if not _playwright_filehost_policy_enabled():
+        return
+
+    filehost_module = import_module("nonebot_plugin_htmlrender.resources.filehost")
+    ensure_filehost_plugin_loaded = filehost_module.ensure_filehost_plugin_loaded
+    ensure_filehost_request_guard_installed = (
+        filehost_module.ensure_filehost_request_guard_installed
+    )
+
+    if not ensure_filehost_plugin_loaded(reason="plugin_import"):
+        return
+    ensure_filehost_request_guard_installed(reason="plugin_import")

nonebot_plugin_htmlrender/_compat.py

@@ -0,0 +1,308 @@
+# 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 __future__ import annotations
+
+from contextlib import asynccontextmanager
+from importlib import import_module
+from os import getcwd
+from typing import TYPE_CHECKING, Any, Literal, cast
+from typing_extensions import deprecated
+
+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,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+    from typing_extensions import Unpack
+
+    from playwright.async_api import Browser
+
+    from nonebot_plugin_htmlrender.backend.playwright.types import (
+        BrowserSessionKwargs,
+        GotoKwargs,
+        HtmlPageKwargs,
+        LocatorScreenshotKwargs,
+        PageContextKwargs,
+        TemplatePageKwargs,
+    )
+
+
+async def read_file(path: str) -> str:
+    operations = import_module(
+        "nonebot_plugin_htmlrender.backend.playwright.operations"
+    )
+    read_file_fn = operations.read_file
+
+    return await read_file_fn(path)
+
+
+async def read_tpl(path: str) -> str:
+    operations = import_module(
+        "nonebot_plugin_htmlrender.backend.playwright.operations"
+    )
+    read_tpl_fn = operations.read_tpl
+
+    return await read_tpl_fn(path)
+
+
+def _require_browser(session: object) -> Browser:
+    """从渲染会话中提取 Browser 实例。
+
+    Args:
+        session: 渲染会话对象，需包含 ``handle`` 属性。
+
+    Returns:
+        会话中的 :class:`Browser` 实例。
+
+    Raises:
+        RuntimeError: 当前渲染目标不是 Browser 实例时抛出。
+    """
+    playwright_api = import_module("playwright.async_api")
+    browser_type = playwright_api.Browser
+
+    browser = getattr(session, "handle", None)
+    if isinstance(browser, browser_type):
+        return cast("Browser", 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 缓存。"""
+    runtime = import_module("nonebot_plugin_htmlrender.backend.playwright.runtime")
+    clean_cache = runtime.clean_playwright_cache
+
+    clean_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 缓存目录。"""
+    runtime = import_module("nonebot_plugin_htmlrender.backend.playwright.runtime")
+    reconcile_cache = runtime.reconcile_legacy_playwright_cache
+
+    reconcile_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,39 @@
+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,
+)
+
+__all__ = [
+    "Backend",
+    "BackendAvailability",
+    "BackendCapability",
+    "BackendStatus",
+    "RenderRuntime",
+    "RenderSession",
+    "SupportsHtmlRenderBackend",
+    "available_backends",
+    "backend_statuses",
+    "build_backend",
+    "get_backend_status",
+    "is_backend_available",
+    "is_backend_registered",
+    "register_backend",
+    "registered_backends",
+    "unavailable_backends",
+]