v16.3.0 release notes

Might take time for big files. Pdf.open() potentially is expensive as well, but QPDF doesn't give us progress feedback for that.

Closes Show progress during postprocessing #1313

.github/ISSUE_TEMPLATE/1-bug-report-general.yml

@@ -24,7 +24,7 @@ body:
   - type: dropdown
     id: packaging-system
     attributes:
-      label: Where are you installing from?
+      label: Where are you installing/running from?
       multiple: true
       options:
         - PyPI (pip, poetry, pipx, etc.)
@@ -37,6 +37,11 @@ body:
         - source build
     validations:
       required: true
+  - type: input
+    id: version
+    attributes:
+      label: OCRmyPDF version
+      description: Paste "ocrmypdf --version" here
   - type: dropdown
     id: operating-system
     attributes:
@@ -47,6 +52,17 @@ body:
         - Windows
         - macOS
         - BSD
+  - type: input
+    id: os_version
+    attributes:
+      label: Operating system details and version
+  - type: checkboxes
+    attributes:
+      label: Simple sanity checks
+      description: Select all that apply
+      options:
+        - label: Operating system is currently supported by its vendor (not end of life)
+        - label: Python version is compatible with OCRmyPDF
   - type: textarea
     id: logs
     attributes:

.github/workflows/build.yml

@@ -101,16 +101,19 @@ jobs:
 
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v4
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
         with:
           files: ./coverage.xml
           env_vars: OS,PYTHON
 
+
   test_macos:
     name: Test macOS
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [macos-latest]
+        os: [macos-latest, macos-13]  # macos-latest is arm64, macos-13 is x86_64
         python: ["3.10", "3.11", "3.12"]
 
     env:

README.md

@@ -70,6 +70,7 @@ Linux, Windows, macOS and FreeBSD are supported. Docker images are also availabl
 | Windows Subsystem for Linux   | ``apt install ocrmypdf``      |
 | Fedora                        | ``dnf install ocrmypdf``      |
 | macOS (Homebrew)              | ``brew install ocrmypdf``     |
+| macOS (MacPorts)              | ``port install ocrmypdf``     |
 | macOS (nix)                   | ``nix-env -i ocrmypdf``       |
 | LinuxBrew                     | ``brew install ocrmypdf``     |
 | FreeBSD                       | ``pkg install py-ocrmypdf``   |

docs/advanced.rst

@@ -118,15 +118,16 @@ OCR for huge images
 -------------------
 
 Tesseract has internal limits on the size
-of images it will process. If you issue
-``--tesseract-downsample-large-images``, OCRmyPDF will downsample images
-to fit Tesseract limits. (The limits are usually entered only for scanned
-images of oversized media, such as large maps or blueprints exceeding
-110 cm or 43 inches in either dimension, and at high DPI.)
+of images it will process. By default,
+``--tesseract-downsample-large-images`` is enabled, and OCRmyPDF will
+downsample images to fit Tesseract limits. (The limits are usually encountered
+only for scanned images of oversized media, such as large maps or blueprints exceeding
+110 cm or 43 inches in either dimension, and at high DPI.) This feature can disabled
+using ``--no-tesseract-downsample-large-images``.
 
 ``--tesseract-downsample-above Npixels`` adjusts the threshold at which images
 will be downsampled. By default, only images that exceed any of Tesseract's
-internal limits are downsampled.
+internal limits are downsampled (32767 pixels on either dimension).
 
 You will also need to set ``--tesseract-timeout`` high enough to allow
 for processing.

docs/installation.rst

@@ -23,7 +23,9 @@ These platforms have one-liner installs:
 +-------------------------------+-----------------------------------------+
 | Fedora                        | ``dnf install ocrmypdf tesseract-osd``  |
 +-------------------------------+-----------------------------------------+
-| macOS                         | ``brew install ocrmypdf``               |
+| macOS (Homebrew)              | ``brew install ocrmypdf``               |
++-------------------------------+-----------------------------------------+
+| macOS (MacPorts)              | ``port install ocrmypdf``               |
 +-------------------------------+-----------------------------------------+
 | LinuxBrew                     | ``brew install ocrmypdf``               |
 +-------------------------------+-----------------------------------------+
@@ -99,12 +101,12 @@ For full details on version availability for your platform, check the
 Fedora
 ------
 
-.. |fedora-37| image:: https://repology.org/badge/version-for-repo/fedora_37/ocrmypdf.svg
-    :alt: Fedora 37
-
 .. |fedora-38| image:: https://repology.org/badge/version-for-repo/fedora_38/ocrmypdf.svg
     :alt: Fedora 38
 
+.. |fedora-39| image:: https://repology.org/badge/version-for-repo/fedora_39/ocrmypdf.svg
+    :alt: Fedora 39
+
 .. |fedora-rawhide| image:: https://repology.org/badge/version-for-repo/fedora_rawhide/ocrmypdf.svg
     :alt: Fedore Rawhide
 
@@ -113,7 +115,7 @@ Fedora
 +-----------------------------------------------+
 | |latest|                                      |
 +-----------------------------------------------+
-| |fedora-37| |fedora-38| |fedora-rawhide|      |
+| |fedora-38| |fedora-39| |fedora-rawhide|      |
 +-----------------------------------------------+
 
 Users of Fedora may simply
