v11.6.0 release notes

.github/ISSUE_TEMPLATE/1-general-issues.md

@@ -21,8 +21,12 @@ If applicable, add screenshots to help explain your problem.
 
 **System (please complete the following information):**
  - OS:
- - Python version: 
+ - Python version:
  - OCRmyPDF version:
 
+**Installation**
+How did you install OCRmyPDF? Did you install it from your operating system's
+package manager, or using pip?
+
 **Additional context**
 Add any other context about the problem here.

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v3.1.0
+    rev: v3.4.0
     hooks:
       - id: check-case-conflict
       - id: check-merge-conflict
@@ -12,11 +12,11 @@ repos:
     hooks:
       - id: seed-isort-config
   - repo: https://github.com/pre-commit/mirrors-isort
-    rev: v5.0.5 # pick the isort version you'd like to use from https://github.com/pre-commit/mirrors-isort/releases
+    rev: v5.7.0 # pick the isort version you'd like to use from https://github.com/pre-commit/mirrors-isort/releases
     hooks:
       - id: isort
   - repo: https://github.com/psf/black
-    rev: 19.10b0
+    rev: 20.8b1
     hooks:
       - id: black
         language_version: python

docs/apiref.rst

@@ -5,6 +5,15 @@ API Reference
 This page summarizes the rest of the public API. Generally speaking this
 should mainly of interest to plugin developers.
 
+ocrmypdf
+========
+
+.. autoclass:: ocrmypdf.PageContext
+    :members:
+
+.. autoclass:: ocrmypdf.PdfContext
+    :members:
+
 ocrmypdf.exceptions
 ===================
 
@@ -17,6 +26,9 @@ ocrmypdf.helpers
 
 .. automodule:: ocrmypdf.helpers
     :members:
+    :noindex: deprecated
+
+    .. autodecorator:: deprecated
 
 ocrmypdf.hocrtransform
 ======================

docs/installation.rst

@@ -520,7 +520,7 @@ DLLs or other Windows patches, and may require a reboot.
 You may then use ``pip`` to install ocrmypdf. (This can performed by a user or
 Administrator.):
 
-* ``pip install ocrmypdf
+* ``pip install ocrmypdf``
 
 Chocolatey automatically selects appropriate versions of these applications. If you
 are installing them manually, please install 64-bit versions of all applications for
@@ -533,6 +533,12 @@ override the versions OCRmyPDF selects, you can modify the ``PATH`` environment
 variable. `Follow these directions <https://www.computerhope.com/issues/ch000549.htm#dospath>`_
 to change the PATH.
 
+.. warning::
+
+    As of early 2021, users have reported problems with the Microsoft Store version of
+    Python affected most third party Python packages including OCRmyPDF. Please use
+    Python downloaded from Python.org or Chocolatey as recommended here.
+
 Windows Subsystem for Linux
 ---------------------------
 

docs/plugins.rst

@@ -65,6 +65,27 @@ similar to ``pytest`` packages such as ``pytest-cov`` (the package) and
     ``ocrmypdf-`` (for the package name on PyPI) and ``ocrmypdf_`` (for the
     module), just like pytest plugins.
 
+Setuptools plugins
+==================
+
+You can also create a plugin that OCRmyPDF will always automatically load if both are
+installed in the same virtual environment, using a setuptools entrypoint.
+
+Your package's ``setup.py`` would need to contain the following, for a plugin
+named ``ocrmypdf-exampleplugin``:
+
+.. code-block:: python
+
+    # sample ./setup.py file
+    from setuptools import setup
+
+    setup(
+        name="ocrmypdf-exampleplugin",
+        packages=["exampleplugin"],
+        # the following makes a plugin available to pytest
+        entry_points={"ocrmypdf": ["exampleplugin = exampleplugin.pluginmodule"]},
+    )
+
 Plugin requirements
 ===================
 

docs/release_notes.rst

@@ -12,6 +12,16 @@ may be unreliable. Use the API to depend on precise behavior.
 The public API may be useful in scripts that launch OCRmyPDF processes or that
 wish to use some of its features for working with PDFs.
 
+v11.6.0
+=======
+
+-  OCRmyPDF will now automatically register plugins from the same virtual environment
+   with an appropriate setuptools entrypoint.
+-  Refactor the plugin manager to remove unnecessary complications and make plugin
+   registration more automatic.
+-  ``PageContext`` and ``PdfContext`` are now formally part of the API, as they
+   should have been, since they were part of ``ocrmypdf.pluginspec``.
+
 v11.5.0
 =======
 

src/ocrmypdf/__init__.py

