-
-
--At first sight this might seem natural and straightforward. However, it -is a fairly complex problem to establish cross-extension-module -dependencies while maintaining the same ease of use Boost.Python -provides for classes that are wrapped in the same extension module. To -a large extent this complexity can be hidden from the author of a -Boost.Python extension module, but not entirely. - -
-import std_vector -v = std_vector.double([1, 2, 3, 4]) -v.push_back(5) -v.size() -- -Suppose the std_vector module is done well and reflects all C++ -functions that are useful at the Python level, for all C++ built-in -data types (std_vector.int, std_vector.long, etc.). - -
-Suppose further that there is statistic module with a C++ class that -has constructors or member functions that use or return a std::vector. -For example: - -
-class xy {
- private:
- std::vector<double> m_x;
- std::vector<double> m_y;
- public:
- xy(const std::vector<double>& x, const std::vector<double>& y) : m_x(x), m_y(y) {}
- const std::vector<double>& x() const { return m_x; }
- const std::vector<double>& y() const { return m_y; }
- double correlation();
-}
-
-
-What is more natural then reusing the std_vector extension module to
-expose these constructors or functions to Python?
-
--Unfortunately, what seems natural needs a little work in both the -std_vector and the statistics module. - -
-In the std_vector extension module, std::vector<double> needs to be -exposed to Python with the x_class_builder<> template instead of the -regular class_builder<>. For example: - -
- x_class_builder<std::vector<double> > v_double(std_vector_module, "double"); -- -In the extension module that wraps class xy we need to use -the import_class_builder<> template: - -
- import_class_builder<std::vector<double> > v_double("std_vector", "double");
-
-
-That is all. All the properties that are defined for std_vector.double
-in the std_vector Boost.Python module will be available for the
-returned objects of xy.x() and xy.y(). Similarly, the constructor for
-xy will accept objects that were created by the std_vector module.
-
--xptr_class_builder<store> py_store(your_module, "store"); -- -The corresponding import_class_builder<> does not need any special -attention: - -
-import_class_builder<store> py_store("noncopyable_export", "store");
-
-
--import std_vector -import statistics -x = std_vector.double([1, 2, 3, 4]) -y = std_vector.double([2, 4, 6, 8]) -xy = statistics.xy(x, y) -xy.correlation() -- -In this example it is clear that Python has to be able to find both the -std_vector and the statistics extension module. In other words, both -extension modules need to be in the Python module search path -(sys.path). - -
-The situation is not always that obvious. Suppose the statistics -module has a random function that returns a vector of random -numbers with a given length: - -
-import statistics -x = statistics.random(5) -y = statistics.random(5) -xy = statistics.xy(x, y) -xy.correlation() -- -A naive user will not easily anticipate that the std_vector module is -used to pass the x and y vectors around. If the std_vector module is in -the Python module search path, this form of ignorance is of no harm. -On the contrary, we are glad that we do not have to bother the user -with details like this. - -
-If the std_vector module is not in the Python module search path, a -Python exception will be raised: - -
-Traceback (innermost last): - File "foo.py", line 2, in ? - x = statistics.random(5) -ImportError: No module named std_vector -- -As is the case with any system of a non-trivial complexity, it is -important that the setup is consistent and complete. - -
-Suppose there is a module ivect that implements vectors of integers, -and a similar module dvect that implements vectors of doubles. We want -to be able do convert an integer vector to a double vector and vice -versa. For example: - -
-import ivect -iv = ivect.ivect((1,2,3,4,5)) -dv = iv.as_dvect() -- -The last expression will implicitly import the dvect module in order to -enable the conversion of the C++ representation of dvect to a Python -object. The analogous is possible for a dvect: - -
-import dvect -dv = dvect.dvect((1,2,3,4,5)) -iv = dv.as_ivect() -- -Now the ivect module is imported implicitly. - -
-Note that the two-way dependencies are possible because the -dependencies are resolved only when needed. This is, the initialization -of the ivect module does not rely on the dvect module, and vice versa. -Only if as_dvect() or as_ivect() is actually invoked will the -corresponding module be implicitly imported. This also means that, for -example, the dvect module does not have to be available at all if -as_dvect() is never used. - -
-If a library is wrapped that consists of both header files and compiled -components (e.g. libdvect.a, dvect.lib, etc.), both the Boost.Python -extension module with the x_class_wrapper<> and the module with the -import_class_wrapper<> need to be linked against the object library. -Ideally one would build a shared library (e.g. libdvect.so, dvect.dll, -etc.). However, this introduces the issue of getting the search path -for the dynamic loading configured correctly. For small libraries it is -therefore often more convenient to ignore the fact that the object -files are loaded into memory more than once. - -
-The main purpose of Boost.Python's support for resolving cross-module -dependencies at runtime is to allow for a modular system layout. With -this support it is straightforward to reflect C++ code organization at -the Python level. Without the cross-module support, a multi-purpose -module like std_vector would be impractical because the entire wrapper -code would somehow have to be duplicated in all extension modules that -use it, making them harder to maintain and harder to build. - -
-Finally, there is an important psychological component. If a group of -classes is lumped together with many others in a huge module, the -authors will have difficulties in being identified with their work. -The situation is much more transparent if the work is represented by -a module with a recognizable name. This is not just a question of -strong egos, but also of getting credit and funding. - -