Add :hide_err: option to suppress [runpythonerror] in runpython output

Copilot · xadupre · web-flow · commit fda0362cec2f · 2026-04-29T16:43:20.000Z
Agent-Logs-Url: https://github.com/sdpython/sphinx-runpython/sessions/398ae408-14c9-4d08-b0cf-259ba560c7bb Co-authored-by: xadupre <22452781+xadupre@users.noreply.github.com>
diff --git a/_unittests/ut_runpython/test_runpython_extension.py b/_unittests/ut_runpython/test_runpython_extension.py
@@ -218,6 +218,35 @@ def depart_rp_node(self, node):
         if t1 not in html:
             raise AssertionError(html)
 
+    def test_runpython_hide_err(self):
+        """
+        Test that :hide_err: suppresses [runpythonerror] from the output.
+        """
+        if "enable_disabled_documented_pieces_of_code" in sys.__dict__:
+            raise AssertionError("this case should not be")
+
+        content = """
+                    test a directive
+                    ================
+
+                    .. runpython::
+                        :rst:
+                        :hide_err:
+
+                        import warnings
+                        warnings.warn("deprecated", DeprecationWarning)
+                        print("output line")
+                    """.replace("                    ", "")
+
+        html = rst2html(content, writer_name="rst")
+
+        if "runpythonerror" in html:
+            raise AssertionError(f"[runpythonerror] should not appear in output:\n{html}")
+        if "DeprecationWarning" in html:
+            raise AssertionError(f"DeprecationWarning should not appear in output:\n{html}")
+        if "output line" not in html:
+            raise AssertionError(f"stdout should still appear in output:\n{html}")
+
     def test_runpython_raw(self):
         """
         this test also test the extension runpython
diff --git a/sphinx_runpython/runpython/sphinx_runpython_extension.py b/sphinx_runpython/runpython/sphinx_runpython_extension.py
@@ -559,6 +559,10 @@ class RunPythonDirective(Directive):
         the script to be stored somewhere in order to retrieve it.
     * ``:debug:`` if ``:rst:`` is used, it shows some information to help
       debugging.
+    * ``:hide_err:`` if present, hides any error or warning output that would
+      otherwise be appended as ``[runpythonerror]`` in the content. This is
+      useful when the code produces stderr output (such as deprecation warnings)
+      that should not appear in the rendered documentation.
 
     Option *rst* can be used the following way::
 
@@ -630,6 +634,7 @@ class RunPythonDirective(Directive):
         "store_in_file": directives.unchanged,
         "linenos": directives.unchanged,
         "debug": directives.unchanged,
+        "hide_err": directives.unchanged,
     }
     has_content = True
     runpython_class = runpython_node
@@ -693,6 +698,7 @@ def run(self):
             "store": "store" in self.options and self.options["store"] in bool_set_,
             "restore": "restore" in self.options
             and self.options["restore"] in bool_set_,
+            "hide_err": "hide_err" in self.options,
         }
 
         if p["setsysvar"] is not None and len(p["setsysvar"]) == 0:
@@ -821,7 +827,7 @@ def run(self):
         if err is not None:
             err = err.rstrip(" \n\r\t")
         content = out
-        if len(err) > 0:
+        if len(err) > 0 and not p["hide_err"]:
             content += "\n[runpythonerror]\n" + err
 
         # add member
