Setting up embedded Python for Scripting a C++ Game

Boost.Python uses the BOOST_PYTHON_MODULE macro to define a Python module initializer. The resulting function is not the module importer. This difference is similar to that of creating a modthingy.py module and calling import modthingy.

When importing a module, Python will first check if the module is a built-in module. If the module is not there, then Python will then search the module search path trying to find a python file or library based on the module name. If a library is found, then Python expects the library to provide a function that will initialize the module. Once found, the import will create an empty module in the modules table, then initialize it. For statically linked modules, such as modthingy, the module search path will not be helpful, as there is no library for it to find.

For embedding, the module table and initialization function documentation states that for static modules, the module initializer function will not be automatically called unless there is an entry in the initialization table. For Python 2 and Python 3, one can accomplish this by calling PyImport_AppendInittab() before Py_Initialize():

BOOST_PYTHON_MODULE(modthingy)
{
  // ...
}

PyImport_AppendInittab("modthingy", &initmodthingy);
Py_Initialize();
// ...
boost::python::object modthingy = boost::python::import("modthingy");

Alternatively, for Python 2, once the interpreter has been initialized, one can create an empty module that is added to the modules dictionary via PyImport_AddModule(), then explicitly initialize the module.

BOOST_PYTHON_MODULE(modthingy)
{
  // ...
}

Py_Initialize();
PyImport_AddModule("modythingy");
initmodthingy();
boost::python::object modthingy = boost::python::import("modthingy");

This approach is demonstrated in the official Python embedded demo, embed/demo.c. The module initializer created from BOOST_PYTHON_MODULE does not call PyImport_AddModule(), thus it must be explicitly called.

Also note that the Python's C API for embedding changed naming conventions for module initialization functions between Python 2 and 3, so for BOOST_PYTHON_MODULE(modthingy), one may need to use &initmodthingy for Python 2 and &PyInit_modthingy for Python 3.

Here is a minimal complete example demonstrating importing a module statically linked with the embedded interpreter:

#include <iostream>
#include <string>

#include <boost/python.hpp>

std::string spam() { return "Spam spam spam"; }

BOOST_PYTHON_MODULE(example)
{
  namespace python = boost::python;
  python::def("spam", &spam);
}

int main()
{
  // Add example to built-in.
  PyImport_AppendInittab("example", &initexample);

  // Start the interpreter.
  Py_Initialize();

  namespace python = boost::python;
  try
  {
    // >>> import example
    python::object example = python::import("example");
    // >>> x = example.spam()
    python::object x = example.attr("spam")();
    // >>> print x
    std::cout << "x = " << python::extract<std::string>(x)() << std::endl;
  }
  catch (const python::error_already_set&)
  {
    PyErr_Print();
  }
}

Output:

x = Spam spam spam