@@ -8,6 +8,7 @@
 from pluggy import HookimplMarker as _HookimplMarker
 
 from ocrmypdf import helpers, hocrtransform, leptonica, pdfa, pdfinfo
+from ocrmypdf._jobcontext import PageContext, PdfContext
 from ocrmypdf._version import PROGRAM_NAME, __version__
 from ocrmypdf.api import Verbosity, configure_logging, ocr
 from ocrmypdf.exceptions import (

src/ocrmypdf/_exec/pngquant.py

@@ -9,10 +9,8 @@
 
 from contextlib import contextmanager
 from io import BytesIO
-from os import fspath
 from pathlib import Path
 from subprocess import PIPE
-from tempfile import NamedTemporaryFile
 
 from PIL import Image
 

src/ocrmypdf/_jobcontext.py

@@ -10,15 +10,22 @@ import shutil
 import sys
 from argparse import Namespace
 from copy import copy
-from io import IOBase
 from pathlib import Path
 from typing import Iterator
 
+from pluggy import PluginManager
+
 from ocrmypdf.pdfinfo import PdfInfo
+from ocrmypdf.pdfinfo.info import PageInfo
 
 
 class PdfContext:
-    """Holds our context for a particular run of the pipeline"""
+    """Holds the context for a particular run of the pipeline."""
+
+    options: Namespace  #: The specified options for processing this PDF.
+    origin: Path  #: The filename of the original input file.
+    pdfinfo: PdfInfo  #: Detailed data for this PDF.
+    plugin_manager: PluginManager  #: PluginManager for processing the current PDF.
 
     def __init__(
         self,
@@ -35,21 +42,33 @@ class PdfContext:
         self.plugin_manager = plugin_manager
 
     def get_path(self, name: str) -> 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.
+        """
         return self.work_folder / name
 
     def get_page_contexts(self) -> Iterator['PageContext']:
+        """Get all ``PageContext`` for this PDF."""
         npages = len(self.pdfinfo)
         for n in range(npages):
             yield PageContext(self, n)
 
 
 class PageContext:
-    """Holds our context for a page
+    """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__.
+    capable of their serializing themselves via ``__getstate__``.
     """
 
+    options: Namespace  #: The specified options for processing this PDF.
+    origin: Path  #: The filename of the original input file.
+    pageno: int  #: This page number (zero-based).
+    pageinfo: PageInfo  #: Information on this page.
+    plugin_manager: PluginManager  #: PluginManager for processing the current PDF.
+
     def __init__(self, pdf_context: PdfContext, pageno):
         self.work_folder = pdf_context.work_folder
         self.origin = pdf_context.origin
@@ -59,6 +78,11 @@ class PageContext:
         self.plugin_manager = pdf_context.plugin_manager
 
     def get_path(self, name: str) -> 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.
+        """
         return self.work_folder / ("%06d_%s" % (self.pageno + 1, name))
 
     def __getstate__(self):

src/ocrmypdf/_plugin_manager.py

@@ -8,13 +8,14 @@
 import argparse
 import importlib
 import importlib.util
+import pkgutil
 import sys
-from functools import partial
 from pathlib import Path
-from typing import Callable, List, Tuple, Union
+from typing import List, Tuple, Union
 
 import pluggy
 
+import ocrmypdf.builtin_plugins
 from ocrmypdf import pluginspec
 from ocrmypdf.cli import get_parser, plugins_only_parser
 
@@ -30,62 +31,69 @@ class OcrmypdfPluginManager(pluggy.PluginManager):
     """
 
     def __init__(
-        self, *args, setup_func: Callable[[pluggy.PluginManager], None], **kwargs
+        self,
+        *args,
+        plugins: List[Union[str, Path]],
+        builtins: bool = True,
+        **kwargs,
     ):
-        self._init_args = args
-        self._setup_func = setup_func
-        self._init_kwargs = kwargs
+        self.__init_args = args
+        self.__init_kwargs = kwargs
+        self.__plugins = plugins
+        self.__builtins = builtins
         super().__init__(*args, **kwargs)
-        setup_func(self)
+        self.setup_plugins()
 
     def __getstate__(self):
         state = dict(
-            _init_args=self._init_args,
-            _setup_func=self._setup_func,
-            _init_kwargs=self._init_kwargs,
+            init_args=self.__init_args,
+            plugins=self.__plugins,
+            builtins=self.__builtins,
+            init_kwargs=self.__init_kwargs,
         )
         return state
 
     def __setstate__(self, state):
         self.__init__(
-            *state['_init_args'],
-            setup_func=state['_setup_func'],
-            **state['_init_kwargs'],
+            *state['init_args'],
+            plugins=state['plugins'],
+            builtins=state['builtins'],
+            **state['init_kwargs'],
         )
 
+    def setup_plugins(self):
+        self.add_hookspecs(pluginspec)
 
-def _setup_plugins(
-    pm: pluggy.PluginManager, plugins: List[Union[str, Path]], builtins: bool = True
-):
-    pm.add_hookspecs(pluginspec)
+        # 1. Register builtins
+        if self.__builtins:
+            for module in pkgutil.iter_modules(ocrmypdf.builtin_plugins.__path__):
+                name = f'ocrmypdf.builtin_plugins.{module.name}'
+                module = importlib.import_module(name)
+                self.register(module)
 
-    all_plugins: List[Union[str, Path]] = []
-    if builtins:
-        all_plugins.extend(
-            [
-                'ocrmypdf.builtin_plugins.ghostscript',
-                'ocrmypdf.builtin_plugins.tesseract_ocr',
-            ]
-        )
-    all_plugins.extend(plugins)
-    for name in all_plugins:
-        if isinstance(name, Path) or name.endswith('.py'):
-            # Import by filename
-            module_name = Path(name).stem
-            spec = importlib.util.spec_from_file_location(module_name, name)
-            module = importlib.util.module_from_spec(spec)
-            sys.modules[module_name] = module
-            spec.loader.exec_module(module)
-        else:
-            # Import by dotted module name
-            module = importlib.import_module(name)
-        pm.register(module)
+        # 2. Register setuptools plugins
+        self.load_setuptools_entrypoints('ocrmypdf')
+
+        # 3. Register plugins specified on command line
+        for name in self.__plugins:
+            if isinstance(name, Path) or name.endswith('.py'):
+                # Import by filename
+                module_name = Path(name).stem
+                spec = importlib.util.spec_from_file_location(module_name, name)
+                module = importlib.util.module_from_spec(spec)
+                sys.modules[module_name] = module
+                spec.loader.exec_module(module)
+            else:
+                # Import by dotted module name
+                module = importlib.import_module(name)
+            self.register(module)
 
 
 def get_plugin_manager(plugins: List[Union[str, Path]], builtins=True):
     pm = OcrmypdfPluginManager(
         project_name='ocrmypdf',
-        setup_func=partial(_setup_plugins, plugins=plugins, builtins=builtins),
+        plugins=plugins,
+        builtins=builtins,
     )
     return pm
 

src/ocrmypdf/helpers.py

@@ -17,7 +17,7 @@ from functools import wraps
 from io import StringIO
 from math import isclose
 from pathlib import Path
-from typing import Any, Sequence, TypeVar
+from typing import Any, Sequence
 
 import pikepdf
 
@@ -63,8 +63,13 @@ class NeverRaise(Exception):
 
 
 def safe_symlink(input_file: os.PathLike, soft_link_name: os.PathLike):
-    """
-    Helper function: relinks soft symbolic link if necessary
+    """Create a symbolic link at ``soft_link_name``, which references ``input_file``.
+
+    Think of this as copying ``input_file`` to ``soft_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.
     """
     input_file = os.fspath(input_file)
     soft_link_name = os.fspath(soft_link_name)
@@ -72,8 +77,8 @@ def safe_symlink(input_file: os.PathLike, soft_link_name: os.PathLike):
     # Guard against soft linking to oneself
     if input_file == soft_link_name:
         log.warning(
-            "No symbolic link made. You are using "
-            "the original data directory as the working directory."
+            "No symbolic link created. You are using  the original data directory "
+            "as the working directory."
         )
         return
 
@@ -114,7 +119,7 @@ def is_iterable_notstr(thing: Any) -> bool:
 
 
 def monotonic(L: Sequence) -> bool:
-    """Does list increase monotonically?"""
+    """Does this sequence increase monotonically?"""
     return all(b > a for a, b in zip(L, L[1:]))
 
 
@@ -173,7 +178,8 @@ def is_file_writable(test_file: os.PathLike) -> bool:
 def check_pdf(input_file: Path) -> bool:
     """Check if a PDF complies with the PDF specification.
 
-    Checks for proper formatting and proper linearization.
+    Checks for proper formatting and proper linearization. Uses pikepdf (which in
+    turn, uses QPDF) to perform the checks.
     """
     pdf = None
     try:
@@ -217,7 +223,7 @@ def check_pdf(input_file: Path) -> bool:
 
 
 def clamp(n, smallest, largest):  # mypy doesn't understand types for this
-    """Clamps the value of n to between smallest and largest."""
+    """Clamps the value of ``n`` to between ``smallest`` and ``largest``."""
     return max(smallest, min(n, largest))
 
 
@@ -235,7 +241,7 @@ def pikepdf_enable_mmap():
 
 
 def deprecated(func):
-    """Warn that function is deprecated"""
+    """Warn that function is deprecated."""
 
     @wraps(func)
     def new_func(*args, **kwargs):

src/ocrmypdf/hocrtransform.py

@@ -31,11 +31,10 @@
 import argparse
 import os
 import re
-from collections import namedtuple
 from itertools import chain
 from math import atan, cos, sin
 from pathlib import Path
-from typing import Optional, Tuple, Union
+from typing import Any, NamedTuple, Optional, Tuple, Union
 from xml.etree import ElementTree
 
 from reportlab.lib.colors import black, cyan, magenta, red
@@ -44,7 +43,14 @@ from reportlab.pdfgen.canvas import Canvas
 
 Element = ElementTree.Element
 
-Rect = namedtuple('Rect', ['x1', 'y1', 'x2', 'y2'])
+
+class Rect(NamedTuple):  # pylint: disable=inherit-non-class
+    """A rectangle for managing PDF coordinates."""
+
+    x1: Any
+    y1: Any
+    x2: Any
+    y2: Any
 
 
 class HocrTransformError(Exception):

src/ocrmypdf/leptonica.py

@@ -13,7 +13,6 @@
 import argparse
 import logging
 import os
-import platform
 import sys
 import threading
 import warnings

src/ocrmypdf/optimize.py

@@ -10,11 +10,9 @@ import sys
 import tempfile
 from collections import defaultdict
 from functools import partial
-from io import BytesIO
 from os import fspath
 from pathlib import Path
 from typing import (
-    Any,
     Callable,
     Dict,
     Iterator,
@@ -49,7 +47,7 @@ DEFAULT_PNG_QUALITY = 70
 Xref = NewType('Xref', int)
 
 
-class XrefExt(NamedTuple):
+class XrefExt(NamedTuple):  # pylint: disable=inherit-non-class
     xref: Xref
     ext: str
 
@@ -212,7 +210,10 @@ def extract_image_generic(
 
 
 def extract_images(
-    pike: Pdf, root: Path, options, extract_fn: Callable[..., Optional[XrefExt]],
+    pike: Pdf,
+    root: Path,
+    options,
+    extract_fn: Callable[..., Optional[XrefExt]],
 ) -> Iterator[Tuple[int, XrefExt]]:
     """Extract image using extract_fn
 
@@ -564,10 +565,10 @@ def rewrite_png(pike: Pdf, im_obj: Object, compdata) -> None:  # pragma: no cove
         # ncolors == 0 means we are using a colorspace without a palette
         if compdata.spp == 1:
             cs = Name.DeviceGray
-        elif compdata.spp == 3:
-            cs = Name.DeviceRGB
         elif compdata.spp == 4:
             cs = Name.DeviceCMYK
+        else:  # spp == 3
+            cs = Name.DeviceRGB
     im_obj.ColorSpace = cs
     im_obj.write(compdata.read(), filter=Name.FlateDecode, decode_parms=dparms)
 

src/ocrmypdf/pdfa.py

@@ -112,7 +112,7 @@ def generate_pdfa_ps(target_filename: Path, icc: str = 'sRGB'):
 
 
 def file_claims_pdfa(filename: Path):
-    """Determines if the file claims to be PDF/A compliant
+    """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.

src/ocrmypdf/pdfinfo/info.py

@@ -15,7 +15,7 @@ from functools import partial
 from math import hypot, isclose
 from os import PathLike
 from pathlib import Path
-from typing import Any, Container, Dict, Iterator, List, Optional, Tuple, Union
+from typing import Container, Iterator, Optional, Tuple, Union
 from warnings import warn
 
 import pikepdf

tests/test_optimize.py

@@ -173,3 +173,15 @@ def test_multiple_pngs(resources, outdir):
             inim = next(iter(inpdf.pages[n].images.values()))
             outim = next(iter(outpdf.pages[n].images.values()))
             assert len(outim.read_raw_bytes()) < len(inim.read_raw_bytes()), n
+
+
+def test_optimize_off(resources, outpdf):
+    check_ocrmypdf(
+        resources / 'trivial.pdf',
+        outpdf,
+        '--optimize=0',
+        '--output-type',
+        'pdf',
+        '--plugin',
+        'tests/plugins/tesseract_noop.py',
+    )