快速开始
Python 文档转换库
在 Python 应用程序加入具类型的 DOCX、PDF、HTML、Markdown、YAML、JSON 与图片转换，并使用引擎中立的请求、结果、批量及诊断。
库概览
公开 API 使用引擎中立的具类型模型。请依集成需求选择最精简的入口。
| 入口 | 适用场景 |
|---|---|
| ConversionRequest.from_source | 由路径推断并验证来源格式 |
| convert(request) | 执行单一转换并获取 ConversionResult |
| DocumentConversionService | 注入引擎，或直接使用 service 方法 |
| convert_batch(requests) | 执行依序且失败隔离的转换 |
| probe_engines() | 探索 renderer 可用性与注释能力 |
| result.to_dict() | 产生稳定、JSON 兼容的结果数据 |
单文件转换
ConversionRequest.from_source 会验证允许的扩展名并推断来源格式。convert 对一般转换失败会返回 ConversionResult，而非直接抛出异常，因此读取 artifacts 前请先检查 success 与 error。ConversionError 用于无效请求及相关契约错误。
from pathlib import Path
from gordon_doc_converter import ConversionRequest, convert
result = convert(ConversionRequest.from_source(Path('report.docx')))
if not result.success:
raise RuntimeError(result.error.message if result.error else 'conversion failed')
print(result.artifacts[0].path)选项与严格策略
使用 ConversionOptions 设置输出路径、覆写行为、超时、部署模式、明确引擎、注释处理、metadata detail 与图像设置。EngineName 是严格选择：指定的引擎不可用时，会得到可诊断的失败，而不是静默改用其他引擎。若转换路径支持，ArtifactType 可要求 PDF、DOCX、ODT、HTML、Markdown、YAML、JSON 或页面图像。
from pathlib import Path
from gordon_doc_converter import (
ArtifactType, ConversionOptions, ConversionRequest, convert,
)
request = ConversionRequest.from_source(
Path('report.docx'),
artifacts=(ArtifactType.YAML, ArtifactType.JSON),
options=ConversionOptions(output_path=Path('report')),
)
result = convert(request)批量、探测与结果处理
DocumentConversionService 支持引擎的 dependency injection 与依环境执行的 orchestration。convert_batch 会依序处理请求并隔离失败。probe_engines 返回 EngineProbeResult，包含可用性、版本、支持的修订模式与注释模式。结果可通过 to_dict() 序列化为稳定、JSON 兼容的基本类型，适合日志或 API；请勿记录文档内容或敏感路径。
from gordon_doc_converter import DocumentConversionService
service = DocumentConversionService()
for probe in service.probe_engines():
print(probe.engine, probe.available, probe.version)
results = service.convert_batch(requests)
payload = [result.to_dict() for result in results]