使用 OCRmyPDF API

OCRmyPDF 最初是一个命令行程序并延续了这一传统，但它的部分功能可以被导入并在其他 Python 应用程序中使用。

有些应用程序可能希望考虑通过子进程调用来运行 ocrmypdf，因为这能隔离其活动。

示例

OCRmyPDF 提供了一个高级函数，可用于从应用程序运行其主要引擎。参数与命令行参数对称，功能也基本相同。

import ocrmypdf

if __name__ == '__main__':  # To ensure correct behavior on Windows and macOS
    ocrmypdf.ocr('input.pdf', 'output.pdf', deskew=True)

除了一些例外，所有的命令行参数都可用，并且可以作为等效的关键字传递。

一些区别在于 verbose 和 quiet 不可用。相反，输出应通过配置日志来管理。

父进程要求

ocrmypdf.ocr() 函数运行 OCRmyPDF 的方式类似于命令行执行。为此，它将

创建工作进程或线程
管理其工作进程的信号标志
执行其他子进程（分叉并执行其他程序）

调用 ocrmypdf.ocr() 的 Python 进程必须具有足够的权限来执行这些操作。

目前除了参数 jobs=（它将限制工作进程的数量）之外，没有其他选项来管理作业的调度方式。

建议创建一个子进程来调用 ocrmypdf.ocr()。这样，即使 OCRmyPDF 因任何原因失败，您的应用程序也能继续运行并保持交互性。例如

from multiprocessing import Process

def ocrmypdf_process():
    ocrmypdf.ocr('input.pdf', 'output.pdf')

def call_ocrmypdf_from_my_app():
    p = Process(target=ocrmypdf_process)
    p.start()
    p.join()

调用 ocrmypdf.ocr() 的程序还应安装一个 SIGBUS 信号处理程序（Windows 除外），以便在访问内存映射文件失败时引发异常。OCRmyPDF 可能会使用内存映射。

ocrmypdf.ocr() 将获取一个线程锁，以防止其在同一 Python 解释器进程中多次运行。这不是线程安全的，因为 OCRmyPDF 的插件和 Python 的库导入系统的工作方式。如果您需要并行运行 OCRmyPDF，请使用进程。

警告

在 Windows 和 macOS 上，调用 ocrmypdf.ocr() 的脚本必须由“ifmain”保护（if __name__ == '__main__'）。如果您不采取至少一项这些步骤，进程语义将阻止 OCRmyPDF 正常工作。

日志记录

OCRmyPDF 将在名为 ocrmypdf 的日志记录器下进行记录。此外，它还会导入 pdfminer 和 PIL，这两者都会在各自的日志记录命名空间下发布日志消息。

您可以根据应用程序的需求配置日志记录，或者调用 ocrmypdf.configure_logging() 以与 OCRmyPDF 本身相同的方式配置日志记录。命令行参数如 --quiet 和 --verbose 在 API 中没有等效项；您必须使用提供的配置函数或以适合您的用例的方式进行配置。

进度监控

OCRmyPDF 使用 rich 包来实现其进度条。ocrmypdf.configure_logging() 将以与进度条显示兼容的方式将日志输出设置为 sys.stderr。使用 ocrmypdf.ocr(...progress_bar=False) 可以禁用进度条。

标准输出

OCRmyPDF 严格限制不写入标准输出，以便用户可以安全地在管道中使用它并生成有效的输出文件。调用应用程序如果想兼容此行为并支持通过管道输出到文件，也必须确保不写入标准输出。如上所述，在子进程中运行 OCRmyPDF 的另一个好处是它不会干扰父进程的标准输出。

异常

OCRmyPDF 可能会抛出标准的 Python 异常、ocrmypdf.exceptions.* 异常、一些与多进程相关的异常以及 KeyboardInterrupt。父进程应该提供一个异常处理程序。发生异常时，OCRmyPDF 会自动清理其临时文件和工作进程。

当 OCRmyPDF 有条件地成功时，它返回一个整数退出代码。