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 将不会配置日志记录，调用者需要使用 Python 标准库的日志记录模块自行设置日志记录。如果调用了此函数，调用者当然可以进一步调整日志记录。

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

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

Parameters:

  • verbosity – 详细程度级别。

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

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

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

Returns:

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

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

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

Parameters:

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

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

  • parser – ArgumentParser 对象。

  • **kwargs – 关键字参数。

Returns:

argparse.Namespace – 一个包含解析后参数的命名空间对象。

Raises:

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)进程作为起点。如果您有页数较多的文件，请运行较少的进程，每个进程运行更多的作业。如果您有很多短文件，请运行更多的进程，每个进程运行较少的作业。

这里讨论了一些特定的参数：

Parameters:

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

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

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

Raises:

  • 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报告其配置无效。

Returns:

ocrmypdf.ExitCode

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

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

Parameters:

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

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

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

使用命令行异常处理运行OCR管道。

Parameters:

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

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

ocrmypdf.exceptions

OCRmyPDF的异常。

exception ocrmypdf.exceptions.BadArgsError

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

exit_code = 1
exception ocrmypdf.exceptions.ColorConversionNeededError

PDF需要进行颜色转换。

message = 'The input PDF has an unusual color space. Use\n--color-conversion-strategy to convert to a common color space\nsuch as RGB, or use --output-type pdf to skip PDF/A conversion\nand retain the original color space.\n'
exception ocrmypdf.exceptions.DigitalSignatureError

PDF 具有数字签名。

message = 'Input PDF has a digital signature. OCR would alter the document,\ninvalidating the signature.\n'
exception ocrmypdf.exceptions.DpiError

缺少关于输入图像DPI的信息。

exit_code = 2
exception ocrmypdf.exceptions.EncryptedPdfError

输入的PDF已加密。

exit_code = 8
message = "Input PDF is encrypted. The encryption must be removed to\nperform OCR.\n\nFor information about this PDF's security use\n    qpdf --show-encryption infilename\n\nYou can remove the encryption using\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 = 'This PDF is marked as a Tagged PDF. This often indicates\nthat the PDF was generated from an office document and does\nnot need OCR. Use --force-ocr, --skip-text or --redo-ocr to\noverride this error.\n'
exception ocrmypdf.exceptions.TesseractConfigError

Tesseract 配置无法解析。

exit_code = 9
message = 'Error occurred while parsing a Tesseract configuration file'
exception ocrmypdf.exceptions.UnsupportedImageFormatError

不支持该图像格式。

exit_code = 2

ocrmypdf.helpers

支持函数。

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

装饰一个函数以表示其已弃用

This function wraps a method that will soon be removed and does two things:

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

  • 通过 warnings 模块引发一个 DeprecatedWarning，它是内置的 DeprecationWarning 的子类。请注意，默认情况下会忽略内置的 DeprecationWarning，因此用户需要启用这些警告才能收到通知——有关更多详细信息，请参阅 warnings 模块文档。

Parameters:

  • 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)

每个2D方向上每英寸的像素数。

如果分辨率对象在合理的容差范围内相等，则它们被视为“相等”以用于==目的。

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的调和平均数作为一维近似值。

在大多数情况下，分辨率是二维的，但通常是“正方形”（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

获取由文件名隐含的基于1的页码（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='140327228779984'>, font: Font = <MagicMock spec='str' id='140327226352560'>, 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='140327195795728'>

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

classmethod normalize_text(s: str) → str

使用NFKC规范化形式对给定文本进行规范化。

classmethod polyval(poly, x)

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

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

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

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

Parameters:

  • 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时的许多版本特定错误和特性。

我们输入的唯一信息指定我们希望文件是PDF/A格式，并且我们希望Ghostscript在遇到任何它认为必须转换的对象时将其转换为sRGB色彩空间。

Parameters:

  • 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文本中有多少个唯一单词与字典匹配。

只有当测试单词的大小写与混合大小写的单词完全匹配时，才被视为匹配。

Returns:

匹配的单词数 / 数字

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

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

Parameters:

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

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

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

  • need_version – 最低要求的版本。

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

  • 推荐 – 如果推荐使用此外部程序，而不是引发异常，则记录警告并允许继续执行。

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

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

获取指定程序的版本。

Parameters:

  • 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 相同，除了以下内容：

Parameters:

  • 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已经设置好，则不需要是二进制的。