Prerequisites

The Boost installation and build process for these libraries are described in more detail in Appendix A.

Project Settings

We can see from Table 8-1 that the project settings are similar to the previous project. In this case, we have not renamed the target output. We leave this for the post-build script (see in the following). In the Additional Include Directories, we reference the location of Python.h and the StatsLib project include directory. In addition, we reference the Boost libraries with $(BOOST_ROOT) macro. Similarly, in the Additional Library Directories, we add a reference to both the Python libs and the Boost libs.

With these settings in place, everything should build without warnings or errors.

Code Organization

The Visual Studio Community Edition 2019–generated project for a Windows dll generates a handful of files that we ignore. We ignore the dllmain.cpp file (which contains the entry point for a standard Windows dll). We also ignore the files framework.h and pch.cpp (except insofar as it includes pch.h, the precompiled header).

The macro indicates that in this dll module, we are statically linking to Boost Python:

oost_1_76_0stageliblibboost_python38-vc142-mt-...-...-1_76.lib

The “...” depend on the specific processor architecture, though in our case we target only x64. The second line brings in all the Boost Python headers. The rest of the code is organized as before into three main areas: the functions (Functions.h/Functions.cpp), the conversion layer (Conversion.h/Conversion.cpp), and the module definition. In addition, for this project, we have a wrapper class StatisticalTests.h/StatisticalTests.cpp that wraps up the t-test functionality. We will deal with each of these areas in turn.

Functions

Inside the API namespace we declare two functions: DescriptiveStatistics and LinearRegression. Both functions take the corresponding boost::python arguments. Boost.Python comes with a set of derived object types corresponding to those of Python’s:

    Python type        Boost type

• list        boost::python::list

• dict        boost::python::dict

• tuple    boost::python::tuple

• str        boost::python::str

This makes converting to STL types quite straightforward, as we shall see. The code inside the functions is also straightforward. We first convert the parameters to types usable by the StatsLib. Then we call the underlying C++ function, collect the results, and translate these back into a form Python understands. The Boost.Python library makes this very straightforward and flexible. Listing 8-1 shows the implementation of the DescriptiveStatistics function.

-

Listing 8-1

The DescriptiveStatistics wrapper function

The DescriptiveStatistics function in Listing 8-1 should look familiar. It follows the same structure as the raw Python example in the previous chapter. The major difference in the function declaration is that instead of PyObject pointers, we can use types defined in the Boost.Python library. In this case, both parameters are passed in as const references to a boost::python::list. The second parameter is defaulted, as we want to be able to call DescriptiveStatistics with or without the keys. The input arguments are converted to a std::vector<double> and a std::vector<std::string>, respectively. These are then used in the call to the underlying statistical library function. The results package is returned as before (a std::unordered_map<std::string, double> type) and converted to a boost::python::dict.

Listing 8-2 shows the code for the LinearRegression function.

-

Listing 8-2

The LinearRegression wrapper function

As can be seen from Listing 8-2, the LinearRegression function follows the same structure as previously. The function takes in two lists, converts them into the corresponding datasets, calls the underlying function, and converts the results package into a Python dictionary.

StatisticalTests

Inside the API namespace, we create a separate namespace StatisticalTests for the three statistical hypothesis test functions. As in the “raw” case, here we have initially chosen to wrap up the usage of the TTest class inside a function. Listing 8-3 shows the summary data t-test function.

-

Listing 8-3

Wrapping up the TTest class in a function

As shown in Listing 8-3, the approach of providing a procedural wrapper for a class is straightforward: we get the input data and create an instance of the TTest class (depending on the function call and the arguments). We then call Perform to do the calculation and Results to retrieve the results. These are then translated back to the Python caller. The SummaryDataTTest function in this example takes four parameters corresponding to the constructor arguments of the summary data t-test. The arguments are typed as const references to a boost::python::object. This provides a wrapper around PyObject. The function then makes use of boost::python::extract<T>(val) to get a double value out of the argument. In general, the syntax is cleaner and more direct than using PyArg_ParseTuple. The remainder of the function calls Perform and retrieves the Results. As in the previous case of DescriptiveStatistics and LinearRegression, these are converted to a boost::python::dict and returned to the caller.

The Conversion Layer

Listing 8-4 starts by constructing an empty std::vector. Then, we iterate over the input list extracting the individual values and inserting them into the vector. We use this basic approach to illustrate accessing list elements in a standard manner. We could have used the boost::python::stl_input_iterator<T> to construct the results vector<T> directly from iterators. We use this function to convert a list of doubles to a vector of doubles and also to convert a list of string keys to a vector of strings.

In this case, we input a const reference to a std::unordered_map<std::string, double> and return the contents into a boost::python::dict by simply iterating over the results. The final function is to_list. This is similar to the previous to_dict function. In this case, we create a Python list and populate it from a vector of doubles.

