nonebot-plugin-receipts 0.1.0__py3-none-any.whl

nonebot_plugin_receipts/__init__.py

@@ -0,0 +1,97 @@
+from nonebot import get_plugin_config, on_command
+from nonebot.adapters.onebot.v11 import Message, MessageEvent
+from nonebot.matcher import Matcher
+from nonebot.params import Arg, CommandArg
+from nonebot.plugin import PluginMetadata
+
+from .config import Config
+from .renderer import ReceiptRenderError, render_receipt
+from .spooler import SpoolerClient, SpoolerError
+from .template import ReceiptTemplateContext
+
+__plugin_meta__ = PluginMetadata(
+    name="小票打印",
+    description="将发送给 Bot 的文本和图片消息通过 receipts-spooler 打印",
+    usage=(
+        "发送 /小票 后附带文本/图片，或单独发送命令后按提示再发送一条要打印的消息。"
+    ),
+    type="application",
+    config=Config,
+    supported_adapters={"~onebot.v11"},
+    extra={},
+)
+
+plugin_config = get_plugin_config(Config)
+
+ReceiptPrint = on_command(
+    "ticket",
+    aliases={"小票", "ticket", "receipt"},
+    block=True,
+    priority=10,
+)
+
+
+def _has_printable_content(message: Message) -> bool:
+    if message.extract_plain_text().strip():
+        return True
+    return any(segment.type == "image" for segment in message)
+
+
+def _build_template_context(event: MessageEvent) -> ReceiptTemplateContext:
+    sender = getattr(event, "sender", None)
+    sender_name = ""
+
+    if sender is not None:
+        sender_name = str(sender.card or sender.nickname or "").strip()
+
+    if not sender_name:
+        sender_name = str(getattr(event, "user_id", ""))
+
+    return ReceiptTemplateContext(
+        sender_name=sender_name,
+        sender_id=str(getattr(event, "user_id", "")),
+    )
+
+
+async def _submit_print_job(event: MessageEvent, message: Message) -> str:
+    rendered = await render_receipt(
+        message,
+        plugin_config,
+        _build_template_context(event),
+    )
+    client = SpoolerClient(plugin_config)
+    response = await client.push_raw(rendered)
+    queue_size = response.get("queue_size")
+    if isinstance(queue_size, int):
+        return f"打印任务已提交，当前队列长度：{queue_size}"
+    return "打印任务已提交到 receipts-spooler。"
+
+
+@ReceiptPrint.handle()
+async def handle_print_command(
+    matcher: Matcher, message: Message = CommandArg()
+) -> None:
+    if _has_printable_content(message):
+        matcher.set_arg("receipt_content", message)
+
+
+@ReceiptPrint.got(
+    "receipt_content",
+    prompt="请发送一条要打印的消息，支持文本、图片，或两者混合。",
+)
+async def handle_receipt_content(
+    event: MessageEvent,
+    receipt_content: Message = Arg("receipt_content"),
+) -> None:
+    if not _has_printable_content(receipt_content):
+        await ReceiptPrint.reject("这条消息里没有可打印的文本或图片，请重新发送。")
+
+    result: str
+    try:
+        result = await _submit_print_job(event, receipt_content)
+    except ReceiptRenderError as exc:
+        await ReceiptPrint.finish(f"生成打印内容失败：{exc}")
+    except SpoolerError as exc:
+        await ReceiptPrint.finish(f"提交到 receipts-spooler 失败：{exc}")
+
+    await ReceiptPrint.finish(result)

nonebot_plugin_receipts/config.py

@@ -0,0 +1,19 @@
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class Config(BaseModel):
+    receipts_spooler_url: str = "http://127.0.0.1:8000"
+    receipts_spooler_token: str | None = None
+    receipts_spooler_timeout: float = 5.0
+    receipt_image_fetch_timeout: float = 5.0
+    receipt_render_mode: Literal["raster", "hybrid"] = "raster"
+    receipt_printer_width: int = Field(default=576, ge=128, le=576)
+    receipt_template_path: str | None = None
+    receipt_font_path: str | None = None
+    receipt_font_size: int = Field(default=24, ge=12, le=96)
+    receipt_line_spacing: int = Field(default=6, ge=0, le=40)
+    receipt_section_gap: int = Field(default=6, ge=0, le=100)
+    receipt_feed_lines: int = Field(default=4, ge=0, le=10)
+    receipt_enable_cut: bool = True

