diff --git a/docs/advanced/deprecated.rst b/docs/advanced/deprecated.rst index c9f4a2e666..8b4eb8e62a 100644 --- a/docs/advanced/deprecated.rst +++ b/docs/advanced/deprecated.rst @@ -11,58 +11,190 @@ and will be removed in a future version. The default mode is also going to change to ``"new"`` from ``"compat"`` in the future. The following features were deprecated before pybind11 3.0, and may be removed -in minor releases of pybind11 3.x. +in minor releases of pybind11 3.x. "Compiler" means a ``[[deprecated]]`` +warning at compile time. Items that started to warn in 3.x will be kept +until at least pybind11 4.0. -.. list-table:: Deprecated Features +.. list-table:: Deprecated before 3.0 :header-rows: 1 - :widths: 30 15 10 + :widths: 30 30 8 8 14 * - Feature - - Deprecated Version + - Replacement + - Version - Year - * - ``py::metaclass()`` + - Warning + * - ``handle::call(...)`` + - ``operator()(...)`` + - 1.8 + - 2016 + - Compiler + * - ``py::base()`` + - ``py::class_`` + - 2.0 + - 2016 + - Compiler + * - ``handle::check()`` + - ``handle::operator bool()`` + - 2.0 + - 2016 + - Compiler + * - ``Name::check()`` on ``py::object`` subclasses + - ``py::isinstance(obj)`` + - 2.0 + - 2016 + - Compiler + * - ``object(handle, bool)`` and ``Name(handle, bool)`` + - ``py::reinterpret_borrow`` / ``py::reinterpret_steal`` + - 2.0 + - 2016 + - Compiler + * - ``capsule(PyObject *, bool)`` + - ``py::reinterpret_borrow`` / ``py::reinterpret_steal`` + - 2.0 + - 2016 + - Compiler + * - ``array_t(handle, bool)`` + - ``array_t::ensure()`` + - 2.0 + - 2016 + - Compiler + * - ``obj.attr(...)`` as ``bool`` + - ``py::hasattr(obj, ...)`` + - 2.0 + - 2016 + - Compiler + * - ``obj[key]`` as ``bool`` + - ``obj.contains(key)`` + - 2.0 + - 2016 + - Compiler + * - ``obj.str()`` + - ``py::str(obj)`` - 2.1 - 2017 + - Compiler + * - ``py::metaclass()`` without arguments + - Remove it (default since 2.1) + - 2.1 + - 2017 + - Compiler + * - ``handle::operator==`` / ``operator!=`` + - ``obj1.is(obj2)`` + - 2.2 + - 2017 + - Compiler + * - ``error_already_set::clear()`` + - Remove it (does nothing) + - 2.2 + - 2017 + - Compiler * - ``PYBIND11_PLUGIN`` + - ``PYBIND11_MODULE`` - 2.2 - 2017 - * - ``py::set_error()`` replacing ``operator()`` - - 2.12 - - 2024 - * - ``get_type_overload`` + - Compiler + * - ``#include `` + - ``#include `` + - 2.2.1 + - 2017 + - ``#warning`` + * - Old-style placement-new ``__init__`` / ``__setstate__`` + - ``py::init(...)`` / ``py::pickle(...)`` + - 2.2 + - 2017 + - Runtime, debug builds only + * - ``py::module_(name, doc)`` constructor + - ``PYBIND11_MODULE`` or ``module_::create_extension_module`` + - 2.6 + - 2020 + - Compiler + * - ``get_type_overload(const void *, const detail::type_info *, name)`` + - ``get_override(const T *, name)``; needs a typed pointer, the type + info is found from ``T`` + - 2.6 + - 2020 + - Compiler + * - ``obj.get_type()`` + - ``py::type::handle_of(obj)`` + - 2.6 + - 2020 + - Compiler (since 3.0) + * - ``PYBIND11_OVERLOAD*`` macros, ``get_overload`` + - ``PYBIND11_OVERRIDE*``, ``get_override`` + - 2.6 + - 2020 + - Compiler (since 3.2) + * - ``PYBIND11_CPP_STANDARD`` (CMake) + - ``CMAKE_CXX_STANDARD`` + - 2.6 + - 2020 + - CMake + * - ``pybind11_add_module(... SYSTEM)`` (CMake) + - Remove it (does nothing) + - 2.6 + - 2020 + - CMake + * - ``PYTHON_VERSION`` as an input (CMake) + - ``PYBIND11_PYTHON_VERSION`` - 2.6 - 2020 - * - ``call()`` + - CMake + * - ``py::capsule(value, destructor)`` with a ``PyCapsule_Destructor`` + (``void (*)(PyObject *)``); the ``void (*)(void *)`` overload is not + deprecated + - ``py::capsule(value, name, destructor)`` + - 2.10.1 + - 2022 + - Compiler + * - ``py::exception::operator()(message)`` + - ``py::set_error(exc, message)`` + - 2.12 + - 2024 + - Compiler + * - ``py::arg_t`` + - ``py::arg_v`` - 2.0 - 2016 - * - ``.str()`` - - ? - - - * - ``.get_type()`` - - 2.6 - - - * - ``==`` and ``!=`` - - 2.2 - - 2017 - * - ``.check()`` - - ? - - - * - ``object(handle, bool)`` - - ? - - - * - ``error_already_set.clear()`` - - 2.2 - - 2017 - * - ``obj.attr(…)`` as ``bool`` - - ? - - - * - ``.contains`` - - ? (maybe 2.4) - - - * - ``py::capsule`` two-argument with destructor - - ? - - + - Compiler (since 3.2) + * - ``py::detail::_(...)`` + - ``py::detail::const_name(...)`` + - 2.9.1 + - 2022 + - Compiler (since 3.2) + +The following features were deprecated in pybind11 3.0 or later. They will be +kept until at least pybind11 4.0. + +.. list-table:: Deprecated in 3.x + :header-rows: 1 + :widths: 30 30 8 8 14 + * - Feature + - Replacement + - Version + - Year + - Warning + * - FindPythonLibs mode (CMake) + - FindPython mode (``PYBIND11_FINDPYTHON=ON``) + - 3.0 + - 2025 + - None + * - ``py::enum_`` + - ``py::native_enum`` + - 3.0 + - 2025 + - None + * - ``py::module_::module_def`` + - ``PyModuleDef`` + - 3.0 + - 2025 + - Compiler (since 3.2) + * - ``py::mod_gil_not_used(bool)`` + - ``py::mod_gil_not_used()`` / ``py::mod_gil_used()`` + - 3.1 + - 2026 + - Compiler .. _deprecated_enum: diff --git a/include/pybind11/cast.h b/include/pybind11/cast.h index 79e743d9bb..3ef830129a 100644 --- a/include/pybind11/cast.h +++ b/include/pybind11/cast.h @@ -2081,9 +2081,8 @@ arg_v arg::operator=(T &&value) const { return {*this, std::forward(value)}; } -/// Alias for backward compatibility -- to be removed in version 2.0 template -using arg_t = arg_v; +using arg_t PYBIND11_DEPRECATED("Use py::arg_v instead") = arg_v; inline namespace literals { /** \rst diff --git a/include/pybind11/detail/descr.h b/include/pybind11/detail/descr.h index 4f5ae34fc8..9429e5a526 100644 --- a/include/pybind11/detail/descr.h +++ b/include/pybind11/detail/descr.h @@ -126,31 +126,38 @@ io_name(char const (&)[N1], char const (&)[N2], char const (&text3)[N3], char co #ifndef _ # define PYBIND11_DETAIL_UNDERSCORE_BACKWARD_COMPATIBILITY template +PYBIND11_DEPRECATED("Use py::detail::const_name instead") constexpr descr _(char const (&text)[N]) { return const_name(text); } template +PYBIND11_DEPRECATED("Use py::detail::const_name instead") constexpr enable_if_t> _(char const (&text1)[N1], char const (&text2)[N2]) { return const_name(text1, text2); } template +PYBIND11_DEPRECATED("Use py::detail::const_name instead") constexpr enable_if_t> _(char const (&text1)[N1], char const (&text2)[N2]) { return const_name(text1, text2); } template +PYBIND11_DEPRECATED("Use py::detail::const_name instead") constexpr enable_if_t _(const T1 &d1, const T2 &d2) { return const_name(d1, d2); } template +PYBIND11_DEPRECATED("Use py::detail::const_name instead") constexpr enable_if_t _(const T1 &d1, const T2 &d2) { return const_name(d1, d2); } template +PYBIND11_DEPRECATED("Use py::detail::const_name instead") auto constexpr _() -> remove_cv_t::digits)> { return const_name(); } template +PYBIND11_DEPRECATED("Use py::detail::const_name instead") constexpr descr<1, Type> _() { return const_name(); } diff --git a/include/pybind11/pybind11.h b/include/pybind11/pybind11.h index 2459a12f5f..c5253ce461 100644 --- a/include/pybind11/pybind11.h +++ b/include/pybind11/pybind11.h @@ -818,8 +818,7 @@ class module_ : public object { \endrst */ void add_object(const char *name, handle obj, bool overwrite = false); - // DEPRECATED (since PR #5688): Use PyModuleDef directly instead. - using module_def = PyModuleDef; + using module_def PYBIND11_DEPRECATED("Use PyModuleDef instead") = PyModuleDef; #if !defined(PYBIND11_OPAQUE_PYOBJECT) /** \rst @@ -2629,28 +2628,51 @@ function get_override(const T *this_ptr, const char *name) { // Deprecated versions -PYBIND11_DEPRECATED("get_type_overload has been deprecated") +PYBIND11_DEPRECATED("get_type_overload has been deprecated, use get_override instead") inline function get_type_overload(const void *this_ptr, const detail::type_info *this_type, const char *name) { return detail::get_type_override(this_ptr, this_type, name); } template +PYBIND11_DEPRECATED("get_overload has been deprecated, use get_override instead") inline function get_overload(const T *this_ptr, const char *name) { return get_override(this_ptr, name); } +PYBIND11_NAMESPACE_BEGIN(detail) +// Called by the deprecated macros below, so that their use gives a compiler warning. +PYBIND11_DEPRECATED("PYBIND11_OVERLOAD* macros have been deprecated, use PYBIND11_OVERRIDE*") +inline void overload_macro_deprecated() {} +PYBIND11_NAMESPACE_END(detail) + #define PYBIND11_OVERLOAD_INT(ret_type, cname, name, ...) \ - PYBIND11_OVERRIDE_IMPL(PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), name, __VA_ARGS__) + do { \ + ::pybind11::detail::overload_macro_deprecated(); \ + PYBIND11_OVERRIDE_IMPL(PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), name, __VA_ARGS__); \ + } while (false) #define PYBIND11_OVERLOAD_NAME(ret_type, cname, name, fn, ...) \ - PYBIND11_OVERRIDE_NAME(PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), name, fn, __VA_ARGS__) + do { \ + ::pybind11::detail::overload_macro_deprecated(); \ + PYBIND11_OVERRIDE_NAME( \ + PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), name, fn, __VA_ARGS__); \ + } while (false) #define PYBIND11_OVERLOAD_PURE_NAME(ret_type, cname, name, fn, ...) \ - PYBIND11_OVERRIDE_PURE_NAME( \ - PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), name, fn, __VA_ARGS__); + do { \ + ::pybind11::detail::overload_macro_deprecated(); \ + PYBIND11_OVERRIDE_PURE_NAME( \ + PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), name, fn, __VA_ARGS__); \ + } while (false); #define PYBIND11_OVERLOAD(ret_type, cname, fn, ...) \ - PYBIND11_OVERRIDE(PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), fn, __VA_ARGS__) + do { \ + ::pybind11::detail::overload_macro_deprecated(); \ + PYBIND11_OVERRIDE(PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), fn, __VA_ARGS__); \ + } while (false) #define PYBIND11_OVERLOAD_PURE(ret_type, cname, fn, ...) \ - PYBIND11_OVERRIDE_PURE(PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), fn, __VA_ARGS__); + do { \ + ::pybind11::detail::overload_macro_deprecated(); \ + PYBIND11_OVERRIDE_PURE(PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), fn, __VA_ARGS__); \ + } while (false); PYBIND11_NAMESPACE_END(PYBIND11_NAMESPACE) diff --git a/tests/test_const_name.cpp b/tests/test_const_name.cpp index 2ad01e6827..00357c23a0 100644 --- a/tests/test_const_name.cpp +++ b/tests/test_const_name.cpp @@ -40,16 +40,24 @@ CONST_NAME_TESTS(const_name_tests, py::detail::const_name) -#ifdef PYBIND11_DETAIL_UNDERSCORE_BACKWARD_COMPATIBILITY +// Suppressing the deprecation warning is not worth the trouble for these compilers. +#if defined(PYBIND11_DETAIL_UNDERSCORE_BACKWARD_COMPATIBILITY) && !defined(__INTEL_COMPILER) \ + && !defined(__NVCOMPILER) +# define PYBIND11_TEST_UNDERSCORE +PYBIND11_WARNING_PUSH +PYBIND11_WARNING_DISABLE_CLANG("-Wdeprecated-declarations") +PYBIND11_WARNING_DISABLE_GCC("-Wdeprecated-declarations") +PYBIND11_WARNING_DISABLE_MSVC(4996) CONST_NAME_TESTS(underscore_tests, py::detail::_) +PYBIND11_WARNING_POP #endif TEST_SUBMODULE(const_name, m) { m.def("const_name_tests", const_name_tests); -#if defined(PYBIND11_DETAIL_UNDERSCORE_BACKWARD_COMPATIBILITY) +#if defined(PYBIND11_TEST_UNDERSCORE) m.def("underscore_tests", underscore_tests); #else - m.attr("underscore_tests") = "PYBIND11_DETAIL_UNDERSCORE_BACKWARD_COMPATIBILITY not defined."; + m.attr("underscore_tests") = "py::detail::_ not tested."; #endif } diff --git a/tests/test_cross_module_rtti/bindings.cpp b/tests/test_cross_module_rtti/bindings.cpp index 4bd7d37a4f..1c565706b6 100644 --- a/tests/test_cross_module_rtti/bindings.cpp +++ b/tests/test_cross_module_rtti/bindings.cpp @@ -5,7 +5,7 @@ class BaseTrampoline : public lib::Base, public pybind11::trampoline_self_life_support { public: using lib::Base::Base; - int get() const override { PYBIND11_OVERLOAD(int, lib::Base, get, ); } + int get() const override { PYBIND11_OVERRIDE(int, lib::Base, get, ); } }; PYBIND11_MODULE(test_cross_module_rtti_bindings, m, pybind11::mod_gil_used()) { diff --git a/tests/test_custom_type_casters.cpp b/tests/test_custom_type_casters.cpp index 0ca2d25414..c8a71487b9 100644 --- a/tests/test_custom_type_casters.cpp +++ b/tests/test_custom_type_casters.cpp @@ -26,12 +26,7 @@ namespace detail { template <> struct type_caster { public: - // Classic -#ifdef PYBIND11_DETAIL_UNDERSCORE_BACKWARD_COMPATIBILITY - PYBIND11_TYPE_CASTER(ArgInspector1, _("ArgInspector1")); -#else PYBIND11_TYPE_CASTER(ArgInspector1, const_name("ArgInspector1")); -#endif bool load(handle src, bool convert) { value.arg = "loading ArgInspector1 argument " + std::string(convert ? "WITH" : "WITHOUT")