API Reference¶
This page summarizes the rest of the public API. Generally speaking this should mainly of interest to plugin developers.
ocrmypdf¶
-
class
ocrmypdf.
PageContext
(pdf_context: ocrmypdf._jobcontext.PdfContext, pageno)¶ Holds our context for a page.
Must be pickable, so stores only intrinsic/simple data elements or those capable of their serializing themselves via
__getstate__
.-
get_path
(name: str) → pathlib.Path¶ Generate a
Path
for a file that is part of processing this page.The path will be based in a common temporary folder and have a prefix based on the page number.
-
options
= None¶ The specified options for processing this PDF.
-
origin
= None¶ The filename of the original input file.
-
pageinfo
= None¶ Information on this page.
-
pageno
= None¶ This page number (zero-based).
-
plugin_manager
= None¶ PluginManager for processing the current PDF.
-
-
class
ocrmypdf.
PdfContext
(options: argparse.Namespace, work_folder: pathlib.Path, origin: pathlib.Path, pdfinfo: ocrmypdf.pdfinfo.info.PdfInfo, plugin_manager)¶ Holds the context for a particular run of the pipeline.
-
get_page_contexts
() → Iterator[ocrmypdf._jobcontext.PageContext]¶ Get all
PageContext
for this PDF.
-
get_path
(name: str) → pathlib.Path¶ Generate a
Path
for an intermediate file involved in processing.The path will be in a temporary folder that is common for all processing of this particular PDF.
-
options
= None¶ The specified options for processing this PDF.
-
origin
= None¶ The filename of the original input file.
-
pdfinfo
= None¶ Detailed data for this PDF.
-
plugin_manager
= None¶ PluginManager for processing the current PDF.
-
ocrmypdf.exceptions¶
-
exception
ocrmypdf.exceptions.
EncryptedPdfError
¶ -
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
¶ An enumeration.
-
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.
PdfMergeFailedError
¶ -
exit_code
= 2¶
-
message
= 'Failed to merge PDF image layer with OCR layer\n\nUsually this happens because the input PDF file is malformed and\nocrmypdf cannot automatically correct the problem on its own.\n\nTry using\n ocrmypdf --pdf-renderer sandwich [..other args..]\n'¶
-
ocrmypdf.helpers¶
-
exception
ocrmypdf.helpers.
NeverRaise
An exception that is never raised
-
class
ocrmypdf.helpers.
Resolution
The number of pixels per inch in each 2D direction.
-
ocrmypdf.helpers.
available_cpu_count
() → int Returns number of CPUs in the system.
-
ocrmypdf.helpers.
check_pdf
(input_file: pathlib.Path) → bool Check if a PDF complies with the PDF specification.
Checks for proper formatting and proper linearization. Uses pikepdf (which in turn, uses QPDF) to perform the checks.
-
ocrmypdf.helpers.
clamp
(n, smallest, largest) Clamps the value of
n
to betweensmallest
andlargest
.
-
ocrmypdf.helpers.
deprecated
(func) Warn that function is deprecated.
-
ocrmypdf.helpers.
is_file_writable
(test_file: os.PathLike) → bool Intentionally racy test if target is writable.
We intend to write to the output file if and only if we succeed and can replace it atomically. Before doing the OCR work, make sure the location is writable.
-
ocrmypdf.helpers.
is_iterable_notstr
(thing: Any) → bool Is this is an iterable type, other than a string?
-
ocrmypdf.helpers.
monotonic
(L: Sequence) → bool Does this sequence increase monotonically?
-
ocrmypdf.helpers.
page_number
(input_file: os.PathLike) → int Get one-based page number implied by filename (000002.pdf -> 2)
-
ocrmypdf.helpers.
safe_symlink
(input_file: os.PathLike, soft_link_name: os.PathLike) Create a symbolic link at
soft_link_name
, which referencesinput_file
.Think of this as copying
input_file
tosoft_link_name
with less overhead.Use symlinks safely. Self-linking loops are prevented. On Windows, file copy is used since symlinks may require administrator privileges. An existing link at the destination is removed.
ocrmypdf.hocrtransform¶
-
class
ocrmypdf.hocrtransform.
HocrTransform
(hocr_filename: Union[str, pathlib.Path], dpi: float)¶ A class for converting documents from the hOCR format. For details of the hOCR format, see: http://kba.cloud/hocr-spec/
-
classmethod
baseline
(element: xml.etree.ElementTree.Element) → Tuple[float, float]¶ Returns a tuple containing the baseline slope and intercept.
-
classmethod
element_coordinates
(element: xml.etree.ElementTree.Element) → ocrmypdf.hocrtransform.Rect¶ Returns a tuple containing the coordinates of the bounding box around an element
-
pt_from_pixel
(pxl) → ocrmypdf.hocrtransform.Rect¶ Returns the quantity in PDF units (pt) given quantity in pixels
-
classmethod
replace_unsupported_chars
(s: str) → str¶ Given an input string, returns the corresponding string that: * is available in the Helvetica facetype * does not contain any ligature (to allow easy search in the PDF file)
-
to_pdf
(out_filename: pathlib.Path, image_filename: Optional[pathlib.Path] = None, show_bounding_boxes: bool = False, fontname: str = 'Helvetica', invisible_text: bool = False, interword_spaces: bool = False) → None¶ Creates a PDF file with an image superimposed on top of the text. Text is positioned according to the bounding box of the lines in the hOCR file. The image need not be identical to the image used to create the hOCR file. It can have a lower resolution, different color mode, etc.
Parameters: - out_filename – Path of PDF to write.
- image_filename – Image to use for this file. If omitted, the OCR text is shown.
- show_bounding_boxes – Show bounding boxes around various text regions, for debugging.
- fontname – Name of font to use.
- invisible_text – If True, text is rendered invisible so that is selectable but never drawn. If False, text is visible and may be seen if the image is skipped or deleted in Acrobat.
- interword_spaces – If True, insert spaces between words rather than drawing each word without spaces. Generally this improves text extraction.
-
classmethod
-
exception
ocrmypdf.hocrtransform.
HocrTransformError
¶
ocrmypdf.pdfa¶
Utilities for PDF/A production and confirmation with Ghostspcript.
-
ocrmypdf.pdfa.
file_claims_pdfa
(filename: pathlib.Path)¶ Determines if the file claims to be PDF/A compliant.
This only checks if the XMP metadata contains a PDF/A marker. It does not do full PDF/A validation.
-
ocrmypdf.pdfa.
generate_pdfa_ps
(target_filename: pathlib.Path, icc: str = 'sRGB')¶ Create a Postscript PDFMARK file for Ghostscript PDF/A conversion
pdfmark is an extension to the Postscript language that describes some PDF features like bookmarks and annotations. It was originally specified Adobe Distiller, for Postscript to PDF conversion.
Ghostscript uses pdfmark for PDF to PDF/A conversion as well. To use Ghostscript to create a PDF/A, we need to create a pdfmark file with the necessary metadata.
This function takes care of the many version-specific bugs and pecularities in Ghostscript’s handling of pdfmark.
The only information we put in specifies that we want the file to be a PDF/A, and we want to Ghostscript to convert objects to the sRGB colorspace if it runs into any object that it decides must be converted.
Parameters: - target_filename – filename to save
- icc – ICC identifier such as ‘sRGB’
References
Adobe PDFMARK Reference: https://www.adobe.com/content/dam/acom/en/devnet/acrobat/pdfs/pdfmark_reference.pdf
ocrmypdf.quality¶
Utilities to measure OCR quality
-
class
ocrmypdf.quality.
OcrQualityDictionary
(*, wordlist: Iterable[str])¶ Manages a dictionary for simple OCR quality checks.
-
measure_words_matched
(ocr_text: str) → float¶ Check how many unique words in the OCR text match a dictionary.
Words with mixed capitalized are only considered a match if the test word matches that capitalization.
Returns: number of words that match / number
-
ocrmypdf.subprocess¶
Wrappers to manage subprocess calls
-
ocrmypdf.subprocess.
get_version
¶ Get the version of the specified program
Parameters: - program – The program to version check.
- version_arg – The argument needed to ask for its version, e.g.
--version
. - regex – A regular expression to parse the program’s output and obtain the version.
- env – Custom
os.environ
in which to run program.
-
ocrmypdf.subprocess.
run
(args, *, env=None, logs_errors_to_stdout=False, **kwargs)¶ Wrapper around
subprocess.run()
The main purpose of this wrapper is to log subprocess output in an orderly fashion that indentifies the responsible subprocess. An additional task is that this function goes to greater lengths to find possible Windows locations of our dependencies when they are not on the system PATH.
Arguments should be identical to
subprocess.run
, except for following:Parameters: logs_errors_to_stdout – If True, indicates that the process writes its error messages to stdout rather than stderr, so stdout should be logged if there is an error. If False, stderr is logged. Could be used with stderr=STDOUT, stdout=PIPE for example.
-
ocrmypdf.subprocess.
run_polling_stderr
(args, *, callback, check=False, env=None, **kwargs)¶ Run a process like
ocrmypdf.subprocess.run
, and poll stderr.Every line of produced by stderr will be forwarded to the callback function. The intended use is monitoring progress of subprocesses that output their own progress indicators. In addition, each line will be logged if debug logging is enabled.
Requires stderr to be opened in text mode for ease of handling errors. In addition the expected encoding= and errors= arguments should be set. Note that if stdout is already set up, it need not be binary.