diff --git a/doc/v2/CallPolicies.html b/doc/v2/CallPolicies.html index 3c2b98fd..9d582e7d 100644 --- a/doc/v2/CallPolicies.html +++ b/doc/v2/CallPolicies.html @@ -1,124 +1,152 @@ + + - - - -Boost.Python - CallPolicies Concept - - - + + + + + Boost.Python - CallPolicies Concept + + + +
- - - - -
-

C++ Boost

- 		-

Boost.Python

-

CallPolicies Concept

-
-
-
-
Introduction
-
CallPolicies Composition
-
Concept Requirements
-
-
CallPolicies Concept
-
-
+ + +

C++ Boost

+ -

Introduction

+ +

Boost.Python

-

Models of the CallPolicies concept are used to specialize the -behavior of Python callable objects generated by Boost.Python to -wrapped C++ objects like function and member function -pointers, providing three behaviors: -

    -
  1. precall - Python argument tuple management before -the wrapped object is invoked -
  2. result_converter - C++ return value handling -
  3. postcall - Python argument tuple and result -management after the wrapped object is invoked -
+

CallPolicies Concept

+ + + +
-

CallPolicies Composition

+
+
Introduction
-In order to allow the use of multiple models of CallPolicies in the -same callable object, Boost.Python's CallPolicies class templates -provide a chaining interface which allows them to be recursively -composed. This interface takes the form of an optional template -parameter, Base which defaults to -default_call_policies. By convention, the -precall function of the -Base is invoked after the precall -function supplied by the outer template, and the postcall -function of the Base is invoked before the -postcall function of the outer template. If a -result_converter is supplied by the outer template, it -replaces any result_converter supplied by the -Base. For an example, see -return_internal_reference. +
CallPolicies Composition
-

Concept Requirements

-

CallPolicies Concept

+
Concept Requirements
-

In the table below, x denotes an object whose -type P is a model of CallPolicies, -a denotes a PyObject* pointing to -a Python argument tuple object, and r denotes a -PyObject* referring to a "preliminary" result -object. +

+
+
CallPolicies Concept
+
+
+
- +

Introduction

- - - - - +

Models of the CallPolicies concept are used to specialize the behavior + of Python callable objects generated by Boost.Python to wrapped C++ + objects like function and member function pointers, providing three + behaviors:

- - - - - - -
ExpressionTypeResult/Semantics
x.precall(a)convertible to bool - returns false and PyErr_Occurred() != 0 - upon failure, true otherwise. +
    +
  1. precall - Python argument tuple management before the + wrapped object is invoked
    2. -