@@ -123,7 +125,7 @@ Users of Fedora may simply
     dnf install ocrmypdf tesseract-osd
 
 For full details on version availability, check the `Fedora Package
-Tracker <https://apps.fedoraproject.org/packages/ocrmypdf>`__.
+Tracker <https://packages.fedoraproject.org/pkgs/ocrmypdf/ocrmypdf/>`__.
 
 If the version available for your platform is out of date, you could opt
 to install the latest version from source. See `Installing HEAD revision
@@ -135,7 +137,7 @@ from sources <#installing-head-revision-from-sources>`__.
    issues. OCRmyPDF works fine without it but will produce larger output
    files. If you build jbig2enc from source, ocrmypdf 7.0.0 and later
    will automatically detect it on the ``PATH``. To add JBIG2 encoding,
-   see `Installing the JBIG2 encoder <jbig2>`__.
+   see :ref:`Installing the JBIG2 encoder <jbig2>`.
 
 .. _ubuntu-lts-latest:
 
@@ -160,7 +162,7 @@ and build ocrmypdf in virtual environment:
 
     python3.11 -m venv .venv
 
-To add JBIG2 encoding, see `Installing the JBIG2 encoder <jbig2>`__.
+To add JBIG2 encoding, see :ref:`Installing the JBIG2 encoder <jbig2>`.
 
 Note Fedora packages for language data haven't been branched for RHEL/EPEL, but you can get traineddata files directly from `tesseract
 <https://github.com/tesseract-ocr/tessdata/>`__ and place them in ``/usr/share/tesseract/tessdata``.
@@ -217,7 +219,7 @@ you are using a VM image, such as `the official Vagrant image
 be completed for you.
 
 Next you should install the `base-devel package group
-<https://www.archlinux.org/groups/x86_64/base-devel/>`__. This includes the
+<https://archlinux.org/packages/core/any/base-devel/>`__. This includes the
 standard tooling needed to build packages, such as a compiler and binary tools.
 
 .. code-block:: bash
@@ -260,7 +262,7 @@ page.
     <https://aur.archlinux.org/packages/jbig2enc-git/>`__ and may be installed
     using the same series of steps as for the installation OCRmyPDF AUR
     package. Alternatively, it may be built manually from source following the
-    instructions in `Installing the JBIG2 encoder <jbig2>`__.  If JBIG2 is
+    instructions in :ref:`Installing the JBIG2 encoder <jbig2>`.  If JBIG2 is
     installed, OCRmyPDF 7.0.0 and later will automatically detect it.
 
 Alpine Linux
@@ -325,6 +327,22 @@ languages you can optionally install them all:
 
     brew install tesseract-lang  # Optional: Install all language packs
 
+MacPorts
+--------
+
+.. image:: https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fports.macports.org%2Fapi%2Fv1%2Fports%2Focrmypdf%2F%3Fformat%3Djson&query=version&label=MacPorts
+   :alt: Macports Version Information
+   :target: https://ports.macports.org/port/ocrmypdf
+
+OCRmyPDF is includes in MacPorts:
+
+.. code-block:: bash
+
+    sudo port install ocrmypdf
+
+Note that while this will install tesseract you will need to install
+the appropriate tesseract `language ports <https://ports.macports.org/search/?selected_facets=categories_exact%3Atextproc&installed_file=&q=tesseract&name=on>`__. 
+
 Manual installation on macOS
 ----------------------------
 
@@ -623,7 +641,7 @@ environment:
     pip install git+https://github.com/ocrmypdf/OCRmyPDF.git
 
 Or, to install in `development
-mode <https://pythonhosted.org/setuptools/setuptools.html#development-mode>`__,
+mode <https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/#working-in-development-mode>`__,
 allowing customization of OCRmyPDF, use the ``-e`` flag:
 
 .. code-block:: bash

docs/languages.rst

@@ -68,6 +68,22 @@ to what languages it should search for. Multiple languages can be
 requested using either ``-l eng+fra`` (English and French) or
 ``-l eng -l fra``.
 
+Archlinux
+------
+
+.. code-block:: bash
+
+   # Display a list of all Tesseract language packs
+   pacman -Ss tesseract-data
+
+   # Install German language pack
+   pacman -S tesseract-data-deu
+
+You can then pass the ``-l LANG`` argument to OCRmyPDF to give a hint as
+to what languages it should search for. Multiple languages can be
+requested using either ``-l eng+fra`` (English and French) or
+``-l eng -l fra``.
+
 Gentoo
 ------
 
@@ -122,4 +138,4 @@ Custom language packs
 If you have fine-tuned or trained Tesseract and generated custom trained data, you can
 copy your ``customlang.traineddata`` file into your Tesseract "tessdata" folder, and
 then use the ``-l customlang`` argument to tell OCRmyPDF to pass that language on to
-Tesseract.
+Tesseract.

docs/maintainers.rst

@@ -64,4 +64,13 @@ installation documentation.
 
 If you maintain a Linux distribution that supports 32-bit x86 or ARM, OCRmyPDF
 should continue to work as long as all of its dependencies continue to be
