MAINT: Use placeholder-based approach for logger_warning

[MestreY0d4-Uninter]

Summary

This is the follow-up PR for #3384 that covers logger_warning.

It updates logger_warning to support placeholder-based logging without breaking warning messages that do not interpolate values, and converts logger_warning call sites away from f-strings / preformatted warning messages.

Changes

• update logger_warning to accept message, source, **values
• avoid passing an empty mapping when the warning has no placeholders
• convert logger_warning call sites to %(name)s / %(name)r placeholder style
• update direct mock expectations for the new placeholder-based call shape
• add regression coverage for placeholder and no-placeholder logger_warning usage

Validation

Local validation completed:

• ruff check .
• python3 -m py_compile pypdf/__init__.py tests/test_utils.py tests/test_text_extraction.py
• .venv/bin/python -m pytest tests/test_utils.py tests/test_encryption.py::test_aes_decrypt__wrong_padding tests/test_reader.py::test_read_pdf15_xref_stream__size_limit tests/test_reader.py::test_get_object_from_stream__size_limit tests/test_text_extraction.py::test_layout_mode_warnings tests/generic/test_data_structures.py::test_tree_object__cyclic_reference tests/generic/test_image_xobject.py tests/test_filters.py::test_ascii_hex_decode_missing_eod -q

Note: a broader local run in this checkout hits missing sample/pdf_cache artifacts that are environment-specific here; the focused warning-related coverage above passed, and CI will exercise the full project matrix.

Related issue

Fixes #3384

AI assistance

Created with AI coding assistance via Hermes Agent.

[stefan6419846]

Thanks for the PR. Please have a look at the test failures and the inline comments.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.61%. Comparing base (4f96a2e) to head (2f9197b).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3746      +/-   ##
==========================================
+ Coverage   97.59%   97.61%   +0.02%     
==========================================
  Files          55       55              
  Lines       10225    10231       +6     
  Branches     1877     1879       +2     
==========================================
+ Hits         9979     9987       +8     
+ Misses        141      140       -1     
+ Partials      105      104       -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[MestreY0d4-Uninter]

Thanks for the follow-up review, @stefan6419846.

I addressed the latest comments in the current branch (4a71dd6d):

• changed the reviewed _reader.py / _writer.py placeholders that represent counts/object numbers/offsets to integer placeholders (%d) where appropriate
• applied the suggested Top Level Form Field %(obj_ref)s has a non-expected parent wording
• switched the text-extraction warning assertions to caplog
• removed the extra assertion helper and now use direct assert "..." in caplog.messages / caplog.text checks

Validation:

• GitHub CI is currently green for the PR checks, including pytest on Windows/macOS/Python 3.9-3.14, code style, package build, coverage, Codecov, and ReadTheDocs
• Local focused validation after the review check:
  • git diff --check
  • uv run pytest tests/test_utils.py::test_logger_warning tests/test_text_extraction.py::test_layout_mode_warnings -q → 2 passed

Ready for re-review.

[MestreY0d4-Uninter]

Re-review requested — CI is green. I validated the logger_warning/logger_error alignment, caplog usage, missed call sites, and the coverage patch. Local test run: test_utils, 111 passed.

[MestreY0d4-Uninter]

Addressed the two remaining current review threads in e7f92a1a:

• kept the logger_warning no-values branch, but documented why it is still needed: it matches the logger_error behavior and avoids passing an empty dict to logging.warning, which is not equivalent to calling logging.warning(message) for plain messages.
• moved the decode_as_image # pragma: no cover markers from the message strings to the logger_warning(...) call level.

Validation:

• uv run pytest tests/test_utils.py::test_logger_warning tests/test_utils.py::test_logger_error -q → 2 passed
• uv run pytest tests/test_utils.py tests/test_text_extraction.py::test_layout_mode_warnings -q → 112 passed
• uv run pre-commit run --files pypdf/_utils.py pypdf/generic/_data_structures.py tests/test_utils.py → passed
• git diff --check → passed
• GitHub CI is green again for the updated commit.

Ready for re-review.

[MestreY0d4-Uninter]

@stefan6419846 I replied to the remaining current thread and marked it resolved. The latest head is e7f92a1a; all GitHub checks are green. Ready for re-review when you have time.

[stefan6419846]

While it is valid syntax, please use proper grouping to make such cases more readable, id est something like this:

logger_warning(
    (
        "Length of text %(text)s exceeds maximum length (%(max_length)d) "
        "of field, input truncated."
    ),
    source=__name__,
    text=text,
    max_length=max_length
)

[stefan6419846]

Please adjust the remaining similar sections as well (spotted at least one instance in _reader.py).

[stefan6419846]

This should be updated as well, see #3746 (comment).