Add deprecated tag, e.g. py::deprecated to mark API exported via pybind11 as deprecated

[dyollb]

Maintaining APIs means sometimes you have to retire old functions or parameters.

I find myself using something like this to mark functions/methods as deprecated in our pybind11-exported APIs:

PYBIND11_MODULE(example, m) {
    py::class_<MyClass>(m, "MyClass")
        .def(py::init<>())

        // Deprecated wrapper
        .def("old_method", [](const MyClass &self) {
            PyErr_WarnEx(PyExc_DeprecationWarning,
                         "MyClass.old_method() is deprecated and will be removed in a future release.",
                         1);
            self.old_method();
        }, "Deprecated method. Use new_method instead.");
}

I would be nice if this could be standardized using a py::deprecated tag, that could contain fields like

• deprecated since [version]
• removed in [some future version]
• message explaining how to replace api

Maybe something like this decorator but for pybind11...?