P::result_converterA model of ResultConverterGenerator. - An MPL unarymetafunction object used produce the - "preliminary" result object. +
  • result_converter - C++ return value handling
    • -
    x.postcall(a, r)convertible to PyObject* - 0 0 and PyErr_Occurred() != 0 - upon failure. Must "conserve references" even in the - event of an exception. In other words, if r is not - returned, its reference count must be decremented; if another - existing object is returned, its reference count must be - incremented. -
    +
  • postcall - Python argument tuple and result management + after the wrapped object is invoked
    • + -Models of CallPolicies are required to be CopyConstructible. +

    CallPolicies Composition

    + In order to allow the use of multiple models of CallPolicies in the same + callable object, Boost.Python's CallPolicies class templates provide a + chaining interface which allows them to be recursively composed. This + interface takes the form of an optional template parameter, + Base which defaults to default_call_policies. + By convention, the precall function of the Base + is invoked after the precall function supplied by the + outer template, and the postcall function of the + Base is invoked before the postcall + function of the outer template. If a result_converter is + supplied by the outer template, it replaces any + result_converter supplied by the Base. For an + example, see return_internal_reference. + -
    -

    Revised - - 19 May, 2002 - -

    -

    © Copyright Dave - Abrahams 2002. All Rights Reserved. +

    Concept Requirements

    -

    Permission to copy, use, modify, sell - and distribute this software is granted provided this copyright notice appears - in all copies. This software is provided "as is" without express or implied - warranty, and with no claim as to its suitability for any purpose. - +

    CallPolicies Concept

    + +

    In the table below, x denotes an object whose type + P is a model of CallPolicies, a + denotes a PyObject* pointing to a Python argument tuple + object, and r denotes a PyObject* + referring to a "preliminary" result object.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ExpressionTypeResult/Semantics
    x.precall(a)convertible to boolreturns false and PyErr_Occurred() != 0 + upon failure, true otherwise.
    P::result_converterA model of ResultConverterGenerator.An MPL unary Metafunction + Class used produce the "preliminary" result object.
    x.postcall(a, r)convertible to PyObject*0 0 and PyErr_Occurred() != 0 + upon failure. Must "conserve references" even in the event of an + exception. In other words, if r is not returned, its + reference count must be decremented; if another existing object is + returned, its reference count must be incremented.
    + Models of CallPolicies are required to be CopyConstructible. +
    + +

    Revised + + 19 May, 2002 +

    + +

    © Copyright Dave Abrahams 2002. All Rights + Reserved.

    + +

    Permission to copy, use, modify, sell and distribute this software is + granted provided this copyright notice appears in all copies. This + software is provided "as is" without express or implied warranty, and + with no claim as to its suitability for any purpose.

    + + diff --git a/doc/v2/call_method.html b/doc/v2/call_method.html index f2c52a9b..3aae0e35 100644 --- a/doc/v2/call_method.html +++ b/doc/v2/call_method.html @@ -1,74 +1,89 @@ + + - - - -Boost.Python - <call_method.hpp> - - - + + + + + Boost.Python - <call_method.hpp> + + + +
    - - - - -
    -

    -

    -     		-

    Boost.Python

    -

    Header <call_method.hpp>

    -
    -
    -

    Contents

    -
    -
    Introduction
    -
    Functions
    -
    -
    call_method
    -
    + + +

    C++ Boost

    + -
    Example(s)
    + +

    Boost.Python

    -
    -
    -

    Introduction

    -

    - <boost/python/call_method.hpp> defines the call_method family of overloaded function - templates, used to invoke callable attributes of Python objects from C++. +

    Header <call_method.hpp>

    + + + +
    -

    Functions

    +

    Contents

    + +
    +
    Introduction
    + +
    Functions
    + +
    +
    +
    call_method
    +
    +
    + +
    Example(s)
    +
    +
    + +

    Introduction

    + +

    <boost/python/call_method.hpp> defines the call_method family of overloaded + function templates, used to invoke callable attributes of Python objects + from C++.

    + +

    Functions

    -template <class R, class A1, class A2, ... class An>
+template <class R, class A1, class A2, ... class An>
 R call_method(PyObject* self, char const* method, A1 const&, A2 const&, ... An const&)
    -
    -
    Requires: R is a pointer type, reference - type, or a complete type with an accessible copy constructor
    -
    Effects: Invokes self.method(a1, a2, ...an) in - Python, where a1...an are the arguments to - call_method(), converted to Python objects. For a - complete semantic description, see this - page. +
    +
    Requires: R is a pointer type, reference type, + or a complete type with an accessible copy constructor
    -
    Returns: The result of the Python call, converted to the - C++ type R.
    +
    Effects: Invokes + self.method(a1, a2, ...an) in + Python, where a1...an are the + arguments to call_method(), converted to Python objects. + For a complete semantic description, see this + page.
    -
    -
    Rationale: call_method is critical to - implementing C++ virtual functions which are overridable in Python, - as shown by the example below. -
    -
    +
    Returns: The result of the Python call, converted to the C++ + type R.
    -

    Example(s)

    +
    Rationale: call_method is critical to + implementing C++ virtual functions which are overridable in Python, as + shown by the example below.
    + -The following C++ illustrates the use of call_method in -wrapping a class with a virtual function that can be overridden in -Python: +

    Example(s)

    + The following C++ illustrates the use of call_method in + wrapping a class with a virtual function that can be overridden in + Python: -

    C++ Module Definition

    +

    C++ Module Definition

     #include <boost/python/module.hpp>
 #include <boost/python/class.hpp>
