gdb/python: introduce gdb.warning() function

This commit adds a new gdb.warning() function.  This function takes a
string and then calls GDB's internal warning() function.  This will
display the string as a warning.

Using gdb.warning() means that the message will get the new emoji
prefix if the user has that feature turned on.  Also, the message will
be sent to gdb.STDERR without the user having to remember to print to
the correct stream.

Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Tom Tromey <tom@tromey.com>

diff --git a/gdb/NEWS b/gdb/NEWS
index d180c49c834685618cf15f5d9270f99932111dd2..6c8a008d39d31659709f9e259c8f930662514b00 100644 (file)
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -156,6 +156,9 @@ info threads [-gid] [-stopped] [-running] [ID]...
      text for all sub-commands, unless the prefix command is a 'show'
      command, in which case the value of all sub-commands is printed.
 
+  ** New gdb.warning() function that takes a string and prints it as a
+     warning, with GDB's standard 'warning' prefix.
+
 * Guile API
 
   ** New type <gdb:color> for dealing with colors.

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 6139bc33d2e4c2c79d6caa4df38b8f2369306bb2..4ef640698bd814a2b2ed99f44eb2ee35bd80b6b4 100644 (file)
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -28023,6 +28023,7 @@ then it will be used.
 @item show style sources
 Show the current state of source code styling.
 
+@anchor{warning-prefix}
 @item set style warning-prefix
 @itemx show style warning-prefix
 @itemx set style error-prefix

diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index f343d0b44578b8577c6ec7367e116e7bf57266ee..6fa22851f6a7879a7e601c9ef2bd72d3d5006600 100644 (file)
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -509,6 +509,17 @@ Flushing @code{sys.stdout} or @code{sys.stderr} will automatically
 call this function for the relevant stream.
 @end defun
 
+@defun gdb.warning (text)
+Print a warning message to @value{GDBN}'s standard output stream.  The
+warning message is the warning prefix (@pxref{warning-prefix}), the
+string @w{@samp{warning: }}, and then @var{text}, which must be a
+non-empty string.
+
+Due to the warning prefix, @var{text} should not begin with a capital
+letter (except for proper nouns), and @var{text} should end with a
+period.
+@end defun
+
 @defun gdb.target_charset ()
 Return the name of the current target character set (@pxref{Character
 Sets}).  This differs from @code{gdb.parameter('target-charset')} in

diff --git a/gdb/python/python.c b/gdb/python/python.c
index 7c3d0d104b52482ea1ea34b23564c6d1dd7a1c53..ff50c424ad9450bbb7643eea970d82c4778b0c49 100644 (file)
--- a/gdb/python/python.c
+++ b/gdb/python/python.c
@@ -1630,6 +1630,40 @@ gdbpy_flush (PyObject *self, PyObject *args, PyObject *kw)
   Py_RETURN_NONE;
 }
 
+/* Implement gdb.warning().  Takes a single text string argument and emit a
+   warning using GDB's 'warning' function.  The input text string must not
+   be empty.  */
+
+static PyObject *
+gdbpy_warning (PyObject *self, PyObject *args, PyObject *kw)
+{
+  const char *text;
+  static const char *keywords[] = { "text", nullptr };
+
+  if (!gdb_PyArg_ParseTupleAndKeywords (args, kw, "s", keywords, &text))
+    return nullptr;
+
+  if (strlen (text) == 0)
+    {
+      PyErr_SetString (PyExc_ValueError,
+                      _("Empty text string passed to gdb.warning"));
+      return nullptr;
+    }
+
+  try
+    {
+      warning ("%s", text);
+    }
+  catch (const gdb_exception &ex)
+    {
+      /* The warning() call probably cannot throw an exception.  But just
+        in case it ever does.  */
+      return gdbpy_handle_gdb_exception (nullptr, ex);
+    }
+
+  Py_RETURN_NONE;
+}
+
 /* Return non-zero if print-stack is not "none".  */
 
 int
@@ -3124,6 +3158,12 @@ Return the current print options." },
     METH_VARARGS | METH_KEYWORDS,
     "notify_mi (name, data) -> None\n\
 Output async record to MI channels if any." },
+
+  { "warning", (PyCFunction) gdbpy_warning,
+    METH_VARARGS | METH_KEYWORDS,
+    "warning (text) -> None\n\
+Print a warning." },
+
   {NULL, NULL, 0, NULL}
 };
 

diff --git a/gdb/testsuite/gdb.python/py-warning.exp b/gdb/testsuite/gdb.python/py-warning.exp
new file mode 100644 (file)
index 0000000..b0256fa
--- /dev/null
+++ b/gdb/testsuite/gdb.python/py-warning.exp
@@ -0,0 +1,46 @@
+# Copyright (C) 2025 Free Software Foundation, Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+# Test the gdb.warning() function.
+
+load_lib gdb-python.exp
+
+require allow_python_tests
+
+clean_restart
+
+# Basic usage.
+gdb_test "python gdb.warning(\"some text\")" \
+    "warning: some text"
+
+# Basic usage with named argument.
+gdb_test "python gdb.warning(text=\"a warning message\")" \
+    "warning: a warning message"
+
+# Make sure GDB prints format specifiers correctly.
+gdb_test "python gdb.warning(\"%s %d %p\")" \
+    "warning: %s %d %p"
+
+# Empty string gives an error.
+gdb_test "python gdb.warning(\"\")" \
+    [multi_line \
+        "Python Exception <class 'ValueError'>: Empty text string passed to gdb\\.warning" \
+        "Error occurred in Python: Empty text string passed to gdb\\.warning"]
+
+# Missing argument gives an error.
+gdb_test "python gdb.warning()" \
+    [multi_line \
+        "Python Exception <class 'TypeError'>: function missing required argument 'text' \\(pos 1\\)" \
+        "Error occurred in Python: function missing required argument 'text' \\(pos 1\\)"]