# Boost.Python - <boost/python/module.hpp>

###

# 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.