使用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 有条件成功时，它会返回一个整数退出代码。