API 参考

本页概述了公共 API 的其余部分。一般来说，这主要对插件开发者感兴趣。

ocrmypdf.api

用于将 ocrmypdf 作为 API 使用的函数。

class ocrmypdf.api.PageNumberFilter(name='')

将发出日志消息的 PDF 页码插入到日志记录中。

filter(record)

确定指定的记录是否应被记录。

如果记录应该被记录，则返回 True，否则返回 False。如果认为合适，记录可能会被就地修改。

class ocrmypdf.api.Verbosity(value)

configure_logging 的详细级别。

debug = 1

输出 ocrmypdf 调试消息

debug_all = 2

来自 ocrmypdf 和依赖模块的更详细调试信息

default .= 0

默认日志级别

quiet .= -1

抑制大部分消息

ocrmypdf.api.configure_logging(verbosity: Verbosity, *, progress_bar_friendly: bool = True, manage_root_logger: bool = False, plugin_manager: PluginManager | None = None)

设置日志记录。

在调用 ocrmypdf.ocr() 之前，如果您希望 ocrmypdf 的输出看起来像 ocrmypdf 命令行界面，可以使用此函数来配置日志记录。它将注册日志处理程序、日志过滤器和格式化程序，配置标准错误的颜色日志记录，并调整第三方库的日志级别。这些细节经过微调，可能会发生变化。verbosity 参数等同于参数 --verbose 并应用这些设置。如果您有一个 ocrmypdf 的包装脚本，并且希望它与 ocrmypdf 非常相似，请使用此函数；如果您将 ocrmypdf 作为管理自身日志记录的应用程序的一部分使用，您可能不需要此函数。

如果未调用此函数，ocrmypdf 将不配置日志记录，而是由 ocrmypdf.ocr() 的调用者使用 Python 标准库的 logging 模块按其意愿设置日志记录。如果调用了此函数，调用者当然可以对日志记录进行进一步调整。

无论是否调用此函数，ocrmypdf 都将在 "ocrmypdf" 日志命名空间下执行所有日志记录。此外，ocrmypdf 导入了 pdfminer，它在 "pdfminer" 下记录日志。库用户可能希望配置两者；请注意，pdfminer 在日志级别 logging.INFO 下非常详细。

此函数不设置命令行界面在某些详细级别下的 debug.log 日志文件。应用程序应自行配置其调试日志记录。

参数:

• verbosity – 详细级别。

• progress_bar_friendly – 如果为 True（默认值），则安装一个与进度条和颜色输出兼容的自定义日志处理程序。

• manage_root_logger – 配置进程的根日志记录器。

• plugin_manager – 插件管理器，用于获取自定义日志处理程序。

返回:

ocrmypdf 的顶级日志记录器（如果我们正在管理它，则为根日志记录器）。

ocrmypdf.api.create_options(*, input_file: BinaryIO | Path | str | bytes, output_file: BinaryIO | Path | str | bytes, parser: ArgumentParser, **kwargs) → Namespace

根据输入/输出文件和关键字参数构建一个选项对象。

参数:

• input_file – 输入文件路径或文件对象。

• output_file – 输出文件路径或文件对象。

• parser – ArgumentParser 对象。

• **kwargs – 关键字参数。

返回:

argparse.Namespace – 包含已解析参数的 Namespace 对象。

抛出:

TypeError – 如果关键字参数的类型不受支持。

ocrmypdf.api.get_parser()

获取主 CLI 解析器。