nonebot_plugin_receipts/renderer.py

@@ -0,0 +1,479 @@
+from __future__ import annotations
+
+import base64
+import binascii
+import io
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+from urllib.parse import urlparse
+
+import httpx
+from PIL import Image, ImageDraw, ImageFont, ImageOps
+
+from .template import (
+    ReceiptTemplate,
+    ReceiptTemplateContext,
+    ReceiptTemplateError,
+    load_receipt_template,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Sequence
+
+    from nonebot.adapters.onebot.v11 import Message
+
+    from .config import Config
+
+
+MAX_RECEIPT_WIDTH = 576
+
+
+@dataclass
+class ReceiptBlock:
+    """A normalized message block used by both render modes."""
+
+    kind: str
+    text: str = ""
+    image: Image.Image | None = None
+
+
+@dataclass
+class CanvasLayout:
+    """Shared layout measurements for raster text rendering."""
+
+    width: int
+    margin: int
+    content_width: int
+    line_height: int
+    draw: ImageDraw.ImageDraw
+    font: ImageFont.FreeTypeFont | ImageFont.ImageFont
+
+
+class ReceiptRenderError(RuntimeError):
+    """Raised when receipt content cannot be rendered for printing."""
+
+    INVALID_IMAGE_DATA = "图片消息数据格式无效。"
+    INACCESSIBLE_IMAGE = "存在无法读取的图片消息，请确认适配器提供了可访问的图片 URL。"
+    IMAGE_DECODE_FAILED = "读取图片消息失败。"
+    INVALID_LAYOUT = "渲染模板边距过大，导致没有可用的打印宽度。"
+    EMPTY_CONTENT = "消息中没有可打印的内容。"
+
+    @classmethod
+    def font_load_failed(cls, font_path: str) -> "ReceiptRenderError":
+        return cls(f"无法加载字体文件: {font_path}")
+
+    @classmethod
+    def unsupported_render_mode(cls, mode: str) -> "ReceiptRenderError":
+        return cls(f"不支持的渲染模式: {mode}")
+
+
+async def render_receipt(
+    message: Message,
+    config: Config,
+    template_context: ReceiptTemplateContext | None = None,
+) -> bytes:
+    """Render a OneBot message into ESC/POS bytes using the configured mode."""
+    try:
+        template = load_receipt_template(config)
+    except ReceiptTemplateError as exc:
+        raise ReceiptRenderError(str(exc)) from exc
+
+    blocks = await _extract_blocks(message, config)
+    context = template_context or ReceiptTemplateContext()
+
+    if config.receipt_render_mode == "raster":
+        canvas = _render_raster_canvas(
+            blocks,
+            config,
+            template,
+            context,
+        )
+        return _image_to_escpos(canvas, config)
+
+    if config.receipt_render_mode == "hybrid":
+        return _render_hybrid_escpos(
+            blocks,
+            config,
+            template,
+            context,
+        )
+
+    raise ReceiptRenderError.unsupported_render_mode(config.receipt_render_mode)
+
+
+def _render_raster_canvas(
+    blocks: Sequence[ReceiptBlock],
+    config: Config,
+    template: ReceiptTemplate,
+    template_context: ReceiptTemplateContext,
+) -> Image.Image:
+    """Render all receipt blocks into a single raster canvas."""
+    layout = _build_canvas_layout(config, template)
+
+    sections: list[Image.Image] = []
+    total_height = layout.margin
+
+    for block in blocks:
+        if block.kind == "text" and block.text:
+            if section := _build_wrapped_text_section(block.text, layout):
+                sections.append(section)
+                total_height += section.height
+            continue
+
+        if block.kind == "image" and block.image is not None:
+            section = _build_image_section(
+                block.image,
+                layout.width,
+                layout.content_width,
+                config.receipt_section_gap,
+            )
+            sections.append(section)
+            total_height += section.height
+
+    if not sections:
+        raise ReceiptRenderError(ReceiptRenderError.EMPTY_CONTENT)
+
+    footer_text = template.render_footer_text(template_context)
+    if footer_text:
+        footer = _build_wrapped_text_section(footer_text, layout)
+        if footer is not None:
+            sections.append(footer)
+            total_height += footer.height + layout.margin
+
+    canvas = Image.new("L", (layout.width, total_height), color=255)
+    top = layout.margin
+    for section in sections:
+        canvas.paste(section, (0, top))
+        top += section.height
+
+    return canvas
+
+
+def _render_hybrid_escpos(
+    blocks: Sequence[ReceiptBlock],
+    config: Config,
+    template: ReceiptTemplate,
+    template_context: ReceiptTemplateContext,
+) -> bytes:
+    """Render text natively and images as raster sections in message order."""
+    width = min(config.receipt_printer_width, MAX_RECEIPT_WIDTH)
+    margin = template.margin
+    content_width = width - margin * 2
+    if content_width <= 0:
+        raise ReceiptRenderError(ReceiptRenderError.INVALID_LAYOUT)
+
+    font = _load_font(config)
+    probe = Image.new("L", (width, 10), color=255)
+    draw = ImageDraw.Draw(probe)
+    avg_char_width = max(1, _measure_text(draw, "AA", font) // 2)
+    width_chars = max(1, content_width // avg_char_width)
+
+    chunks: list[bytes] = [b"\x1b@"]
+
+    for block in blocks:
+        if block.kind == "text" and block.text:
+            lines = _wrap_native_text(block.text, width_chars)
+            if lines:
+                chunks.append(_encode_native_text(lines))
+            continue
+
+        if block.kind == "image" and block.image is not None:
+            section = _build_image_section(
+                block.image,
+                width,
+                content_width,
+                config.receipt_section_gap,
+            )
+            chunks.append(_image_to_escpos(section, config, initialize=False))
+
+    footer_text = template.render_footer_text(template_context)
+    if footer_text:
+        chunks.append(_encode_native_text(_wrap_native_text(footer_text, width_chars)))
+
+    if config.receipt_feed_lines:
+        chunks.append(b"\n" * config.receipt_feed_lines)
+    if config.receipt_enable_cut:
+        chunks.append(b"\x1dV\x00")
+    return b"".join(chunks)
+
+
+def _measure_text(
+    draw: ImageDraw.ImageDraw,
+    text: str,
+    font: ImageFont.FreeTypeFont | ImageFont.ImageFont,
+) -> int:
+    """Measure text width in pixels using the active PIL font."""
+    sample = text or " "
+    left, _, right, _ = draw.textbbox((0, 0), sample, font=font)
+    return int(right - left)
+
+
+def _wrap_text(
+    text: str,
+    draw: ImageDraw.ImageDraw,
+    font: ImageFont.FreeTypeFont | ImageFont.ImageFont,
+    max_width: int,
+) -> list[str]:
+    """Wrap raster text using pixel measurements from the active font."""
+    return _wrap_by_measure(
+        text,
+        max_width,
+        lambda candidate: _measure_text(draw, candidate, font),
+    )
+
+
+def _wrap_by_measure(
+    text: str,
+    max_width: int,
+    measure: Callable[[str], int],
+) -> list[str]:
+    """Wrap text by repeatedly measuring candidate lines."""
+    wrapped: list[str] = []
+    for paragraph in text.splitlines() or [""]:
+        if not paragraph:
+            wrapped.append("")
+            continue
+
+        current = ""
+        for char in paragraph:
+            candidate = current + char
+            if current and measure(candidate) > max_width:
+                wrapped.append(current)
+                current = char
+            else:
+                current = candidate
+        if current:
+            wrapped.append(current)
+    return wrapped
+
+
+def _measure_line_height(
+    draw: ImageDraw.ImageDraw,
+    font: ImageFont.FreeTypeFont | ImageFont.ImageFont,
+) -> int:
+    """Estimate a readable line height for the current font."""
+    _, top, _, bottom = draw.textbbox((0, 0), "Ag", font=font)
+    return max(1, int(bottom - top))
+
+
+def _flush_text_block(blocks: list[ReceiptBlock], text_buffer: list[str]) -> None:
+    """Flush accumulated text into a normalized text block."""
+    text = "".join(text_buffer)
+    if text:
+        blocks.append(ReceiptBlock(kind="text", text=text))
+        text_buffer.clear()
+
+
+async def _fetch_image_bytes(
+    client: httpx.AsyncClient,
+    url: str,
+) -> bytes:
+    """Download image bytes from a remote URL."""
+    try:
+        response = await client.get(url)
+        response.raise_for_status()
+    except httpx.HTTPError as exc:
+        raise ReceiptRenderError(ReceiptRenderError.INACCESSIBLE_IMAGE) from exc
+    return response.content
+
+
+async def _extract_image_block(
+    client: httpx.AsyncClient,
+    file_value: str,
+    url: str,
+) -> ReceiptBlock:
+    """Normalize one image message segment into a grayscale image block."""
+    raw_bytes: bytes | None = None
+
+    if url:
+        raw_bytes = await _fetch_image_bytes(client, url)
+    elif file_value.startswith("base64://"):
+        try:
+            raw_bytes = base64.b64decode(
+                file_value.removeprefix("base64://"),
+                validate=True,
+            )
+        except binascii.Error as exc:
+            raise ReceiptRenderError(ReceiptRenderError.INVALID_IMAGE_DATA) from exc
+    elif file_value and urlparse(file_value).scheme in {"http", "https"}:
+        raw_bytes = await _fetch_image_bytes(client, file_value)
+
+    if raw_bytes is None:
+        raise ReceiptRenderError(ReceiptRenderError.INACCESSIBLE_IMAGE)
+
+    try:
+        image = Image.open(io.BytesIO(raw_bytes))
+        return ReceiptBlock(kind="image", image=image.convert("L"))
+    except OSError as exc:
+        raise ReceiptRenderError(ReceiptRenderError.IMAGE_DECODE_FAILED) from exc
+
+
+async def _extract_blocks(message: Message, config: Config) -> list[ReceiptBlock]:
+    """Convert a mixed OneBot message into ordered text and image blocks."""
+    blocks: list[ReceiptBlock] = []
+    async with httpx.AsyncClient(timeout=config.receipt_image_fetch_timeout) as client:
+        text_buffer: list[str] = []
+
+        for segment in message:
+            if segment.type == "text":
+                text_buffer.append(str(segment.data.get("text") or ""))
+                continue
+
+            if segment.type != "image":
+                continue
+
+            _flush_text_block(blocks, text_buffer)
+            url = str(segment.data.get("url") or "").strip()
+            file_value = str(segment.data.get("file") or "").strip()
+            blocks.append(await _extract_image_block(client, file_value, url))
+
+        _flush_text_block(blocks, text_buffer)
+
+    return blocks
+
+
+def _resize_image(image: Image.Image, target_width: int) -> Image.Image:
+    """Resize an image to fit the printable width while preserving aspect ratio."""
+    if image.width <= target_width:
+        return image
+    new_height = max(1, int(image.height * (target_width / image.width)))
+    return image.resize((target_width, new_height), Image.Resampling.LANCZOS)
+
+
+def _load_font(config: Config) -> ImageFont.FreeTypeFont | ImageFont.ImageFont:
+    """Load the configured font or fall back to Pillow's default font."""
+    if config.receipt_font_path:
+        try:
+            return ImageFont.truetype(
+                config.receipt_font_path,
+                size=config.receipt_font_size,
+            )
+        except OSError as exc:
+            raise ReceiptRenderError.font_load_failed(config.receipt_font_path) from exc
+    return ImageFont.load_default()
+
+
+def _build_canvas_layout(config: Config, template: ReceiptTemplate) -> CanvasLayout:
+    """Prepare common layout values used by raster text rendering."""
+    width = min(config.receipt_printer_width, MAX_RECEIPT_WIDTH)
+    margin = template.margin
+    content_width = width - margin * 2
+    if content_width <= 0:
+        raise ReceiptRenderError(ReceiptRenderError.INVALID_LAYOUT)
+
+    font = _load_font(config)
+    probe = Image.new("L", (width, 10), color=255)
+    draw = ImageDraw.Draw(probe)
+    line_height = _measure_line_height(draw, font) + config.receipt_line_spacing
+    return CanvasLayout(
+        width=width,
+        margin=margin,
+        content_width=content_width,
+        line_height=line_height,
+        draw=draw,
+        font=font,
+    )
+
+
+def _build_wrapped_text_section(
+    text: str,
+    layout: CanvasLayout,
+) -> Image.Image | None:
+    """Render wrapped text into a raster section image."""
+    lines = _wrap_text(text, layout.draw, layout.font, layout.content_width)
+    if not lines:
+        return None
+
+    text_height = max(layout.line_height * len(lines), layout.line_height)
+    text_image = Image.new(
+        "L",
+        (layout.width, text_height + layout.margin),
+        color=255,
+    )
+    text_draw = ImageDraw.Draw(text_image)
+    y = 0
+    for line in lines:
+        text_draw.text((layout.margin, y), line, fill=0, font=layout.font)
+        y += layout.line_height
+    return text_image
+
+
+def _build_image_section(
+    image: Image.Image,
+    width: int,
+    content_width: int,
+    section_gap: int,
+) -> Image.Image:
+    """Render one image block into a raster section with gap padding."""
+    fitted = _resize_image(image, content_width)
+    framed = Image.new(
+        "L",
+        (width, fitted.height + section_gap),
+        color=255,
+    )
+    offset_x = (width - fitted.width) // 2
+    framed.paste(fitted, (offset_x, 0))
+    return framed
+
+
+def _wrap_native_text(text: str, width_chars: int) -> list[str]:
+    """Wrap text for native printer output using ASCII=1 and non-ASCII=2 width."""
+    return _wrap_by_measure(
+        text,
+        width_chars,
+        lambda candidate: sum(1 if char.isascii() else 2 for char in candidate),
+    )
+
+
+def _encode_native_text(lines: Sequence[str]) -> bytes:
+    """Encode wrapped lines using a broad Chinese-compatible printer code page."""
+    chunks: list[bytes] = []
+    for line in lines:
+        chunks.append(line.encode("gb18030", errors="replace"))
+        chunks.append(b"\n")
+    return b"".join(chunks)
+
+
+def _image_to_escpos(
+    image: Image.Image, config: Config, *, initialize: bool = True
+) -> bytes:
+    """Convert a raster image into ESC/POS raster bit image commands."""
+    grayscale = ImageOps.autocontrast(image).convert("L")
+    bw = grayscale.convert("1", dither=Image.Dither.FLOYDSTEINBERG)
+    width, height = bw.size
+    width_bytes = (width + 7) // 8
+    raster_data = bytearray()
+
+    for y in range(height):
+        row_offset = y * width_bytes
+        raster_data.extend(b"\x00" * width_bytes)
+        for x in range(width):
+            if bw.getpixel((x, y)) == 0:
+                raster_data[row_offset + (x // 8)] |= 0x80 >> (x % 8)
+
+    chunks: list[bytes] = [b"\x1b@"] if initialize else []
+    max_chunk_height = 255
+    for start in range(0, height, max_chunk_height):
+        chunk_height = min(max_chunk_height, height - start)
+        chunk = bytearray()
+        for y in range(start, start + chunk_height):
+            offset = y * width_bytes
+            chunk.extend(raster_data[offset : offset + width_bytes])
+        chunks.append(
+            b"\x1d\x76\x30\x00"
+            + bytes(
+                (
+                    width_bytes & 0xFF,
+                    (width_bytes >> 8) & 0xFF,
+                    chunk_height & 0xFF,
+                    (chunk_height >> 8) & 0xFF,
+                )
+            )
+            + bytes(chunk)
+        )
+
+    if initialize and config.receipt_feed_lines:
+        chunks.append(b"\n" * config.receipt_feed_lines)
+    if initialize and config.receipt_enable_cut:
+        chunks.append(b"\x1dV\x00")
+    return b"".join(chunks)

nonebot_plugin_receipts/spooler.py

@@ -0,0 +1,51 @@
+import base64
+import json
+from typing import Any
+
+import httpx
+
+from .config import Config
+
+
+class SpoolerError(RuntimeError):
+    INVALID_RESPONSE = "receipts-spooler 返回了不可识别的响应。"
+
+
+class SpoolerClient:
+    def __init__(self, config: Config) -> None:
+        self._config = config
+
+    async def push_raw(self, payload: bytes) -> dict[str, Any]:
+        url = self._config.receipts_spooler_url.rstrip("/")
+        headers: dict[str, str] = {}
+        if self._config.receipts_spooler_token:
+            headers["X-Spooler-Token"] = self._config.receipts_spooler_token
+
+        body = {
+            "data_type": "escpos_base64",
+            "payload": base64.b64encode(payload).decode("ascii"),
+        }
+
+        try:
+            async with httpx.AsyncClient(
+                timeout=self._config.receipts_spooler_timeout
+            ) as client:
+                response = await client.post(
+                    f"{url}/api/v1/task/push_raw",
+                    json=body,
+                    headers=headers,
+                )
+                response.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            detail = exc.response.text.strip() or str(exc)
+            raise SpoolerError(detail) from exc
+        except httpx.HTTPError as exc:
+            raise SpoolerError(str(exc)) from exc
+
+        try:
+            data = response.json()
+        except json.JSONDecodeError as exc:
+            raise SpoolerError(SpoolerError.INVALID_RESPONSE) from exc
+        if not isinstance(data, dict):
+            raise SpoolerError(SpoolerError.INVALID_RESPONSE)
+        return data

nonebot_plugin_receipts/template.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, Field, ValidationError
+
+if TYPE_CHECKING:
+    from .config import Config
+
+
+class ReceiptTemplateContext(BaseModel):
+    sender_name: str = ""
+    sender_id: str = ""
+
+
+class ReceiptTemplate(BaseModel):
+    """Layout template for receipt rendering."""
+
+    margin: int = Field(default=16, ge=0, le=64)
+    footer_enabled: bool = True
+    footer_text: str = "{sender_name}({sender_id}) @ {timestamp}"
+    footer_timestamp_format: str = "%Y-%m-%d %H:%M:%S"
+    footer_timezone_offset_hours: int = Field(default=8, ge=-12, le=14)
+
+    def render_footer_text(self, context: ReceiptTemplateContext) -> str:
+        if not self.footer_enabled:
+            return ""
+
+        timestamp = datetime.now(
+            timezone(timedelta(hours=self.footer_timezone_offset_hours))
+        ).strftime(self.footer_timestamp_format)
+        try:
+            return self.footer_text.format(
+                timestamp=timestamp,
+                sender_name=context.sender_name,
+                sender_id=context.sender_id,
+            )
+        except (KeyError, ValueError) as exc:
+            raise ReceiptTemplateError(
+                ReceiptTemplateError.INVALID_FOOTER_TEXT
+            ) from exc
+
+
+class ReceiptTemplateError(RuntimeError):
+    """Raised when a receipt template cannot be loaded."""
+
+    INVALID_FOOTER_TEXT = (
+        "渲染模板 footer_text 不合法，只能使用"
+        " {timestamp}、{sender_name}、{sender_id} 占位符。"
+    )
+
+    @classmethod
+    def read_failed(cls, path: str) -> "ReceiptTemplateError":
+        return cls(f"无法读取渲染模板文件: {path}")
+
+    @classmethod
+    def invalid_json(cls, path: str) -> "ReceiptTemplateError":
+        return cls(f"渲染模板文件不是合法的 JSON: {path}")
+
+    @classmethod
+    def invalid_data(cls, path: str) -> "ReceiptTemplateError":
+        return cls(f"渲染模板配置无效: {path}")
+
+
+def load_receipt_template(config: Config) -> ReceiptTemplate:
+    if not config.receipt_template_path:
+        return ReceiptTemplate()
+
+    path = Path(config.receipt_template_path)
+    try:
+        raw_text = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ReceiptTemplateError.read_failed(str(path)) from exc
+
+    try:
+        data = json.loads(raw_text)
+    except json.JSONDecodeError as exc:
+        raise ReceiptTemplateError.invalid_json(str(path)) from exc
+
+    if not isinstance(data, dict):
+        raise ReceiptTemplateError.invalid_data(str(path))
+
+    try:
+        return ReceiptTemplate.model_validate(data)
+    except ValidationError as exc:
+        raise ReceiptTemplateError.invalid_data(str(path)) from exc

nonebot_plugin_receipts-0.1.0.dist-info/METADATA

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: nonebot_plugin_receipts
+Version: 0.1.0
+Summary: NoneBot2 plugin for sending text and image messages to receipts-spooler
+Project-URL: homepage, https://github.com/Effect-Wei/nonebot_plugin_receipts
+Project-URL: repository, https://github.com/Effect-Wei/nonebot_plugin_receipts
+Project-URL: documentation, https://github.com/Effect-Wei/nonebot_plugin_receipts#readme
+Requires-Python: <4.0,>=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: nonebot2[fastapi,httpx]>=2.5.0
+Requires-Dist: nonebot-adapter-onebot>=2.4.6
+Requires-Dist: pillow>=12.2.0
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pyright[nodejs]; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+
+# nonebot_plugin_receipts
+
+一个面向 NoneBot2 的独立插件，用来把发送给 Bot 的文本和图片消息转成 ESC/POS 原始打印数据，再投递给 [`receipts-spooler`](https://github.com/Effect-Wei/receipts-spooler)。
+
+当前实现面向 OneBot v11 适配器，适合 QQ 机器人消息场景。
+
+## 功能
+
+- 提供 `ticket`、`小票`、`receipt` 指令，三者互为别名
+- 支持命令后直接附带文本和图片
+- 如果命令后没有内容，会继续追问下一条消息
+- 将文本和图片合成为一张热敏小票图，再编码为 ESC/POS 栅格打印命令
+- 通过 `receipts-spooler` 的 `/api/v1/task/push_raw` 接口提交打印任务
+
+## 安装
+
+```powershell
+cd nonebot_plugin_receipts
+pip install -e .
+```
+
+然后在你的 NoneBot2 项目中加载插件：
+
+```python
+nonebot.load_plugin("nonebot_plugin_receipts")
+```
+
+## 配置
+
+插件通过 NoneBot 全局配置读取以下环境变量：
+
+| 变量                          | 默认值                  | 说明                                  |
+| ----------------------------- | ----------------------- | ------------------------------------- |
+| `RECEIPTS_SPOOLER_URL`        | `http://127.0.0.1:8000` | `receipts-spooler` 服务地址           |
+| `RECEIPTS_SPOOLER_TOKEN`      | 空                      | 对应 `X-Spooler-Token`                |
+| `RECEIPTS_SPOOLER_TIMEOUT`    | `5.0`                   | 调用 spooler 的 HTTP 超时             |
+| `RECEIPT_IMAGE_FETCH_TIMEOUT` | `5.0`                   | 下载图片消息内容时的 HTTP 超时        |
+| `RECEIPT_RENDER_MODE`         | `raster`                | 渲染模式，可选 `raster`/`hybrid`      |
+| `RECEIPT_PRINTER_WIDTH`       | `576`                   | 小票像素宽度，最大 `576`              |
+| `RECEIPT_TEMPLATE_PATH`       | 空                      | 可选，指向渲染模板 JSON 文件          |
+| `RECEIPT_FONT_PATH`           | 空                      | 可选，建议配置支持中文的 TTF/OTF 字体 |
+| `RECEIPT_FONT_SIZE`           | `24`                    | 文本字号                              |
+| `RECEIPT_LINE_SPACING`        | `6`                     | 文本行距                              |
+| `RECEIPT_SECTION_GAP`         | `6`                     | 文本和图片之间的垂直间距              |
+| `RECEIPT_FEED_LINES`          | `4`                     | 打印后走纸行数                        |
+| `RECEIPT_ENABLE_CUT`          | `true`                  | 是否附加切纸命令                      |
+
+### 渲染模式
+
+- `raster`：把文本和图片一起渲染成整张位图，再输出 ESC/POS 栅格数据，兼容性最好。
+- `hybrid`：文本走打印机原生字符输出，图片仍走位图，能减少大量文字被渲染成图片。
+
+`hybrid` 模式下，中文是否正常输出取决于打印机对中英文字符集的支持情况。
+
+### 渲染模板
+
+如果你想单独调整小票布局，可以配置 `RECEIPT_TEMPLATE_PATH` 指向一个 JSON 文件。项目根目录里附带了一个示例文件 [`receipt_template.example.json`](receipt_template.example.json)。
+
+支持的模板字段：
+
+| 字段                           | 默认值                                     | 说明                   |
+| ------------------------------ | ------------------------------------------ | ---------------------- |
+| `margin`                       | `16`                                       | 左右和顶部内边距       |
+| `footer_enabled`               | `true`                                     | 是否渲染页脚           |
+| `footer_text`                  | `{sender_name}({sender_id}) @ {timestamp}` | 页脚文字模板           |
+| `footer_timestamp_format`      | `%Y-%m-%d %H:%M:%S`                        | 时间格式               |
+| `footer_timezone_offset_hours` | `8`                                        | 页脚时间使用的时区偏移 |
+
+`footer_text` 支持这些占位符：
+
+- `{timestamp}`
+- `{sender_name}`
+- `{sender_id}`
+
+示例：
+
+```json
+{
+  "margin": 24,
+  "footer_enabled": true,
+  "footer_text": "{sender_name}({sender_id}) 打印于 {timestamp}",
+  "footer_timestamp_format": "%Y/%m/%d %H:%M",
+  "footer_timezone_offset_hours": 8
+}
+```
+
+## 使用
+
+直接在命令后附带内容：
+
+```text
+/小票 今晚睡大觉
+```
+
+或者：
+
+1. 发送 `/小票`
+2. 按提示继续发送一条包含文本、图片或两者混合的消息
+
+插件会把纯文本和图片消息段一起打印，并在提交成功后回复当前队列长度。
+
+## 注意事项
+
+- 如果你需要打印中文，最好配置 `RECEIPT_FONT_PATH` 指向支持中文的字体文件。
+- 图片消息需要 OneBot 事件中带有可访问的 `url`，或消息段 `file` 为 `base64://...` / `http(s)://...`。
+- 本插件不会直接连接打印机，只负责把任务提交到 `receipts-spooler`。

nonebot_plugin_receipts-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+nonebot_plugin_receipts/__init__.py,sha256=tpKyLkhTCOsOEqhSfDGIbFnLFeYpdulw82pHCjZYRks,3095
+nonebot_plugin_receipts/config.py,sha256=slOHZfld5pKjZeD2Q2QpqSHOOOcbb8EsddiyfpgqkbI,781
+nonebot_plugin_receipts/renderer.py,sha256=Fq-3iCOUMt5C0I76pby_0zyrlSPtxDSpcNFi94sWwlo,15239
+nonebot_plugin_receipts/spooler.py,sha256=EziTDisUmJtuZS9QtTPNWJV_fruSYjc9vHHV4kWSuGg,1623
+nonebot_plugin_receipts/template.py,sha256=QwOO_E51DcD4MaZcvV8_3492cEse3DhQEbcPuH4ROtw,2825
+nonebot_plugin_receipts-0.1.0.dist-info/METADATA,sha256=iK2yfr-gGIRbEirIp6rb3Jdz_Jd0Z2KIYRBEAvuwr9w,5605
+nonebot_plugin_receipts-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+nonebot_plugin_receipts-0.1.0.dist-info/top_level.txt,sha256=sL2lEyveuzLuEU9aWF8an5t5LblzdrHIGWMLnlEk1Q4,24
+nonebot_plugin_receipts-0.1.0.dist-info/RECORD,,

nonebot_plugin_receipts-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

nonebot_plugin_receipts-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+nonebot_plugin_receipts