| /* Wrappers for some Python safety. | |
| Copyright (C) 2026 Free Software Foundation, Inc. | |
| This file is part of GDB. | |
| 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/>. */ | |
| #ifndef GDB_PYTHON_PY_SAFETY_H | |
| #define GDB_PYTHON_PY_SAFETY_H | |
| #include "gdbsupport/traits.h" | |
| #include "py-ref.h" | |
| #include "py-wrappers.h" | |
| #include "charset.h" | |
| /* This file holds wrapper templates for the various ways that gdb | |
| code might be exposed to Python. These wrappers are part of gdb's | |
| "Python safety" approach -- utilities designed to try to prevent | |
| refcount problems, missing error checks, and that also remove the | |
| need to wrap calls into gdb in an explicit try/catch. | |
| See py-wrappers.h for some more discussion of this. | |
| Implementation functions and methods -- the stuff you write to | |
| expose some part of gdb to Python -- are written in a certain | |
| style. | |
| An implementation function is a module-level function. For example | |
| something like 'gdb.register_window_type' is implemented as a | |
| function. An implementation method is a method of the gdb class | |
| implementing a certain Python type; for example | |
| 'gdb.TuiWindow.width' is implemented via a method of | |
| gdbpy_tui_window. | |
| Each of these will accept gdbpy_borrowed_ref arguments (or in some | |
| more limited situations, a gdbpy_opt_borrowed_ref) and return any | |
| relevant type, which will be automatically converted (see the | |
| 'to_python' overloads below) to the correct Python type. Note that | |
| if the 'to_python' functions aren't appropriate in your case, you | |
| can always use the escape hatch of returning a gdbpy_ref<> and | |
| handling type conversion manually. | |
| There are some constexpr functions below that wrap the | |
| implementation methods, and create PyMethodDef objects and the | |
| like. | |
| Implementation methods are expected to use the wrappers in | |
| py-wrappers.h and not generally call into Python directly. | |
| Implementation details of the method-wrapping safety code are put | |
| into this namespace, just to emphasize that these shouldn't be used | |
| elsewhere. Skip past the namespace to find the public APIs. */ | |
| namespace safety_details | |
| { | |
| /* Overloads of "to_python" are used by the safety wrappers to convert | |
| a function's real return value to a Python object. A new reference | |
| will always be returned. These are a detail of the method-wrapping | |
| code. Note that unlike the "safe" wrapper APIs that are commonly | |
| used in gdb, these are all Python-facing and will return NULL on | |
| error. */ | |
| template<typename T, typename = gdb::Requires<std::is_integral<T>>> | |
| static inline PyObject * | |
| to_python (T value) | |
| { | |
| if constexpr (std::is_same<T, bool>::value) | |
| return PyBool_FromLong (value); | |
| else if constexpr (std::is_signed<T>::value) | |
| return gdb_py_object_from_longest (value).release (); | |
| else | |
| return gdb_py_object_from_ulongest (value).release (); | |
| } | |
| static inline PyObject * | |
| to_python (const char *value) | |
| { | |
| if (value == nullptr) | |
| return py_none ().release (); | |
| return PyUnicode_Decode (value, strlen (value), host_charset (), nullptr); | |
| } | |
| static inline PyObject * | |
| to_python (std::string &&value) | |
| { | |
| return PyUnicode_Decode (value.c_str (), value.size (), | |
| host_charset (), nullptr); | |
| } | |
| static inline PyObject * | |
| to_python (const std::string &value) | |
| { | |
| return PyUnicode_Decode (value.c_str (), value.size (), | |
| host_charset (), nullptr); | |
| } | |
| static inline PyObject * | |
| to_python (gdb::unique_xmalloc_ptr<char> &&value) | |
| { | |
| if (value == nullptr) | |
| return py_none ().release (); | |
| return PyUnicode_Decode (value.get (), strlen (value.get ()), | |
| host_charset (), nullptr); | |
| } | |
| static inline PyObject * | |
| to_python (gdbpy_ref<> &&value) | |
| { | |
| return value.release (); | |
| } | |
| static inline PyObject * | |
| to_python (const frame_info_ptr &frame) | |
| { | |
| if (frame.is_null ()) | |
| return py_none ().release (); | |
| /* Note that currently this might return NULL on error; but that is | |
| fine in this context. */ | |
| return frame_info_to_frame_object (frame).release (); | |
| } | |
| static inline PyObject * | |
| to_python (symbol *sym) | |
| { | |
| if (sym == nullptr) | |
| return py_none ().release (); | |
| /* Note that currently this might return NULL on error; but that is | |
| fine in this context. */ | |
| return symbol_to_symbol_object (sym).release (); | |
| } | |
| /* An instantiation of this function is used when calling a gdb method | |
| from Python. It accepts some number of arguments (normally | |
| gdbpy_borrowed_ref or gdbpy_opt_borrowed_ref), and then calls the | |
| underlying function F. Any exceptions are caught and converted, | |
| and the return value of F is converted to a Python object as | |
| appropriate. */ | |
| template<auto F, typename... Args> | |
| PyObject * | |
| wrapped_function (Args... args) | |
| { | |
| try | |
| { | |
| using result_type = typename std::invoke_result_t<decltype (F), Args...>; | |
| if constexpr (std::is_void_v<result_type>) | |
| { | |
| F (args...); | |
| return py_none ().release (); | |
| } | |
| else | |
| return to_python (F (args...)); | |
| } | |
| catch (const gdb_python_exception &pye) | |
| { | |
| gdb_assert (PyErr_Occurred () != nullptr); | |
| return nullptr; | |
| } | |
| catch (const gdb_exception &exc) | |
| { | |
| return gdbpy_handle_gdb_exception (nullptr, exc); | |
| } | |
| } | |
| /* An instantiation of this function is used when calling a gdb method | |
| from Python. It accepts some number of arguments (normally | |
| gdbpy_borrowed_ref or gdbpy_opt_borrowed_ref), and then calls the | |
| method METH. Any exceptions are caught and converted, and the | |
| return value of METH is converted to a Python object as | |
| appropriate. */ | |
| template<typename Class, typename Ret, typename... Args> | |
| PyObject * | |
| wrapped_method (Ret (Class::*meth) (Args...), Class *self, Args... args) | |
| { | |
| try | |
| { | |
| if constexpr (std::is_void_v<Ret>) | |
| { | |
| (self->*meth) (args...); | |
| return py_none ().release (); | |
| } | |
| else | |
| return to_python ((self->*meth) (args...)); | |
| } | |
| catch (const gdb_python_exception &pye) | |
| { | |
| gdb_assert (PyErr_Occurred () != nullptr); | |
| return nullptr; | |
| } | |
| catch (const gdb_exception &exc) | |
| { | |
| return gdbpy_handle_gdb_exception (nullptr, exc); | |
| } | |
| } | |
| /* A variant of wrapped_method that accepts a const method. */ | |
| template<typename Class, typename Ret, typename... Args> | |
| PyObject * | |
| wrapped_method (Ret (Class::*meth) (Args...) const, Class *self, Args... args) | |
| { | |
| try | |
| { | |
| if constexpr (std::is_void_v<Ret>) | |
| { | |
| (self->*meth) (args...); | |
| return py_none ().release (); | |
| } | |
| else | |
| return to_python ((self->*meth) (args...)); | |
| } | |
| catch (const gdb_python_exception &pye) | |
| { | |
| gdb_assert (PyErr_Occurred () != nullptr); | |
| return nullptr; | |
| } | |
| catch (const gdb_exception &exc) | |
| { | |
| return gdbpy_handle_gdb_exception (nullptr, exc); | |
| } | |
| } | |
| template<auto F> | |
| PyObject * | |
| fn_wrapper (PyObject *self, PyObject *args, PyObject *kw) | |
| { | |
| return wrapped_function<F> (gdbpy_borrowed_ref<> (args), | |
| gdbpy_opt_borrowed_ref<> (kw)); | |
| } | |
| template<typename C, auto M> | |
| PyObject * | |
| varargs_wrapper (PyObject *self, PyObject *args, PyObject *kw) | |
| { | |
| return wrapped_method (M, static_cast<C *> (self), | |
| gdbpy_borrowed_ref<> (args), | |
| gdbpy_opt_borrowed_ref<> (kw)); | |
| } | |
| } /* namespace safety_details */ | |
| /* Create a PyMethodDef for a no-argument function. It takes the | |
| underlying function F as template parameters, and the name and | |
| documentation as arguments. The function F is wrapped to call | |
| to_python and to catch exceptions per the safety protocol. F | |
| should not accept any arguments. */ | |
| template<auto F> | |
| constexpr PyMethodDef | |
| noargs_function (const char *name, const char *doc) | |
| { | |
| using namespace safety_details; | |
| return { | |
| name, | |
| [] (PyObject *self, PyObject *args) -> PyObject * | |
| { | |
| return wrapped_function<F> (); | |
| }, | |
| METH_NOARGS, | |
| doc, | |
| }; | |
| } | |
| /* Create a PyMethodDef for a no-argument method. It takes the | |
| underlying class C and a pointer-to-method M as template | |
| parameters, and the name and documentation as arguments. The | |
| method M is wrapped to call to_python and to catch exceptions per | |
| the safety protocol. */ | |
| template<typename C, auto M> | |
| constexpr PyMethodDef | |
| noargs_method (const char *name, const char *doc) | |
| { | |
| using namespace safety_details; | |
| return { | |
| name, | |
| [] (PyObject *self, PyObject *args) -> PyObject * | |
| { | |
| return wrapped_method (M, static_cast<C *> (self)); | |
| }, | |
| METH_NOARGS, | |
| doc, | |
| }; | |
| } | |
| /* This is used to create the PyMethodDef for a varargs function. It | |
| takes the underlying implementation function as a template | |
| argument, and also arguments for the method name and documentation | |
| string. | |
| The underlying function should accept a gdbpy_borrowed_ref argument | |
| (the arguments to the Python function), and then a | |
| gdbpy_opt_borrowed_ref for the keywords. The function can return | |
| any type (see the to_python overloads); and should throw an | |
| exception on error. If gdb_python_exception is thrown, the Python | |
| exception must already have been set. | |
| The gdb policy is that varargs methods must also accept keywords, | |
| and this is enforced here. */ | |
| template<auto F> | |
| constexpr PyMethodDef | |
| varargs_function (const char *name, const char *doc) | |
| { | |
| using namespace safety_details; | |
| return { | |
| name, | |
| (PyCFunction) fn_wrapper<F>, | |
| /* gdb's rule is that varargs should also use keywords. */ | |
| METH_VARARGS | METH_KEYWORDS, | |
| doc, | |
| }; | |
| } | |
| /* Like a varargs function, but this implements a method on some | |
| Python type that gdb provides. The implementation class and a | |
| pointer-to-method must be specified. */ | |
| template<typename C, auto M> | |
| constexpr PyMethodDef | |
| varargs_method (const char *name, const char *doc) | |
| { | |
| using namespace safety_details; | |
| return { | |
| name, | |
| (PyCFunction) varargs_wrapper<C, M>, | |
| /* gdb's rule is that varargs should also use keywords. */ | |
| METH_VARARGS | METH_KEYWORDS, | |
| doc, | |
| }; | |
| } | |
| /* A function that wraps a "repr" or "str" method. */ | |
| template<typename C, auto M> | |
| PyObject * | |
| wrap_tp_callback (PyObject *arg) | |
| { | |
| using namespace safety_details; | |
| return wrapped_method (M, static_cast<C *> (arg)); | |
| } | |
| /* A function that wraps a "get" method. */ | |
| template<typename C, auto M> | |
| PyObject * | |
| wrap_getter (PyObject *arg, void *closure) | |
| { | |
| using namespace safety_details; | |
| /* In gdb the closure argument is never used. */ | |
| return wrapped_method (M, static_cast<C *> (arg)); | |
| } | |
| /* A function that wraps a "set" method. */ | |
| template<typename C, void (C::*M) (gdbpy_opt_borrowed_ref<>)> | |
| int | |
| wrap_setter (PyObject *arg, PyObject *value, void *closure) | |
| { | |
| using namespace safety_details; | |
| try | |
| { | |
| C *self = static_cast<C *> (arg); | |
| /* In gdb the closure argument is never used. */ | |
| (self->*M) (gdbpy_opt_borrowed_ref<> (value)); | |
| } | |
| catch (const gdb_python_exception &pye) | |
| { | |
| gdb_assert (PyErr_Occurred () != nullptr); | |
| return -1; | |
| } | |
| catch (const gdb_exception &exc) | |
| { | |
| return gdbpy_handle_gdb_exception (-1, exc); | |
| } | |
| return 0; | |
| } | |
| /* A function that wraps a richcompare method. | |
| A Python tp_richcompare function can either raise an exception, | |
| return True or False, or return "not implemented". The wrapped | |
| method must return a std::optional<bool>, which allows all these | |
| results: exceptions are simply thrown, true and false are ordinary | |
| returns, and the return of an empty optional means "not | |
| implemented". */ | |
| template<typename C, std::optional<bool> (C::*M) (gdbpy_borrowed_ref<>, int)> | |
| PyObject * | |
| wrap_richcompare (PyObject *arg, PyObject *value, int op) | |
| { | |
| using namespace safety_details; | |
| try | |
| { | |
| C *self = static_cast<C *> (arg); | |
| std::optional<bool> result = (self->*M) (value, op); | |
| if (result.has_value ()) | |
| return to_python (*result); | |
| return py_notimplemented ().release (); | |
| } | |
| catch (const gdb_python_exception &pye) | |
| { | |
| gdb_assert (PyErr_Occurred () != nullptr); | |
| return nullptr; | |
| } | |
| catch (const gdb_exception &exc) | |
| { | |
| return gdbpy_handle_gdb_exception (nullptr, exc); | |
| } | |
| } | |
| #endif /* GDB_PYTHON_PY_SAFETY_H */ |