Transforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.
Python ai4sciencedocument-analysisdocxextract-datalayout-analysisocrparserpdfpdf-converterpdf-extractor-llmpdf-extractor-pretrainpdf-extractor-ragpdf-parserpptxpythonxlsx
"""WebUI 会话任务、完整状态快照和同步输出工作的取消边界。"""
from __future__ import annotations
import asyncio
import json
from collections.abc import Callable
from dataclasses import dataclass, field
from pathlib import Path
from typing import TYPE_CHECKING, Any, ParamSpec, TypeVar
from .status import STATUS_COMPLETED, STATUS_PREPARING_REQUEST, ParseStatusUpdate, StatusPanelState
if TYPE_CHECKING:
from .artifacts import RunArtifacts
P = ParamSpec("P")
T = TypeVar("T")
@dataclass(frozen=True)
class ConversionInput:
"""描述一次转换输入,不依赖 Gradio 请求或组件。"""
file_path: str | None
tier_position: int | float
page_range: str
force_ocr: bool = False
session_id: str = ""
source_id: str = ""
@dataclass(frozen=True)
class PreviewPlan:
"""描述结果预览所需路径与占位状态,由界面层决定组件更新方式。"""
preserve_source: bool
pdf_path: Path | None = None
image_path: Path | None = None
show_ready_placeholder: bool = False
@dataclass(frozen=True)
class ConversionOutput:
"""保存已物化的转换输出,不保留解析语义树。"""
artifacts: RunArtifacts
html: str
structured_json: str
preview: PreviewPlan
@dataclass(frozen=True)
class ConversionSuccess:
"""表示解析及所有输出准备均已完成。"""
output: ConversionOutput
@dataclass(frozen=True)
class ConversionFailure:
"""记录最终错误,由界面层保持既有失败响应格式。"""
message: str
@dataclass(frozen=True)
class ConversionCancelled:
"""表示任务已失效且同步工作已退出,不再应用界面结果。"""
ConversionOutcome = ConversionSuccess | ConversionFailure | ConversionCancelled
@dataclass
class ConversionRun:
"""只保留当前任务的状态和素材路径,不在会话缓存中持有解析结果。"""
run_id: str
state: StatusPanelState = field(init=False)
snapshot: str = ""
cancelled: bool = False
terminal: bool = False
task: asyncio.Task[ConversionOutput] | None = None
artifacts: dict[str, Any] | None = None
def __post_init__(self) -> None:
"""使用浏览器或 API 分配的唯一标识初始化准备阶段。"""
self.state = StatusPanelState(run_id=self.run_id)
self.publish(STATUS_PREPARING_REQUEST)
def publish(self, message: str | ParseStatusUpdate, *, at: float | None = None, final_failure: bool = False) -> None:
"""最终错误可补全已有失败快照,成功、取消和迟到通知仍受终态保护。"""
text = message.message if isinstance(message, ParseStatusUpdate) else message
replace_failure = final_failure and self.state.message.startswith("Failed:") and text.startswith("Failed:")
if self.cancelled or (self.terminal and not replace_failure) or not self.state.append(message, at=at):
return
self.terminal = self.state.message == STATUS_COMPLETED or self.state.message.startswith("Failed:")
self.snapshot = json.dumps(
{
"run_id": self.run_id,
"sequence": self.state.sequence,
"terminal": self.terminal,
"html": self.state.render(),
},
ensure_ascii=False,
)
def cancel(self) -> asyncio.Task[ConversionOutput] | None:
"""立即失效界面回执,实际任务在同步工作退出后释放执行槽。"""
self.cancelled = True
self.artifacts = None
if self.task is not None and not self.task.done():
self.task.cancel()
return self.task
class SessionConversions:
"""按 Gradio 会话隔离任务,并让所有实际解析共享一个执行槽。"""
def __init__(self) -> None:
"""在构建 WebUI 时创建注册表,不在模块导入期间分配运行资源。"""
self.runs: dict[str, ConversionRun] = {}
self.revisions: dict[str, int] = {}
self.slot = asyncio.Semaphore(1)
def start(self, session: str, run_id: str, *, revision: int | None = None) -> ConversionRun | None:
"""拒绝晚到的旧提交,替换会话任务时先取消其后台工作。"""
if revision is not None:
if revision <= self.revisions.get(session, 0):
return None
self.revisions[session] = revision
previous = self.runs.get(session)
if previous is not None:
previous.cancel()
run = ConversionRun(run_id)
self.runs[session] = run
return run
def current(self, session: str, run_id: str) -> ConversionRun | None:
"""只能读取当前会话仍有效的指定任务,避免跨任务状态混入。"""
run = self.runs.get(session)
return run if run is not None and run.run_id == run_id and not run.cancelled else None
def cancel(self, session: str, run_id: str | None = None) -> asyncio.Task[ConversionOutput] | None:
"""按回执身份取消任务,迟到的文件切换请求不能取消新任务。"""
run = self.runs.get(session)
if run is None or (run_id is not None and run.run_id != run_id):
return None
self.runs.pop(session, None)
return run.cancel()
async def await_task_completion(task: asyncio.Task[T]) -> T:
"""收到取消后仍等待实际工作退出,再传播取消以保持资源和槽位有效。"""
cancelled = False
while not task.done():
try:
await asyncio.shield(task)
except asyncio.CancelledError:
cancelled = True
except Exception:
break
if cancelled:
if not task.cancelled():
task.exception()
raise asyncio.CancelledError
return task.result()
async def run_sync_output(function: Callable[P, T], *args: P.args, **kwargs: P.kwargs) -> T:
"""同步输出线程不可强制取消,必须等它退出后才能释放外层执行槽。"""
return await await_task_completion(asyncio.create_task(asyncio.to_thread(function, *args, **kwargs)))
__all__ = [
"ConversionCancelled",
"ConversionFailure",
"ConversionInput",
"ConversionOutcome",
"ConversionOutput",
"ConversionRun",
"ConversionSuccess",
"PreviewPlan",
"SessionConversions",
"await_task_completion",
"run_sync_output",
]