python - 将 pybind11 绑定(bind)标记为已弃用的最佳方法

Question

我有一个使用 pybind11 进行 Python 绑定(bind)的 C++ 类。

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

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被触发。

Answer 1

好的，这是我的工作示例。我实际上想不出用 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")它启用所有类型的警告，但仅在第一次被击中时。还有其他方法可以控制它，包括使用 -W运行 python 或环境变量时的标志。
https://docs.python.org/3/library/warnings.html#describing-warning-filters