@@ -79,13 +94,13 @@ Python:
 class Base
 {
  public:
-   virtual char const* class_name() const { return "Base"; }
+   virtual char const* class_name() const { return "Base"; }
    virtual ~Base();
 };
 
 bool is_base(Base* b)
 {
-   return !std::strcmp(b->class_name(), "Base");
+   return !std::strcmp(b->class_name(), "Base");
 }
 
 // Wrapper code begins here
@@ -97,26 +112,25 @@ class Base_callback : public Base
  public:
    Base_callback(PyObject* self) : m_self(self) {}
 
-   char const* class_name() const { return call_method(m_self, "class_name"); }
+   char const* class_name() const { return call_method(m_self, "class_name"); }
    char const* Base_name() const { return Base::class_name(); }
  private:
-   PyObject* m_self;
+   PyObject* const m_self;
 };
 
 using namespace boost::python;
 BOOST_PYTHON_MODULE_INIT(my_module)
 {
-   module("my_module")
-      .def("is_base", is_base)
-      .add(
-         class_<Base,Base_callback, noncopyable>("Base")
-             .def("class_name", Base_callback::Base_name);
-         )
-       ;
+    def("is_base", is_base)
+
+    class_<Base,Base_callback, noncopyable>("Base")
+        .def("class_name", &Base_callback::Base_name)
+        ;
+
 }
    -

    Python Code

    +

    Python Code

     >>> from my_module import *
 >>> class Derived(Base):
