nonebot-plugin-htmlrender 0.6.7__tar.gz → 0.7.0a1__tar.gz

nonebot_plugin_htmlrender-0.7.0a1/.github/workflows/_test-os-arch.yml

@@ -0,0 +1,67 @@
+on:
+  workflow_call:
+    inputs:
+      python-version:
+        required: true
+        type: string
+
+jobs:
+  test:
+    name: Test (Py ${{ inputs.python-version }} — ${{ matrix.os_label }})
+    runs-on: ${{ matrix.runs_on }}
+    strategy:
+      fail-fast: true
+      matrix:
+        include:
+          - runs_on: ubuntu-latest
+            os_label: ubuntu-latest x64
+            arch: x64
+            platform: linux
+
+          - runs_on: macos-latest
+            os_label: macos-latest arm64
+            arch: arm64
+            platform: macos
+
+          - runs_on: windows-latest
+            os_label: windows-latest x64
+            arch: x64
+            platform: windows
+
+          - runs_on: ubuntu-24.04-arm
+            os_label: ubuntu-24.04-arm arm64
+            arch: arm64
+            platform: linux
+
+    env:
+      OS: ${{ matrix.os_label }}
+      PYTHON_VERSION: ${{ inputs.python-version }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ inputs.python-version }}
+          enable-cache: true
+          cache-suffix: ${{ matrix.runs_on }}-${{ inputs.python-version }}
+
+      - name: Sync deps
+        run: uv sync --locked --all-extras --dev
+
+      - name: Install Playwright (Linux)
+        if: matrix.platform == 'linux'
+        run: uv run playwright install --with-deps && uv run playwright install --with-deps
+      - name: Install Playwright (non-Linux)
+        if: matrix.platform != 'linux'
+        run: uv run playwright install && uv run playwright install
+
+      - name: Run tests
+        run: uv run pytest -s -n auto
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          env_vars: OS,PYTHON_VERSION
+          verbose: true

nonebot_plugin_htmlrender-0.7.0a1/.github/workflows/codecov.yml

