Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
206 changes: 169 additions & 37 deletions docs/advanced/deprecated.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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<T>()``
- ``py::class_<T, Base>``
- 2.0
- 2016
- Compiler
* - ``handle::check()``
- ``handle::operator bool()``
- 2.0
- 2016
- Compiler
* - ``Name::check()`` on ``py::object`` subclasses
- ``py::isinstance<Name>(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<T>(handle, bool)``
- ``array_t<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 <pybind11/common.h>``
- ``#include <pybind11/pybind11.h>``
- 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<T>::operator()(message)``
- ``py::set_error(exc, message)``
- 2.12
- 2024
- Compiler
* - ``py::arg_t<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:
Expand Down
3 changes: 1 addition & 2 deletions include/pybind11/cast.h
Original file line number Diff line number Diff line change
Expand Up @@ -2081,9 +2081,8 @@ arg_v arg::operator=(T &&value) const {
return {*this, std::forward<T>(value)};
}

/// Alias for backward compatibility -- to be removed in version 2.0
template <typename /*unused*/>
using arg_t = arg_v;
using arg_t PYBIND11_DEPRECATED("Use py::arg_v instead") = arg_v;

inline namespace literals {
/** \rst
Expand Down
7 changes: 7 additions & 0 deletions include/pybind11/detail/descr.h
Original file line number Diff line number Diff line change
Expand Up @@ -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 <size_t N>
PYBIND11_DEPRECATED("Use py::detail::const_name instead")
constexpr descr<N - 1> _(char const (&text)[N]) {
return const_name<N>(text);
}
template <bool B, size_t N1, size_t N2>
PYBIND11_DEPRECATED("Use py::detail::const_name instead")
constexpr enable_if_t<B, descr<N1 - 1>> _(char const (&text1)[N1], char const (&text2)[N2]) {
return const_name<B, N1, N2>(text1, text2);
}
template <bool B, size_t N1, size_t N2>
PYBIND11_DEPRECATED("Use py::detail::const_name instead")
constexpr enable_if_t<!B, descr<N2 - 1>> _(char const (&text1)[N1], char const (&text2)[N2]) {
return const_name<B, N1, N2>(text1, text2);
}
template <bool B, typename T1, typename T2>
PYBIND11_DEPRECATED("Use py::detail::const_name instead")
constexpr enable_if_t<B, T1> _(const T1 &d1, const T2 &d2) {
return const_name<B, T1, T2>(d1, d2);
}
template <bool B, typename T1, typename T2>
PYBIND11_DEPRECATED("Use py::detail::const_name instead")
constexpr enable_if_t<!B, T2> _(const T1 &d1, const T2 &d2) {
return const_name<B, T1, T2>(d1, d2);
}

template <size_t Size>
PYBIND11_DEPRECATED("Use py::detail::const_name instead")
auto constexpr _() -> remove_cv_t<decltype(int_to_str<Size / 10, Size % 10>::digits)> {
return const_name<Size>();
}
template <typename Type>
PYBIND11_DEPRECATED("Use py::detail::const_name instead")
constexpr descr<1, Type> _() {
return const_name<Type>();
}
Expand Down
40 changes: 31 additions & 9 deletions include/pybind11/pybind11.h
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 <class T>
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)

Expand Down
14 changes: 11 additions & 3 deletions tests/test_const_name.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
2 changes: 1 addition & 1 deletion tests/test_cross_module_rtti/bindings.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -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()) {
Expand Down
5 changes: 0 additions & 5 deletions tests/test_custom_type_casters.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -26,12 +26,7 @@ namespace detail {
template <>
struct type_caster<ArgInspector1> {
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")
Expand Down
Loading