@@ -130,12 +144,15 @@ BOOST_PYTHON_MODULE_INIT(my_module)
 >>> is_base(Derived())
 0
    -

    Revised - - 10 May, 2002 - -

    -

    © Copyright Dave Abrahams - 2002. All Rights Reserved.

    - + +

    Revised + + 28 Sept, 2002 +

    + +

    © Copyright Dave Abrahams 2002. All Rights + Reserved.

    + + diff --git a/doc/v2/class.html b/doc/v2/class.html index 0496d2ca..240a1364 100644 --- a/doc/v2/class.html +++ b/doc/v2/class.html @@ -1,70 +1,108 @@ - + + + + Boost.Python - <boost/python/class.hpp>, <boost/python/class_fwd.hpp> + + +
    -

    -

    +

    C++ Boost

    +

    Boost.Python

    Headers <boost/python/class.hpp>, <boost/python/class_fwd.hpp>

    +

    Contents

    -
    Introduction +
    Introduction
    -
    Classes +
    Classes
    -
    Class template class_ +
    Class template + class_
    Class class_ - synopsis + synopsis
    Class class_ - constructors + constructors
    Class class_ - modifier functions - -
    Class class_ - observer functions + modifier functions
    +
    -
    Class template bases +
    Class template + bases
    -
    Class bases - synopsis +
    Class template + bases synopsis
    +
    -
    Class template args +
    Class template init
    -
    Class args - synopsis +
    Class template + init synopsis
    + +
    Class init + constructors
    + +
    init-expressions
    +
    + +
    Class template + optional
    + +
    +
    +
    Class template + optional synopsis
    +
    +
    + +
    Class template + init_with_call_policies
    + +
    +
    +
    Class + template init_with_call_policies synopsis
    +
    +
    +
    -
    Example(s) +
    Example(s)
    @@ -72,168 +110,181 @@

    <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. It also exposes the args - and bases utility class templates, which are used in - conjunction with class_. + class_ class template, which is parameterized on the class + type being exposed. It also exposes the init, + optional 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. + declaration of the class_ class template.

    -

    Classes

    +

    Classes

    -

    Class template class_<T, Bases, HeldType, NonCopyable>

    +

    Class template + class_<T, Bases, HeldType, + NonCopyable>

    -

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

    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.

    +

    - - - - + - - - + - - - - + - - - - + - - - + +
    Template Parameter + Template ParameterRequirements + RequirementsSemantics + SemanticsDefault + Default
    T + TA class type. + A class type.The class being wrapped + The class being wrapped
    Bases + BasesA specialization of bases<...> which - specifies previously-exposed C++ base classes of T[1]. + 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. + 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<> + bases<>
    HeldType + HeldTypeMust be T, a class derived - from T, or a Dereferenceable type for which - pointee<HeldType>::type - is T or a class derived from T. - + 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. + Specifies the type which is actually embedded in a Python object + wrapping a T instance. More details below.T + T
    NonCopyable + NonCopyableIf supplied, must be boost::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. + 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.
    -

    HeldType Semantics

    +

    HeldType Semantics

    -
      -
    1. - If HeldType 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. +
        +
      1. If HeldType is derived from T, its exposed + constructor(s) must accept an initial PyObject* argument + which refers back to the Python object that contains the + HeldType instance, as shown in this example. This argument is not + included in the init-expression passed to def(init_expr), below, nor is + it passed explicitly by users when Python instances of T + are created. This idiom allows C++ virtual functions which will be + overridden in Python to access the Python object so the Python method + can be invoked. Boost.Python automatically registers additional + converters which allow wrapped instances of T to be passed + to wrapped C++ functions expecting HeldType + arguments.
        2. -
      2. Because Boost.Python will always allow - wrapped instances of 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>. +
      3. Because Boost.Python will always allow wrapped instances of + 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>.
        4. -
      4. - As in case 1 above, when HeldType is a smart pointer to - a class derived from T, the initial - PyObject* argument must be supplied by all exposed - constructors. +
      5. As in case 1 above, when HeldType is a smart pointer + to a class derived from T, the initial + PyObject* argument must be supplied by all of + HeldType's exposed constructors.
        6. -
      6. - Except in cases 1 and 3, users may optionally specify that T itself - gets initialized with a similar initial PyObject* - argument by specializing has_back_reference. -
      +
    2. Except in cases 1 and 3, users may optionally specify that T itself + gets initialized with a similar initial PyObject* argument + by specializing has_back_reference<T>.
      3. +
    -

    Class template - class_ synopsis

    +

    Class template class_ + synopsis

     namespace boost { namespace python
 {
   template <class T
-            , class Bases = bases<>
+           , class Bases = bases<>
             , class HeldType = T
             , class NonCopyable = unspecified
            >
-  class class_
+  class class_ : public object
   {
-    class_();
+    // Constructors with default __init__
     class_(char const* name);
+    class_(char const* name, char const* docstring);
 
-    // exposing constructors
-    class_& def_init();
+    // Constructors, specifying non-default __init__
+    template <class Init>
+    class_(char const* name, Init);
+    template <class Init>
+    class_(char const* name, char const* docstring, Init);
 
-    template <class Args>
-    class_& def_init(Args const& = Args());
+    // Exposing additional __init__ functions
+    template <class Init>
+    class_& def(Init);
 
-    template <class Args, class CallPolicy>
-    class_& def_init(Args const&, CallPolicy policy);
-
-    // exposing member functions
+    // defining methods
     template <class F>
     class_& def(char const* name, F f);
-
-    template <class Fn, class CallPolies>
-    class_& def(char const* name, Fn fn, CallPolies);
+    template <class Fn, class A1>
+    class_& def(char const* name, Fn fn, A1 const&);
+    template <class Fn, class A1, class A2>
+    class_& def(char const* name, Fn fn, A1 const&, A2 const&);
+    template <class Fn, class A1, class A2, class A3>
+    class_& def(char const* name, Fn fn, A1 const&, A2 const&, A3 const&);
 
     // exposing operators
     template <unspecified>
-    class_& def(detail::operator_<unspecified>);
+    class_& def(detail::operator_<unspecified>);
+
+    // Raw attribute modification
+    template <class U>
+    class_& setattr(char const* name, U const&);
 
     // exposing data members
     template <class D>
@@ -242,287 +293,505 @@ namespace boost { namespace python
     template <class D>
     class_& def_readwrite(char const* name, D T::*pm);
 
-    // Raw attribute modification
-    class_& setattr(char const* name, ref const&);
-
     // property creation
-    void add_property(char const* name, ref const& fget);
-    void add_property(char const* name, ref const& fget, ref const& fset);
+    template <class Get>
+    void add_property(char const* name, Get const& fget);
+    template <class Get, class Set>
+    void add_property(char const* name, Get const& fget, Set const& fset);
 
-    // accessing the Python class object
-    ref object() const;
+    // pickle support
+    void enable_pickling(bool getstate_manages_dict);
+    template <typename PickleSuite>
+    self& def_pickle(PickleSuite const&);
   };
 }}
    -

    Class template class_ constructors

    - -
    -class_();
-
    - -
    -
    Requires: The platform's std::type_info::name() - implementation produces a string which corresponds to the type's - declaration in C++ - -
    Effects: Constructs a class_ object which - generates a Boost.Python extension class with the same name as - T. - -
    Rationale: Many platforms can generate reasonable names for - Python classes without user intervention. -
    +

    Class template class_ + constructors

     class_(char const* name);
+class_(char const* name, char const* docstring);
+template <class Init>
+class_(char const* name, Init init_spec);
+template <class Init>
+class_(char const* name, char const* docstring, Init init_spec);
    -
    Requires: name is a ntbs which conforms to - Python's identifier - naming rules. +
    Requires: name is a ntbs which conforms to Python's identifier + naming rules. If docstring is supplied, it must be an + ntbs. If init_spec is + supplied, it must be either the special enumeration constant + no_init or an init-expression compatible with + T.
    -
    Effects: Constructs a class_ object which - generates a Boost.Python extension class named name. +
    Effects: Constructs a class_ object holding a + Boost.Python extension class named name. The + named attribute of the current scope is bound to the new + extension class.
    -
    Rationale: Gives the user full control over class naming. +
    + +
    + +
    Rationale:Allowing the user to specify constructor arguments + in the class_<> constructor helps her to avoid the + common run-time errors which result from invoking wrapped member + functions without having exposed an __init__ function + which creates the requisite T instance. Types which are + not default-constructible will cause a compile-time error unless + Init is supplied. The user must always supply + name as there is currently no portable method to derive + the text of the class name from its type.
    -

    Class template class_ - modifier functions

    - +

    Class template + 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);
