squash-merge smart_holder branch into master

.codespell-ignore-lines

@@ -12,6 +12,17 @@ template <op_id id, op_type ot, typename L, typename R>
     template <detail::op_id id, detail::op_type ot, typename L, typename R, typename... Extra>
     class_ &def(const detail::op_<id, ot, L, R> &op, const Extra &...extra) {
     class_ &def_cast(const detail::op_<id, ot, L, R> &op, const Extra &...extra) {
+    int valu;
+    explicit movable_int(int v) : valu{v} {}
+    movable_int(movable_int &&other) noexcept : valu(other.valu) { other.valu = 91; }
+    explicit indestructible_int(int v) : valu{v} {}
+    REQUIRE(hld.as_raw_ptr_unowned<zombie>()->valu == 19);
+        REQUIRE(othr.valu == 19);
+        REQUIRE(orig.valu == 91);
+        (m.pass_valu, "Valu", "pass_valu:Valu(_MvCtor)*_CpCtor"),
+atyp_valu        rtrn_valu() { atyp_valu obj{"Valu"}; return obj; }
+    assert m.atyp_valu().get_mtxt() == "Valu"
+// valu(e), ref(erence), ptr or p (pointer), r = rvalue, m = mutable, c = const,
 @pytest.mark.parametrize("access", ["ro", "rw", "static_ro", "static_rw"])
 struct IntStruct {
     explicit IntStruct(int v) : value(v){};

.github/workflows/ci.yml

@@ -7,6 +7,7 @@ on:
     branches:
       - master
       - stable
+      - smart_holder
       - v*
 
 permissions: read-all
@@ -87,6 +88,20 @@ jobs:
           # Extra ubuntu latest job
           - runs-on: ubuntu-latest
             python: '3.11'
+          # Exercise PYBIND11_USE_SMART_HOLDER_AS_DEFAULT
+          # with recent (or ideally latest) released Python version.
+          - runs-on: ubuntu-latest
+            python: '3.12'
+            args: >
+              -DCMAKE_CXX_FLAGS="-DPYBIND11_USE_SMART_HOLDER_AS_DEFAULT"
+          - runs-on: macos-13
+            python: '3.12'
+            args: >
+              -DCMAKE_CXX_FLAGS="-DPYBIND11_USE_SMART_HOLDER_AS_DEFAULT"
+          - runs-on: windows-2022
+            python: '3.12'
+            args: >
+              -DCMAKE_CXX_FLAGS="/DPYBIND11_USE_SMART_HOLDER_AS_DEFAULT /GR /EHsc"
         exclude:
           # The setup-python action currently doesn't have graalpy for windows
           - python: 'graalpy-24.1'

.github/workflows/configure.yml

@@ -7,6 +7,7 @@ on:
     branches:
       - master
       - stable
+      - smart_holder
       - v*
 
 permissions:

.github/workflows/emscripten.yaml

@@ -6,6 +6,7 @@ on:
     branches:
     - master
     - stable
+    - smart_holder
     - v*
 
 concurrency:

.github/workflows/format.yml

@@ -10,6 +10,7 @@ on:
     branches:
     - master
     - stable
+    - smart_holder
     - "v*"
 
 permissions:

.github/workflows/pip.yml

@@ -7,6 +7,7 @@ on:
     branches:
     - master
     - stable
+    - smart_holder
     - v*
   release:
     types:

.pre-commit-config.yaml

@@ -76,6 +76,7 @@ repos:
   - id: mixed-line-ending
   - id: requirements-txt-fixer
   - id: trailing-whitespace
+    exclude: \.patch?$
 
 # Also code format the docs
 - repo: /~https://github.com/adamchainz/blacken-docs
@@ -90,6 +91,7 @@ repos:
   rev: "v1.5.5"
   hooks:
   - id: remove-tabs
+    exclude: (^docs/.*|\.patch)?$
 
 # Avoid directional quotes
 - repo: /~https://github.com/sirosen/texthooks

CMakeLists.txt

@@ -131,10 +131,13 @@ set(PYBIND11_HEADERS
     include/pybind11/detail/common.h
     include/pybind11/detail/cpp_conduit.h
     include/pybind11/detail/descr.h
+    include/pybind11/detail/dynamic_raw_ptr_cast_if_possible.h
     include/pybind11/detail/init.h
     include/pybind11/detail/internals.h
+    include/pybind11/detail/struct_smart_holder.h
     include/pybind11/detail/type_caster_base.h
     include/pybind11/detail/typeid.h
+    include/pybind11/detail/using_smart_holder.h
     include/pybind11/detail/value_and_holder.h
     include/pybind11/detail/exception_translation.h
     include/pybind11/attr.h
@@ -164,6 +167,7 @@ set(PYBIND11_HEADERS
     include/pybind11/stl.h
     include/pybind11/stl_bind.h
     include/pybind11/stl/filesystem.h
+    include/pybind11/trampoline_self_life_support.h
     include/pybind11/type_caster_pyobject_ptr.h
     include/pybind11/typing.h
     include/pybind11/warnings.h)

MANIFEST.in

@@ -1,4 +1,5 @@
 prune tests
+include README_smart_holder.rst
 recursive-include pybind11/include/pybind11 *.h
 recursive-include pybind11 *.py
 recursive-include pybind11 py.typed

README.rst

@@ -1,7 +1,7 @@
 .. figure:: /~https://github.com/pybind/pybind11/raw/master/docs/pybind11-logo.png
    :alt: pybind11 logo
 
-**pybind11 — Seamless operability between C++11 and Python**
+**pybind11 (v3)  — Seamless interoperability between C++ and Python**
 
 |Latest Documentation Status| |Stable Documentation Status| |Gitter chat| |GitHub Discussions| |CI| |Build status|
 

docs/advanced/classes.rst

@@ -125,6 +125,32 @@ extend ``Animal``, but not ``Dog``: see :ref:`virtual_and_inheritance` for the
 necessary steps required to providing proper overriding support for inherited
 classes.
 
+To enable safely passing a ``std::unique_ptr`` to a trampoline object between
+Python and C++,
+
+1. the C++ type (``Animal`` above) must be wrapped with ``py::classh``
+   (see :ref:`smart_holder`), and
+
+2. the trampoline helper class must inherit from
+   ``py::trampoline_self_life_support``.
+
+I.e. the example above needs these two changes:
+
+.. code-block:: cpp
+
+   class PyAnimal : public Animal, public py::trampoline_self_life_support {
+       ...
+   };
+
+.. code-block:: cpp
+
+    py::classh<Animal, PyAnimal>(m, "Animal");
+
+.. seealso::
+
+    A fairly minimal but complete example is in
+    :file:`tests/test_class_sh_trampoline_unique_ptr.cpp`.
+
 The Python session below shows how to override ``Animal::go`` and invoke it via
 a virtual method call.