The Module Definition

In order to do this, we need two separate overloaded functions. This is the same approach that we used in the C++/CLI wrapper in Chapter 3. In this case, however, we do not need to explicitly write the overloads. We make use of the macro BOOST_PYTHON_FUNCTION_OVERLOADS to generate the overloads for us. The arguments are the generator name, the function we want to overload, the minimum number of parameters (1 in this case), and the maximum number of parameters (2 in this case). Having defined this, we then pass the f_overloads structure , along with the docstring, to the def function.

The C++ wrapper class for the t-test is defined in StatisticalTests.h. The class template argument references our wrapper class. In this case, we have named it StudentTTest to distinguish it from the underlying Stats::TTest class. This class holds an instance of the underlying Stats::TTest class. The constructors determine the type of t-test to be performed and convert between boost::python types and the underlying C++ types, using the same conversions that we have seen.

From the module definition in Listing 8-6b, we can see that the first parameter is the name of the class, "TTest". This is the name for the type we will call from Python. Alongside this, we define an init function (the constructor) which takes four arguments. We then define two additional init functions, one each for the remaining constructors with their corresponding arguments. Finally, we define the two functions Perform and Results. All the functions provide a docstring. That is all we need to do to expose a native C++ type to Python.

The items contain the dataset name and the number of observations in the data. The function first obtains the currently loaded datasets from the m_manager member that this class wraps. Inside the for-loop, we use the function boost::python::make_tuple to create a Python tuple element with the dataset information. This is then appended to the results list and returned to the caller. The remaining functions are similarly straightforward.

Exception Handling

This is the error that is thrown from the underlying StatsLib. Basically, the same error handling that we wrote in the previous chapter is now provided for free.

Prerequisites