+template <class Init>
+class_& def(Init init_expr);
    -
    Requires: 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. +
    Requires: init_expr is the result of an init-expression compatible with + T.
    -
    Effects: Adds the result of +
    Effects: For each valid + prefix P of Init, adds an + __init__(...) function overload to the + extension class accepting P as arguments. Each overload + generated constructs an object of HeldType according to + the semantics described above, using a copy of + init_expr's call policies. + If the longest valid prefix of Init contains N + types and init_expr holds M keywords, an initial + sequence of the keywords are used for all but the first + N - M arguments of each overload.
    -make_constructor<args<>,Holder>(), +
    Returns: *this
    -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 concrete subclass of instance_holder - which holds the HeldType. If the extension class - already has an "__init__" attribute, the usual overloading procedure applies. - -
    Returns: *this - -
    Rationale: Allows users to easily expose a class' constructor - to Python. +
    Rationale: Allows users to easily expose a class' + constructor to Python.
    - -
    - +
    + 
     template <class F>
-class_& def(char const* name, F f);
-
-template <class Fn, class CallPolicies>
-class_& def(char const* name, Fn f, CallPolicies policies);
+class_& def(char const* name, Fn fn);
+template <class Fn, class A1>
+class_& def(char const* name, Fn fn, A1 const& a1);
+template <class Fn, class A1, class A2>
+class_& def(char const* name, Fn fn, A1 const& a1, A2 const& a2);
+template <class Fn, class A1, class A2, class A3>
+class_& def(char const* name, Fn fn, A1 const& a1, A2 const& a2, A3 const& a3);
    -
    Requires: f is a non-null - pointer-to-function or pointer-to-member-function, or a callable - Python object passed as a PyObject* or ref. 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 policies is a model of CallPolicies. +
    Requires: name is a ntbs which conforms to Python's identifier + naming rules.
    -
    Effects: Adds the result of make_function(f) or make_function(f, policies) to - the Boost.Python extension class being defined, with the given - name. If the extension class already has an attribute named - name, the usual overloading procedure applies. +
    + +
    + +
    Returns: *this
    - 
     template <unspecified>