-available in 32-bit form. Please note we do not test on 32-bit platforms.
+available in 32-bit form. Please note we do not test on 32-bit platforms.
+
+HEIF/HEIC
+---------
+
+OCRmyPDF defaults to installing the pi-heif PyPI package, which supports converting
+HEIF (High Efficiency Image File Format) images to PDF from the command line.
+If your distribution does not have this library available, you can exclude it and
+OCRmyPDF will gracefully degrade automatically, losing only support for this
+feature.

docs/release_notes.rst

@@ -30,6 +30,34 @@ OCRmyPDF typically supports the three most recent Python versions.
 
 .. |OCRmyPDF PyPI| image:: https://img.shields.io/pypi/v/ocrmypdf.svg
 
+v16.3.0
+=======
+
+-  Fixed progress bar not displaying for Ghostscript PDF/A conversion. :issue:`1313`
+-  Added progress bar for linearization. :issue:`1313`
+-  If `--rotate-pages-threshold` issued without `--rotate-pages` we now exit with
+   an error since the user likely intended to use `--rotate-pages`. :issue:`1309`
+-  If Tesseract hOCR gives an invalid line box, print an error message instead of
+   exiting with an error. :issue:`1312`
+
+v16.2.0
+=======
+
+-  Fixed issue 'NoneType' object has no attribute 'get' when optimizing certain PDFs.
+   :issue:`1293,1271`
+-  Switched formatting from black to ruff.
+-  Added support for sending sidecar output to io.BytesIO.
+-  Added support for converting HEIF/HEIC images (the native image of iPhones and
+   some other devices) to PDFs, when the appropriate pi-hief library is installed.
+   This library is marked as a dependency, but maintainers may opt out if needed.
+-  We now default to downsampling large images that would exceed Tesseract's internal
+   limits, but only if it cause processing to fail. Previously, this behavior only
+   occurred if specifically requested on command line. It can still be configured
+   and disabled. See the --tesseract command line options.
+-  Added Macports install instructions. Thanks @akierig.
+-  Improved logging output when an unexpected error occurs while trying to obtain
+   the version of a third party program.
+
 v16.1.2
 =======
 

misc/batch.py

@@ -27,7 +27,8 @@ import ocrmypdf
 # pylint: disable=logging-format-interpolation
 # pylint: disable=logging-not-lazy
 
-def filecompare(a,b):
+
+def filecompare(a, b):
     try:
         return filecmp.cmp(a, b, shallow=True)
     except FileNotFoundError:
@@ -82,7 +83,9 @@ for filename in start_dir.glob("**/*.pdf"):
         except ocrmypdf.exceptions.DigitalSignatureError:
             logging.info("Skipped document because it has a digital signature")
         except ocrmypdf.exceptions.TaggedPDFError:
-            logging.info("Skipped document because it does not need ocr as it is tagged")
+            logging.info(
+                "Skipped document because it does not need ocr as it is tagged"
+            )
         except:
             logging.error("Unhandled error occured")
         logging.info("OCR complete")

misc/synology.py

@@ -53,9 +53,10 @@ for dir_name, _subdirs, file_list in os.walk(start_dir):
         ]
         logging.info(cmd)
         full_path_ocr = os.path.join(dir_name, filename_ocr)