@@ -0,0 +1,20 @@
+name: Code Coverage
+
+on:
+  push:
+    branches: [ master, dev , feat/*]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  per-python:
+    name: Python ${{ matrix.python-version }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [ "3.9", "3.10", "3.11", "3.12", "3.13" ]
+
+    uses: ./.github/workflows/_test-os-arch.yml
+    with:
+      python-version: ${{ matrix.python-version }}
+    secrets: inherit

{nonebot_plugin_htmlrender-0.6.7 → nonebot_plugin_htmlrender-0.7.0a1}/.pre-commit-config.yaml

@@ -7,10 +7,10 @@ ci:
   autoupdate_commit_msg: ":arrow_up: auto update by pre-commit hooks"
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.8.2
+    rev: v0.12.12
     hooks:
-      - id: ruff
-        args: [--fix]
-        stages: [pre-commit]
       - id: ruff-format
-        stages: [pre-commit]
+      - id: ruff-check
+        args: [ --fix, --exit-non-zero-on-fix ]
+        types_or: [ python, pyi ]
+        require_serial: true

{nonebot_plugin_htmlrender-0.6.7 → nonebot_plugin_htmlrender-0.7.0a1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nonebot-plugin-htmlrender
-Version: 0.6.7
+Version: 0.7.0a1
 Summary: 通过浏览器渲染图片
 Project-URL: Homepage, https://github.com/kexue-z/nonebot-plugin-htmlrender
 Project-URL: Bug Tracker, https://github.com/kexue-z/nonebot-plugin-htmlrender/issues
@@ -31,11 +31,13 @@ Requires-Python: <4.0,>=3.9
 Requires-Dist: aiofiles>=0.8.0
 Requires-Dist: jinja2>=3.0.3
 Requires-Dist: markdown>=3.3.6
+Requires-Dist: nonebot-plugin-localstore>=0.7.4
 Requires-Dist: nonebot2>=2.4.2
 Requires-Dist: playwright>=1.48.0
 Requires-Dist: pygments>=2.10.0
 Requires-Dist: pymdown-extensions>=9.1
 Requires-Dist: python-markdown-math>=0.8
+Requires-Dist: tenacity>=9.1.2
 Description-Content-Type: text/markdown
 
 # nonebot-plugin-htmlrender

nonebot_plugin_htmlrender-0.7.0a1/nonebot_plugin_htmlrender/__init__.py

@@ -0,0 +1,64 @@
+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,
+)
+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.utils import _clear_playwright_env_vars
+
+__plugin_meta__ = PluginMetadata(
+    name="nonebot-plugin-htmlrender",
+    description="通过浏览器渲染图片",
+    usage="",
+    type="library",
+    config=Config,
+    homepage="https://github.com/kexue-z/nonebot-plugin-htmlrender",
+    extra={},
+)
+
+driver = nonebot.get_driver()
+
+
+@driver.on_startup
+async def init(**kwargs):
+    logger.info("HTMLRender Starting...")
+    await startup_htmlrender(**kwargs)
+    logger.opt(colors=True).info(
+        f"HTMLRender Started with <cyan>{plugin_config.htmlrender_browser}</cyan>."
+    )
+
+
+@driver.on_shutdown
+async def shutdown():
+    logger.info("HTMLRender Shutting down...")
+    await shutdown_htmlrender()
+    _clear_playwright_env_vars()
+    logger.info("HTMLRender Shut down.")
+
+
+__all__ = [
+    "capture_element",
+    "get_new_page",
+    "html_to_pic",
+    "md_to_pic",
+    "shutdown_htmlrender",
+    "startup_htmlrender",
+    "template_to_html",
+    "template_to_pic",
+    "text_to_pic",
+]

{nonebot_plugin_htmlrender-0.6.7 → nonebot_plugin_htmlrender-0.7.0a1}/nonebot_plugin_htmlrender/browser.py

@@ -1,5 +1,5 @@
 from collections.abc import AsyncIterator
-from contextlib import asynccontextmanager
+from contextlib import AsyncExitStack, asynccontextmanager
 from typing import Optional
 
 from nonebot.log import logger
@@ -10,10 +10,17 @@ from playwright.async_api import (
     Playwright,
     async_playwright,
 )
+from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_fixed
 
 from nonebot_plugin_htmlrender.config import plugin_config
 from nonebot_plugin_htmlrender.install import install_browser
-from nonebot_plugin_htmlrender.utils import proxy_settings, suppress_and_log, with_lock
+from nonebot_plugin_htmlrender.utils import (
+    _prepare_playwright_env_vars,
+    clean_playwright_cache,
+    proxy_settings,
+    suppress_and_log,
+    with_lock,
+)
 
 _browser: Optional[Browser] = None
 _playwright: Optional[Playwright] = None
@@ -40,22 +47,6 @@ async def _launch(browser_type: str, **kwargs) -> Browser:
     return await _browser_cls.launch(**kwargs)
 
 
-async def init_browser(**kwargs) -> Browser:
-    """
-    初始化浏览器实例。
-
-    Args:
-        **kwargs: 传递给`playwright.launch`的关键字参数。
-
-    Returns:
-        Browser: 浏览器实例。
-
-    Raises:
-        RuntimeError: 如果浏览器无法启动或安装失败。
-    """
-    return await start_browser(**kwargs)
-
-
 @asynccontextmanager
 async def get_new_page(device_scale_factor: float = 2, **kwargs) -> AsyncIterator[Page]:
     """
@@ -88,7 +79,7 @@ async def get_browser(**kwargs) -> Browser:
     if _browser and _browser.is_connected():
         return _browser
 
-    return await init_browser(**kwargs)
+    return await startup_htmlrender(**kwargs)
 
 
 async def _connect_via_cdp(**kwargs) -> Browser:
@@ -106,12 +97,12 @@ async def _connect_via_cdp(**kwargs) -> Browser:
     """
     kwargs["endpoint_url"] = plugin_config.htmlrender_connect_over_cdp
     logger.info(
-        f"正在使用 CDP 连接 Chromium({plugin_config.htmlrender_connect_over_cdp})"
+        f"Connecting to Chromium via CDP ({plugin_config.htmlrender_connect_over_cdp})"
     )
     if _playwright is not None:
         return await _playwright.chromium.connect_over_cdp(**kwargs)
     else:
-        raise RuntimeError("Playwright 未初始化")
+        raise RuntimeError("Playwright is not initialized")
 
 
 async def _connect(browser_type: str, **kwargs) -> Browser:
@@ -131,16 +122,40 @@ async def _connect(browser_type: str, **kwargs) -> Browser:
     _browser_cls: BrowserType = getattr(_playwright, browser_type)
     kwargs["ws_endpoint"] = plugin_config.htmlrender_connect
     logger.info(
-        f"正在使用 Playwright 协议连接 {browser_type}({plugin_config.htmlrender_connect})"
+        f"Connecting to {browser_type.capitalize()} via "
+        f"WebSocket endpoint: {plugin_config.htmlrender_connect}"
     )
     if _playwright is not None:
         return await _browser_cls.connect(**kwargs)
     else:
-        raise RuntimeError("Playwright 未初始化")
+        raise RuntimeError("Playwright is not initialized")
+
+
+@retry(
+    retry=retry_if_exception_type(RuntimeError),
+    stop=stop_after_attempt(4),
+    wait=wait_fixed(1),
+    reraise=True,
+    before_sleep=lambda retry_state: logger.warning(
+        f"Attempt {retry_state.attempt_number} failed, retrying..."
+    ),
+)
+async def _check_env_with_install_retry(**kwargs):
+    try:
+        return await check_playwright_env(**kwargs)
+    except RuntimeError:
+        if plugin_config.htmlrender_ci_mode:
+            raise
+        try:
+            await install_browser()
+        except Exception as e:
+            logger.error(f"Browser installation failed: {e!s}")
+            raise RuntimeError(f"install_browser failed: {e}") from e
+        raise
 
 
 @with_lock
-async def start_browser(**kwargs) -> Browser:
+async def startup_htmlrender(**kwargs) -> Browser:
     """
     启动 Playwright 浏览器实例。
 
@@ -152,8 +167,14 @@ async def start_browser(**kwargs) -> Browser:
     """
     global _browser, _playwright
 
-    await shutdown_browser()
+    await shutdown_htmlrender()
+
+    if not plugin_config.htmlrender_ci_mode:
+        clean_playwright_cache()
+        _prepare_playwright_env_vars()
+
     _playwright = await async_playwright().start()
+    logger.debug("Playwright started")
 
     if (
         plugin_config.htmlrender_browser == "chromium"
@@ -174,35 +195,100 @@ async def start_browser(**kwargs) -> Browser:
 
         if plugin_config.htmlrender_browser_executable_path:
             kwargs["executable_path"] = plugin_config.htmlrender_browser_executable_path
-        else:
             try:
-                await check_playwright_env(**kwargs)
-            except RuntimeError:
-                await install_browser()
-                await check_playwright_env(**kwargs)
-
-        _browser = await _launch(plugin_config.htmlrender_browser, **kwargs)
+                _browser = await _launch(plugin_config.htmlrender_browser, **kwargs)
+            except Exception as e:
+                raise RuntimeError(
+                    f"Failed to launch browser with executable path"
+                    f" '{plugin_config.htmlrender_browser_executable_path}': {e}"
+                ) from e
+        else:
+            _browser = await _check_env_with_install_retry(**kwargs)
 
     return _browser
 
 
-async def shutdown_browser() -> None:
-    """关闭浏览器和 Playwright 实例。"""
-    if _browser:
+async def shutdown_htmlrender() -> None:
+    is_remote = bool(
+        plugin_config.htmlrender_connect or plugin_config.htmlrender_connect_over_cdp
+    )
+    async with AsyncExitStack() as stack:
+        await _schedule_browser_shutdown(stack, is_remote=is_remote)
+        await _schedule_playwright_shutdown(stack)
+    _clear_globals()
+
+
+async def _schedule_browser_shutdown(stack: AsyncExitStack, *, is_remote: bool) -> None:
+    global _browser
+    if not _browser:
+        return
+
+    should_close = (not is_remote) and plugin_config.htmlrender_shutdown_browser_on_exit
+    if not should_close:
+        logger.info(
+            "Skipping browser shutdown due to configuration or remote connection."
+        )
+        return
+
+    browser = _browser
+    if not browser.is_connected():
+        logger.info("Browser was already disconnected.")
+        return
+
+    logger.debug("Disconnecting browser...")
+
+    async def _close_browser():
         with suppress_and_log():
-            await _browser.close()
-    if _playwright:
+            await browser.close()
+            logger.info("Disconnected browser.")
+
+    stack.push_async_callback(_close_browser)
+
+
+async def _schedule_playwright_shutdown(stack: AsyncExitStack) -> None:
+    global _playwright
+    if not _playwright:
+        return
+
+    pw = _playwright
+    logger.debug("Stopping Playwright...")
+
+    async def _stop_pw():
         with suppress_and_log():
-            await _playwright.stop()
+            await pw.stop()
+            logger.info("Playwright stopped.")
+
+    stack.push_async_callback(_stop_pw)
+
+
+def _clear_globals() -> None:
+    global _browser, _playwright
+    _browser = None
+    _playwright = None
 
 
-async def check_playwright_env(**kwargs):
-    """Check Playwright environment."""
+async def check_playwright_env(**kwargs) -> Browser:
+    """
+    检查Playwright环境，复用_launch方法避免逻辑重复。
+
+    Args:
+        **kwargs: 传递给`playwright.launch`的关键字参数。
+
+    Raises:
+        RuntimeError: 如果Playwright环境设置不正确。
+    """
     logger.info("Checking Playwright environment...")
+    global _browser, _playwright
+
     try:
-        async with async_playwright() as p:
-            await getattr(p, plugin_config.htmlrender_browser).launch(**kwargs)
+        _playwright = await async_playwright().start()
+        _browser = await _launch(plugin_config.htmlrender_browser, **kwargs)
+        logger.success("Playwright environment is set up correctly.")
+        return _browser
+
     except Exception as e:
+        await shutdown_htmlrender()
+
         raise RuntimeError(
             "Playwright environment is not set up correctly. "
             "Refer to https://playwright.dev/python/docs/intro#system-requirements"

{nonebot_plugin_htmlrender-0.6.7 → nonebot_plugin_htmlrender-0.7.0a1}/nonebot_plugin_htmlrender/config.py

@@ -1,11 +1,18 @@
+from pathlib import Path
 from typing import Any, Optional
 
 from nonebot import get_driver, get_plugin_config
 from nonebot.compat import model_validator
+from nonebot.log import logger
+import nonebot_plugin_localstore as store
 from pydantic import BaseModel, Field
 
 from nonebot_plugin_htmlrender.consts import BROWSER_CHANNEL_TYPES, BROWSER_ENGINE_TYPES
 
+plugin_cache_dir: Path = store.get_plugin_cache_dir()
+plugin_config_dir: Path = store.get_plugin_config_dir()
+plugin_data_dir: Path = store.get_plugin_data_dir()
+
 
 class Config(BaseModel):
     """插件配置类。"""
@@ -14,6 +21,26 @@ class Config(BaseModel):
         default="chromium",
         description="Playwright浏览器引擎类型，默认值为 'chromium'。",
     )
+    htmlrender_storage_path: Path = Field(
+        default=plugin_data_dir,
+        description="存储路径，不填则使用 `nonebot-plugin-localstore` 管理",
+    )
+    htmlrender_cache_path: Path = Field(
+        default=plugin_cache_dir,
+        description="缓存路径，不填则使用 `nonebot-plugin-localstore` 管理",
+    )
+    htmlrender_config_path: Path = Field(
+        default=plugin_config_dir,
+        description="配置路径，不填则使用 `nonebot-plugin-localstore` 管理",
+    )
+    htmlrender_shutdown_browser_on_exit: bool = Field(
+        default=True,
+        description="在插件关闭时关闭浏览器实例，在连接到远程浏览器时默认为 False。",
+    )
+    htmlrender_ci_mode: bool = Field(
+        default=False,
+        description="启用CI模式，跳过浏览器安装和环境变量",
+    )
     htmlrender_download_host: Optional[str] = Field(
         default=None, description="下载Playwright浏览器时的主机地址。"
     )
@@ -29,7 +56,7 @@ class Config(BaseModel):
     htmlrender_browser_channel: Optional[str] = Field(
         default=None, description="Playwright浏览器通道类型。"
     )
-    htmlrender_browser_executable_path: Optional[str] = Field(
+    htmlrender_browser_executable_path: Optional[Path] = Field(
         default=None, description="Playwright浏览器可执行文件的路径。"
     )
     htmlrender_connect_over_cdp: Optional[str] = Field(
@@ -38,7 +65,6 @@ class Config(BaseModel):
     htmlrender_connect: Optional[str] = Field(
         default=None, description="通过Playwright协议连接Playwright浏览器的端点地址。"
     )
-
     htmlrender_browser_args: Optional[str] = Field(
         default=None, description="Playwright 浏览器启动参数。"
     )
@@ -76,3 +102,8 @@ class Config(BaseModel):
 
 global_config = get_driver().config
 plugin_config = get_plugin_config(Config)
+
+if plugin_config.htmlrender_ci_mode:
+    logger.info(
+        "CI mode enabled, skipping browser installation and environment variable setup."
+    )

{nonebot_plugin_htmlrender-0.6.7 → nonebot_plugin_htmlrender-0.7.0a1}/nonebot_plugin_htmlrender/data_source.py

@@ -87,7 +87,7 @@ async def md_to_pic(
         if md_path:
             md = await read_file(md_path)
         else:
-            raise Exception("必须输入 md 或 md_path")
+            raise Exception("md or md_path must be provided")
     logger.debug(md)
     md = markdown.markdown(
         md,
@@ -174,7 +174,7 @@ async def template_to_html(
     if filters:
         for filter_name, filter_func in filters.items():
             template_env.filters[filter_name] = filter_func
-            logger.debug(f"加载自定义过滤器 {filter_name}")
+            logger.debug(f"Custom filter loaded: {filter_name}")
 
     template = template_env.get_template(template_name)
 
@@ -209,9 +209,9 @@ async def html_to_pic(
     """
     # logger.debug(f"html:\n{html}")
     if "file:" not in template_path:
-        raise Exception("template_path 应该为 file:///path/to/template")
+        raise Exception("template_path should be file:///path/to/template")
     async with get_new_page(device_scale_factor, **kwargs) as page:
-        page.on("console", lambda msg: logger.debug(f"浏览器控制台: {msg.text}"))
+        page.on("console", lambda msg: logger.debug(f"[Browser Console]: {msg.text}"))
         await page.goto(template_path)
         await page.set_content(html, wait_until="networkidle")
         await page.wait_for_timeout(wait)
@@ -266,7 +266,7 @@ async def template_to_pic(
     if filters:
         for filter_name, filter_func in filters.items():
             template_env.filters[filter_name] = filter_func
-            logger.debug(f"加载自定义过滤器 {filter_name}")
+            logger.debug(f"Custom filter loaded: {filter_name}")
 
     template = template_env.get_template(template_name)
 

{nonebot_plugin_htmlrender-0.6.7 → nonebot_plugin_htmlrender-0.7.0a1}/nonebot_plugin_htmlrender/install.py

@@ -86,7 +86,10 @@ async def download_context() -> AsyncIterator[None]:
     try:
         best_mirror = await check_mirror_connectivity()
         if best_mirror is not None:
-            logger.info(f"Using Mirror source: {best_mirror.name} ({best_mirror.url})")
+            logger.opt(colors=True).info(
+                f"Using Mirror source: <cyan>{best_mirror.name}</cyan> "
+                f"{best_mirror.url}"
+            )
             os.environ["PLAYWRIGHT_DOWNLOAD_HOST"] = best_mirror.url
         else:
             logger.info("Mirror source not available, using default")
@@ -125,30 +128,25 @@ async def read_stream(
     if stream is None:
         return ""
 
-    last_progress = ""  # 上一次显示的进度
     output = []  # 存储读取到的文本内容
 
     while True:
         try:
-            char = await stream.read(1)
-            if not char:
+            line_data = await stream.readline()
+            if not line_data:
                 break
 
-            if char == b"\r":
-                continue
+            line = line_data.decode().strip()
 
-            line = char + await stream.readuntil(b"\n")
-            text = line.decode().strip()
+            if callback:
+                try:
+                    await callback(line)
+                except UnicodeEncodeError:
+                    safe_text = "".join(c if ord(c) < 128 else "?" for c in line)
+                    await callback(safe_text)
 
-            if "|" in text and "%" in text:
-                if text != last_progress:
-                    if callback:
-                        await callback(f"Progress: {text}")
-                    last_progress = text
-            else:
-                if callback:
-                    await callback(text)
-                output.append(text)
+            if line:
+                output.append(line)
 
         except asyncio.IncompleteReadError:
             break
@@ -171,6 +169,7 @@ async def execute_install_command(timeout: int) -> tuple[bool, str]:
     try:
         logger.debug("Starting playwright install process...")
         install_signal_handler()
+
         process = await create_process(
             "playwright",
             "install",
@@ -179,13 +178,21 @@ async def execute_install_command(timeout: int) -> tuple[bool, str]:
             stdout=asyncio.subprocess.PIPE,
             stderr=asyncio.subprocess.PIPE,
         )
-        logger.debug("Process created successfully")
 
         async def stdout_callback(line: str) -> None:
-            logger.info(f"{line.strip()}")
+            line_stripped = line.strip()
+            if (
+                not line_stripped.startswith("Progress:")
+                and "|" not in line_stripped
+                and "%" not in line_stripped
+                and line_stripped
+            ):
+                logger.info(line_stripped)
 
         async def stderr_callback(line: str) -> None:
-            logger.warning(f"Install error: {line.strip()}")
+            line_stripped = line.strip()
+            if line_stripped:
+                logger.warning(f"Install error: {line_stripped}")
 
         stdout_task = asyncio.create_task(read_stream(process.stdout, stdout_callback))
         stderr_task = asyncio.create_task(read_stream(process.stderr, stderr_callback))
@@ -195,18 +202,20 @@ async def execute_install_command(timeout: int) -> tuple[bool, str]:
                 asyncio.gather(stdout_task, stderr_task), timeout=timeout
             )
         except asyncio.TimeoutError:
+            logger.error(f"Timed out ({timeout}s)")
             await terminate_process(process)
             return False, f"Timed out ({timeout}s)"
 
         await process.wait()
-        returncode = process.returncode
+        return_code = process.returncode
 
-        if returncode != 0:
-            return False, f"Exited with code {returncode}"
+        if return_code != 0:
+            return False, f"Exited with code {return_code}"
 
         return True, "Installation completed"
 
     except Exception as e:
+        logger.error(f"An error occurred during installation: {e!s}")
         return False, f"An error occurred during installation: {e!s}"