Merge pull request #466 from ManifoldFR/topic/add-deprecation-call-policy

Add deprecation call policy. Backport from pinocchio bindings.

.github/workflows/linux.yml

@@ -42,7 +42,7 @@ jobs:
           echo $(g++ --version)
       - run: cmake . -DPYTHON_EXECUTABLE=$(which python${{ matrix.python }}) -DBUILD_TESTING_SCIPY=ON
       - run: make -j2
-      - run: make test
+      - run: ctest --output-on-failure
 
   check:
     if: always()

CHANGELOG.md

@@ -6,6 +6,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
 
+### Added
+- Added a deprecation call policy shortcut ([#466](https://github.com/stack-of-tasks/eigenpy/pull/466))
+
 ## [3.5.1] - 2024-04-25
 
 ### Fixed

CMakeLists.txt

@@ -220,6 +220,7 @@ set(${PROJECT_NAME}_HEADERS
     ${${PROJECT_NAME}_DECOMPOSITIONS_HEADERS}
     include/eigenpy/alignment.hpp
     include/eigenpy/computation-info.hpp
+    include/eigenpy/deprecation-policy.hpp
     include/eigenpy/eigenpy.hpp
     include/eigenpy/exception.hpp
     include/eigenpy/scalar-conversion.hpp

include/eigenpy/deprecation-policy.hpp

+//
+// Copyright (C) 2020 INRIA
+// Copyright (C) 2024 LAAS-CNRS, INRIA
+//
+#ifndef __eigenpy_deprecation_hpp__
+#define __eigenpy_deprecation_hpp__
+
+#include "eigenpy/fwd.hpp"
+
+namespace eigenpy {
+
+enum class DeprecationType { DEPRECATION, FUTURE };
+
+namespace detail {
+
+constexpr PyObject *deprecationTypeToPyObj(DeprecationType dep) {
+  switch (dep) {
+    case DeprecationType::DEPRECATION:
+      return PyExc_DeprecationWarning;
+    case DeprecationType::FUTURE:
+      return PyExc_FutureWarning;
+  }
+}
+
+}  // namespace detail
+
+/// @brief A Boost.Python call policy which triggers a Python warning on
+/// precall.
+template <DeprecationType deprecation_type = DeprecationType::DEPRECATION,
+          class BasePolicy = bp::default_call_policies>
+struct deprecation_warning_policy : BasePolicy {
+  using result_converter = typename BasePolicy::result_converter;
+  using argument_package = typename BasePolicy::argument_package;
+
+  deprecation_warning_policy(const std::string &warning_msg)
+      : BasePolicy(), m_what(warning_msg) {}
+
+  std::string what() const { return m_what; }
+
+  const BasePolicy *derived() const {
+    return static_cast<const BasePolicy *>(this);
+  }
+
+  template <class ArgPackage>
+  bool precall(const ArgPackage &args) const {
+    PyErr_WarnEx(detail::deprecationTypeToPyObj(deprecation_type),
+                 m_what.c_str(), 1);
+    return derived()->precall(args);
+  }
+
+ protected:
+  const std::string m_what;
+};
+
+template <DeprecationType deprecation_type = DeprecationType::DEPRECATION,
+          class BasePolicy = bp::default_call_policies>
+struct deprecated_function
+    : deprecation_warning_policy<deprecation_type, BasePolicy> {
+  deprecated_function(const std::string &msg =
+                          "This function has been marked as deprecated, and "
+                          "will be removed in the future.")
+      : deprecation_warning_policy<deprecation_type, BasePolicy>(msg) {}
+};
+
+template <DeprecationType deprecation_type = DeprecationType::DEPRECATION,
+          class BasePolicy = bp::default_call_policies>
+struct deprecated_member
+    : deprecation_warning_policy<deprecation_type, BasePolicy> {
+  deprecated_member(const std::string &msg =
+                        "This attribute or method has been marked as "
+                        "deprecated, and will be removed in the future.")
+      : deprecation_warning_policy<deprecation_type, BasePolicy>(msg) {}
+};
+
+}  // namespace eigenpy
+
+#endif  // ifndef __eigenpy_deprecation_hpp__

unittest/CMakeLists.txt

@@ -37,6 +37,7 @@ endif()
 add_lib_unit_test(tensor)
 add_lib_unit_test(geometry)
 add_lib_unit_test(complex)
+add_lib_unit_test(deprecation_policy)
 add_lib_unit_test(return_by_ref)
 add_lib_unit_test(include)
 if(NOT ${EIGEN3_VERSION} VERSION_LESS "3.2.0")
@@ -104,6 +105,8 @@ add_python_lib_unit_test("py-matrix" "unittest/python/test_matrix.py")
 add_python_lib_unit_test("py-tensor" "unittest/python/test_tensor.py")
 add_python_lib_unit_test("py-geometry" "unittest/python/test_geometry.py")
 add_python_lib_unit_test("py-complex" "unittest/python/test_complex.py")
+add_python_lib_unit_test("py-deprecation-policy"
+                         "unittest/python/test_deprecation_policy.py")
 add_python_lib_unit_test("py-return-by-ref"
                          "unittest/python/test_return_by_ref.py")
 add_python_lib_unit_test("py-eigen-ref" "unittest/python/test_eigen_ref.py")

unittest/deprecation_policy.cpp

+#include "eigenpy/eigenpy.hpp"
+#include "eigenpy/deprecation-policy.hpp"
+
+#include <iostream>
+
+namespace bp = boost::python;
+using eigenpy::DeprecationType;
+
+void some_deprecated_function() {
+  std::cout << "Calling this should produce a warning" << std::endl;
+}
+
+void some_future_deprecated_function() {
+  std::cout
+      << "Calling this should produce a warning about a future deprecation"
+      << std::endl;
+}
+
+class X {
+ public:
+  void deprecated_member_function() {}
+};
+
+BOOST_PYTHON_MODULE(deprecation_policy) {
+  bp::def("some_deprecated_function", some_deprecated_function,
+          eigenpy::deprecated_function<DeprecationType::DEPRECATION>());
+  bp::def("some_future_deprecated_function", some_future_deprecated_function,
+          eigenpy::deprecated_function<DeprecationType::FUTURE>());
+
+  bp::class_<X>("X", bp::init<>(bp::args("self")))
+      .def("deprecated_member_function", &X::deprecated_member_function,
+           eigenpy::deprecated_member<>());
+}

unittest/python/test_deprecation_policy.py

+from deprecation_policy import (
+    X,
+    some_deprecated_function,
+    some_future_deprecated_function,
+)
+
+some_deprecated_function()
+some_future_deprecated_function()
+X().deprecated_member_function()