ocrmypdf.api.ocr(input_file: BinaryIO | Path | str | bytes, output_file: BinaryIO | Path | str | bytes, *, language: Iterable[str] | None = None, image_dpi: int | None = None, output_type: str | None = None, sidecar: BinaryIO | Path | str | bytes | None = None, jobs: int | None = None, use_threads: bool | None = None, title: str | None = None, author: str | None = None, subject: str | None = None, keywords: str | None = None, rotate_pages: bool | None = None, remove_background: bool | None = None, deskew: bool | None = None, clean: bool | None = None, clean_final: bool | None = None, unpaper_args: str | None = None, oversample: int | None = None, remove_vectors: bool | None = None, force_ocr: bool | None = None, skip_text: bool | None = None, redo_ocr: bool | None = None, skip_big: float | None = None, optimize: int | None = None, jpg_quality: int | None = None, png_quality: int | None = None, jbig2_lossy: bool | None = None, jbig2_page_group_size: int | None = None, jbig2_threshold: float | None = None, pages: str | None = None, max_image_mpixels: float | None = None, tesseract_config: Iterable[str] | None = None, tesseract_pagesegmode: int | None = None, tesseract_oem: int | None = None, tesseract_thresholding: int | None = None, pdf_renderer: str | None = None, tesseract_timeout: float | None = None, tesseract_non_ocr_timeout: float | None = None, tesseract_downsample_above: int | None = None, tesseract_downsample_large_images: bool | None = None, rotate_pages_threshold: float | None = None, pdfa_image_compression: str | None = None, color_conversion_strategy: str | None = None, user_words: PathLike | None = None, user_patterns: PathLike | None = None, fast_web_view: float | None = None, continue_on_soft_render_error: bool | None = None, invalidate_digital_signatures: bool | None = None, plugins: Iterable[Path | str] | None = None, plugin_manager=None, keep_temporary_files: bool | None = None, progress_bar: bool | None = None, **kwargs)

对单个 PDF 或图像运行 OCRmyPDF。

有关大多数参数，请参阅等效命令行参数的文档。

此 API 会获取一个线程锁，因为 OCRmyPDF 特别是对于插件系统使用了全局状态。jobs 参数将用于在不同时间创建工作线程或进程池，可能会有所变动。一个 Python 进程只能同时运行一个 OCRmyPDF 任务。

为了并行化运行 OCRmyPDF 实例，请使用独立的 Python 进程进行水平扩展。一般来说，您应该将 jobs 设置为 sqrt(cpu_count)，并作为起点运行 sqrt(cpu_count) 个进程。如果您的文件页数较多，则应运行较少的进程并增加每个进程的 jobs 数。如果您的短文件较多，则应运行较多的进程并减少每个进程的 jobs 数。

此处将讨论一些特定参数：

参数:

• use_threads – 使用工作线程而不是进程。这会降低性能，但可能使调试更容易，因为设置断点更容易。

• input_file – 如果是 pathlib.Path、str 或 bytes 类型，则解释为输入文件的文件系统路径。如果对象看起来是可读流（具有如 .read() 和 .seek() 的方法），则将完整读取该对象并保存到临时文件。如果 input_file 是 "-"，则将读取标准输入。

• output_file – 如果是 pathlib.Path、str 或 bytes 类型，则解释为输出文件的文件系统路径。如果对象看起来是可写流（具有如 .write() 和 .seek() 的方法），则输出将写入此流。如果 output_file 是 "-"，则输出将写入 sys.stdout (前提是标准输出不像是终端设备)。当使用流作为输出时，无论是通过可写对象还是 "-"，都不会执行一些最终验证步骤（我们在写入流后不会回读它）。

抛出:

• ocrmypdf.MissingDependencyError – 如果所需的依赖程序缺失或未在 PATH 中找到。

• ocrmypdf.UnsupportedImageFormatError – 如果输入文件类型是无法读取的图像，或其他不是 PDF 的文件类型。

• ocrmypdf.DpiError – 如果输入文件是图像，但图像分辨率不可信（继续处理会导致 OCR 效果不佳）。

• ocrmypdf.OutputFileAccessError – 如果尝试写入目标输出文件失败。

• ocrmypdf.PriorOcrFoundError – 如果输入 PDF 似乎已经有 OCR 或数字文本，并且设置未指示我们继续。

• ocrmypdf.InputFileError – 输入文件的任何其他问题。

• ocrmypdf.SubprocessOutputError – 与执行子进程相关的任何错误。

• ocrmypdf.EncryptedPdfError – 如果输入 PDF 已加密（受密码保护）。OCRmyPDF 不移除密码。

• ocrmypdf.TesseractConfigError – 如果 Tesseract 报告其配置无效。

返回:

ocrmypdf.ExitCode

