feat: 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'
+          # Run tests with py::smart_holder as the default holder
+          # with recent (or ideally latest) released Python version.
+          - runs-on: ubuntu-latest
+            python: '3.12'
+            args: >
+              -DCMAKE_CXX_FLAGS="-DPYBIND11_RUN_TESTING_WITH_SMART_HOLDER_AS_DEFAULT_BUT_NEVER_USE_IN_PRODUCTION_PLEASE"
+          - runs-on: macos-13
+            python: '3.12'
+            args: >
+              -DCMAKE_CXX_FLAGS="-DPYBIND11_RUN_TESTING_WITH_SMART_HOLDER_AS_DEFAULT_BUT_NEVER_USE_IN_PRODUCTION_PLEASE"
+          - runs-on: windows-2022
+            python: '3.12'
+            args: >
+              -DCMAKE_CXX_FLAGS="/DPYBIND11_RUN_TESTING_WITH_SMART_HOLDER_AS_DEFAULT_BUT_NEVER_USE_IN_PRODUCTION_PLEASE /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)

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/cast/eigen.rst

@@ -102,7 +102,7 @@ example:
     };
 
     // Later, in binding code:
-    py::class_<MyClass>(m, "MyClass")
+    py::classh<MyClass>(m, "MyClass")
         .def(py::init<>())
         .def("copy_matrix", &MyClass::getMatrix) // Makes a copy!
         .def("get_matrix", &MyClass::getMatrix, py::return_value_policy::reference_internal)
@@ -250,7 +250,7 @@ copying to take place:
 
     // The associated binding code:
     using namespace pybind11::literals; // for "arg"_a
-    py::class_<MyClass>(m, "MyClass")
+    py::classh<MyClass>(m, "MyClass")
         // ... other class definitions
         .def("some_method", &MyClass::some_method, py::arg().noconvert());
 

docs/advanced/cast/overview.rst

@@ -3,13 +3,13 @@ Overview
 
 .. rubric:: 1. Native type in C++, wrapper in Python
 
-Exposing a custom C++ type using :class:`py::class_` was covered in detail
-in the :doc:`/classes` section. There, the underlying data structure is
-always the original C++ class while the :class:`py::class_` wrapper provides
-a Python interface. Internally, when an object like this is sent from C++ to
-Python, pybind11 will just add the outer wrapper layer over the native C++
-object. Getting it back from Python is just a matter of peeling off the
-wrapper.
+Exposing a custom C++ type using ``py::classh`` (or ``py::class_``) was
+covered in detail in the :doc:`/classes` section. There, the underlying
+data structure is always the original C++ class while the ``py::classh``
+wrapper provides a Python interface. Internally, when an object like this
+is sent from C++ to Python, pybind11 will just add the outer wrapper layer
+over the native C++ object. Getting it back from Python is just a matter of
+peeling off the wrapper.
 
 .. rubric:: 2. Wrapper in C++, native type in Python
 

docs/advanced/cast/stl.rst

@@ -135,7 +135,7 @@ functions:
 
     /* ... binding code ... */
 
-    py::class_<MyClass>(m, "MyClass")
+    py::classh<MyClass>(m, "MyClass")
         .def(py::init<>())
         .def_readwrite("contents", &MyClass::contents);
 
@@ -169,12 +169,12 @@ macro must be specified at the top level (and outside of any namespaces), since
 it adds a template instantiation of ``type_caster``. If your binding code consists of
 multiple compilation units, it must be present in every file (typically via a
 common header) preceding any usage of ``std::vector<int>``. Opaque types must
-also have a corresponding ``class_`` declaration to associate them with a name
+also have a corresponding ``py::classh`` declaration to associate them with a name
 in Python, and to define a set of available operations, e.g.:
 
 .. code-block:: cpp
 
-    py::class_<std::vector<int>>(m, "IntVector")
+    py::classh<std::vector<int>>(m, "IntVector")
         .def(py::init<>())
         .def("clear", &std::vector<int>::clear)
         .def("pop_back", &std::vector<int>::pop_back)