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>

5 files changed, 101 insertions, 0 deletions

diff --git a/gdb/NEWS b/gdb/NEWS
index d180c49..6c8a008 100644
--- 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 6139bc3..4ef6406 100644
--- 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 f343d0b..6fa2285 100644
--- 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 7c3d0d1..ff50c42 100644
--- 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
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\\)"]