The only prerequisite for this section is to install PyBind into your Python environment. You can use either pip install pybind from a command prompt. Or you can download the wheel (https://pypi.org/project/pybind11/#files) and run pip install "pybind11-2.7.0-py2.py3-none-any.whl".

Project Settings

Additionally, we have removed the pch file and set the project setting to not using precompiled headers. Finally, we have added a reference to the StatsLib project in the project References. At this point, everything should build without warnings or errors.

Code Organization: module.cpp

In this project, there is only a single file, module.cpp. This file contains all the code. As we have seen in the previous section on Boost.Python and in the previous chapter as well, we have generally separated the conversion layer from the wrapped functions and classes. And we have separated these from the module definition. This was a convenient way to organize the code in the wrapper layer and allowed us to separate concerns (like converting types or calling functions) appropriately. However, PyBind simplifies both these aspects.

This is followed by our StatsLib includes.

The PYBIND11_MODULE macro defines the module name StatsPythonPyBind that is used by Python in the import statement. Inside the module definition, we can see the declarations of the DescriptiveStatistics and LinearRegression functions. The .def(...) function is used to define an exported function. Just as before, we give it a name that is called from Python and the final parameter which is a docstring.

What is important here is not how the function wraps the TTest class, but rather the fact that the wrapper function uses native C++ and STL types both for the function parameters and the return value. Using Boost.Python, we would have had to convert from/to boost::python::object. But here we no longer need to convert from Python types to C++ types. Of course, we can, if we wish, explicitly wrap functions. This is a design choice.

Listing 8-8b shows how the TTest class from the underlying C++ StatsLib is exposed to Python. As in the case of Boost.Python, we describe the type “TTest” that we want to use. But, in this case, the template argument to the py::class_ object is the underlying Stats::TTest class. The class that is referenced is not a wrapper class, as was the case with Boost.Python. After the template arguments and the parameters passed to the constructor of py::class_, we use the .def function to describe the structure of the class. In this case, we declare the three TTest constructors with their respective arguments passed as template parameters to the py::init<> function. Again, it is worth highlighting that we do not need to do any conversions; we simply pass in native C++ types and STL types (rather than boost::python::object types). Finally, we declare the functions Perform and Results, and an anonymous function to return a string representation of the object to Python.

As we can see from Listing 8-8c, all we need to do in the .def function is to provide a mapping from the function names used by Python to the underlying C++ functions. Apart from the functions that are available in the DataManager class, we also have access to functions that form part of the definition of the Python class. For example, the DataManager extends the __repr__ function with a custom to_string function that outputs internal information regarding the dataset.

As we can see in this project, both the wrapper and the “conversion” layer are minimal. PyBind provides a wide range of facilities, allowing us to easily connect C++ code to Python. In this chapter, we have only just scratched the surface. There are a large number of features and we have only covered a fraction of them. Moreover, we are aware that we have really only written code for the most “vanilla” situations (taking advantage of the fact that PyBind allows us to do this easily).

However, while using PyBind makes exposing C++ classes and functions straightforward, we need to be aware that there is a lot going on under the hood. In particular, we need to be aware of the return value policies that can be passed to the module_::def() and the class_::def() functions. These annotations allow us to tune the memory management for functions that return a non-trivial type. In this project, we have only used the default policy return_value_policy::automatic. A full discussion of this topic is beyond the scope of this chapter. But, as the documentation points out, return value policies are tricky, and it’s important to get them right.¹

If we take a step back for a moment, we can see that in terms of the module definition, both Boost.Python and PyBind provide us with a meta-language for defining Python entities. It might seem a complicated way to go. Arguably, writing equivalent classes in native Python is somewhat easier than using a meta-language to describe C++ classes. However, the approach we have adopted here, describing native C++ classes, clearly addresses a different issue, that is, it provides a (relatively) easy way to export classes out of C++ and have them managed in an expected way in a Python environment.

Listing 8-9 shows the output from the StatsPythonPyBind module using the built-in help() function. We can see that it provides a description of the class methods and the class initialization along with the docstrings that we provided. It also provides detailed information both about the argument types used and the return types. We can see quite clearly how the declarative C++ class description has been translated into a Python entity. The output from StatsPythonBoost is similar, though not identical, and worthwhile comparing. As an alternative to the help function, we can use the inspect module to introspect on our Python extension. The inspect module provides additional useful functions to help get information about objects. This can be useful if you need to display a detailed traceback. As expected, we can retrieve all the information from our module except, of course, the source code. What both these approaches serve to illustrate is that, with a limited amount of C++ code, we have developed a proper Python object.

Exception Handling

The exception handling provides sufficient information to determine the cause of the issue and processing can proceed appropriately. It is worth pointing out that PyBind’s exception handling capabilities go beyond simple translation of C++ exceptions. PyBind provides support for several specific Python exceptions. It also supports registering custom exception handlers. The details are covered in the PyBind documentation.

Performance

One of the reasons for trying to connect C++ and Python is the potential for performance gains from C++ code. To this end, we have written a small script, PerformanceTest.py. We want to test the performance of the mean and (sample) standard deviation functions. We would like to do this for Python vs. PyBind computing Mean and StdDev for 500k items.

From the Python side we have two approaches. Firstly, we define the functions mean, variance, and stddev. The implementations of these only use basic Python functionality. We also define the same functions, this time using the Python statistics library. This allows us to have two different baselines.

In Listing 8-11, we add the function "Mean", supply the address of the C++ implementation, and add the documentation string.

The StandardDeviation function is slightly more involved. The underlying C++ function takes two parameters, a std::vector<double> and an enumeration for the VarianceType . If we just pass the function address to the module definition, we will get a runtime error from Python as the function expects two arguments. To address this, we need to extend the code. At this point we have a choice. We can either write a small wrapper function that provides a hardcoded VarianceType argument or we can expose the VarianceType enumeration. We’ll look at both approaches.

In Listing 8-13, we use the name “StdDevS” to reflect the fact that we are requesting the sample standard deviation. Now we can use this function in our performance test.

With these modifications in place, we can return to the performance test. The PerformanceTest.py script is straightforward. We import the required libraries, including StatsPythonPyBind. We define two versions of both mean and stddev in Python. One version doesn’t use the statistics library and the second version does. This just facilitates the comparison between Python functions and our library functions. We add a simple test function that uses random data and returns the mean and stddev with timing information.

The Python function mean(x) is about two orders of magnitude faster than the native C++ function. Changing the C++ code to use a for-loop instead of std::accumulate made no significant difference. It might be interesting to investigate if the latency in the C++ side is due to the conversion layer or simply unnecessary copying of vectors. Nevertheless, the native C++ StdDev function is substantially faster than either of the Python variants.

The Statistics Service

In the StatsPython project , there is a script StatsService.py that launches a small Flask app. The Flask app is a simple demonstration of a web service. It is extremely limited and only allows the user to compute a summary data t-test. The main page is shown in Figure 8-1.

The main page consists of a simple form that allows the user to input the parameters of a summary data t-test. After pressing the Submit button, we compute the required values and return them, as shown in Figure 8-2.

This starts the Flask service on port 5000. In your browser address bar, go to http://localhost:5000/. This points to the Summary Data T-Test page which is the main page for this app. Fill in the required details and press submit. The results are returned as expected, using the underlying TTest class from the StatsPythonPyBind module.

Apart from the small amount of code required to get this up and running, what is worth emphasizing is what we have achieved in terms of a multi-language development infrastructure. We have got an infrastructure that allows us to develop and adapt native C++ code, build this into a library, incorporate the library into a Python module, and have this functionality available for use in a Python web service. This flexibility is valuable when developing software systems.

Additional Resources