跳转到主要内容
xparse-client 是 TextIn xParse 的官方 Python SDK，提供同步解析、异步任务管理、类型安全的响应模型和完善的错误处理，基于最新版 API 封装。

​
安装

pip install xparse-client
系统要求： Python >= 3.9

​
认证与初始化

SDK 支持多种认证方式（优先级：构造参数 > 环境变量 > .env 文件）： 
import os
os.environ["TEXTIN_APP_ID"] = "your-app-id"
os.environ["TEXTIN_SECRET_CODE"] = "your-secret-code"

from xparse_client import XParseClient
client = XParseClient()
推荐使用环境变量方式，避免在代码中硬编码密钥。

​
API 概览

方法说明返回类型
client.parse.run()同步解析文档ParseResponse
client.parse.create_job()创建异步解析任务AsyncJobResponse
client.parse.get_job()查询异步任务状态JobStatusResponse
client.parse.wait_job()轮询等待异步任务完成JobStatusResponse

​
同步解析

适用于一般大小的文档，直接返回解析结果。 
from xparse_client import XParseClient, ParseConfig, Capabilities, Scope

client = XParseClient()

with open("document.pdf", "rb") as f:
    result = client.parse.run(
        file=f,
        filename="document.pdf",
        config=ParseConfig(
            capabilities=Capabilities(
                include_table_structure=True,  # 返回表格详细结构
                include_image_data=True,       # 返回图片数据
                title_tree=True,               # 返回目录树
                pages=True,                    # 返回页面元信息
            ),
            scope=Scope(page_range="1-10"),     # 指定解析页面范围
        ),
    )

# 输出 Markdown
print(result.markdown)

# 遍历元素
for el in result.elements:
    print(f"[{el.type}] p{el.page_number}: {el.text[:60]}")

​
解析配置参数

ParseConfig 支持以下配置：
参数类型说明
capabilities.include_hierarchybool返回元素父子关系
capabilities.include_inline_objectsbool返回行内对象（公式、手写体、复选框）
capabilities.include_char_detailsbool返回字符级坐标和置信度
capabilities.include_image_databool返回图片 URL、MIME 类型、OCR 文本
capabilities.include_table_structurebool返回表格行/列/单元格详细结构
capabilities.pagesbool返回页面元信息列表
capabilities.title_treebool返回文档目录树
capabilities.table_view"markdown" | "html"表格视图格式
scope.page_rangestring解析页面范围，如 "1-10"
document.passwordstring加密 PDF 的密码

​
异步解析

适用于大文件或批量处理场景。

​
创建任务并等待结果

client = XParseClient()

# 创建异步任务
with open("large_document.pdf", "rb") as f:
    job = client.parse.create_job(
        file=f,
        filename="large_document.pdf",
        webhook="https://example.com/callback",  # 可选：完成后回调通知
    )

print(f"任务已创建: {job.job_id}")

# 等待任务完成（自动轮询）
result = client.parse.wait_job(
    job_id=job.job_id,
    timeout=300.0,       # 超时时间（秒）
    poll_interval=5.0,   # 轮询间隔（秒）
)

if result.is_completed:
    # 异步任务返回 result_url，需单独下载获取解析结果
    import httpx
    resp = httpx.get(result.result_url)
    print(resp.json())

​
手动查询任务状态

status = client.parse.get_job(job_id="your-job-id")

print(f"状态: {status.status}")  # pending | in_progress | completed | failed

​
错误处理

SDK 提供了完善的错误分类，方便您精确处理不同的异常情况。

​
错误类型

错误类说明
XParseClientError基础错误类，捕获所有 SDK 错误
ValidationError客户端参数校验失败
AuthenticationError认证失败（app-id 或 secret-code 错误）
PermissionDeniedErrorIP 不在白名单
InsufficientBalanceError余额不足
InvalidParameterError参数错误
UnsupportedFileTypeError不支持的文件类型
FileSizeError文件超过 500MB 限制
CorruptedFileError文件损坏
PasswordProtectedErrorPDF 需要密码
ServerError服务端错误（HTTP 5xx）
ServiceUnavailableError服务暂时不可用

​
错误处理示例

from xparse_client.exceptions import (
    XParseClientError,
    BusinessError,
    AuthenticationError,
    APIError,
)

try:
    with open("document.pdf", "rb") as f:
        result = client.parse.run(file=f, filename="document.pdf")
except AuthenticationError as e:
    print(f"认证失败: {e.message}")
except BusinessError as e:
    print(f"业务错误 [{e.business_code}]: {e.message}")
    print(f"请求ID: {e.x_request_id}")  # 用于技术支持排查
except APIError as e:
    print(f"API错误 [HTTP {e.status_code}]: {e.message}")
except XParseClientError as e:
    print(f"SDK错误: {e.message}")

​
获取请求 ID

每个 API 请求都会返回 x_request_id，可用于联系技术支持排查问题： 
result = client.parse.run(file=f, filename="document.pdf")
print(f"请求ID: {result.x_request_id}")

​
高级配置

​
超时与重试

client = XParseClient(
    timeout=120.0,    # 请求超时（秒），默认 630
    max_retries=3,    # 最大重试次数，默认 3
)

​
自定义 API 地址

client = XParseClient(
    server_url="https://custom-api.example.com"
)

​
自定义 HTTP 客户端

支持代理、自定义 SSL 证书等场景： 
import httpx

http_client = httpx.Client(
    proxy="http://proxy.example.com:8080",
    verify="/path/to/custom-ca.pem",
)

client = XParseClient(
    app_id="your-app-id",
    secret_code="your-secret-code",
    http_client=http_client,
)

​
资源管理

使用上下文管理器自动关闭连接： 
with XParseClient() as client:
    result = client.parse.run(...)
    # 退出时自动关闭连接

​
调试日志

启用 DEBUG 级别日志查看请求详情： 
import logging
logging.getLogger("xparse_client").setLevel(logging.DEBUG)

​
常见问题

问题解决方案
AuthenticationError检查 TEXTIN_APP_ID 和 TEXTIN_SECRET_CODE 是否正确
FileSizeError文件大小限制为 500MB
TimeoutException增大超时时间：XParseClient(timeout=300.0)

​
相关链接