-class_& def(detail::operator_<unspecified>);
+class_& def(detail::operator_<unspecified>);
    -
    Effects: Adds a Python special - method as described here. +
    Effects: Adds a Python special method as + described here.
    -
    Returns: *this +
    Returns: *this
    - 
    -template <class F>
-class_& setattr(char const* name, ref x);
+template <class U>
+class_& setattr(char const* name, U const& u);
    Requires: name is a ntbs which conforms to Python's identifier - naming rules. + "http://www.python.org/doc/current/ref/identifiers.html">identifier + naming rules.
    -
    Effects: PyObject_SetAttrString(this->object(), name, x.get()); +
    Effects: Converts u to Python and adds it to the attribute + dictionary of the extension class:
    -
    Returns: *this +
    +
    + PyObject_SetAttrString(this->ptr(), name, object(u).ptr()); +
    +
    + +
    Returns: *this
    - -
    - +
    + 
    -void add_property(char const* name, ref const& fget);
-void add_property(char const* name, ref const& fget, ref const& fset);
-
    -
    - -
    Requires: name is a ntbs which conforms to - Python's identifier - naming rules. - -
    Effects: Creates a new Python 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. - -
    Returns: *this - -
    Rationale: Allows users to easily expose a class' - data member such that it can be inspected from Python with a - natural syntax. -
    - -
    -
    -    template <class D>
-    class_& def_readonly(char const* name, D T::*pm);
+template <class Get>
+void add_property(char const* name, Get const& fget);
+template <class Get, class Set>
+void add_property(char const* name, Get const& fget, Set const& fset);
    -
    Requires: name is a ntbs which conforms to Python's identifier - naming rules. + "http://www.python.org/doc/current/ref/identifiers.html">identifier + naming rules.
    -
    Effects: +
    Effects: Creates a new Python property + class instance, passing object(fget) (and object(fset) in the + second form) to its constructor, then adds that property to the Python + class object under construction with the given attribute + name.
    + +
    Returns: *this
    + +
    Rationale: Allows users to easily expose functions that can + be invoked from Python with attribute access syntax.
    +
    + 
    -this->add_property(name, ref(make_getter(pm)));
+template <class D>
+class_& def_readonly(char const* name, D T::*pm);
    -
    Returns: *this +
    +
    Requires: name is a ntbs which conforms to + Python's identifier + naming rules.
    -
    Rationale: Allows users to easily expose a class' - data member such that it can be inspected from Python with a - natural syntax. +
    Effects:
    + +
    +
    +this->add_property(name, make_getter(pm));
+
    +
    + +
    Returns: *this
    + +
    Rationale: Allows users to easily expose a class' data + member such that it can be inspected from Python with a natural + syntax.
    - -
    - 
     template <class D>
 class_& def_readwrite(char const* name, D T::*pm);
    +
    Effects:
    -
    Effects: + 
    -ref fget(make_getter(pm));
-ref fset(make_setter(pm));
-this->add_property(name, fget, fset);
+this->add_property(name, make_getter(pm), make_setter(pm));
    +
    -
    Returns: *this +
    Returns: *this
    -
    Rationale: Allows users to easily expose a class' - data member such that it can be inspected and set from Python with a - natural syntax. - -

    Class template class_ - observer functions

    +
    Rationale: Allows users to easily expose a class' data + member such that it can be inspected and set from Python with a natural + syntax.
    + 
    -ref object() const;
