<boost/python/class.hpp> defines the interface
through which users expose their C++ classes to Python. It declares the
- class_ class template, which is parameterized on the class
- type being exposed, and the args and bases
- utility class templates in the anonymous namespace (the latter definitions
- will probably be moved in a future release).
+ class_ class template, which is parameterized on the
+ class type being exposed. It also exposes the args
+ and bases utility class templates, which are used in
+ conjunction with class_.
<boost/python/class_fwd.hpp> contains a forward
declaration of the class_ class template.
-
class_<T, Bases, HolderGenerator>Creates a Python class associated with the C++ type passed as its first
- parameter. Its template arguments are:
+
Creates a Python class associated with the C++ type passed as
+ its first parameter. Although it has four template parameters,
+ only the first one is required. The three optional arguments can
+ actually be supplied in any
+ order; Boost.Python determines the role of the argument
+ from its type.
-
| Parameter + | Template Parameter | Requirements + | Semantics + | Default | |
|---|---|---|---|---|---|
| A class type. - | |||||
Bases
-
- | An MPL sequence of
- C++ base classes of T.
-
- | An unspecified empty sequence + | The class being wrapped | ||
HolderGenerator
+ | Bases
- | A model of HolderGenerator.
+ | A specialization of bases<...> which
+ specifies previously-exposed C++ base classes of T[1].
+
+ | Registers from_python conversions from
+ wrapped T instances to each of its exposed direct
+ and indirect bases. For each polymorphic base B,
+ registers conversions from indirectly-held wrapped
+ B instances to T.
+
+ | bases<>
+
+ |
HeldType
+
+ | Must be T, a class derived
+ from T, or a Dereferenceable type for which
+ pointee<HeldType>::type
+ is T or a class derived from T.
+
+
+ | Specifies the type which is actually embedded in a Python
+ object wrapping a T instance. More details below.
+
+ | T
+
+ | ||
NonCopyable
+
+ | If supplied, must be boost::noncopyable. + + | Suppresses automatic registration of to_python
+ conversions which copy
+ T instances. Required when T has no
+ publicly-accessible copy constructor.
+
+ | An unspecified type other than boost::noncopyable.
- | boost::python::objects::value_holder_generator
|
class_
- synopsisHeldType is derived from T, its
+ exposed constructor(s) must accept an initial
+ PyObject* argument which refers back to the Python
+ object that contains it, as shown in this example. This argument is
+ not included in the argument list type passed to def_init(), below, nor is
+ it passed explicitly by users when Python instances of
+ T are created. This is the idiom which allows C++ virtual
+ functions to be overridden in Python. Boost.Python automatically
+ registers additional converters which allow wrapped instances of
+ T to be passed to wrapped C++ functions expecting
+ HeldType arguments.
+
+T to be passed in place of
+ HeldType arguments, specifying a smart pointer for
+ HeldType allows users to pass Python
+ T instances where a smart pointer-to-T is
+ expected. Smart pointers such as std::auto_ptr<>
+ or boost::shared_ptr<>
+ which contain a nested type element_type designating
+ the referent type are automatically supported; additional smart
+ pointer types can be supported by specializing pointee<HeldType>.
+
+HeldType is a smart pointer to
+ a class derived from T, the initial
+ PyObject* argument must be supplied by all exposed
+ constructors.
+
+PyObject*
+ argument by specializing has_back_referenceclass_ synopsis
namespace boost { namespace python
{
-
template <class T
- , class Bases = none
- , class HolderGenerator = objects::value_holder_generator>
- class class_
+ , class Bases = bases<>
+ , class HeldType = T
+ , class NonCopyable = unspecified
+ >
+ class class_
{
class_();
class_(char const* name);
- template <class F>
- class_& def(char const* name, F f);
+ // exposing constructors
+ class_& def_init();
- template <class Fn, class CallPolicy>
- class_& def(char const* name, Fn fn, CallPolicy policy);
-
template <class Args>
class_& def_init(Args const& = Args());
- class_& def_init();
+ template <class Args, class CallPolicy>
+ self& def_init(Args const&, CallPolicy policy);
+ // exposing member functions
+ template <class F>
+ class_& def(char const* name, F f);
+
+ template <class Fn, class CallPolies>
+ class_& def(char const* name, Fn fn, CallPolies);
+
+ // exposing data members
+ template <class D>
+ self& def_readonly(char const* name, D T::*pm);
+
+ template <class D>
+ self& def_readwrite(char const* name, D T::*pm);
+
+ // property creation
+ void add_property(char const* name, ref const& fget);
+ void add_property(char const* name, ref const& fget, ref const& fset);
+
+ // accessing the Python class object
ref object() const;
};
}}
- class_
- constructorsclass_ constructors-class_() +class_();
-class_(char const* name) +class_(char const* name);
class_
modifier functions+class_& def_init(); + +template <class Args> +class_& def_init(Args const& argument_types); + +template <class Args, class CallPolicies> +class_& def_init(Args const& argument_types, CallPolicies policies); ++ +
Args is an MPL sequence of C++ argument
+ types (A1, A2,... AN) such that if
+ a1, a2... aN are objects of type
+ A1, A2,... AN respectively, the expression
+ T(a1, a2... aN) is valid. In the first form,
+ the expression T() must be valid.
+
+ make_constructor<args<>,Holder>(),
+
+make_constructor<Args,Holder>(), or
+
+make_constructor<Args,Holder>(policies),
+ respectively, to the Boost.Python extension class being defined under the name
+ "__init__". Holder is a model of Holder which contains the
+ HeldType. If the extension class
+ already has an "__init__" attribute, the usual overloading procedure applies.
+
+ *this
+
+ template <class F> -class_& def(char const* name, F f) +class_& def(char const* name, F f); -template <class Fn, class CallPolicy> -class_& def(char const* name, Fn f, CallPolicy policy) +template <class Fn, class CallPolicies> +class_& def(char const* name, Fn f, CallPolicies policies);
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 policies is a model of CallPolicies.
Returns: *this
-template <class Args> -class_& def_init(Args const& argument_types) - -class_& def_init() +void add_property(char const* name, ref const& fget); +void add_property(char const* name, ref const& fget, ref const& fset);-
a1, a2... aN are objects of type
- A1, A2,... AN respectively, the expression
- T(a1, a2... aN) is valid. In the second form,
- the expression T() must be valid.
- make_constructor<T,Args,HolderGenerator>()
- to the Boost.Python extension class being defined with the name
- "__init__". If the 2nd form is used, an unspecified empty MPL sequence type is substituted
- for Args. If the extension class already has an "__init__"
- attribute, the usual overloading
- procedure applies.
+ name is a ntbs which conforms to
+ Python's identifier
+ naming rules.
+
+ property
+ class instance, passing fget.get() (and
+ fset.get() in the second form) to its constructor,
+ then adds that property to the Python class object under
+ construction with the given attribute name.
*this
- + template <class D> + self& def_readonly(char const* name, D T::*pm); ++ +
name is a ntbs which conforms to
+ Python's identifier
+ naming rules.
+
+ +this->add_property(name, ref(make_getter(pm))); ++ +
*this
+
+ +template <class D> +self& def_readwrite(char const* name, D T::*pm); ++ +
+ref fget(make_getter(pm)); +ref fset(make_setter(pm)); +this->add_property(name, fget, fset); ++ +
*this
+
+ class_
observer functions
@@ -264,39 +452,42 @@ ref object() const;
Class template
args<T1, T2,...TN>
- Essentially an alias for boost::mpl::type_list which users
- can use in def_init calls to make their code more readable.
- Currently it is in the global unnammed namespace, but that will probably
- change.
+
A conveniently-named MPL sequence which
+ users pass to def_init calls to make
+ their code more readable.
Class template args
synopsis
-namespace
+namespace boost { namespace python
{
template <T1 = unspecified,...TN = unspecified>
- struct args : ::boost::mpl::type_list<T1,...TN>::type
+ struct args
{};
-}
+}}
Class template
bases<T1, T2,...TN>
- Essentially an alias for boost::mpl::type_list which users
- can use in class_<...> instantiations to
- make their code more readable. Currently it is in the global unnammed
- namespace, but that will probably change.
+
An MPL sequence which
+ can be used in class_<...>
+ instantiations indicate a list of base classes. Although users
+ can pass any MPL sequence in place of args, above, the use of
+ bases to indicate base classes is mandatory.
Class template bases
synopsis
-namespace
+namespace boost { namespace python
{
template <T1 = unspecified,...TN = unspecified>
- struct bases : ::boost::mpl::type_list<T1,...TN>::type
+ struct bases
{};
-}
+}}
Example(s)
@@ -311,24 +502,47 @@ class Foo : public Bar, public Baz
std::string const& name() { return m_name; }
void name(char const*);
+
+ double value; // public data
private:
...
};
- A corresponding Boost.Python extension class can be created with:
+
+ A corresponding Boost.Python extension class can be created with:
using namespace boost::python;
-ref foo =
-class_<Foo,bases<Bar,Baz> >()
+
+ref foo = class_<Foo,bases<Bar,Baz> >()
.def_init(args<int,char const*>())
.def_init(args<double>())
.def("get_name", &Foo::get_name, return_internal_reference<>())
.def("set_name", &Foo::set_name)
+ .def_readwrite("value", &Foo::value)
.object();
+
+B in bases, an instance of
+class_<B> must have already been
+constructed. Ensuring this in a portable manner when a class and its
+bases are exposed in the same module entails using separate
+full-expressions, rather than chaining consecutive definitions with
+".add(...).
+
+
+module m("module_name");
+m.add(class_<Base>()
+ .def_init());
+m.add(class_<Derived, bases<Base>>()
+ .def_init());
+
+
Revised
- 05 November, 2001
+ 09 May, 2002