From 216f0ff2deaf70a18c798761a4102480cf430f17 Mon Sep 17 00:00:00 2001
From: kevin-s-ikegami <108323852+kevin-s-ikegami@users.noreply.github.com>
Date: Mon, 8 Jun 2026 11:33:55 +0900
Subject: [PATCH] DOC: Explain pypdf logging customization

---
 docs/user/suppress-warnings.md | 43 ++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/docs/user/suppress-warnings.md b/docs/user/suppress-warnings.md
index 7384468991..8e45c1bce8 100644
--- a/docs/user/suppress-warnings.md
+++ b/docs/user/suppress-warnings.md
@@ -85,3 +85,46 @@ defines six log levels:
 * INFO
 * DEBUG
 * NOTSET
+
+Because pypdf emits log messages with Python's standard
+[`logging`](https://docs.python.org/3/library/logging.html) module, you can
+attach handlers, filters, or formatters in the same way as for any other Python
+library:
+
+```{testcode}
+import logging
+
+logger = logging.getLogger("pypdf")
+handler = logging.StreamHandler()
+handler.setLevel(logging.WARNING)
+handler.setFormatter(logging.Formatter("%(name)s: %(message)s"))
+logger.addHandler(handler)
+logger.setLevel(logging.WARNING)
+```
+
+If you do not want pypdf log messages to propagate to the root logger, disable
+propagation:
+
+```{testcode}
+import logging
+
+logger = logging.getLogger("pypdf")
+logger.propagate = False
+```
+
+pypdf uses module names as logging sources. For example, messages emitted while
+reading a PDF might come from `pypdf._reader`, and messages emitted while
+decoding streams might come from `pypdf.filters`. Configure the `pypdf` logger
+to affect all pypdf log messages, or configure a more specific logger if you
+only want to handle messages from one module:
+
+```{testcode}
+import logging
+
+logging.getLogger("pypdf.filters").setLevel(logging.ERROR)
+```
+
+Avoid overwriting internal helpers such as `pypdf._utils.logger_warning`.
+Those helpers are imported directly by pypdf modules, so patching one location
+does not reliably affect every existing import. Configuring the `logging`
+module is the supported way to customize pypdf log records.