-        with open(filename, 'rb') as input_file, open(
-            full_path_ocr, 'wb'
-        ) as output_file:
+        with (
+            open(filename, 'rb') as input_file,
+            open(full_path_ocr, 'wb') as output_file,
+        ):
             proc = subprocess.run(
                 cmd,
                 stdin=input_file,

pyproject.toml

@@ -12,12 +12,13 @@ readme = "README.md"
 license = { text = "MPL-2.0" }
 requires-python = ">=3.10"
 dependencies = [
-  "Pillow>=10.0.1",
   "deprecation>=2.1.0",
   "img2pdf>=0.5",
   "packaging>=20",
   "pdfminer.six>=20220319",
+  "pi-heif",                # Heif image format - maintainers: if this is removed, it will NOT break
   "pikepdf>=8.10.1",
+  "Pillow>=10.0.1",
   "pluggy>=1",
   "rich>=13",
 ]
@@ -60,7 +61,7 @@ test = [
   "types-Pillow",
   "types-humanfriendly",
 ]
-watcher = ["watchdog>=1.0.2", "typer[all]", "python-dotenv"]
+watcher = ["watchdog>=1.0.2", "typer-slim[standard]", "python-dotenv"]
 webservice = ["Flask>=2.0.1"]
 
 [project.scripts]
@@ -78,29 +79,6 @@ namespaces = false
 [tool.distutils.bdist_wheel]
 python-tag = "py310"
 
-[tool.black]
-line-length = 88
-target-version = ["py310", "py311", "py312"]
-skip-string-normalization = true
-include = '\.pyi?$'
-exclude = '''
-/(
-    \.eggs
-  | \.git
-  | \.hg
-  | \.mypy_cache
-  | \.tox
-  | \.venv
-  | _build
-  | buck-out
-  | build
-  | dist
-  | docs
-  | misc
-  | \.egg-info
-)/
-'''
-
 [tool.coverage.run]
 branch = true
 parallel = true
@@ -176,3 +154,6 @@ convention = "google"
 "tests/*.py" = ["D100", "D101", "D102", "D103", "D105"]
 "misc/*.py" = ["D103", "D101", "D102"]
 "src/ocrmypdf/builtin_plugins/*.py" = ["D103", "D102", "D105"]
+
+[tool.ruff.format]
+quote-style = "preserve"

src/ocrmypdf/_defaults.py

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: 2024 James R. Barlow
+# SPDX-License-Identifier: MPL-2.0
+
+# Enforce English hegemony
+DEFAULT_LANGUAGE = 'eng'
+
+# Default rotation threshold
+DEFAULT_ROTATE_PAGES_THRESHOLD = 14.0

src/ocrmypdf/_exec/ghostscript.py

@@ -177,6 +177,17 @@ class GhostscriptFollower:
         self.progressbar_class = progressbar_class
         self.progressbar = None
 
+    def __enter__(self):
+        # We can't actually set up the progressbar here, because we don't know
+        # how many pages there are until the first __call__() happens. So we
+        # do it in __call__().
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        if self.progressbar:
+            return self.progressbar.__exit__(exc_type, exc_value, traceback)
+        return False
+
     def __call__(self, line):
         if not self.progressbar_class:
             return
@@ -187,7 +198,8 @@ class GhostscriptFollower:
                 self.progressbar = self.progressbar_class(
                     total=self.count, desc="PDF/A conversion", unit='page'
                 )
-                return
+                # Now that we know the count, we can set up the progressbar.
+                self.progressbar.__enter__()
         else:
             if self.re_page.match(line.strip()):
                 self.progressbar.update()
@@ -265,7 +277,10 @@ def generate_pdfa(
     )
     args_gs.extend(fspath(s) for s in pdf_pages)  # Stringify Path objs
     try:
-        with Path(output_file).open('wb') as output:
+        with (
+            Path(output_file).open('wb') as output,
+            GhostscriptFollower(progressbar_class) as pbar,
+        ):
             p = run_polling_stderr(
                 args_gs,
                 stdout=output,
@@ -274,7 +289,7 @@ def generate_pdfa(
                 text=True,
                 encoding='utf-8',
                 errors='replace',
-                callback=GhostscriptFollower(progressbar_class),
+                callback=pbar,
             )
     except CalledProcessError as e:
         # Ghostscript does not change return code when it fails to create

src/ocrmypdf/_exec/tesseract.py

@@ -220,7 +220,8 @@ def get_deskew(
 
 def tesseract_log_output(stream: bytes) -> None:
     tlog = TesseractLoggerAdapter(
-        log, extra=log.extra if hasattr(log, 'extra') else None  # type: ignore
+        log,
+        extra=log.extra if hasattr(log, 'extra') else None,  # type: ignore
     )
 
     if not stream:

src/ocrmypdf/_metadata.py

@@ -153,22 +153,52 @@ def _set_language(pdf: Pdf, languages: list[str]):
     pdf.Root.Lang = iso639_2
 
 
+class MetadataProgress:
+    def __init__(self, progressbar_class):
+        self.progressbar_class = progressbar_class
+        self.progressbar = self.progressbar_class(
+            total=100, desc="Linearizing", unit='%'
+        )
+
+    def __enter__(self):
+        self.progressbar.__enter__()
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        return self.progressbar.__exit__(exc_type, exc_value, traceback)
+
+    def __call__(self, percent: int):
+        if not self.progressbar_class:
+            return
+        self.progressbar.update(completed=percent)
+
+
 def metadata_fixup(
     working_file: Path, context: PdfContext, pdf_save_settings: dict[str, Any]
 ) -> Path:
-    """Fix certain metadata fields after Ghostscript PDF/A conversion.
+    """Fix certain metadata fields whether PDF or PDF/A.
+
+    Override some of Ghostscript's metadata choices.
 
     Also report on metadata in the input file that was not retained during
-    PDF/A conversion.
+    conversion.
     """
     output_file = context.get_path('metafix.pdf')
     options = context.options
 
-    with Pdf.open(context.origin) as original, Pdf.open(working_file) as pdf:
+    pbar_class = context.plugin_manager.hook.get_progressbar_class()
+    with (
+        Pdf.open(context.origin) as original,
+        Pdf.open(working_file) as pdf,
+        MetadataProgress(pbar_class) as pbar,
+    ):
         docinfo = get_docinfo(original, context)
-        with original.open_metadata(
-            set_pikepdf_as_editor=False, update_docinfo=False, strict=False
-        ) as meta_original, pdf.open_metadata() as meta_pdf:
+        with (
+            original.open_metadata(
+                set_pikepdf_as_editor=False, update_docinfo=False, strict=False
+            ) as meta_original,
+            pdf.open_metadata() as meta_pdf,
+        ):
             meta_pdf.load_from_docinfo(
                 docinfo, delete_missing=False, raise_failure=False
             )
@@ -179,6 +209,6 @@ def metadata_fixup(
             report_on_metadata(options, meta_missing)
 
         _set_language(pdf, options.languages)
-        pdf.save(output_file, **pdf_save_settings)
+        pdf.save(output_file, progress=pbar, **pdf_save_settings)
 
     return output_file

src/ocrmypdf/_pipeline.py

@@ -41,12 +41,23 @@ from ocrmypdf.pdfa import generate_pdfa_ps
 from ocrmypdf.pdfinfo import Colorspace, Encoding, PageInfo, PdfInfo
 from ocrmypdf.pluginspec import OrientationConfidence
 
+try:
+    from pi_heif import register_heif_opener
+except ImportError:
+
+    def register_heif_opener():
+        pass
+
+
 T = TypeVar("T")
 log = logging.getLogger(__name__)
 
 VECTOR_PAGE_DPI = 400
 
 
+register_heif_opener()
+
+
 def triage_image_file(input_file: Path, output_file: Path, options) -> None:
     """Triage the input image file.
 
@@ -131,7 +142,7 @@ def _pdf_guess_version(input_file: Path, search_window=1024) -> str:
     """
     with open(input_file, 'rb') as f:
         signature = f.read(search_window)
-    m = re.search(br'%PDF-(\d\.\d)', signature)
+    m = re.search(rb'%PDF-(\d\.\d)', signature)
     if m:
         return m.group(1).decode('ascii')
     return ''
@@ -767,7 +778,9 @@ def render_hocr_page(hocr: Path, page_context: PageContext) -> Path:
             font=Courier(),
         )
     HocrTransform(
-        hocr_filename=hocr, dpi=dpi.to_scalar(), **debug_kwargs  # square
+        hocr_filename=hocr,
+        dpi=dpi.to_scalar(),
+        **debug_kwargs,  # square
     ).to_pdf(
         out_filename=output_file,
         image_filename=None,

src/ocrmypdf/_pipelines/hocr_to_ocr_pdf.py

@@ -4,7 +4,6 @@
 
 """Implements the concurrent and page synchronous parts of the pipeline."""
 
-
 from __future__ import annotations
 
 import argparse

src/ocrmypdf/_pipelines/ocr.py

@@ -4,7 +4,6 @@
 
 """Implements the concurrent and page synchronous parts of the pipeline."""
 
-
 from __future__ import annotations
 
 import argparse
@@ -155,12 +154,13 @@ def _run_pipeline(
     options: argparse.Namespace,
     plugin_manager: OcrmypdfPluginManager,
 ) -> ExitCode:
-    with manage_work_folder(
-        work_folder=Path(mkdtemp(prefix="ocrmypdf.io.")),
-        retain=options.keep_temporary_files,
-        print_location=options.keep_temporary_files,
-    ) as work_folder, manage_debug_log_handler(
-        options=options, work_folder=work_folder
+    with (
+        manage_work_folder(
+            work_folder=Path(mkdtemp(prefix="ocrmypdf.io.")),
+            retain=options.keep_temporary_files,
+            print_location=options.keep_temporary_files,
+        ) as work_folder,
+        manage_debug_log_handler(options=options, work_folder=work_folder),
     ):
         executor = setup_pipeline(options, plugin_manager)
         check_requested_output_file(options)

src/ocrmypdf/_pipelines/pdf_to_hocr.py

@@ -4,7 +4,6 @@
 
 """Implements the concurrent and page synchronous parts of the pipeline."""
 
-
 from __future__ import annotations
 
 import argparse

src/ocrmypdf/_progressbar.py

@@ -66,7 +66,7 @@ class ProgressBar(Protocol):
     def __exit__(self, *args):
         """Exit a progress bar context."""
 
-    def update(self, n=1):
+    def update(self, n=1, *, completed=None):
         """Update the progress bar by an increment.
 
         For use within a progress bar context.
@@ -85,7 +85,7 @@ class NullProgressBar:
     def __exit__(self, exc_type, exc_value, traceback):
         return False
 
-    def update(self, _arg=None):
+    def update(self, _arg=None, *, completed=None):
         return
 
 
@@ -103,6 +103,7 @@ class RichProgressBar:
         disable: bool = False,
         **kwargs,
     ):
+        self._entered = False
         self.progress = Progress(
             TextColumn(
                 "[progress.description]{task.description}",
@@ -130,6 +131,7 @@ class RichProgressBar:
 
     def __enter__(self):
         self.progress.start()
+        self._entered = True
         return self
 
     def __exit__(self, exc_type, exc_value, traceback):
@@ -137,6 +139,10 @@ class RichProgressBar:
         self.progress.stop()
         return False
 
-    def update(self, value=None):
-        advance = self.unit_scale if value is None else value
-        self.progress.update(self.progress_bar, advance=advance)
+    def update(self, n=1, *, completed=None):
+        assert self._entered, "Progress bar must be entered before updating"
+        if completed is None:
+            advance = self.unit_scale if n is None else n
+            self.progress.update(self.progress_bar, advance=advance)
+        else:
+            self.progress.update(self.progress_bar, completed=completed)

src/ocrmypdf/_validation.py

@@ -20,6 +20,7 @@ import pikepdf
 import PIL
 from pluggy import PluginManager
 
+from ocrmypdf._defaults import DEFAULT_LANGUAGE, DEFAULT_ROTATE_PAGES_THRESHOLD
 from ocrmypdf._exec import unpaper
 from ocrmypdf.exceptions import (
     BadArgsError,
@@ -30,17 +31,9 @@ from ocrmypdf.exceptions import (
 from ocrmypdf.helpers import is_file_writable, monotonic, safe_symlink
 from ocrmypdf.subprocess import check_external_program
 
-# -------------
-# External dependencies
-
-DEFAULT_LANGUAGE = 'eng'  # Enforce English hegemony
-
 log = logging.getLogger(__name__)
 
 
-# --------
-
-
 def check_platform() -> None:
     if sys.maxsize <= 2**32:  # pragma: no cover
         log.warning(
@@ -130,6 +123,11 @@ def check_options_preprocessing(options: Namespace) -> None:
         options.clean = True
     if options.unpaper_args and not options.clean:
         raise BadArgsError("--clean is required for --unpaper-args")
+    if (
+        options.rotate_pages_threshold != DEFAULT_ROTATE_PAGES_THRESHOLD
+        and not options.rotate_pages
+    ):
+        raise BadArgsError("--rotate-pages is required for --rotate-pages-threshold")
     if options.clean:
         check_external_program(
             program='unpaper',

src/ocrmypdf/api.py

@@ -209,6 +209,9 @@ def create_options(
         cmdline.append('stream://output_file')
     else:
         cmdline.append(os.fspath(output_file))
+    if 'sidecar' in kwargs and isinstance(kwargs['sidecar'], BinaryIO | IOBase):
+        cmdline.append('--sidecar')
+        cmdline.append('stream://sidecar')
 
     parser.enable_api_mode()
     options = parser.parse_args(cmdline)
@@ -219,6 +222,8 @@ def create_options(
         options.input_file = input_file
     if options.output_file == 'stream://output_file':
         options.output_file = output_file
+    if options.sidecar == 'stream://sidecar':
+        options.sidecar = kwargs['sidecar']
 
     return options
 
@@ -230,7 +235,7 @@ def ocr(  # noqa: D417
     language: Iterable[str] | None = None,
     image_dpi: int | None = None,
     output_type: str | None = None,
-    sidecar: StrPath | None = None,
+    sidecar: PathOrIO | None = None,
     jobs: int | None = None,
     use_threads: bool | None = None,
     title: str | None = None,

src/ocrmypdf/builtin_plugins/default_filters.py

@@ -8,7 +8,5 @@ from ocrmypdf import hookimpl
 
 
 @hookimpl
-def filter_pdf_page(
-    page, image_filename, output_pdf
-):  # pylint: disable=unused-argument
+def filter_pdf_page(page, image_filename, output_pdf):  # pylint: disable=unused-argument
     return output_pdf

src/ocrmypdf/builtin_plugins/tesseract_ocr.py

@@ -2,9 +2,9 @@
 # SPDX-License-Identifier: MPL-2.0
 """Built-in plugin to implement OCR using Tesseract."""
 
-
 from __future__ import annotations
 
+import argparse
 import logging
 import os
 
@@ -94,7 +94,8 @@ def add_options(parser):
     )
     tess.add_argument(
         '--tesseract-downsample-large-images',
-        action='store_true',
+        action=argparse.BooleanOptionalAction,
+        default=True,
         help=(
             "Downsample large images before OCR. Tesseract has an upper limit on the "
             "size images it will support. If this argument is given, OCRmyPDF will "
@@ -220,7 +221,7 @@ class TesseractOcrEngine(OcrEngine):
 
     @staticmethod
     def creator_tag(options):
-        tag = '-PDF' if options.pdf_renderer == 'sandwich' else 'hOCR'
+        tag = '-PDF' if options.pdf_renderer == 'sandwich' else '-hOCR'
         return f"Tesseract OCR{tag} {TesseractOcrEngine.version()}"
 
     def __str__(self):

src/ocrmypdf/cli.py

@@ -9,6 +9,7 @@ import argparse
 from collections.abc import Callable, Mapping
 from typing import Any, TypeVar
 
+from ocrmypdf._defaults import DEFAULT_ROTATE_PAGES_THRESHOLD
 from ocrmypdf._version import PROGRAM_NAME as _PROGRAM_NAME
 from ocrmypdf._version import __version__ as _VERSION
 
@@ -403,7 +404,7 @@ Online documentation is located at:
     )
     advanced.add_argument(
         '--rotate-pages-threshold',
-        default=14.0,
+        default=DEFAULT_ROTATE_PAGES_THRESHOLD,
         type=numeric(float, 0, 1000),
         metavar='CONFIDENCE',
         help="Only rotate pages when confidence is above this value (arbitrary "

src/ocrmypdf/hocrtransform/_hocr.py

@@ -117,15 +117,12 @@ class HocrTransform:
             # Stop after first div that has page coordinates
             break
 
-    def _get_element_text(self, element: Element):
+    def _get_element_text(self, element: Element) -> str:
         """Return the textual content of the element and its children."""
-        text = ''
-        if element.text is not None:
-            text += element.text
+        text = element.text if element.text is not None else ''
         for child in element:
             text += self._get_element_text(child)
-        if element.tail is not None:
-            text += element.tail
+        text += element.tail if element.tail is not None else ''
         return text
 
     @classmethod
@@ -286,7 +283,10 @@ class HocrTransform:
         line_box = self.element_coordinates(line)
         if not line_box:
             return
-        assert line_box.ury > line_box.lly  # lly is top, ury is bottom
+        if line_box.ury <= line_box.lly:
+            log.error("line box is invalid so we cannot render it: box=%s text=%s",
+                      line_box, self._get_element_text(line))
+            return
 
         self._debug_draw_line_bbox(canvas, line_box)
 

src/ocrmypdf/languages.py

@@ -7,12 +7,12 @@ Derived from
 https://www.loc.gov/standards/iso639-2/ascii_8bits.html
 """
 
-
 from typing import NamedTuple
 
 
 class ISOCodeData(NamedTuple):
     """Data for a single ISO 639 code."""
+
     alt: str
     alpha_2: str
     english: str
@@ -168,8 +168,10 @@ ISO_639_3 = {
     'chu': ISOCodeData(
         '',
         'cu',
-        ('Church Slavic; Old Slavonic; Church Slavonic;'
-         ' Old Bulgarian; Old Church Slavonic'),
+        (
+            'Church Slavic; Old Slavonic; Church Slavonic;'
+            ' Old Bulgarian; Old Church Slavonic'
+        ),
         "slavon d'église; vieux slave; slavon liturgique; vieux bulgare",
     ),
     'chv': ISOCodeData('', 'cv', 'Chuvash', 'tchouvache'),

src/ocrmypdf/optimize.py

@@ -3,7 +3,6 @@
 
 """Post-processing image optimization of OCR PDFs."""
 
-
 from __future__ import annotations
 
 import logging
@@ -90,6 +89,7 @@ def extract_image_filter(
         if (
             len(pim.filter_decodeparms) == 2
             and first_filtdp[0] == Name.FlateDecode
+            and first_filtdp[1] is not None
             and first_filtdp[1].get(Name.Predictor, 1) == 1
             and second_filtdp[0] == Name.DCTDecode
             and not second_filtdp[1]

src/ocrmypdf/pdfa.py

@@ -90,7 +90,7 @@ def generate_pdfa_ps(target_filename: Path, icc: str = 'sRGB'):
         icc: ICC identifier such as 'sRGB'
     References:
         Adobe PDFMARK Reference:
-        https://www.adobe.com/content/dam/acom/en/devnet/acrobat/pdfs/pdfmark_reference.pdf
+        https://opensource.adobe.com/dc-acrobat-sdk-docs/library/pdfmark/
     """
     if icc != 'sRGB':
         raise NotImplementedError("Only supporting sRGB")

src/ocrmypdf/pdfinfo/info.py

@@ -239,7 +239,13 @@ def _interpret_contents(contentstream: Object, initial_shorthand=UNIT_SQUARE):
                 # to do. Just pretend nothing happened, keep calm and carry on.
                 warn("PDF graphics stack underflowed - PDF may be malformed")
         elif operator == 'cm':
-            ctm = Matrix(operands) @ ctm
+            try:
+                ctm = Matrix(operands) @ ctm
+            except ValueError:
+                raise InputFileError(
+                    "PDF content stream is corrupt - this PDF is malformed. "
+                    "Use a PDF editor that is capable of visually inspecting the PDF."
+                )
         elif operator == 'Do':
             image_name = operands[0]
             settings = XobjectSettings(

src/ocrmypdf/quality.py

@@ -3,7 +3,6 @@
 
 """Utilities to measure OCR quality."""
 
-
 from __future__ import annotations
 
 import re

src/ocrmypdf/subprocess/__init__.py

@@ -171,6 +171,7 @@ def get_version(
         ) from e
     except CalledProcessError as e:
         if e.returncode != 0:
+            log.exception(e)
             raise MissingDependencyError(
                 f"Ran program '{program}' but it exited with an error:\n{e.output}"
             ) from e

src/ocrmypdf/subprocess/_windows.py

@@ -79,7 +79,7 @@ def registry_path_ghostscript(env=None) -> Iterator[Path]:
                 registry_subkeys(k), key=ghostscript_version_key, default=(0, 0, 0)
             )
         with winreg.OpenKey(
-            winreg.HKEY_LOCAL_MACHINE, fr"SOFTWARE\Artifex\GPL Ghostscript\{latest_gs}"
+            winreg.HKEY_LOCAL_MACHINE, rf"SOFTWARE\Artifex\GPL Ghostscript\{latest_gs}"
         ) as k:
             for _, gs_path, _ in registry_values(k):
                 yield Path(gs_path) / 'bin'

tests/plugins/tesseract_cache.py

@@ -169,22 +169,25 @@ class CacheOcrEngine(TesseractOcrEngine):
 
     @staticmethod
     def get_orientation(input_file, options):
-        with CacheOcrEngine.lock, patch(
-            'ocrmypdf._exec.tesseract.run', new=partial(cached_run, options)
+        with (
+            CacheOcrEngine.lock,
+            patch('ocrmypdf._exec.tesseract.run', new=partial(cached_run, options)),
         ):
             return TesseractOcrEngine.get_orientation(input_file, options)
 
     @staticmethod
     def get_deskew(input_file, options) -> float:
-        with CacheOcrEngine.lock, patch(
-            'ocrmypdf._exec.tesseract.run', new=partial(cached_run, options)
+        with (
+            CacheOcrEngine.lock,
+            patch('ocrmypdf._exec.tesseract.run', new=partial(cached_run, options)),
         ):
             return TesseractOcrEngine.get_deskew(input_file, options)
 
     @staticmethod
     def generate_hocr(input_file, output_hocr, output_text, options):
-        with CacheOcrEngine.lock, patch(
-            'ocrmypdf._exec.tesseract.run', new=partial(cached_run, options)
+        with (
+            CacheOcrEngine.lock,
+            patch('ocrmypdf._exec.tesseract.run', new=partial(cached_run, options)),
         ):
             TesseractOcrEngine.generate_hocr(
                 input_file, output_hocr, output_text, options
@@ -192,8 +195,9 @@ class CacheOcrEngine(TesseractOcrEngine):
 
     @staticmethod
     def generate_pdf(input_file, output_pdf, output_text, options):
-        with CacheOcrEngine.lock, patch(
-            'ocrmypdf._exec.tesseract.run', new=partial(cached_run, options)
+        with (
+            CacheOcrEngine.lock,
+            patch('ocrmypdf._exec.tesseract.run', new=partial(cached_run, options)),
         ):
             TesseractOcrEngine.generate_pdf(
                 input_file, output_pdf, output_text, options

tests/plugins/tesseract_debug_rotate.py

@@ -72,9 +72,10 @@ class FixedRotateNoopOcrEngine(OcrEngine):
 
     @staticmethod
     def generate_hocr(input_file, output_hocr, output_text, options):
-        with Image.open(input_file) as im, open(
-            output_hocr, 'w', encoding='utf-8'
-        ) as f:
+        with (
+            Image.open(input_file) as im,
+            open(output_hocr, 'w', encoding='utf-8') as f,
+        ):
             w, h = im.size
             f.write(HOCR_TEMPLATE.format(str(w), str(h)))
         with open(output_text, 'w') as f:

tests/plugins/tesseract_noop.py

@@ -70,9 +70,10 @@ class NoopOcrEngine(OcrEngine):
 
     @staticmethod
     def generate_hocr(input_file, output_hocr, output_text, options):
-        with Image.open(input_file) as im, open(
-            output_hocr, 'w', encoding='utf-8'
-        ) as f:
+        with (
+            Image.open(input_file) as im,
+            open(output_hocr, 'w', encoding='utf-8') as f,
+        ):
             w, h = im.size
             f.write(HOCR_TEMPLATE.format(str(w), str(h)))
         with open(output_text, 'w') as f:

tests/plugins/tesseract_simulate_oom_killer.py

@@ -9,6 +9,7 @@ ensure we fail with an error rather than deadlock in such cases.
 Page 4 was chosen because of this number's association with bad luck
 in many East Asian cultures.
 """
+
 # type: ignore
 from __future__ import annotations
 

tests/test_api.py

@@ -29,6 +29,18 @@ def test_stream_api(resources: Path):
     assert b'%PDF' in out.read(1024)
 
 
+def test_sidecar_stringio(resources: Path, outdir: Path, outpdf: Path):
+    s = BytesIO()
+    ocrmypdf.ocr(
+        resources / 'ccitt.pdf',
+        outpdf,
+        plugins=['tests/plugins/tesseract_cache.py'],
+        sidecar=s
+    )
+    s.seek(0)
+    assert b'the' in s.getvalue()
+
+
 def test_hocr_api_multipage(resources: Path, outdir: Path, outpdf: Path):
     ocrmypdf.api._pdf_to_hocr(
         resources / 'multipage.pdf',
@@ -62,3 +74,4 @@ def test_hocr_to_pdf_api(resources: Path, outdir: Path, outpdf: Path):
 
     text = extract_text(outpdf)
     assert 'hocr' in text and 'the' not in text
+

tests/test_graft.py

@@ -11,9 +11,11 @@ import ocrmypdf
 
 
 def test_no_glyphless_graft(resources, outdir):
-    with pikepdf.open(resources / 'francais.pdf') as pdf, pikepdf.open(
-        resources / 'aspect.pdf'
-    ) as pdf_aspect, pikepdf.open(resources / 'cmyk.pdf') as pdf_cmyk:
+    with (
+        pikepdf.open(resources / 'francais.pdf') as pdf,
+        pikepdf.open(resources / 'aspect.pdf') as pdf_aspect,
+        pikepdf.open(resources / 'cmyk.pdf') as pdf_cmyk,
+    ):
         pdf.pages.extend(pdf_aspect.pages)
         pdf.pages.extend(pdf_cmyk.pages)
         pdf.save(outdir / 'test.pdf')

tests/test_metadata.py

@@ -35,9 +35,10 @@ def test_preserve_docinfo(output_type, resources, outpdf):
         '--plugin',
         'tests/plugins/tesseract_noop.py',
     )
-    with pikepdf.open(resources / 'graph.pdf') as pdf_before, pikepdf.open(
-        output
-    ) as pdf_after:
+    with (
+        pikepdf.open(resources / 'graph.pdf') as pdf_before,
+        pikepdf.open(output) as pdf_after,
+    ):
         for key in ('/Title', '/Author'):
             assert pdf_before.docinfo[key] == pdf_after.docinfo[key]
         pdfa_info = file_claims_pdfa(str(output))