+void enable_pickling(bool getstate_manages_dict);
    -
    Returns: A ref object which holds a reference to - the Boost.Python extension class object created by the - class_ constructor. +
    Requires: {{Ralf}}
    -
    Rationale: Mostly not needed by users, since module::add() uses this to insert the - extension class in the module. +
    Effects: {{Ralf}}
    + +
    Rationale: Allows users to easily expose functions that can + be invoked from Python with attribute access syntax.
    +
    +template <typename PickleSuite>
+class_& def_pickle(PickleSuite const&);
+
    -

    Class template - args<T1, T2,...TN>

    +
    +
    Requires: {{Ralf}}
    -

    A conveniently-named MPL sequence which - users pass to def_init calls to make - their code more readable. +

    Effects: {{Ralf}}
    -

    Class template args +
    Returns: *this
    + +
    Rationale: {{Ralf}}
    +

    +
    + + +

    Class template init<T1 = + unspecified, T2 = + unspecified,...Tn = + unspecified>

    + +

    A MPL sequence which + can be used to specify a family of one or more __init__ + functions. Only the last Ti supplied + may be an instantiation of optional<...>.

    + +

    Class template init synopsis

     namespace boost { namespace python
 {
-  template <T1 = unspecified,...TN = unspecified>
-  struct args
-  {};
+  template <T1 = unspecified,...Tn = unspecified>
+  struct init
+  {
+      init(char const* doc = 0);
+      template <class Keywords> init(Keywords const& kw, char const* doc = 0);
+      template <class Keywords> init(char const* doc, Keywords const& kw);
+
+      template <class CallPolicies>
+      unspecified operator[](CallPolicies const& policies) const
+  };
+}}
+
    + +

    Class template init + constructors

    +
    +init(char const* doc = 0);
+template <class Keywords> init(Keywords const& kw, char const* doc = 0);
+template <class Keywords> init(char const* doc, Keywords const& kw);
+
    + +
    +
    Requires: If supplied, doc is an ntbs. If supplied, kw is the + result of a
    + +
    Effects: The result is an init-expression whose + docstring is doc and whose keywords are + a reference to kw. If the first form is used, the + resulting expression's keywords are empty. The expression's + call policies are an instance of default_call_policies. + If Tn is optional<U1, U2,... + Um>, the + expression's valid prefixes are given by:
    + +
    +
    + (T1, T2,...Tn-1), + (T1, T2,...Tn-1 + , U1), + (T1, T2,...Tn-1 + , U1, U2), + ...(T1, T2,...Tn-1 + , U1, U2,...Um). +
    + Otherwise, the expression has one valid prefix given by the + the template arguments the user specified. +
    +
    + +

    Class template init + observer functions

    +
    +template <class Policies>
+unspecified operator[](Policies const& policies) const
+
    + +
    +
    Requires: Policies is a model of CallPolicies.
    + +
    Effects: Returns a new init-expression with all the same + properties as the init object except that its + callpolicies are replaced by a reference to + policies.
    +
    + +

    init-expressions

    + An init-expression is a transport vehicle for the following + properties, used to describe a family of __init__ methods to + be generated for an extension class: + +
    +
    docstring: An ntbs whose + value will bound to the method's __doc__ attribute
    + +
    keywords: A keyword-expression which will be + used to name (a trailing subset of) the arguments to the generated + __init__ function(s).
    + +
    call policies: An instance of a model of CallPolicies.
    + +
    argument types: An MPL sequence of C++ argument types which + will be used to construct the wrapped C++ object. An init expression + has one or more valid prefixes which are given by a sequence of + prefixes of its argument types.
    +
    + +

    Class template optional<T1 + = unspecified, T2 = + unspecified,...Tn = + unspecified>

    + +

    A MPL sequence which + can be used to specify the optional arguments to an __init__ + function.

    + +

    Class template + optional synopsis

    +
    +namespace boost { namespace python
+{
+  template <T1 = unspecified,...Tn = unspecified>
+  struct optional {};
 }}

    Class template - bases<T1, T2,...TN>

    + bases<T1, T2,...TN> -

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

    An MPL sequence + which can be used in class_<...> + instantiations indicate a list of base classes.

    Class template bases synopsis

     namespace boost { namespace python
 {
-  template <T1 = unspecified,...TN = unspecified>
+  template <T1 = unspecified,...Tn = unspecified>
   struct bases
   {};
 }}
