C++ Boost

Boost.Python

Header <boost/python/module.hpp>


Contents

Introduction
Macros
BOOST_PYTHON_MODULE_INIT
Classes
Class module
Class module synopsis
Class module constructor
Class module modifier functions
Class module observer functions
Example(s)

Introduction

{{Introductory text}}

Macros

BOOST_PYTHON_MODULE_INIT(name) is used to declare Python module initialization functions. The name argument must exactly match the name of the module to be initialized, and must conform to Python's identifier naming rules. Where you would normally write

void initname()
{
   ...
Boost.Python modules should be initialized with
BOOST_PYTHON_MODULE_INIT(name)
{
   ...

Classes

Class module

This class represents the Python extension module under construction. It provides functions for adding attributes and for retrieving the underlying Python module object.

Class module synopsis

namespace boost { namespace python
{
  class module : public module_base
  {
   public:
      module(const char* name);

      // modifier functions
      module& setattr(const char* name, PyObject*);
      module& setattr(const char* name, PyTypeObject*);
      module& setattr(const char* name, ref const&);

      module& add(PyTypeObject* x);
      template <class T, class Bases, class HolderGenerator>
      module& add(class_<T,Bases,HolderGenerator> const& c);

      template <class Fn>
      module& def(char const* name, Fn fn);
      template <class Fn, class ResultHandler>
      module& def(char const* name, Fn fn, ResultHandler handler);

      // observer function
      ref object() const;
  };

}}

Class module constructor

module(const char* name);
Requires: name is a ntbs whose value matches the argument passed to BOOST_PYTHON_MODULE_INIT.
Effects: Creates a module object representing a Python module named name.

Class module modifier functions

module& setattr(const char* name, PyObject* obj);
module& setattr(const char* name, PyTypeObject* obj);
module& setattr(const char* name, ref const& r);
Requires: name is a ntbs which conforms to Python's identifier naming rules. In the first two forms, obj is non-null. In the third form, r.get() is non-null.
Effects: Adds the given Python object to the module. If the object is a product of make_function(), the usual overloading procedure applies. In the first two forms, ownership of a reference to obj is transferred from caller to callee, even if an exception is thrown.
Returns: *this
module& add(PyTypeObject* x);

template <class T, class Bases, class HolderGenerator>
module& add(class_<T,Bases,HolderGenerator> const& c);
Requires: In the first form, x is non-null
Effects: The first form adds the Python type object named by x to the Python module under construction, with the name given by the type's tp_name field. The second form adds the extension class object being constructed by c to the module, with the same name that was passed to c's constructor.
Returns: *this
Rationale: Provides a way to set type attributes in the module without having to explicitly specify the name.
template <class Fn>
module& def(char const* name, Fn f);

template <class Fn, class ResultHandler>
module& def(char const* name, Fn f, ResultHandler handler);
Requires: f is a non-null pointer-to-function or pointer-to-member-function. name is a ntbs which conforms to Python's identifier naming rules. In the first form, the return type of f is not a reference and is not a pointer other than char const* or PyObject*. In the second form policy is a model of CallPolicy.
Effects: Adds the result of make_function(f) to the extension module being defined, with the given name. If the module already has an attribute named name, the usual overloading procedure applies.
Returns: *this

Class module observer functions

ref object() const;
Returns: A ref object which holds a reference to the Python module object created by the module constructor.

Example(s)

C++ module definition:

#include <boost/python/module.hpp>

char const* greet()
{
    return "hello, Boost.Python!";
}

BOOST_PYTHON_MODULE_INIT(boost_greet)
{
    module("boost_greet")
        .def("greet", greet);
}
Interactive Python:
>>> import boost_greet
>>> boost_greet.greet()
'hello, Boost.Python!'

Revised 14 February, 2002

© Copyright Dave Abrahams 2002. All Rights Reserved.