BUG: Warn when visitor* arguments are ignored (#2845)

visitor* function arguments are silently ignored when
extraction_mode="layout".  Document this a bit better and add a warning
when these arguments are ignored.

Closes #2840.

pypdf/_page.py

@@ -2172,19 +2172,24 @@ def extract_text(
  default = (0, 90, 180, 270)
  note: currently only 0 (up),90 (turned left), 180 (upside down),
  270 (turned right)
+ Silently ignored in "layout" mode.
  space_width: force default space width
  if not extracted from font (default: 200)
+ Silently ignored in "layout" mode.
  visitor_operand_before: function to be called before processing an operation.
  It has four arguments: operator, operand-arguments,
  current transformation matrix and text matrix.
+ Ignored with a warning in "layout" mode.
  visitor_operand_after: function to be called after processing an operation.
  It has four arguments: operator, operand-arguments,
  current transformation matrix and text matrix.
+ Ignored with a warning in "layout" mode.
  visitor_text: function to be called when extracting some text at some position.
  It has five arguments: text, current transformation matrix,
  text matrix, font-dictionary and font-size.
  The font-dictionary may be None in case of unknown fonts.
  If not None it may e.g. contain key "/BaseFont" with value "/Arial,Bold".
+ Ignored with a warning in "layout" mode.
  extraction_mode (Literal["plain", "layout"]): "plain" for legacy functionality,
  "layout" for experimental layout mode functionality.
  NOTE: orientations, space_width, and visitor_* parameters are NOT respected
@@ -2213,6 +2218,15 @@ def extract_text(
  if extraction_mode not in ["plain", "layout"]:
  raise ValueError(f"Invalid text extraction mode '{extraction_mode}'")
  if extraction_mode == "layout":
+ for visitor in ("visitor_operand_before",
+ "visitor_operand_after",
+ "visitor_text",
+ ):
+ if locals()[visitor]:
+ logger_warning(
+ f"Argument {visitor} is ignored in layout mode",
+ __name__,
+ )
  return self._layout_mode_text(
  space_vertically=kwargs.get("layout_mode_space_vertically", True),
  scale_weight=kwargs.get("layout_mode_scale_weight", 1.25),

tests/test_text_extraction.py

@@ -5,6 +5,7 @@
 """
 from io import BytesIO
 from pathlib import Path
+from unittest.mock import patch
 
 import pytest
 
@@ -173,3 +174,18 @@ def test_layout_mode_indirect_sequence_font_widths():
  with pytest.raises(ParseError) as exc:
  reader.pages[0].extract_text(extraction_mode="layout")
  assert str(exc.value).startswith("Invalid font width definition")
+
+def dummy_visitor_text(text, ctm, tm, fd, fs):
+ pass
+
+@patch("pypdf._page.logger_warning")
+def test_layout_mode_warnings(mock_logger_warning):
+ # Check that a warning is issued when an argument is ignored
+ reader = PdfReader(RESOURCE_ROOT / "hello-world.pdf")
+ page = reader.pages[0]
+ page.extract_text(extraction_mode="plain", visitor_text=dummy_visitor_text)
+ mock_logger_warning.assert_not_called()
+ page.extract_text(extraction_mode="layout", visitor_text=dummy_visitor_text)
+ mock_logger_warning.assert_called_with(
+ "Argument visitor_text is ignored in layout mode", "pypdf._page"
+ )