From cae4ae083e2ed4acbd28f16e1dbe275fe19a700f Mon Sep 17 00:00:00 2001 From: Joshua Oreman Date: Sat, 11 Oct 2025 12:09:14 -0500 Subject: [PATCH] docs: clarify to what extent bindings are actually global (#5859) --- docs/advanced/classes.rst | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/advanced/classes.rst b/docs/advanced/classes.rst index 14bfc0bcd..faaba38b8 100644 --- a/docs/advanced/classes.rst +++ b/docs/advanced/classes.rst @@ -972,9 +972,14 @@ Module-local class bindings =========================== When creating a binding for a class, pybind11 by default makes that binding -"global" across modules. What this means is that a type defined in one module -can be returned from any module resulting in the same Python type. For -example, this allows the following: +"global" across modules. What this means is that instances whose type is +defined with a ``py::class_`` statement in one module can be passed to or +returned from a function defined in any other module that is "ABI compatible" +with the first, i.e., that was built with sufficiently similar versions of +pybind11 and of the C++ compiler and C++ standard library. The internal data +structures that pybind11 uses to keep track of its types and instances are +shared just as they would be if everything were in the same module. +For example, this allows the following: .. code-block:: cpp