112391Sjason@lowepower.comUpgrade guide 212391Sjason@lowepower.com############# 312391Sjason@lowepower.com 412391Sjason@lowepower.comThis is a companion guide to the :doc:`changelog`. While the changelog briefly 512391Sjason@lowepower.comlists all of the new features, improvements and bug fixes, this upgrade guide 612391Sjason@lowepower.comfocuses only the subset which directly impacts your experience when upgrading 712391Sjason@lowepower.comto a new version. But it goes into more detail. This includes things like 812391Sjason@lowepower.comdeprecated APIs and their replacements, build system changes, general code 912391Sjason@lowepower.commodernization and other useful information. 1012391Sjason@lowepower.com 1112391Sjason@lowepower.com 1212391Sjason@lowepower.comv2.2 1312391Sjason@lowepower.com==== 1412391Sjason@lowepower.com 1512391Sjason@lowepower.comDeprecation of the ``PYBIND11_PLUGIN`` macro 1612391Sjason@lowepower.com-------------------------------------------- 1712391Sjason@lowepower.com 1812391Sjason@lowepower.com``PYBIND11_MODULE`` is now the preferred way to create module entry points. 1912391Sjason@lowepower.comThe old macro emits a compile-time deprecation warning. 2012391Sjason@lowepower.com 2112391Sjason@lowepower.com.. code-block:: cpp 2212391Sjason@lowepower.com 2312391Sjason@lowepower.com // old 2412391Sjason@lowepower.com PYBIND11_PLUGIN(example) { 2512391Sjason@lowepower.com py::module m("example", "documentation string"); 2612391Sjason@lowepower.com 2712391Sjason@lowepower.com m.def("add", [](int a, int b) { return a + b; }); 2812391Sjason@lowepower.com 2912391Sjason@lowepower.com return m.ptr(); 3012391Sjason@lowepower.com } 3112391Sjason@lowepower.com 3212391Sjason@lowepower.com // new 3312391Sjason@lowepower.com PYBIND11_MODULE(example, m) { 3412391Sjason@lowepower.com m.doc() = "documentation string"; // optional 3512391Sjason@lowepower.com 3612391Sjason@lowepower.com m.def("add", [](int a, int b) { return a + b; }); 3712391Sjason@lowepower.com } 3812391Sjason@lowepower.com 3912391Sjason@lowepower.com 4012391Sjason@lowepower.comNew API for defining custom constructors and pickling functions 4112391Sjason@lowepower.com--------------------------------------------------------------- 4212391Sjason@lowepower.com 4312391Sjason@lowepower.comThe old placement-new custom constructors have been deprecated. The new approach 4412391Sjason@lowepower.comuses ``py::init()`` and factory functions to greatly improve type safety. 4512391Sjason@lowepower.com 4612391Sjason@lowepower.comPlacement-new can be called accidentally with an incompatible type (without any 4712391Sjason@lowepower.comcompiler errors or warnings), or it can initialize the same object multiple times 4812391Sjason@lowepower.comif not careful with the Python-side ``__init__`` calls. The new-style custom 4912391Sjason@lowepower.comconstructors prevent such mistakes. See :ref:`custom_constructors` for details. 5012391Sjason@lowepower.com 5112391Sjason@lowepower.com.. code-block:: cpp 5212391Sjason@lowepower.com 5312391Sjason@lowepower.com // old -- deprecated (runtime warning shown only in debug mode) 5412391Sjason@lowepower.com py::class<Foo>(m, "Foo") 5512391Sjason@lowepower.com .def("__init__", [](Foo &self, ...) { 5612391Sjason@lowepower.com new (&self) Foo(...); // uses placement-new 5712391Sjason@lowepower.com }); 5812391Sjason@lowepower.com 5912391Sjason@lowepower.com // new 6012391Sjason@lowepower.com py::class<Foo>(m, "Foo") 6112391Sjason@lowepower.com .def(py::init([](...) { // Note: no `self` argument 6212391Sjason@lowepower.com return new Foo(...); // return by raw pointer 6312391Sjason@lowepower.com // or: return std::make_unique<Foo>(...); // return by holder 6412391Sjason@lowepower.com // or: return Foo(...); // return by value (move constructor) 6512391Sjason@lowepower.com })); 6612391Sjason@lowepower.com 6712391Sjason@lowepower.comMirroring the custom constructor changes, ``py::pickle()`` is now the preferred 6812391Sjason@lowepower.comway to get and set object state. See :ref:`pickling` for details. 6912391Sjason@lowepower.com 7012391Sjason@lowepower.com.. code-block:: cpp 7112391Sjason@lowepower.com 7212391Sjason@lowepower.com // old -- deprecated (runtime warning shown only in debug mode) 7312391Sjason@lowepower.com py::class<Foo>(m, "Foo") 7412391Sjason@lowepower.com ... 7512391Sjason@lowepower.com .def("__getstate__", [](const Foo &self) { 7612391Sjason@lowepower.com return py::make_tuple(self.value1(), self.value2(), ...); 7712391Sjason@lowepower.com }) 7812391Sjason@lowepower.com .def("__setstate__", [](Foo &self, py::tuple t) { 7912391Sjason@lowepower.com new (&self) Foo(t[0].cast<std::string>(), ...); 8012391Sjason@lowepower.com }); 8112391Sjason@lowepower.com 8212391Sjason@lowepower.com // new 8312391Sjason@lowepower.com py::class<Foo>(m, "Foo") 8412391Sjason@lowepower.com ... 8512391Sjason@lowepower.com .def(py::pickle( 8612391Sjason@lowepower.com [](const Foo &self) { // __getstate__ 8712391Sjason@lowepower.com return py::make_tuple(f.value1(), f.value2(), ...); // unchanged 8812391Sjason@lowepower.com }, 8912391Sjason@lowepower.com [](py::tuple t) { // __setstate__, note: no `self` argument 9012391Sjason@lowepower.com return new Foo(t[0].cast<std::string>(), ...); 9112391Sjason@lowepower.com // or: return std::make_unique<Foo>(...); // return by holder 9212391Sjason@lowepower.com // or: return Foo(...); // return by value (move constructor) 9312391Sjason@lowepower.com } 9412391Sjason@lowepower.com )); 9512391Sjason@lowepower.com 9612391Sjason@lowepower.comFor both the constructors and pickling, warnings are shown at module 9712391Sjason@lowepower.cominitialization time (on import, not when the functions are called). 9812391Sjason@lowepower.comThey're only visible when compiled in debug mode. Sample warning: 9912391Sjason@lowepower.com 10012391Sjason@lowepower.com.. code-block:: none 10112391Sjason@lowepower.com 10212391Sjason@lowepower.com pybind11-bound class 'mymodule.Foo' is using an old-style placement-new '__init__' 10312391Sjason@lowepower.com which has been deprecated. See the upgrade guide in pybind11's docs. 10412391Sjason@lowepower.com 10512391Sjason@lowepower.com 10612391Sjason@lowepower.comStricter enforcement of hidden symbol visibility for pybind11 modules 10712391Sjason@lowepower.com--------------------------------------------------------------------- 10812391Sjason@lowepower.com 10912391Sjason@lowepower.compybind11 now tries to actively enforce hidden symbol visibility for modules. 11012391Sjason@lowepower.comIf you're using either one of pybind11's :doc:`CMake or Python build systems 11112391Sjason@lowepower.com<compiling>` (the two example repositories) and you haven't been exporting any 11212391Sjason@lowepower.comsymbols, there's nothing to be concerned about. All the changes have been done 11312391Sjason@lowepower.comtransparently in the background. If you were building manually or relied on 11412391Sjason@lowepower.comspecific default visibility, read on. 11512391Sjason@lowepower.com 11612391Sjason@lowepower.comSetting default symbol visibility to *hidden* has always been recommended for 11712391Sjason@lowepower.compybind11 (see :ref:`faq:symhidden`). On Linux and macOS, hidden symbol 11812391Sjason@lowepower.comvisibility (in conjunction with the ``strip`` utility) yields much smaller 11912391Sjason@lowepower.commodule binaries. `CPython's extension docs`_ also recommend hiding symbols 12012391Sjason@lowepower.comby default, with the goal of avoiding symbol name clashes between modules. 12112391Sjason@lowepower.comStarting with v2.2, pybind11 enforces this more strictly: (1) by declaring 12212391Sjason@lowepower.comall symbols inside the ``pybind11`` namespace as hidden and (2) by including 12312391Sjason@lowepower.comthe ``-fvisibility=hidden`` flag on Linux and macOS (only for extension 12412391Sjason@lowepower.commodules, not for embedding the interpreter). 12512391Sjason@lowepower.com 12612391Sjason@lowepower.com.. _CPython's extension docs: https://docs.python.org/3/extending/extending.html#providing-a-c-api-for-an-extension-module 12712391Sjason@lowepower.com 12812391Sjason@lowepower.comThe namespace-scope hidden visibility is done automatically in pybind11's 12912391Sjason@lowepower.comheaders and it's generally transparent to users. It ensures that: 13012391Sjason@lowepower.com 13112391Sjason@lowepower.com* Modules compiled with different pybind11 versions don't clash with each other. 13212391Sjason@lowepower.com 13312391Sjason@lowepower.com* Some new features, like ``py::module_local`` bindings, can work as intended. 13412391Sjason@lowepower.com 13512391Sjason@lowepower.comThe ``-fvisibility=hidden`` flag applies the same visibility to user bindings 13612391Sjason@lowepower.comoutside of the ``pybind11`` namespace. It's now set automatic by pybind11's 13712391Sjason@lowepower.comCMake and Python build systems, but this needs to be done manually by users 13812391Sjason@lowepower.comof other build systems. Adding this flag: 13912391Sjason@lowepower.com 14012391Sjason@lowepower.com* Minimizes the chances of symbol conflicts between modules. E.g. if two 14112391Sjason@lowepower.com unrelated modules were statically linked to different (ABI-incompatible) 14212391Sjason@lowepower.com versions of the same third-party library, a symbol clash would be likely 14312391Sjason@lowepower.com (and would end with unpredictable results). 14412391Sjason@lowepower.com 14512391Sjason@lowepower.com* Produces smaller binaries on Linux and macOS, as pointed out previously. 14612391Sjason@lowepower.com 14712391Sjason@lowepower.comWithin pybind11's CMake build system, ``pybind11_add_module`` has always been 14812391Sjason@lowepower.comsetting the ``-fvisibility=hidden`` flag in release mode. From now on, it's 14912391Sjason@lowepower.combeing applied unconditionally, even in debug mode and it can no longer be opted 15012391Sjason@lowepower.comout of with the ``NO_EXTRAS`` option. The ``pybind11::module`` target now also 15112391Sjason@lowepower.comadds this flag to it's interface. The ``pybind11::embed`` target is unchanged. 15212391Sjason@lowepower.com 15312391Sjason@lowepower.comThe most significant change here is for the ``pybind11::module`` target. If you 15412391Sjason@lowepower.comwere previously relying on default visibility, i.e. if your Python module was 15512391Sjason@lowepower.comdoubling as a shared library with dependents, you'll need to either export 15612391Sjason@lowepower.comsymbols manually (recommended for cross-platform libraries) or factor out the 15712391Sjason@lowepower.comshared library (and have the Python module link to it like the other 15812391Sjason@lowepower.comdependents). As a temporary workaround, you can also restore default visibility 15912391Sjason@lowepower.comusing the CMake code below, but this is not recommended in the long run: 16012391Sjason@lowepower.com 16112391Sjason@lowepower.com.. code-block:: cmake 16212391Sjason@lowepower.com 16312391Sjason@lowepower.com target_link_libraries(mymodule PRIVATE pybind11::module) 16412391Sjason@lowepower.com 16512391Sjason@lowepower.com add_library(restore_default_visibility INTERFACE) 16612391Sjason@lowepower.com target_compile_options(restore_default_visibility INTERFACE -fvisibility=default) 16712391Sjason@lowepower.com target_link_libraries(mymodule PRIVATE restore_default_visibility) 16812391Sjason@lowepower.com 16912391Sjason@lowepower.com 17012391Sjason@lowepower.comLocal STL container bindings 17112391Sjason@lowepower.com---------------------------- 17212391Sjason@lowepower.com 17312391Sjason@lowepower.comPrevious pybind11 versions could only bind types globally -- all pybind11 17412391Sjason@lowepower.commodules, even unrelated ones, would have access to the same exported types. 17512391Sjason@lowepower.comHowever, this would also result in a conflict if two modules exported the 17612391Sjason@lowepower.comsame C++ type, which is especially problematic for very common types, e.g. 17712391Sjason@lowepower.com``std::vector<int>``. :ref:`module_local` were added to resolve this (see 17812391Sjason@lowepower.comthat section for a complete usage guide). 17912391Sjason@lowepower.com 18012391Sjason@lowepower.com``py::class_`` still defaults to global bindings (because these types are 18112391Sjason@lowepower.comusually unique across modules), however in order to avoid clashes of opaque 18212391Sjason@lowepower.comtypes, ``py::bind_vector`` and ``py::bind_map`` will now bind STL containers 18312391Sjason@lowepower.comas ``py::module_local`` if their elements are: builtins (``int``, ``float``, 18412391Sjason@lowepower.cometc.), not bound using ``py::class_``, or bound as ``py::module_local``. For 18512391Sjason@lowepower.comexample, this change allows multiple modules to bind ``std::vector<int>`` 18612391Sjason@lowepower.comwithout causing conflicts. See :ref:`stl_bind` for more details. 18712391Sjason@lowepower.com 18812391Sjason@lowepower.comWhen upgrading to this version, if you have multiple modules which depend on 18912391Sjason@lowepower.coma single global binding of an STL container, note that all modules can still 19012391Sjason@lowepower.comaccept foreign ``py::module_local`` types in the direction of Python-to-C++. 19112391Sjason@lowepower.comThe locality only affects the C++-to-Python direction. If this is needed in 19212391Sjason@lowepower.commultiple modules, you'll need to either: 19312391Sjason@lowepower.com 19412391Sjason@lowepower.com* Add a copy of the same STL binding to all of the modules which need it. 19512391Sjason@lowepower.com 19612391Sjason@lowepower.com* Restore the global status of that single binding by marking it 19712391Sjason@lowepower.com ``py::module_local(false)``. 19812391Sjason@lowepower.com 19912391Sjason@lowepower.comThe latter is an easy workaround, but in the long run it would be best to 20012391Sjason@lowepower.comlocalize all common type bindings in order to avoid conflicts with 20112391Sjason@lowepower.comthird-party modules. 20212391Sjason@lowepower.com 20312391Sjason@lowepower.com 20412391Sjason@lowepower.comNegative strides for Python buffer objects and numpy arrays 20512391Sjason@lowepower.com----------------------------------------------------------- 20612391Sjason@lowepower.com 20712391Sjason@lowepower.comSupport for negative strides required changing the integer type from unsigned 20812391Sjason@lowepower.comto signed in the interfaces of ``py::buffer_info`` and ``py::array``. If you 20912391Sjason@lowepower.comhave compiler warnings enabled, you may notice some new conversion warnings 21012391Sjason@lowepower.comafter upgrading. These can be resolved using ``static_cast``. 21112391Sjason@lowepower.com 21212391Sjason@lowepower.com 21312391Sjason@lowepower.comDeprecation of some ``py::object`` APIs 21412391Sjason@lowepower.com--------------------------------------- 21512391Sjason@lowepower.com 21612391Sjason@lowepower.comTo compare ``py::object`` instances by pointer, you should now use 21712391Sjason@lowepower.com``obj1.is(obj2)`` which is equivalent to ``obj1 is obj2`` in Python. 21812391Sjason@lowepower.comPreviously, pybind11 used ``operator==`` for this (``obj1 == obj2``), but 21912391Sjason@lowepower.comthat could be confusing and is now deprecated (so that it can eventually 22012391Sjason@lowepower.combe replaced with proper rich object comparison in a future release). 22112391Sjason@lowepower.com 22212391Sjason@lowepower.comFor classes which inherit from ``py::object``, ``borrowed`` and ``stolen`` 22312391Sjason@lowepower.comwere previously available as protected constructor tags. Now the types 22412391Sjason@lowepower.comshould be used directly instead: ``borrowed_t{}`` and ``stolen_t{}`` 22512391Sjason@lowepower.com(`#771 <https://github.com/pybind/pybind11/pull/771>`_). 22612391Sjason@lowepower.com 22712391Sjason@lowepower.com 22812391Sjason@lowepower.comStricter compile-time error checking 22912391Sjason@lowepower.com------------------------------------ 23012391Sjason@lowepower.com 23112391Sjason@lowepower.comSome error checks have been moved from run time to compile time. Notably, 23212391Sjason@lowepower.comautomatic conversion of ``std::shared_ptr<T>`` is not possible when ``T`` is 23312391Sjason@lowepower.comnot directly registered with ``py::class_<T>`` (e.g. ``std::shared_ptr<int>`` 23412391Sjason@lowepower.comor ``std::shared_ptr<std::vector<T>>`` are not automatically convertible). 23512391Sjason@lowepower.comAttempting to bind a function with such arguments now results in a compile-time 23612391Sjason@lowepower.comerror instead of waiting to fail at run time. 23712391Sjason@lowepower.com 23812391Sjason@lowepower.com``py::init<...>()`` constructor definitions are also stricter and now prevent 23912391Sjason@lowepower.combindings which could cause unexpected behavior: 24012391Sjason@lowepower.com 24112391Sjason@lowepower.com.. code-block:: cpp 24212391Sjason@lowepower.com 24312391Sjason@lowepower.com struct Example { 24412391Sjason@lowepower.com Example(int &); 24512391Sjason@lowepower.com }; 24612391Sjason@lowepower.com 24712391Sjason@lowepower.com py::class_<Example>(m, "Example") 24812391Sjason@lowepower.com .def(py::init<int &>()); // OK, exact match 24912391Sjason@lowepower.com // .def(py::init<int>()); // compile-time error, mismatch 25012391Sjason@lowepower.com 25112391Sjason@lowepower.comA non-``const`` lvalue reference is not allowed to bind to an rvalue. However, 25212391Sjason@lowepower.comnote that a constructor taking ``const T &`` can still be registered using 25312391Sjason@lowepower.com``py::init<T>()`` because a ``const`` lvalue reference can bind to an rvalue. 25412391Sjason@lowepower.com 25512391Sjason@lowepower.comv2.1 25612391Sjason@lowepower.com==== 25712391Sjason@lowepower.com 25812391Sjason@lowepower.comMinimum compiler versions are enforced at compile time 25912391Sjason@lowepower.com------------------------------------------------------ 26012391Sjason@lowepower.com 26112391Sjason@lowepower.comThe minimums also apply to v2.0 but the check is now explicit and a compile-time 26212391Sjason@lowepower.comerror is raised if the compiler does not meet the requirements: 26312391Sjason@lowepower.com 26412391Sjason@lowepower.com* GCC >= 4.8 26512391Sjason@lowepower.com* clang >= 3.3 (appleclang >= 5.0) 26612391Sjason@lowepower.com* MSVC >= 2015u3 26712391Sjason@lowepower.com* Intel C++ >= 15.0 26812391Sjason@lowepower.com 26912391Sjason@lowepower.com 27012391Sjason@lowepower.comThe ``py::metaclass`` attribute is not required for static properties 27112391Sjason@lowepower.com--------------------------------------------------------------------- 27212391Sjason@lowepower.com 27312391Sjason@lowepower.comBinding classes with static properties is now possible by default. The 27412391Sjason@lowepower.comzero-parameter version of ``py::metaclass()`` is deprecated. However, a new 27512391Sjason@lowepower.comone-parameter ``py::metaclass(python_type)`` version was added for rare 27612391Sjason@lowepower.comcases when a custom metaclass is needed to override pybind11's default. 27712391Sjason@lowepower.com 27812391Sjason@lowepower.com.. code-block:: cpp 27912391Sjason@lowepower.com 28012391Sjason@lowepower.com // old -- emits a deprecation warning 28112391Sjason@lowepower.com py::class_<Foo>(m, "Foo", py::metaclass()) 28212391Sjason@lowepower.com .def_property_readonly_static("foo", ...); 28312391Sjason@lowepower.com 28412391Sjason@lowepower.com // new -- static properties work without the attribute 28512391Sjason@lowepower.com py::class_<Foo>(m, "Foo") 28612391Sjason@lowepower.com .def_property_readonly_static("foo", ...); 28712391Sjason@lowepower.com 28812391Sjason@lowepower.com // new -- advanced feature, override pybind11's default metaclass 28912391Sjason@lowepower.com py::class_<Bar>(m, "Bar", py::metaclass(custom_python_type)) 29012391Sjason@lowepower.com ... 29112391Sjason@lowepower.com 29212391Sjason@lowepower.com 29312391Sjason@lowepower.comv2.0 29412391Sjason@lowepower.com==== 29512391Sjason@lowepower.com 29612391Sjason@lowepower.comBreaking changes in ``py::class_`` 29712391Sjason@lowepower.com---------------------------------- 29812391Sjason@lowepower.com 29912391Sjason@lowepower.comThese changes were necessary to make type definitions in pybind11 30012391Sjason@lowepower.comfuture-proof, to support PyPy via its ``cpyext`` mechanism (`#527 30112391Sjason@lowepower.com<https://github.com/pybind/pybind11/pull/527>`_), and to improve efficiency 30212391Sjason@lowepower.com(`rev. 86d825 <https://github.com/pybind/pybind11/commit/86d825>`_). 30312391Sjason@lowepower.com 30412391Sjason@lowepower.com1. Declarations of types that provide access via the buffer protocol must 30512391Sjason@lowepower.com now include the ``py::buffer_protocol()`` annotation as an argument to 30612391Sjason@lowepower.com the ``py::class_`` constructor. 30712391Sjason@lowepower.com 30812391Sjason@lowepower.com .. code-block:: cpp 30912391Sjason@lowepower.com 31012391Sjason@lowepower.com py::class_<Matrix>("Matrix", py::buffer_protocol()) 31112391Sjason@lowepower.com .def(py::init<...>()) 31212391Sjason@lowepower.com .def_buffer(...); 31312391Sjason@lowepower.com 31412391Sjason@lowepower.com2. Classes which include static properties (e.g. ``def_readwrite_static()``) 31512391Sjason@lowepower.com must now include the ``py::metaclass()`` attribute. Note: this requirement 31612391Sjason@lowepower.com has since been removed in v2.1. If you're upgrading from 1.x, it's 31712391Sjason@lowepower.com recommended to skip directly to v2.1 or newer. 31812391Sjason@lowepower.com 31912391Sjason@lowepower.com3. This version of pybind11 uses a redesigned mechanism for instantiating 32012391Sjason@lowepower.com trampoline classes that are used to override virtual methods from within 32112391Sjason@lowepower.com Python. This led to the following user-visible syntax change: 32212391Sjason@lowepower.com 32312391Sjason@lowepower.com .. code-block:: cpp 32412391Sjason@lowepower.com 32512391Sjason@lowepower.com // old v1.x syntax 32612391Sjason@lowepower.com py::class_<TrampolineClass>("MyClass") 32712391Sjason@lowepower.com .alias<MyClass>() 32812391Sjason@lowepower.com ... 32912391Sjason@lowepower.com 33012391Sjason@lowepower.com // new v2.x syntax 33112391Sjason@lowepower.com py::class_<MyClass, TrampolineClass>("MyClass") 33212391Sjason@lowepower.com ... 33312391Sjason@lowepower.com 33412391Sjason@lowepower.com Importantly, both the original and the trampoline class are now specified 33512391Sjason@lowepower.com as arguments to the ``py::class_`` template, and the ``alias<..>()`` call 33612391Sjason@lowepower.com is gone. The new scheme has zero overhead in cases when Python doesn't 33712391Sjason@lowepower.com override any functions of the underlying C++ class. 33812391Sjason@lowepower.com `rev. 86d825 <https://github.com/pybind/pybind11/commit/86d825>`_. 33912391Sjason@lowepower.com 34012391Sjason@lowepower.com The class type must be the first template argument given to ``py::class_`` 34112391Sjason@lowepower.com while the trampoline can be mixed in arbitrary order with other arguments 34212391Sjason@lowepower.com (see the following section). 34312391Sjason@lowepower.com 34412391Sjason@lowepower.com 34512391Sjason@lowepower.comDeprecation of the ``py::base<T>()`` attribute 34612391Sjason@lowepower.com---------------------------------------------- 34712391Sjason@lowepower.com 34812391Sjason@lowepower.com``py::base<T>()`` was deprecated in favor of specifying ``T`` as a template 34912391Sjason@lowepower.comargument to ``py::class_``. This new syntax also supports multiple inheritance. 35012391Sjason@lowepower.comNote that, while the type being exported must be the first argument in the 35112391Sjason@lowepower.com``py::class_<Class, ...>`` template, the order of the following types (bases, 35212391Sjason@lowepower.comholder and/or trampoline) is not important. 35312391Sjason@lowepower.com 35412391Sjason@lowepower.com.. code-block:: cpp 35512391Sjason@lowepower.com 35612391Sjason@lowepower.com // old v1.x 35712391Sjason@lowepower.com py::class_<Derived>("Derived", py::base<Base>()); 35812391Sjason@lowepower.com 35912391Sjason@lowepower.com // new v2.x 36012391Sjason@lowepower.com py::class_<Derived, Base>("Derived"); 36112391Sjason@lowepower.com 36212391Sjason@lowepower.com // new -- multiple inheritance 36312391Sjason@lowepower.com py::class_<Derived, Base1, Base2>("Derived"); 36412391Sjason@lowepower.com 36512391Sjason@lowepower.com // new -- apart from `Derived` the argument order can be arbitrary 36612391Sjason@lowepower.com py::class_<Derived, Base1, Holder, Base2, Trampoline>("Derived"); 36712391Sjason@lowepower.com 36812391Sjason@lowepower.com 36912391Sjason@lowepower.comOut-of-the-box support for ``std::shared_ptr`` 37012391Sjason@lowepower.com---------------------------------------------- 37112391Sjason@lowepower.com 37212391Sjason@lowepower.comThe relevant type caster is now built in, so it's no longer necessary to 37312391Sjason@lowepower.cominclude a declaration of the form: 37412391Sjason@lowepower.com 37512391Sjason@lowepower.com.. code-block:: cpp 37612391Sjason@lowepower.com 37712391Sjason@lowepower.com PYBIND11_DECLARE_HOLDER_TYPE(T, std::shared_ptr<T>) 37812391Sjason@lowepower.com 37912391Sjason@lowepower.comContinuing to do so won’t cause an error or even a deprecation warning, 38012391Sjason@lowepower.combut it's completely redundant. 38112391Sjason@lowepower.com 38212391Sjason@lowepower.com 38312391Sjason@lowepower.comDeprecation of a few ``py::object`` APIs 38412391Sjason@lowepower.com---------------------------------------- 38512391Sjason@lowepower.com 38612391Sjason@lowepower.comAll of the old-style calls emit deprecation warnings. 38712391Sjason@lowepower.com 38812391Sjason@lowepower.com+---------------------------------------+---------------------------------------------+ 38912391Sjason@lowepower.com| Old syntax | New syntax | 39012391Sjason@lowepower.com+=======================================+=============================================+ 39112391Sjason@lowepower.com| ``obj.call(args...)`` | ``obj(args...)`` | 39212391Sjason@lowepower.com+---------------------------------------+---------------------------------------------+ 39312391Sjason@lowepower.com| ``obj.str()`` | ``py::str(obj)`` | 39412391Sjason@lowepower.com+---------------------------------------+---------------------------------------------+ 39512391Sjason@lowepower.com| ``auto l = py::list(obj); l.check()`` | ``py::isinstance<py::list>(obj)`` | 39612391Sjason@lowepower.com+---------------------------------------+---------------------------------------------+ 39712391Sjason@lowepower.com| ``py::object(ptr, true)`` | ``py::reinterpret_borrow<py::object>(ptr)`` | 39812391Sjason@lowepower.com+---------------------------------------+---------------------------------------------+ 39912391Sjason@lowepower.com| ``py::object(ptr, false)`` | ``py::reinterpret_steal<py::object>(ptr)`` | 40012391Sjason@lowepower.com+---------------------------------------+---------------------------------------------+ 40112391Sjason@lowepower.com| ``if (obj.attr("foo"))`` | ``if (py::hasattr(obj, "foo"))`` | 40212391Sjason@lowepower.com+---------------------------------------+---------------------------------------------+ 40312391Sjason@lowepower.com| ``if (obj["bar"])`` | ``if (obj.contains("bar"))`` | 40412391Sjason@lowepower.com+---------------------------------------+---------------------------------------------+ 405