Parseur

🤖🧙parseur-py

parseur-py 是一个现代化的 Python 客户端，用于调用 Parseur API。

它可让你通过编程或命令行管理邮箱、文档、上传内容和 Webhook。

parseur-py 旨在帮助你大规模自动化文档解析，让你能够快速、轻松地以符合 Python 风格的方式集成 Parseur。

---

✨ 功能

✅ 列出、搜索和排序邮箱
✅ 获取邮箱详情和架构
✅ 列出、搜索、筛选和排序文档
✅ 通过文件或电子邮件内容上传文档
✅ 重新处理、跳过、复制或删除文档
✅ 管理用于实时事件的自定义 Webhook
✅ 使用临时 Webhook 和隧道实时监听事件
✅ 功能齐全的命令行界面（CLI）

---

⚠️ 关于 Localtunnel 的免责声明

使用 parseur listen 命令（支持事件监听器）时，数据会经由 localtunnel 服务器转发。

这些服务器与 Parseur 无关，也不受 Parseur 的隐私政策或数据处理协议约束。

通过 localtunnel 传输的数据不会进行端到端加密。

➡️ 使用此功能的风险由你自行承担。

对于生产级配置，我们强烈建议配置自己的安全 Webhook 端点，而不要依赖 localtunnel。

---

🚀 快速入门

安装软件包

pip install parseur-py

启用事件监听器支持（Flask + localtunnel）

pip install "parseur-py[listener]"

从源代码安装软件包

pip install -e .

构建文档

pip install -r requirements-doc.txt
cd docs
make html

运行测试

单元测试完全离线运行：

pytest

集成测试会调用真实的 Parseur API。它们会创建并删除真实资源，因此除非通过环境变量提供凭据，否则会跳过这些测试（绝不会提交凭据，也不会将其存储在 ~/.parseur.conf 中）：

PARSEUR_API_BASE=https://api.parseur.com \
PARSEUR_API_KEY=sk_your_key \
pytest tests/integration -v

---

初始化配置

安全地保存你的 Parseur API 凭据：

parseur init --api-key YOUR_PARSEUR_API_KEY

配置默认保存在：

~/.parseur.conf

---

使用示例

列出所有邮箱：

parseur list-mailboxes

列出邮箱中的文档：

parseur list-documents 12345

向邮箱上传文件（添加 --wait，即可等待解析完成，并显示实时进度条）：

parseur upload-file 12345 ./path/to/document.pdf
parseur upload-file 12345 ./path/to/document.pdf --wait

将邮箱结果下载为文件（默认输出到 stdout，也可使用 --output）：

parseur download-mailbox 12345 --format csv -o results.csv     # whole mailbox
parseur list-parser-fields 12345                               # find a table field id
parseur download-field 12345 PF951 --format xlsx -o lines.xlsx  # a table field

注册自定义 Webhook：

parseur create-webhook --event document.processed --target-url https://yourserver.com/webhook --mailbox-id 12345

实时监听事件（需要 [listener]）：

parseur listen --event document.processed --mailbox-id 12345

使用转发：

parseur listen --event document.processed --mailbox-id 12345 --redirect-url http://localhost --redirect-port 8000

---

📜 CLI 命令

运行：

parseur --help

查看所有可用命令的完整列表。

亮点

• init：设置 API 令牌和（可选的）基础 URL
• list-mailboxes：搜索和排序邮箱
• get-mailbox：按 ID 获取邮箱
• get-mailbox-schema：获取邮箱解析架构
• list-parser-fields：列出邮箱提取的字段
• download-mailbox / download-field / download-export：将结果下载为文件（csv/json/xlsx）
• list-export-configs：列出邮箱的自定义导出配置
• list-documents：高级文档搜索、筛选和排序
• get-document / get-document-logs：获取文档详情和处理日志
• reprocess-document / skip-document / copy-document / split-document / reverse-split-document / delete-document：文档生命周期操作
• upload-file / upload-text：上传新文档（添加 --wait 可同步解析）
• upload-folder：上传匹配 glob 路径的所有文件
• create-webhook / get-webhook / list-webhooks / delete-webhook：创建、获取、列出和删除自定义 webhook 集成。
• enable-webhook / pause-webhook：为指定邮箱启用或暂停 webhook。
• listen：创建临时 webhook 并实时监听事件（可选重定向和静默模式）

---

🔎 高级搜索与筛选

邮箱列表支持：

• 按名称或电子邮件前缀搜索
• 按以下字段排序：
  • name
  • document_count
  • template_count
  • PARSEDOK_count（已处理）
  • PARSEDKO_count（处理失败）
  • QUOTAEXC_count（超出配额）
  • EXPORTKO_count（导出失败）

文档列表支持：

• 在以下内容中搜索：
  • 文档 ID
  • 文档名称
  • 模板名称
  • 电子邮件地址（from、to、cc、bcc）
  • 文档元数据标头
• 按以下字段排序：
  • name
  • created（接收日期）
  • 处理日期
  • 状态
• 按以下条件筛选：
  • received_after / received_before 日期
• 在响应中包含解析结果

---

⚡ Webhook 支持

轻松注册自定义 webhook，以接收以下事件的通知：

• document.processed
• document.processed.flattened
• document.template_needed
• document.export_failed
• table.processed
• table.processed.flattened

你的 webhook 端点将通过 POST 接收包含 Parseur 负载的通知，从而实现与你的系统实时集成。

---

🤖 MCP 服务（AI 助手）

Parseur 在 https://api.parseur.com/mcp 提供 MCP 服务。将此 URL 添加到任何兼容 MCP 的 AI 助手（Claude、Codex、Cursor，……），即可通过它操作 Parseur。无需本地安装。

---

🛠️ 配置

你的 API 令牌和设置存储在一个简单的 INI 文件中：

[parseur]
api_token = YOUR_API_KEY
base_url = https://api.parseur.com

如有需要，可在调用时设置 --config-path，自定义文件路径。

---

🐍 Python 客户端用法

除了 CLI，parseur-py 还是一个标准的 Python 库。示例：

import parseur

parseur.api_key = "YOUR_API_KEY"

for mailbox in parseur.Mailbox.list():
    print(mailbox.name)

按调用覆盖 API 密钥

每个方法都接受一个可选的 api_key 参数；对于该次调用，它的优先级高于全局的 parseur.api_key。这对多账户或多租户代码很有用：

parseur.Mailbox.list(api_key="sk_account_a")
parseur.Document.upload_file(123, "invoice.pdf", api_key="sk_account_b")

---

📖 文档

• Parseur 官方 API 文档
• 此软件包与 Parseur 的 REST API 保持一致，并添加了分页处理、架构支持和便捷的 CLI 命令。

---

💼 许可证

MIT 许可证

---

🤝 参与贡献

欢迎贡献！请按以下步骤操作：

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/foo）
3. 提交更改（git commit -am 'Add foo'）
4. 推送到该分支（git push origin feature/foo）
5. 发起 pull request

---

✨ 致谢

由 Parseur 团队倾心打造 ❤️。

---

Parseur 是自动从电子邮件和文档中提取数据的最简单方式。告别复制粘贴数据，自动化你的工作流！