Begin API documentation

src/ocrmypdf/__init__.py

@@ -44,4 +44,4 @@ from . import hocrtransform
 from . import leptonica
 from . import pdfa
 from . import pdfinfo
-from .api import ocrmypdf
+from .api import ocrmypdf, configure_logging, Verbosity

src/ocrmypdf/__main__.py

@@ -22,14 +22,14 @@ import sys
 
 from . import __version__
 from .cli import parser
-from .api import configure_logging
+from .api import configure_logging, Verbosity
 from ._jobcontext import make_logger
 from ._sync import run_pipeline
 from ._validation import check_closed_streams, check_options
 from .exceptions import ExitCode, BadArgsError, MissingDependencyError
 
 
-def main(args=None):
+def run(args=None):
     options = parser.parse_args(args=args)
 
     if not check_closed_streams(options):
@@ -44,7 +44,7 @@ def main(args=None):
     if not os.isatty(sys.stderr.fileno()):
         options.progress_bar = False
     if options.quiet:
-        verbosity = -1
+        verbosity = Verbosity.quiet
         options.progress_bar = False
     configure_logging(
         verbosity, progress_bar_friendly=options.progress_bar, manage_root_logger=True
@@ -68,4 +68,4 @@ def main(args=None):
 
 
 if __name__ == '__main__':
-    sys.exit(main())
+    sys.exit(run())

src/ocrmypdf/api.py

@@ -17,6 +17,7 @@
 
 import logging
 import sys
+from enum import IntEnum
 from pathlib import Path
 
 from tqdm import tqdm
@@ -46,8 +47,17 @@ class TqdmConsole:
             self.file.flush()
 
 
+class Verbosity(IntEnum):
+    """Verbosity level for configure_logging."""
+
+    quiet = -1  #: Suppress most messages
+    default = 0  #: Default level of logging
+    debug = 1  #: Output ocrmypdf debug messages
+    debug_all = 2  #: More detailed debugging from ocrmypdf and dependent modules
+
+
 def configure_logging(verbosity, progress_bar_friendly=True, manage_root_logger=False):
-    """Set up logging
+    """Set up logging.
 
     Library users may wish to use this function if they want their log output to be
     similar to ocrmypdf command line interface. If not used, the external application
@@ -61,11 +71,7 @@ def configure_logging(verbosity, progress_bar_friendly=True, manage_root_logger=
     Library users may perform additional configuration afterwards.
 
     Args:
-        verbosity: Verbosity level.
-            * `-1`: Quiet
-            * `0`: Default
-            * `1`: Output ocrmypdf debug messages
-            * `2`: More detailed debugging from ocrmypdf and dependent modules
+        verbosity (Verbosity): Verbosity level.
         progress_bar_friendly (bool): Install the TqdmConsole log handler, which is
             compatible with the tqdm progress bar; without this log messages will
             overwrite the progress bar
@@ -176,7 +182,34 @@ def ocrmypdf(  # pylint: disable=unused-argument
     user_patterns=None,
     keep_temporary_files=None,
     progress_bar=None,
+    process_ocr_image=None,
 ):
+    """Run OCRmyPDF on one PDF or image.
+
+    Raises:
+        ocrmypdf.PdfMergeFailedError: If the input PDF is malformed, preventing merging
+            with the OCR layer.
+        ocrmypdf.MissingDependencyError: If a required dependency program is missing or
+            was not found on PATH.
+        ocrmypdf.UnsupportedImageFormatError: If the input file type was an image that
+            could not be read, or some other file type that is not a PDF.
+        ocrmypdf.DpiError: If the input file is an image, but the resolution of the
+            image is not credible (allowing it to proceed would cause poor OCR).
+        ocrmypdf.OutputFileAccessError: If an attempt to write to the intended output
+            file failed.
+        ocrmypdf.PriorOcrFoundError: If the input PDF seems to have OCR or digital
+            text already, and settings did not tell us to proceed.
+        ocrmypdf.InputFileError: Any other problem with the input file.
+        ocrmypdf.SubprocessOutputError: Any error related to executing a subprocess.
+        ocrmypdf.EncryptedPdfERror: If the input PDF is encrypted (password protected).
+            OCRmyPDF does not remove passwords.
+        ocrmypdf.TesseractConfigError: If Tesseract reported its configuration was not
+            valid.
+
+    Returns:
+        :class:`ocrmypdf.ExitCode`
+    """
+
     options = create_options(**locals())
     check_options(options)
     return run_pipeline(options, api=True)