Add py::module_local() attribute for module-local type bindings
This commit adds a `py::module_local` attribute that lets you confine a
registered type to the module (more technically, the shared object) in
which it is defined, by registering it with:
py::class_<C>(m, "C", py::module_local())
This will allow the same C++ class `C` to be registered in different
modules with independent sets of class definitions. On the Python side,
two such types will be completely distinct; on the C++ side, the C++
type resolves to a different Python type in each module.
This applies `py::module_local` automatically to `stl_bind.h` bindings
when the container value type looks like something global: i.e. when it
is a converting type (for example, when binding a `std::vector<int>`),
or when it is a registered type itself bound with `py::module_local`.
This should help resolve potential future conflicts (e.g. if two
completely unrelated modules both try to bind a `std::vector<int>`.
Users can override the automatic selection by adding a
`py::module_local()` or `py::module_local(false)`.
Note that this does mildly break backwards compatibility: bound stl
containers of basic types like `std::vector<int>` cannot be bound in one
module and returned in a different module. (This can be re-enabled with
`py::module_local(false)` as described above, but with the potential for
eventual load conflicts).
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index 8c7ca63..aa2704b 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -40,6 +40,7 @@
test_eval.cpp
test_exceptions.cpp
test_kwargs_and_defaults.cpp
+ test_local_bindings.cpp
test_methods_and_attributes.cpp
test_modules.cpp
test_multiple_inheritance.cpp
@@ -72,6 +73,7 @@
# doesn't include them) the second module doesn't get built.
set(PYBIND11_CROSS_MODULE_TESTS
test_exceptions.py
+ test_local_bindings.py
)
# Check if Eigen is available; if not, remove from PYBIND11_TEST_FILES (but
diff --git a/tests/local_bindings.h b/tests/local_bindings.h
new file mode 100644
index 0000000..0c53369
--- /dev/null
+++ b/tests/local_bindings.h
@@ -0,0 +1,26 @@
+#pragma once
+#include "pybind11_tests.h"
+
+/// Simple class used to test py::local:
+template <int> class LocalBase {
+public:
+ LocalBase(int i) : i(i) { }
+ int i = -1;
+};
+
+/// Registered with py::local in both main and secondary modules:
+using LocalType = LocalBase<0>;
+/// Registered without py::local in both modules:
+using NonLocalType = LocalBase<1>;
+/// A second non-local type (for stl_bind tests):
+using NonLocal2 = LocalBase<2>;
+/// Tests within-module, different-compilation-unit local definition conflict:
+using LocalExternal = LocalBase<3>;
+
+// Simple bindings (used with the above):
+template <typename T, int Adjust, typename... Args>
+py::class_<T> bind_local(Args && ...args) {
+ return py::class_<T>(std::forward<Args>(args)...)
+ .def(py::init<int>())
+ .def("get", [](T &i) { return i.i + Adjust; });
+};
diff --git a/tests/pybind11_cross_module_tests.cpp b/tests/pybind11_cross_module_tests.cpp
index 0053505..f417a89 100644
--- a/tests/pybind11_cross_module_tests.cpp
+++ b/tests/pybind11_cross_module_tests.cpp
@@ -8,6 +8,8 @@
*/
#include "pybind11_tests.h"
+#include "local_bindings.h"
+#include <pybind11/stl_bind.h>
PYBIND11_MODULE(pybind11_cross_module_tests, m) {
m.doc() = "pybind11 cross-module test module";
@@ -24,4 +26,45 @@
m.def("throw_pybind_type_error", []() { throw py::type_error("pybind11 type error"); });
m.def("throw_stop_iteration", []() { throw py::stop_iteration(); });
+ // test_local_bindings.py
+ // Local to both:
+ bind_local<LocalType, 1>(m, "LocalType", py::module_local())
+ .def("get2", [](LocalType &t) { return t.i + 2; })
+ ;
+
+ // Can only be called with our python type:
+ m.def("local_value", [](LocalType &l) { return l.i; });
+
+ // test_nonlocal_failure
+ // This registration will fail (global registration when LocalFail is already registered
+ // globally in the main test module):
+ m.def("register_nonlocal", [m]() {
+ bind_local<NonLocalType, 0>(m, "NonLocalType");
+ });
+
+ // test_stl_bind_local
+ // stl_bind.h binders defaults to py::module_local if the types are local or converting:
+ py::bind_vector<std::vector<LocalType>>(m, "LocalVec");
+ py::bind_map<std::unordered_map<std::string, LocalType>>(m, "LocalMap");
+ // and global if the type (or one of the types, for the map) is global (so these will fail,
+ // assuming pybind11_tests is already loaded):
+ m.def("register_nonlocal_vec", [m]() {
+ py::bind_vector<std::vector<NonLocalType>>(m, "NonLocalVec");
+ });
+ m.def("register_nonlocal_map", [m]() {
+ py::bind_map<std::unordered_map<std::string, NonLocalType>>(m, "NonLocalMap");
+ });
+
+ // test_stl_bind_global
+ // The default can, however, be overridden to global using `py::module_local()` or
+ // `py::module_local(false)`.
+ // Explicitly made local:
+ py::bind_vector<std::vector<NonLocal2>>(m, "NonLocalVec2", py::module_local());
+ // Explicitly made global (and so will fail to bind):
+ m.def("register_nonlocal_map2", [m]() {
+ py::bind_map<std::unordered_map<std::string, uint8_t>>(m, "NonLocalMap2", py::module_local(false));
+ });
+
+ // test_internal_locals_differ
+ m.def("local_cpp_types_addr", []() { return (uintptr_t) &py::detail::registered_local_types_cpp(); });
}
diff --git a/tests/test_class.cpp b/tests/test_class.cpp
index 8761f26..5860b74 100644
--- a/tests/test_class.cpp
+++ b/tests/test_class.cpp
@@ -9,6 +9,7 @@
#include "pybind11_tests.h"
#include "constructor_stats.h"
+#include "local_bindings.h"
TEST_SUBMODULE(class_, m) {
// test_instance
@@ -224,6 +225,10 @@
aliased.def(py::init<>());
aliased.attr("size_noalias") = py::int_(sizeof(AliasedHasOpNewDelSize));
aliased.attr("size_alias") = py::int_(sizeof(PyAliasedHasOpNewDelSize));
+
+ // This test is actually part of test_local_bindings (test_duplicate_local), but we need a
+ // definition in a different compilation unit within the same module:
+ bind_local<LocalExternal, 17>(m, "LocalExternal", py::module_local());
}
template <int N> class BreaksBase {};
diff --git a/tests/test_local_bindings.cpp b/tests/test_local_bindings.cpp
new file mode 100644
index 0000000..d98840f
--- /dev/null
+++ b/tests/test_local_bindings.cpp
@@ -0,0 +1,62 @@
+/*
+ tests/test_local_bindings.cpp -- tests the py::module_local class feature which makes a class
+ binding local to the module in which it is defined.
+
+ Copyright (c) 2017 Jason Rhinelander <jason@imaginary.ca>
+
+ All rights reserved. Use of this source code is governed by a
+ BSD-style license that can be found in the LICENSE file.
+*/
+
+#include "pybind11_tests.h"
+#include "local_bindings.h"
+#include <pybind11/stl_bind.h>
+
+TEST_SUBMODULE(local_bindings, m) {
+
+ // test_local_bindings
+ // Register a class with py::module_local:
+ bind_local<LocalType, -1>(m, "LocalType", py::module_local())
+ .def("get3", [](LocalType &t) { return t.i + 3; })
+ ;
+
+ m.def("local_value", [](LocalType &l) { return l.i; });
+
+ // test_nonlocal_failure
+ // The main pybind11 test module is loaded first, so this registration will succeed (the second
+ // one, in pybind11_cross_module_tests.cpp, is designed to fail):
+ bind_local<NonLocalType, 0>(m, "NonLocalType")
+ .def(py::init<int>())
+ .def("get", [](LocalType &i) { return i.i; })
+ ;
+
+ // test_duplicate_local
+ // py::module_local declarations should be visible across compilation units that get linked together;
+ // this tries to register a duplicate local. It depends on a definition in test_class.cpp and
+ // should raise a runtime error from the duplicate definition attempt. If test_class isn't
+ // available it *also* throws a runtime error (with "test_class not enabled" as value).
+ m.def("register_local_external", [m]() {
+ auto main = py::module::import("pybind11_tests");
+ if (py::hasattr(main, "class_")) {
+ bind_local<LocalExternal, 7>(m, "LocalExternal", py::module_local());
+ }
+ else throw std::runtime_error("test_class not enabled");
+ });
+
+ // test_stl_bind_local
+ // stl_bind.h binders defaults to py::module_local if the types are local or converting:
+ py::bind_vector<std::vector<LocalType>>(m, "LocalVec");
+ py::bind_map<std::unordered_map<std::string, LocalType>>(m, "LocalMap");
+ // and global if the type (or one of the types, for the map) is global:
+ py::bind_vector<std::vector<NonLocalType>>(m, "NonLocalVec");
+ py::bind_map<std::unordered_map<std::string, NonLocalType>>(m, "NonLocalMap");
+
+ // test_stl_bind_global
+ // They can, however, be overridden to global using `py::module_local(false)`:
+ bind_local<NonLocal2, 10>(m, "NonLocal2");
+ py::bind_vector<std::vector<NonLocal2>>(m, "LocalVec2", py::module_local());
+ py::bind_map<std::unordered_map<std::string, uint8_t>>(m, "NonLocalMap2", py::module_local(false));
+
+ // test_internal_locals_differ
+ m.def("local_cpp_types_addr", []() { return (uintptr_t) &py::detail::registered_local_types_cpp(); });
+}
diff --git a/tests/test_local_bindings.py b/tests/test_local_bindings.py
new file mode 100644
index 0000000..4c5a874
--- /dev/null
+++ b/tests/test_local_bindings.py
@@ -0,0 +1,109 @@
+import pytest
+
+from pybind11_tests import local_bindings as m
+
+
+def test_local_bindings():
+ """Tests that duplicate py::local class bindings work across modules"""
+
+ # Make sure we can load the second module with the conflicting (but local) definition:
+ import pybind11_cross_module_tests as cm
+
+ i1 = m.LocalType(5)
+
+ assert i1.get() == 4
+ assert i1.get3() == 8
+
+ i2 = cm.LocalType(10)
+ assert i2.get() == 11
+ assert i2.get2() == 12
+
+ assert not hasattr(i1, 'get2')
+ assert not hasattr(i2, 'get3')
+
+ assert m.local_value(i1) == 5
+ assert cm.local_value(i2) == 10
+
+ with pytest.raises(TypeError) as excinfo:
+ m.local_value(i2)
+ assert "incompatible function arguments" in str(excinfo.value)
+
+ with pytest.raises(TypeError) as excinfo:
+ cm.local_value(i1)
+ assert "incompatible function arguments" in str(excinfo.value)
+
+
+def test_nonlocal_failure():
+ """Tests that attempting to register a non-local type in multiple modules fails"""
+ import pybind11_cross_module_tests as cm
+
+ with pytest.raises(RuntimeError) as excinfo:
+ cm.register_nonlocal()
+ assert str(excinfo.value) == 'generic_type: type "NonLocalType" is already registered!'
+
+
+def test_duplicate_local():
+ """Tests expected failure when registering a class twice with py::local in the same module"""
+ with pytest.raises(RuntimeError) as excinfo:
+ m.register_local_external()
+ import pybind11_tests
+ assert str(excinfo.value) == (
+ 'generic_type: type "LocalExternal" is already registered!'
+ if hasattr(pybind11_tests, 'class_') else 'test_class not enabled')
+
+
+def test_stl_bind_local():
+ import pybind11_cross_module_tests as cm
+
+ v1, v2 = m.LocalVec(), cm.LocalVec()
+ v1.append(m.LocalType(1))
+ v1.append(m.LocalType(2))
+ v2.append(cm.LocalType(1))
+ v2.append(cm.LocalType(2))
+
+ with pytest.raises(TypeError):
+ v1.append(cm.LocalType(3))
+ with pytest.raises(TypeError):
+ v2.append(m.LocalType(3))
+
+ assert [i.get() for i in v1] == [0, 1]
+ assert [i.get() for i in v2] == [2, 3]
+
+ v3, v4 = m.NonLocalVec(), cm.NonLocalVec2()
+ v3.append(m.NonLocalType(1))
+ v3.append(m.NonLocalType(2))
+ v4.append(m.NonLocal2(3))
+ v4.append(m.NonLocal2(4))
+
+ assert [i.get() for i in v3] == [1, 2]
+ assert [i.get() for i in v4] == [13, 14]
+
+ d1, d2 = m.LocalMap(), cm.LocalMap()
+ d1["a"] = v1[0]
+ d1["b"] = v1[1]
+ d2["c"] = v2[0]
+ d2["d"] = v2[1]
+ assert {i: d1[i].get() for i in d1} == {'a': 0, 'b': 1}
+ assert {i: d2[i].get() for i in d2} == {'c': 2, 'd': 3}
+
+
+def test_stl_bind_global():
+ import pybind11_cross_module_tests as cm
+
+ with pytest.raises(RuntimeError) as excinfo:
+ cm.register_nonlocal_map()
+ assert str(excinfo.value) == 'generic_type: type "NonLocalMap" is already registered!'
+
+ with pytest.raises(RuntimeError) as excinfo:
+ cm.register_nonlocal_vec()
+ assert str(excinfo.value) == 'generic_type: type "NonLocalVec" is already registered!'
+
+ with pytest.raises(RuntimeError) as excinfo:
+ cm.register_nonlocal_map2()
+ assert str(excinfo.value) == 'generic_type: type "NonLocalMap2" is already registered!'
+
+
+def test_internal_locals_differ():
+ """Makes sure the internal local type map differs across the two modules"""
+ import pybind11_cross_module_tests as cm
+ assert m.local_cpp_types_addr() != cm.local_cpp_types_addr()