ocrmypdf.api.run_pipeline(options: Namespace, *, plugin_manager: OcrmypdfPluginManager) → ExitCode

运行 OCR 管道，不进行命令行异常处理。

参数:

• options – 已解析的命令行选项。

• plugin_manager – 要使用的插件管理器。如果未提供，将创建一个新的。

ocrmypdf.api.run_pipeline_cli(options: Namespace, *, plugin_manager: OcrmypdfPluginManager) → ExitCode

运行 OCR 管道，进行命令行异常处理。

参数:

• options – 已解析的命令行选项。

• plugin_manager – 要使用的插件管理器。如果未提供，将创建一个新的。

ocrmypdf.exceptions

OCRmyPDF 的异常。

exception ocrmypdf.exceptions.BadArgsError

命令行或 API 中的无效参数。

exit_code = 1

exception ocrmypdf.exceptions.ColorConversionNeededError

PDF 需要颜色转换。

message = '输入 PDF 使用 了 不 寻 常 的 颜色 空间。 使 用\n--color-conversion-strategy 参数 将其 转换 为 常见 的 颜色 空间\n（如 RGB），或 使用 --output-type pdf 参数 跳 过 PDF/A 转换\n并 保留 原 始 颜色 空间。\n'

exception ocrmypdf.exceptions.DigitalSignatureError

PDF 包含数字签名。

message = '输入 PDF 包含 数字 签 名。 OCR 会 修改 文 档，\n导 致 签 名 失 效。\n'

exception ocrmypdf.exceptions.DpiError

缺少输入图像 DPI 的信息。

exit_code = 2

exception ocrmypdf.exceptions.EncryptedPdfError

输入 PDF 已加密。

exit_code = 8

message = "输入 PDF 已 加 密。 必 须 移除 加 密 才能\n执 行 OCR。\n\n有 关 此 PDF 安 全 性 的 信 息，请 使 用\n    qpdf --show-encryption infilename\n\n您 可以 使 用 以 下 命 令 移 除 加 密：\n    qpdf --decrypt [--password=[password]] infilename\n"

class ocrmypdf.exceptions.ExitCode(value)

OCRmyPDF 的退出码。

already_done_ocr = 6

bad_args = 1

child_process_error = 7

ctrl_c = 130

encrypted_pdf = 8

file_access_error = 5

input_file = 2

invalid_config = 9

invalid_output_pdf = 4

missing_dependency = 3

ok = 0

other_error = 15

pdfa_conversion_failed = 10

exception ocrmypdf.exceptions.ExitCodeException

应使用 sys.exit() 返回退出码的异常。

exit_code = 15

message = ''

exception ocrmypdf.exceptions.InputFileError

输入文件有问题。

exit_code = 2

exception ocrmypdf.exceptions.MissingDependencyError

缺少第三方依赖。

exit_code = 3

exception ocrmypdf.exceptions.OutputFileAccessError

无法访问目标输出文件路径。

exit_code = 5

exception ocrmypdf.exceptions.PriorOcrFoundError

此文件已包含 OCR。

exit_code = 6

exception ocrmypdf.exceptions.SubprocessOutputError

子进程返回了意外错误。

exit_code = 7

exception ocrmypdf.exceptions.TaggedPDFError

PDF 是标记的。

message = '此 PDF 被 标记 为 标记 的 PDF（Tagged PDF）。 这 通常 表示\n该 PDF 是 由 办公 文 档 生 成， 因 此 不 需要 OCR。\n使 用 --force-ocr 、 --skip-text 或 --redo-ocr 参 数\n覆 盖 此 错 误。\n'

exception ocrmypdf.exceptions.TesseractConfigError

Tesseract 配置无法解析。

exit_code = 9

message = '解析 Tesseract 配置 文 件 时 发生 错误'

exception ocrmypdf.exceptions.UnsupportedImageFormatError

图像格式不受支持。

exit_code = 2

ocrmypdf.helpers

辅助函数。

@ocrmypdf.helpers.deprecated(deprecated_in=None, removed_in=None, current_version=None, details='')

标记函数为已弃用

此函数包装了即将移除的方法，并执行两项操作：

