ceph/src/boost/libs/python/doc/reference/module.qbk

   1 [section boost/python/module.hpp]
   2 [section Introduction]
   3 This header provides the basic facilities needed to create a Boost.Python extension module.
   4 [endsect]
   5 [section Macros]
   6 `BOOST_PYTHON_MODULE(name)` is used to declare Python [@http://www.python.org/doc/2.2/ext/methodTable.html#SECTION003400000000000000000 module initialization functions]. The name argument must exactly match the name of the module to be initialized, and must conform to Python's [@http://www.python.org/doc/2.2/ref/identifiers.html identifier naming rules]. Where you would normally write
   7
   8 ``
   9 extern "C" void initname()
  10 {
  11    ...
  12 }
  13 ``
  14 Boost.Python modules should be initialized with
  15 ``
  16 BOOST_PYTHON_MODULE(name)
  17 {
  18    ...
  19 }
  20 ``
  21 This macro generates two functions in the scope where it is used: `extern "C" void initname()`, and `void init_module_name()`, whose body must follow the macro invocation. `init_name` passes `init_module_name` to [link high_level_components.boost_python_errors_hpp.functions handle_exception()] so that any C++ exceptions generated are safely processeed. During the body of `init_name`, the [link high_level_components.boost_python_scope_hpp current scope] refers to the module being initialized.
  22 [endsect]
  23 [section Examples]
  24 C++ module definition:
  25 ``
  26 #include <boost/python/module.hpp>
  27
  28 BOOST_PYTHON_MODULE(xxx)
  29 {
  30     throw "something bad happened"
  31 }
  32 ``
  33 Interactive Python:
  34 ``
  35 >>> import xxx
  36 Traceback (most recent call last):
  37   File "", line 1, in ?
  38 RuntimeError: Unidentifiable C++ Exception
  39 ``
  40 [endsect]
  41 [endsect]