@@ -530,12 +799,12 @@ namespace boost { namespace python
 
     
    Example(s)
    
 
-    
    Given a C++ class declaration:
+    
    Given a C++ class declaration:
    
 
     class Foo : public Bar, public Baz
 {
  public:
-   Foo(int, char const*);
+   Foo(int x, char const* y);
    Foo(double);
 
    std::string const& name() { return m_name; }
@@ -546,44 +815,39 @@ class Foo : public Bar, public Baz
    ...
 };
 
    
-
-   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> >()
-   .def_init(args<int,char const*>())
-   .def_init(args<double>())
+class_<Foo,bases<Bar,Baz> >("Foo",
+          "This is Foo's docstring."
+          "It describes our Foo extension class",
+
+          init<int,char const*>(args("x","y"), "__init__ docstring")
+          )
+   .def(init<double>())
    .def("get_name", &Foo::get_name, return_internal_reference<>())
    .def("set_name", &Foo::set_name)
    .def_readwrite("value", &Foo::value)
-   .object();
+   ;
 
    
-
-
    
-
-[1] By "previously-exposed" we mean that the for each
-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(...).
-
+    
    
+    [1] By "previously-exposed" we mean that the for
+    each B in bases, an instance of
+    class_<B, ...> must have
+    already been constructed. 
 
    -module m("module_name");
-m.add(class_<Base>()
-        .def_init());
-m.add(class_<Derived, bases<Base>>()
-        .def_init());
+class_<Base>("Base");
+class_<Derived, bases<Base> >("Derived");
 
    
-
     Revised 
     
-     09 May, 2002  
-    
+     29 Sept, 2002 
      
 
-    
    © Copyright Dave
-    Abrahams 2002. All Rights Reserved.
+    
    © Copyright Dave Abrahams 2002. All Rights
+    Reserved.
    
+  
+
 
diff --git a/doc/v2/definitions.html b/doc/v2/definitions.html
index 839608bc..4969f977 100644
--- a/doc/v2/definitions.html
+++ b/doc/v2/definitions.html
@@ -1,35 +1,54 @@
+
+
 
-
-
-
-Boost.Python - Definitions
-
-
-
+    
+    
+    
+
+    Boost.Python - Definitions
+  
+
+  
+    
    
-   
-    
-    
-  
-
     
-          
    -
    
-        		 
-      
    Boost.Python
    
-      
    Definitions
    
-    
    
-
    
-
    
-  
    {{term}}: {{definition}}
    
-  
    {{term}}: {{definition}}
    
-
    
-
    
-
    Revised 
-  
-  05 November, 2002 
-  
-
    
-
    © Copyright Dave Abrahams 
-  2002. All Rights Reserved.
    
-
+      
+        
+          
    C++ Boost
    
+        
+
+        
+          
    Boost.Python
    
+
+          
    Definitions
    
+        
+      
+    
+    
    
+
+    
    
+      
    arity: The number of arguments accepted
+      by a function or member function. Unless otherwise specified, the
+      hidden "this" argument to member functions is not counted
+      when specifying arity
    
+
+      
    ntbs: Null-Terminated Byte String, or
+      `C'-string. C++ string literals are ntbses. An
+      ntbs must never be null.
    
+    
    
+    
    
+
+    
    Revised 
+    
+     28 September, 2002 
+    
+    
    
+
+    
    © Copyright Dave Abrahams 2002. All Rights
+    Reserved.
    
+  
 
+