Made module_local types take precedence over global types
Attempting to mix py::module_local and non-module_local classes results
in some unexpected/undesirable behaviour:
- if a class is registered non-local by some other module, a later
attempt to register it locally fails. It doesn't need to: it is
perfectly acceptable for the local registration to simply override
the external global registration.
- going the other way (i.e. module `A` registers a type `T` locally,
then `B` registers the same type `T` globally) causes a more serious
issue: `A.T`'s constructors no longer work because the `self` argument
gets converted to a `B.T`, which then fails to resolve.
Changing the cast precedence to prefer local over global fixes this and
makes it work more consistently, regardless of module load order.
diff --git a/docs/advanced/classes.rst b/docs/advanced/classes.rst
index 71a7a88..04eb253 100644
--- a/docs/advanced/classes.rst
+++ b/docs/advanced/classes.rst
@@ -752,6 +752,11 @@
Invoked with: <dogs.Dog object at 0x123>
+It is possible to use ``py::module_local()`` registrations in one module even if another module
+registers the same type globally: within the module with the module-local definition, all C++
+instances will be cast to the associated bound Python type. Outside the module, any such values
+are converted to the global Python type created elsewhere.
+
.. note::
STL bindings (as provided via the optional :file:`pybind11/stl_bind.h`