将 pybind11 绑定标记为已弃用的最佳方法

Best way to mark a pybind11-binding as deprecated

本文关键字：最佳 方法 pybind11 绑定 记为      更新时间：2023-10-16

我有一个使用 pybind11 的 Python 绑定的C++类。

现在我想将一个方法的绑定标记为已弃用。 让我们假设它看起来像这样：

PYBIND11_MODULE(my_module, m)
{
pybind11::class_<Foobar>(m, "PyFoobar")
.def("old_foo", &Foobar::foo)  // <-- this is deprecated in favour of "new_foo"
.def("new_foo", &Foobar::foo);
}

将PyFoobar.old_foo()标记为已弃用以便用户在调用该方法时注意到它的最佳方法是什么？ 理想情况下，我希望触发DeprecationWarning。

好的，这是我的工作示例。我实际上无法弄清楚使用 Python C 类型调用导入的 python 函数，所以我直接转到 C API，无论如何它应该表现得更好

struct Foobar {
Foobar() {}
void foo(int32_t art) {}
};
PYBIND11_MODULE(example, m) {
pybind11::class_<Foobar>(m, "PyFoobar")
.def(py::init<>())
.def("old_foo",
[](pybind11::object &self, int arg_to_foo)
{
PyErr_WarnEx(PyExc_DeprecationWarning, 
"old_foo() is deprecated, use new_foo() instead.", 
1);
return self.attr("new_foo")(arg_to_foo);
})
.def("new_foo", &Foobar::foo);
}

您可以将此处的任何警告类型作为第一个参数传递： https://docs.python.org/3/c-api/exceptions.html#standard-warning-categories

最后一个 int 是要标记为已弃用的堆栈级别。

所以看看这个python代码

import example
import warnings
warnings.simplefilter("default")
def mary():
f = example.PyFoobar()
f.old_foo(1)
mary()

如果将堆栈级别设置为1则得到

test.py:9: DeprecationWarning: old_foo() is deprecated, use new_foo() instead.
f.old_foo(1)

您可能需要2它将为您提供实际的调用上下文，但取决于您的用例是什么

test.py:11: DeprecationWarning: old_foo() is deprecated, use new_foo() instead.
mary()

同样重要的是要注意，默认情况下，许多版本的 python 都关闭了弃用警告。您可以通过检查以下值来检查这一点warnings.filters.这就是为什么在我的示例中，我调用了warnings.simplefilter("default")，它启用了所有类型的警告，但仅在第一次命中时。还有其他方法可以控制这一点，包括在运行 python 或环境变量时使用-W标志。 https://docs.python.org/3/library/warnings.html#describing-warning-filters

我找到了某种方法来获得我想要的大部分内容：对已弃用的绑定使用 lambda。 在此 lambda 中，发出警告，然后调用实际函数。 就像我的例子一样，唯一的变化是名称，我只是在old_foo里面调用new_foo。 如果绑定的实际函数不同，这将变得更加复杂。

PYBIND11_MODULE(my_module, m)
{
pybind11::class_<Foobar>(m, "PyFoobar")
.def("old_foo",
[](pybind11::object &self, int arg_to_foo)
{
auto warnings = pybind11::module::import("warnings");
warnings.attr("warn")(
"old_foo() is deprecated, use new_foo() instead.");
return self.attr("new_foo")(arg_to_foo);
})
.def("new_foo", &Foobar::foo);
}

这导致

用户警告：old_foo(( 已弃用，请改用 new_foo((。

第一次调用old_foo()时。

不幸的是，我还没有弄清楚如何使其成为DeprecationWarning而不是UserWarning.

相关文章：