• 方法的文档字符串将被修改，包含关于弃用的通知，例如，“从 0.9.11 版本起弃用。请改用 foo。”

• 通过 warnings 模块发出 DeprecatedWarning 警告，它是内置 DeprecationWarning 的子类。请注意，内置 DeprecationWarning`s 默认会被忽略，因此用户需要启用它们才能收到这些警告——详见 warnings 模块文档。

参数:

• deprecated_in – 标记的方法被认为是弃用的版本。这通常是添加此装饰器时将发布的下一个版本。默认值为 None，实际上意味着立即弃用。如果未指定此参数，则会忽略 removed_in 和 current_version 参数。

• removed_in – 标记的方法将移除的版本或 datetime.date。默认值为 None，表示当前不计划移除该函数。注意：如果 deprecated_in=None，则不能设置此参数。

• current_version – 当前运行代码的版本信息来源。这通常是您库中的 __version__ 属性。默认值为 None。当 current_version=None 时，用于确定被包装函数是否处于弃用期或应移除的自动化机制将不起作用，导致在所有情况下都会发出 DeprecatedWarning 警告。

• details – 要添加到方法文档字符串和警告中的额外详细信息。例如，详细信息可能会指示用户使用替代方法，如“请改用 foo_bar 方法”。默认情况下没有详细信息。

ocrmypdf.helpers.NeverRaise()

一个永不引发的异常。

自 15.4.0 版本起弃用。

class ocrmypdf.helpers.Resolution(x: T, y: T)

每个二维方向上每英寸的像素数。

如果 Resolution 对象的 x 和 y 在合理容差范围内相等，则视为“相等”（用于 == 比较）。

flip_axis() → Resolution[T]

返回一个新的 Resolution 对象，其中 x 和 y 已交换。

property is_finite: bool

如果 x 和 y 都是有限数，则为 True。

property is_square: bool

如果分辨率是正方形的（x == y），则为 True。

round(ndigits: int) → Resolution

四舍五入到小数点后 ndigits 位。

take_max(vals: Iterable[Any], yvals: Iterable[Any] | None = None) → Resolution

返回一个具有输入最大分辨率的新 Resolution 对象。

take_min(vals: Iterable[Any], yvals: Iterable[Any] | None = None) → Resolution

返回一个具有输入最小分辨率的新 Resolution 对象。

to_int() → Resolution[int]

四舍五入到最接近的整数。

to_scalar() → float

返回 x 和 y 的调和平均数作为一维近似值。

在大多数情况下，Resolution 是二维的，但通常它是“方形”的 (x == y)，可以近似为一个单独的数字。当不是方形时，使用调和平均数将二维分辨率近似为一个单独的数字。

ocrmypdf.helpers.available_cpu_count() → int

返回系统中的 CPU 数量。

ocrmypdf.helpers.check_pdf(input_file: Path) → bool

检查 PDF 是否符合 PDF 规范。

检查格式是否正确和是否正确线性化。使用 pikepdf（它又使用 QPDF）来执行检查。

ocrmypdf.helpers.clamp(n: T, smallest: T, largest: T) → T

将 n 的值限制在 smallest 和 largest 之间。

ocrmypdf.helpers.is_file_writable(test_file: PathLike) → bool

故意进行竞态测试以检查目标是否可写。

我们只有在成功并且可以原子地替换输出文件时才打算写入。在进行 OCR 工作之前，请确保该位置是可写的。

ocrmypdf.helpers.is_iterable_notstr(thing: Any) → bool

这是可迭代类型，但不是字符串吗？

ocrmypdf.helpers.monotonic(seq: Sequence) → bool

这个序列是单调递增的吗？

ocrmypdf.helpers.page_number(input_file: PathLike) → int

获取文件名隐含的基于一的页码 (000002.pdf -> 2)。

ocrmypdf.helpers.pikepdf_enable_mmap() → None

启用 pikepdf 内存映射。

ocrmypdf.helpers.remove_all_log_handlers(logger: Logger) → None

移除所有日志处理程序，通常在子进程中使用。

子进程在 fork 时会继承父进程的日志处理程序。通常我们希望移除子进程中的所有日志处理程序，以便子进程可以设置一个单独的队列处理程序将日志消息转发给父进程。

ocrmypdf.helpers.running_in_docker() → bool

如果看起来我们正在 Docker 容器中运行，则返回 True。

ocrmypdf.helpers.running_in_snap() → bool

如果看起来我们正在 Snap 容器中运行，则返回 True。

ocrmypdf.helpers.safe_symlink(input_file: PathLike, soft_link_name: PathLike) → None

在 soft_link_name 创建一个引用 input_file 的符号链接。

可以将其视为以较低开销将 input_file 复制到 soft_link_name。

安全地使用符号链接。防止自链接循环。在 Windows 上，由于符号链接可能需要管理员权限，因此使用文件复制。如果目标位置已存在链接，则将其移除。

ocrmypdf.helpers.samefile(file1: PathLike, file2: PathLike) → bool

如果两个文件是同一个文件，则返回 True。

尝试考虑指向同一文件的不同相对路径。

ocrmypdf.hocrtransform

将 .hocr 文件和页面图像转换为文本 PDF。

class ocrmypdf.hocrtransform.DebugRenderOptions(render_paragraph_bbox: bool = False, render_baseline: bool = False, render_triangle: bool = False, render_line_bbox: bool = False, render_word_bbox: bool = False, render_space_bbox: bool = False)

一个用于管理渲染选项的类。

class ocrmypdf.hocrtransform.HocrTransform(*, hocr_filename: str | Path, dpi: float, debug: bool = False, fontname: Name = <MagicMock name='mock()' id='131366782993168'>, font: Font = <MagicMock spec='str' id='131366781171456'>, debug_render_options: DebugRenderOptions | None = None)

一个用于从 hOCR 格式转换文档的类。

有关 hOCR 格式的详细信息，请参阅：http://kba.github.io/hocr-spec/1.2/。

classmethod baseline(element: Element) → tuple[float, float]

获取基线的斜率和截距。

classmethod element_coordinates(element: Element) → <MagicMock name='mock.__or__()' id='131366751017456'>

获取元素周围边界框的坐标。

classmethod normalize_text(s: str) → str

使用 NFKC 标准化形式对给定文本进行标准化。

classmethod polyval(poly, x)

计算多项式在某一点的值。

classmethod textangle(element: Element) → float

获取元素的文本角度。

to_pdf(*, out_filename: Path, image_filename: Path | None = None, invisible_text: bool = True) → None

创建一个 PDF 文件，其中图像叠加在文本之上。

文本根据 hOCR 文件中行的边界框定位。图像不必与用于创建 hOCR 文件的图像完全相同。它可以具有较低的分辨率、不同的颜色模式等。

参数:

• out_filename – 要写入的 PDF 文件路径。

• image_filename – 用于此文件的图像。如果省略，则显示 OCR 文本。

• invisible_text – 如果为 True，则文本被渲染为不可见，以便可以选择但从不绘制。如果为 False，则文本可见，并且如果在 Acrobat 中跳过或删除图像，则可能看到文本。

exception ocrmypdf.hocrtransform.HocrTransformError

应用 hOCR 转换时发生错误。

ocrmypdf.pdfa

用于使用 Ghostscript 生成和确认 PDF/A 的实用程序。

ocrmypdf.pdfa.file_claims_pdfa(filename: Path)

确定文件是否声称符合 PDF/A 标准。

这仅检查 XMP 元数据是否包含 PDF/A 标记。它不执行完整的 PDF/A 验证。

ocrmypdf.pdfa.generate_pdfa_ps(target_filename: Path, icc: str = sRGB)

为 Ghostscript PDF/A 转换创建一个 Postscript PDFMARK 文件。

pdfmark 是 Postscript 语言的一个扩展，它描述了某些 PDF 特性，如书签和注释。它最初由 Adobe Distiller 规范，用于 Postscript 到 PDF 的转换。

Ghostscript 也使用 pdfmark 进行 PDF 到 PDF/A 的转换。要使用 Ghostscript 创建 PDF/A，我们需要创建一个包含必要元数据的 pdfmark 文件。

此函数处理 Ghostscript 在处理 pdfmark 时许多特定于版本的 bug 和特性。

我们放入的唯一信息指定我们希望文件成为 PDF/A，并且我们希望 Ghostscript 将对象转换为 sRGB 色彩空间，如果遇到它认为必须转换的任何对象。

参数:

• target_filename – 要保存的文件名

• icc – ICC 标识符，例如 'sRGB'

参考

Adobe PDFMARK 参考：https://opensource.adobe.com/dc-acrobat-sdk-docs/library/pdfmark/

ocrmypdf.quality

用于测量 OCR 质量的实用程序。

class ocrmypdf.quality.OcrQualityDictionary(*, wordlist: Iterable[str])

管理一个字典以进行简单的 OCR 质量检查。

measure_words_matched(ocr_text: str) → float

检查 OCR 文本中有多少个独特词与字典匹配。

混合大小写的词只有在测试词与该大小写匹配时才被视为匹配。

返回:

匹配词的数量 / 数量

ocrmypdf.subprocess

用于管理子进程调用的包装器。

ocrmypdf.subprocess.check_external_program(*, program: str, package: str, version_checker: ~collections.abc.Callable[[], ~packaging.version.Version], need_version: str | ~packaging.version.Version, required_for: str | None = None, recommended: bool = False, version_parser: type[~packaging.version.Version] = <class 'packaging.version.Version'>) → None

检查外部程序的所需版本，如果不符合则抛出异常。

参数:

• program – 要测试的程序名称。

• package – 通常提供此程序的软件包名称。通常与 program 相同。

• version_checker – 一个无参数的可调用对象，用于检索程序已安装的版本。

• need_version – 最低所需版本。

• required_for – 需要此程序的参数或功能的名称。

• recommended – 如果此外部程序是推荐的，则不抛出异常，而是记录警告并允许执行继续。

• version_parser – 一个应该用于解析和比较版本号的类。当版本号不遵循标准约定时代替使用。

ocrmypdf.subprocess.get_version(program: str, *, version_arg: str = --version, regex=(\d+(\.\d+)*), env: _Environ | None = None) → str

获取指定程序的版本。

参数:

• program – 要检查版本的程序。

• version_arg – 用于获取其版本的参数，例如 --version。

• regex – 用于解析程序输出并获取版本的正则表达式。

• env – 运行程序的自定义 os.environ。

ocrmypdf.subprocess.run(args: Sequence[Path | str], *, env: _Environ | None = None, logs_errors_to_stdout: bool = False, check: bool = False, **kwargs) → CompletedProcess

subprocess.run() 的包装器。

此包装器的主要目的是以有序的方式记录子进程输出，并识别负责的子进程。另一个任务是，当我们的依赖项不在系统 PATH 中时，此函数会更努力地查找它们在 Windows 上的可能位置。

参数应与 subprocess.run 相同，除了以下内容

参数:

• args – 传递给 subprocess.run 的位置参数。

• env – 一组环境变量。如果为 None，则使用操作系统环境。

• logs_errors_to_stdout – 如果为 True，表示进程将其错误消息写入 stdout 而不是 stderr，因此如果发生错误，应记录 stdout。如果为 False，则记录 stderr。例如，可以与 stderr=STDOUT, stdout=PIPE 一起使用。

• check – 如果为 True，则在进程以非零状态码退出时抛出异常。如果为 False，则返回值将指示成功或失败。

• kwargs – 传递给 subprocess.run 的额外参数。

ocrmypdf.subprocess.run_polling_stderr(args: Sequence[Path | str], *, callback: Callable[[str], None], check: bool = False, env: _Environ | None = None, **kwargs) → CompletedProcess

运行一个类似 ocrmypdf.subprocess.run 的进程，并轮询 stderr。

stderr 生成的每一行都将转发给回调函数。其目的是监控输出自身进度指示器的子进程的进度。此外，如果启用了调试日志，每行都将被记录。

要求 stderr 以文本模式打开以便于处理错误。此外，应设置预期的 encoding= 和 errors= 参数。请注意，如果 stdout 已设置，则无需为二进制模式。