module, class_ .def dispatching

[SVN r14963]

Jamfile

@@ -0,0 +1,42 @@
+subproject libs/python ;
+
+# bring in the rules for python
+SEARCH on <module@>python.jam = $(BOOST_BUILD_PATH) ;
+include <module@>python.jam ;
+
+local bpl-ldflags ;
+
+if $(UNIX) && ( $(OS) = AIX )
+{
+    bpl-linkflags = <linkflags>"-e initlibbpl" ;
+}
+
+dll bpl
+  : 
+  src/list.cpp
+  src/long.cpp
+  src/dict.cpp
+  src/tuple.cpp
+  src/str.cpp
+
+  src/aix_init_module.cpp
+  src/converter/from_python.cpp
+  src/converter/registry.cpp
+  src/converter/type_id.cpp
+  src/object/class.cpp
+  src/object/function.cpp
+  src/object/inheritance.cpp
+  src/object/life_support.cpp
+  src/object/pickle_support.cpp
+  src/errors.cpp
+  src/module.cpp
+  src/converter/builtin_converters.cpp
+  src/converter/arg_to_python_base.cpp
+  src/object/iterator.cpp
+  src/object_protocol.cpp
+  src/object_operators.cpp
+  :
+  $(BOOST_PYTHON_V2_PROPERTIES)
+    <define>BOOST_PYTHON_SOURCE
+    $(bpl-linkflags)
+    ;

build/Jamfile

@@ -0,0 +1,173 @@
+#  (C) Copyright David Abrahams 2001. 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.
+#
+# Boost.Python build and test Jamfile
+#
+# To run all tests quietly: jam test
+# To run all tests with verbose output: jam -sPYTHON_TEST_ARGS=-v test
+#
+# Declares the following targets:
+#   1. libboost_python.dll/.so, a dynamic library to be linked with all
+#      Boost.Python modules
+#
+#   2. pairs of test targets of the form <name>.test and <name>.run
+#      <name>.test runs the test when it is out-of-date, and the "test"
+#      pseudotarget depends on it. <name>.run runs
+#      a test unconditionally, and can be used to force a test to run.. Each
+#      test target builds one or more Boost.Python modules and runs a Python
+#      script to test them. The test names are:
+#
+#      from ../test
+#
+#         comprehensive         - a comprehensive test of Boost.Python features
+#
+#      from ../example:
+#         abstract              -
+#         getting_started1      -
+#         getting_started2      -
+#         simple_vector         -
+#         do_it_yourself_convts -
+#         pickle1               -
+#         pickle2               -
+#         pickle3               -
+#
+#         dvect1                -
+#         dvect2                -
+#         ivect1                -
+#         ivect2                -
+#         noncopyable           -
+#
+# subproject-specific environment/command-line variables:
+#
+# PYTHON                - How to invoke the Python interpreter. Defaults to "python"
+#
+# PYTHON_ROOT           - Windows only: where Python is installed. Defaults to "c:/tools/python"
+#
+# PYTHON_VERSION        - Version of Python. Defaults to "2.1" on Windows, "1.5" on Unix
+#
+# PYTHON_TEST_ARGS      - specifies arguments to be passed to test scripts on
+#                         the command line. "-v" can be useful if you want to
+#                         see the output of successful tests.
+#
+# PYTHON_VECT_ITERATIONS - specifies the number of test iterations to use for
+#                          the dvect and ivect tests above.
+
+# declare the location of this subproject relative to the root
+subproject libs/python/build ;
+
+# bring in the rules for python
+SEARCH on <module@>python.jam = $(BOOST_BUILD_PATH) ;
+include <module@>python.jam ;
+
+# This nasty hack works with versions of Python 1.5.2 -> 2.2 to avoid
+# building any Python stuff if there's no installation.
+SEARCH on <find-python-install>__init__.py = $(PYTHON_STDLIB_PATH)/test $(SUBDIR) ;
+include <find-python-install>__init__.py ;
+if ! $(gNO_PYTHON_INSTALL)
+{
+    
+local PYTHON_PROPERTIES = $(PYTHON_PROPERTIES) <define>BOOST_PYTHON_DYNAMIC_LIB ;
+
+#######################
+rule bpl-test ( test-name : sources + )
+{
+    boost-python-test $(test-name) : $(sources) <dll>boost_python ;
+}
+
+#######################
+
+#
+# Declare the boost python static link library
+#
+
+# Base names of the source files for libboost_python
+local CPP_SOURCES =
+  types classes conversions extension_class functions 
+  init_function module_builder objects cross_module errors
+  ;
+
+lib boost_python_static : ../src/$(CPP_SOURCES).cpp
+  # requirements
+  : $(BOOST_PYTHON_INCLUDES)
+    <shared-linkable>true
+    <define>BOOST_PYTHON_STATIC_LIB=1
+    [ difference $(PYTHON_PROPERTIES) : <define>BOOST_PYTHON_DYNAMIC_LIB ] 
+      : <suppress>true # don't build this unless the user asks for it by name
+      ;
+
+dll boost_python
+  # $(SUFDLL[1])
+    : ../src/$(CPP_SOURCES).cpp
+	# requirements
+      : $(BOOST_PYTHON_INCLUDES)
+	<shared-linkable>true
+        <runtime-link>dynamic
+	$(PYTHON_PROPERTIES)
+          ;
+
+stage bin-stage : <dll>boost_python
+    :
+        <tag><debug>"_debug"
+        <tag><debug-python>"_pydebug"
+    :
+        debug release
+    ;
+
+############# comprehensive module and test ###########
+bpl-test boost_python_test
+      : ../test/comprehensive.cpp ;
+
+boost-python-runtest comprehensive
+         : ../test/comprehensive.py <pyd>boost_python_test <dll>boost_python ;
+
+############# simple tests from ../example ############
+
+rule boost-python-example-runtest ( name )
+{
+    bpl-test $(name)
+      : ../example/$(name).cpp ;
+    
+    boost-python-runtest $(name)
+      : ../example/test_$(name).py <pyd>$(name) <dll>boost_python ;
+}
+
+
+boost-python-example-runtest abstract ;
+boost-python-example-runtest getting_started1 ;
+boost-python-example-runtest getting_started2 ;
+boost-python-example-runtest simple_vector ;
+boost-python-example-runtest do_it_yourself_convts ;
+boost-python-example-runtest pickle1 ;
+boost-python-example-runtest pickle2 ;
+boost-python-example-runtest pickle3 ;
+
+
+bpl-test ivect : ../example/ivect.cpp ;
+bpl-test dvect : ../example/dvect.cpp ;
+bpl-test noncopyable_export : ../example/noncopyable_export.cpp ;
+bpl-test noncopyable_import : ../example/noncopyable_import.cpp ;
+
+############## cross-module tests from ../example ##########
+
+# A simple rule to build a test which depends on multiple modules in the PYTHONPATH
+rule boost-python-multi-example-runtest ( test-name : modules + )
+{
+    boost-python-runtest $(test-name)
+        : ../example/tst_$(test-name).py <pyd>$(modules) <dll>boost_python
+        : : : $(PYTHON_VECT_ITERATIONS) ;
+}
+
+PYTHON_VECT_ITERATIONS ?= 10 ;
+
+boost-python-multi-example-runtest dvect1 : ivect dvect ;
+boost-python-multi-example-runtest dvect2 : ivect dvect ;
+
+boost-python-multi-example-runtest ivect1 : ivect dvect ;
+boost-python-multi-example-runtest ivect2 : ivect dvect ;
+
+boost-python-multi-example-runtest
+        noncopyable : noncopyable_import noncopyable_export ;
+
+}

build/__init__.py

@@ -0,0 +1,22 @@
+# Dummy file actually to be included by Jam when the python headers
+# can't be found
+
+if ! $(gNO_PYTHON_INSTALL)
+{
+    ECHO "---------------------------------------------------------------------" ;
+    ECHO skipping Boost.Python library build ;
+    ECHO You can configure the location of your python installation, by setting: ;
+    ECHO "PYTHON_ROOT    - currently" \"$(PYTHON_ROOT:J=" ")\" ;
+    ECHO "PYTHON_VERSION - The 2-part python Major.Minor version number (e.g." ;
+    ECHO "                 \"2.2\", NOT \"2.2.1\")  - currently" \"$(PYTHON_VERSION)\" ;
+    ECHO ;
+    ECHO "The following are automatically configured from PYTHON_ROOT if not" ;
+    ECHO "otherwise set:" ;
+    ECHO "    PYTHON_INCLUDES    - path to Python #include directories; currently" \"$(PYTHON_INCLUDES:J=" ")\" ;
+    ECHO "    PYTHON_LIB_PATH    - path to Python library; currently" ;
+    ECHO "                         " \"$(PYTHON_LIB_PATH:J=" ")\" ;
+    ECHO "    PYTHON_STDLIB_PATH - path to Python standard library modules; currently" ;
+    ECHO "                         " \"$(PYTHON_STDLIB_PATH:J=" ")\" ;
+    ECHO "---------------------------------------------------------------------" ;
+}
+gNO_PYTHON_INSTALL ?= true ;

build/bpl_static.dsp

@@ -1,216 +0,0 @@
-# Microsoft Developer Studio Project File - Name="bpl_static" - Package Owner=<4>
-# Microsoft Developer Studio Generated Build File, Format Version 6.00
-# ** DO NOT EDIT **
-
-# TARGTYPE "Win32 (x86) Static Library" 0x0104
-
-CFG=bpl_static - Win32 Debug
-!MESSAGE This is not a valid makefile. To build this project using NMAKE,
-!MESSAGE use the Export Makefile command and run
-!MESSAGE 
-!MESSAGE NMAKE /f "bpl_static.mak".
-!MESSAGE 
-!MESSAGE You can specify a configuration when running NMAKE
-!MESSAGE by defining the macro CFG on the command line. For example:
-!MESSAGE 
-!MESSAGE NMAKE /f "bpl_static.mak" CFG="bpl_static - Win32 Debug"
-!MESSAGE 
-!MESSAGE Possible choices for configuration are:
-!MESSAGE 
-!MESSAGE "bpl_static - Win32 Release" (based on "Win32 (x86) Static Library")
-!MESSAGE "bpl_static - Win32 Debug" (based on "Win32 (x86) Static Library")
-!MESSAGE 
-
-# Begin Project
-# PROP AllowPerConfigDependencies 0
-# PROP Scc_ProjName ""
-# PROP Scc_LocalPath ""
-CPP=cl.exe
-RSC=rc.exe
-
-!IF  "$(CFG)" == "bpl_static - Win32 Release"
-
-# PROP BASE Use_MFC 0
-# PROP BASE Use_Debug_Libraries 0
-# PROP BASE Output_Dir "Release"
-# PROP BASE Intermediate_Dir "Release"
-# PROP BASE Target_Dir ""
-# PROP Use_MFC 0
-# PROP Use_Debug_Libraries 0
-# PROP Output_Dir "Release"
-# PROP Intermediate_Dir "Release"
-# PROP Target_Dir ""
-# ADD BASE CPP /nologo /W3 /GX /O2 /D "WIN32" /D "NDEBUG" /D "_MBCS" /D "_LIB" /YX /FD /c
-# ADD CPP /nologo /MD /W4 /WX /GR /GX /O2 /I "..\..\.." /I "c:\tools\python\include" /D "WIN32" /D "NDEBUG" /D "_MBCS" /D "_LIB" /FR /YX /FD /c
-# ADD BASE RSC /l 0x409 /d "NDEBUG"
-# ADD RSC /l 0x409 /d "NDEBUG"
-BSC32=bscmake.exe
-# ADD BASE BSC32 /nologo
-# ADD BSC32 /nologo
-LIB32=link.exe -lib
-# ADD BASE LIB32 /nologo
-# ADD LIB32 /nologo
-
-!ELSEIF  "$(CFG)" == "bpl_static - Win32 Debug"
-
-# PROP BASE Use_MFC 0
-# PROP BASE Use_Debug_Libraries 1
-# PROP BASE Output_Dir "Debug"
-# PROP BASE Intermediate_Dir "Debug"
-# PROP BASE Target_Dir ""
-# PROP Use_MFC 0
-# PROP Use_Debug_Libraries 1
-# PROP Output_Dir "Debug"
-# PROP Intermediate_Dir "Debug"
-# PROP Target_Dir ""
-# ADD BASE CPP /nologo /W3 /Gm /GX /ZI /Od /D "WIN32" /D "_DEBUG" /D "_MBCS" /D "_LIB" /YX /FD /GZ  /c
-# ADD CPP /nologo /MDd /W4 /WX /Gm /GR /GX /ZI /Od /I "..\..\.." /I "c:\tools\python\include" /D "WIN32" /D "_DEBUG" /D "_MBCS" /D "_LIB" /FR /YX /FD /GZ  /c
-# ADD BASE RSC /l 0x409 /d "_DEBUG"
-# ADD RSC /l 0x409 /d "_DEBUG"
-BSC32=bscmake.exe
-# ADD BASE BSC32 /nologo
-# ADD BSC32 /nologo
-LIB32=link.exe -lib
-# ADD BASE LIB32 /nologo
-# ADD LIB32 /nologo
-
-!ENDIF 
-
-# Begin Target
-
-# Name "bpl_static - Win32 Release"
-# Name "bpl_static - Win32 Debug"
-# Begin Group "Source Files"
-
-# PROP Default_Filter "cpp;c;cxx;rc;def;r;odl;idl;hpj;bat"
-# Begin Source File
-
-SOURCE=..\src\classes.cpp
-# ADD CPP /W3
-# End Source File
-# Begin Source File
-
-SOURCE=..\src\conversions.cpp
-# ADD CPP /W3
-# End Source File
-# Begin Source File
-
-SOURCE=..\src\extension_class.cpp
-# ADD CPP /W3
-# End Source File
-# Begin Source File
-
-SOURCE=..\src\functions.cpp
-# ADD CPP /W3
-# End Source File
-# Begin Source File
-
-SOURCE=..\src\init_function.cpp
-# ADD CPP /W3
-# End Source File
-# Begin Source File
-
-SOURCE=..\src\module_builder.cpp
-# ADD CPP /W3
-# End Source File
-# Begin Source File
-
-SOURCE=..\src\objects.cpp
-# ADD CPP /W3
-# End Source File
-# Begin Source File
-
-SOURCE=..\src\types.cpp
-# ADD CPP /W3
-# End Source File
-# End Group
-# Begin Group "Header Files"
-
-# PROP Default_Filter "h;hpp;hxx;hm;inl"
-# Begin Source File
-
-SOURCE=..\..\..\boost\python\detail\base_object.hpp
-# End Source File
-# Begin Source File
-
-SOURCE=..\..\..\boost\python\callback.hpp
-# End Source File
-# Begin Source File
-
-SOURCE=..\..\..\boost\python\caller.hpp
-# End Source File
-# Begin Source File
-
-SOURCE=..\..\..\boost\python\detail\cast.hpp
-# End Source File
-# Begin Source File
-
-SOURCE=..\..\..\boost\python\class_builder.hpp
-# End Source File
-# Begin Source File
-
-SOURCE=..\..\..\boost\python\classes.hpp
-# End Source File
-# Begin Source File
-
-SOURCE=..\..\..\boost\python\detail\config.hpp
-# End Source File
-# Begin Source File
-
-SOURCE=..\..\..\boost\python\conversions.hpp
-# End Source File
-# Begin Source File
-
-SOURCE=..\..\..\boost\python\errors.hpp
-# End Source File
-# Begin Source File
-
-SOURCE=..\..\..\boost\python\detail\extension_class.hpp
-# End Source File
-# Begin Source File
-
-SOURCE=..\..\..\boost\python\detail\functions.hpp
-# End Source File
-# Begin Source File
-
-SOURCE=..\..\..\boost\python\detail\init_function.hpp
-# End Source File
-# Begin Source File
-
-SOURCE=..\..\..\boost\python\module_builder.hpp
-# End Source File
-# Begin Source File
-
-SOURCE=..\..\..\boost\python\detail\none.hpp
-# End Source File
-# Begin Source File
-
-SOURCE=..\..\..\boost\python\objects.hpp
-# End Source File
-# Begin Source File
-
-SOURCE=..\..\..\boost\python\operators.hpp
-# End Source File
-# Begin Source File
-
-SOURCE=..\..\..\boost\python\reference.hpp
-# End Source File
-# Begin Source File
-
-SOURCE=..\..\..\boost\python\detail\signatures.hpp
-# End Source File
-# Begin Source File
-
-SOURCE=..\..\..\boost\python\detail\singleton.hpp
-# End Source File
-# Begin Source File
-
-SOURCE=..\..\..\boost\python\detail\types.hpp
-# End Source File
-# Begin Source File
-
-SOURCE=..\..\..\boost\python\detail\wrap_python.hpp
-# End Source File
-# End Group
-# End Target
-# End Project

build/build.dsw

@@ -1,74 +0,0 @@
-Microsoft Developer Studio Workspace File, Format Version 6.00
-# WARNING: DO NOT EDIT OR DELETE THIS WORKSPACE FILE!
-
-###############################################################################
-
-Project: "bpl_static"=.\bpl_static.dsp - Package Owner=<4>
-
-Package=<5>
-{{{
-}}}
-
-Package=<4>
-{{{
-}}}
-
-###############################################################################
-
-Project: "example1"=.\example1\example1.dsp - Package Owner=<4>
-
-Package=<5>
-{{{
-}}}
-
-Package=<4>
-{{{
-    Begin Project Dependency
-    Project_Dep_Name bpl_static
-    End Project Dependency
-}}}
-
-###############################################################################
-
-Project: "rwgk1"=.\rwgk1\rwgk1.dsp - Package Owner=<4>
-
-Package=<5>
-{{{
-}}}
-
-Package=<4>
-{{{
-    Begin Project Dependency
-    Project_Dep_Name bpl_static
-    End Project Dependency
-}}}
-
-###############################################################################
-
-Project: "test"=.\test\test.dsp - Package Owner=<4>
-
-Package=<5>
-{{{
-}}}
-
-Package=<4>
-{{{
-    Begin Project Dependency
-    Project_Dep_Name bpl_static
-    End Project Dependency
-}}}
-
-###############################################################################
-
-Global:
-
-Package=<5>
-{{{
-}}}
-
-Package=<3>
-{{{
-}}}
-
-###############################################################################
-

build/como.mak

@@ -1,6 +1,13 @@
+# Revision History:
+# 17 Apr 01  include cross-module support, compile getting_started1 (R.W. Grosse-Kunstleve) UNTESTED!
+# 06 Mar 01  Fixed typo in use of "PYTHON_LIB" (Dave Abrahams)
+# 04 Mar 01  Changed library name to libboost_python.a (David Abrahams)
+
 LIBSRC = \
     classes.cpp \
     conversions.cpp \
+    cross_module.cpp \
+    errors.cpp \
     extension_class.cpp \
     functions.cpp \
     init_function.cpp \
@@ -30,19 +37,20 @@ endif
             | sed 's/\($*\)\.o[ :]*/\1.o $@ : /g' > $@; \
                 [ -s $@ ] || rm -f $@
 
-example1: example1.o libpycpp.a
-	como-dyn-link -o ../example/hellomodule.$(MODULE_EXTENSION) $(PYHTON_LIB) example1.o -L. -lpycpp
-	python ../example/test_example1.py
+getting_started1: getting_started1.o libboost_python.a
+	como-dyn-link -o ../example/getting_started1.$(MODULE_EXTENSION) $(PYTHON_LIB) getting_started1.o -L. -lboost_python
+	ln -s ../test/doctest.py ../example
+	python ../example/test_getting_started1.py
 
-example1.o: ../example/example1.cpp
+getting_started1.o: ../example/getting_started1.cpp
 	como --pic $(INC) -o $*.o -c $<
 
 clean:
 	rm -rf *.o *.$(MODULE_EXTENSION) *.a *.d *.pyc *.bak a.out
 
-libpycpp.a: $(LIBOBJ)
-	rm -f libpycpp.a
-	ar cq libpycpp.a $(LIBOBJ)
+libboost_python.a: $(LIBOBJ)
+	rm -f libboost_python.a
+	ar cq libboost_python.a $(LIBOBJ)
 
 DEP = $(OBJ:.o=.d)
 

build/example1/example1.dsp

@@ -1,107 +0,0 @@
-# Microsoft Developer Studio Project File - Name="example1" - Package Owner=<4>
-# Microsoft Developer Studio Generated Build File, Format Version 6.00
-# ** DO NOT EDIT **
-
-# TARGTYPE "Win32 (x86) Dynamic-Link Library" 0x0102
-
-CFG=example1 - Win32 Debug
-!MESSAGE This is not a valid makefile. To build this project using NMAKE,
-!MESSAGE use the Export Makefile command and run
-!MESSAGE 
-!MESSAGE NMAKE /f "example1.mak".
-!MESSAGE 
-!MESSAGE You can specify a configuration when running NMAKE
-!MESSAGE by defining the macro CFG on the command line. For example:
-!MESSAGE 
-!MESSAGE NMAKE /f "example1.mak" CFG="example1 - Win32 Debug"
-!MESSAGE 
-!MESSAGE Possible choices for configuration are:
-!MESSAGE 
-!MESSAGE "example1 - Win32 Release" (based on "Win32 (x86) Dynamic-Link Library")
-!MESSAGE "example1 - Win32 Debug" (based on "Win32 (x86) Dynamic-Link Library")
-!MESSAGE 
-
-# Begin Project
-# PROP AllowPerConfigDependencies 0
-# PROP Scc_ProjName ""
-# PROP Scc_LocalPath ""
-CPP=cl.exe
-MTL=midl.exe
-RSC=rc.exe
-
-!IF  "$(CFG)" == "example1 - Win32 Release"
-
-# PROP BASE Use_MFC 0
-# PROP BASE Use_Debug_Libraries 0
-# PROP BASE Output_Dir "Release"
-# PROP BASE Intermediate_Dir "Release"
-# PROP BASE Target_Dir ""
-# PROP Use_MFC 0
-# PROP Use_Debug_Libraries 0
-# PROP Output_Dir "Release"
-# PROP Intermediate_Dir "Release"
-# PROP Ignore_Export_Lib 0
-# PROP Target_Dir ""
-# ADD BASE CPP /nologo /MT /W3 /GX /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE1_EXPORTS" /YX /FD /c
-# ADD CPP /nologo /MD /W3 /GX /O2 /I "..\..\..\.." /I "c:\tools\python\include" /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE1_EXPORTS" /YX /FD /c
-# ADD BASE MTL /nologo /D "NDEBUG" /mktyplib203 /win32
-# ADD MTL /nologo /D "NDEBUG" /mktyplib203 /win32
-# ADD BASE RSC /l 0x409 /d "NDEBUG"
-# ADD RSC /l 0x409 /d "NDEBUG"
-BSC32=bscmake.exe
-# ADD BASE BSC32 /nologo
-# ADD BSC32 /nologo
-LINK32=link.exe
-# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /dll /machine:I386
-# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /dll /machine:I386 /out:"Release/hello.dll" /libpath:"c:\tools\python\libs"
-
-!ELSEIF  "$(CFG)" == "example1 - Win32 Debug"
-
-# PROP BASE Use_MFC 0
-# PROP BASE Use_Debug_Libraries 1
-# PROP BASE Output_Dir "Debug"
-# PROP BASE Intermediate_Dir "Debug"
-# PROP BASE Target_Dir ""
-# PROP Use_MFC 0
-# PROP Use_Debug_Libraries 1
-# PROP Output_Dir "Debug"
-# PROP Intermediate_Dir "Debug"
-# PROP Ignore_Export_Lib 0
-# PROP Target_Dir ""
-# ADD BASE CPP /nologo /MTd /W3 /Gm /GX /ZI /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE1_EXPORTS" /YX /FD /GZ  /c
-# ADD CPP /nologo /MDd /W3 /Gm /GR /GX /ZI /Od /I "..\..\..\.." /I "c:\tools\python\include" /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE1_EXPORTS" /YX /FD /GZ  /c
-# ADD BASE MTL /nologo /D "_DEBUG" /mktyplib203 /win32
-# ADD MTL /nologo /D "_DEBUG" /mktyplib203 /win32
-# ADD BASE RSC /l 0x409 /d "_DEBUG"
-# ADD RSC /l 0x409 /d "_DEBUG"
-BSC32=bscmake.exe
-# ADD BASE BSC32 /nologo
-# ADD BSC32 /nologo
-LINK32=link.exe
-# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /dll /debug /machine:I386 /pdbtype:sept
-# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /dll /debug /machine:I386 /out:"Debug/hello.dll" /pdbtype:sept /libpath:"c:\tools\python\libs"
-
-!ENDIF 
-
-# Begin Target
-
-# Name "example1 - Win32 Release"
-# Name "example1 - Win32 Debug"
-# Begin Group "Source Files"
-
-# PROP Default_Filter "cpp;c;cxx;rc;def;r;odl;idl;hpj;bat"
-# Begin Source File
-
-SOURCE=..\..\example\example1.cpp
-# End Source File
-# End Group
-# Begin Group "Header Files"
-
-# PROP Default_Filter "h;hpp;hxx;hm;inl"
-# End Group
-# Begin Group "Resource Files"
-
-# PROP Default_Filter "ico;cur;bmp;dlg;rc2;rct;bin;rgs;gif;jpg;jpeg;jpe"
-# End Group
-# End Target
-# End Project

build/filemgr.py

@@ -0,0 +1,146 @@
+# Revision history:
+#   12 Apr 01 use os.path, shutil
+#   Initial version: R.W. Grosse-Kunstleve
+
+bpl_src = "/libs/python/src"
+bpl_tst = "/libs/python/test"
+bpl_exa = "/libs/python/example"
+files = (
+bpl_src + "/classes.cpp",
+bpl_src + "/conversions.cpp",
+bpl_src + "/errors.cpp",
+bpl_src + "/extension_class.cpp",
+bpl_src + "/functions.cpp",
+bpl_src + "/init_function.cpp",
+bpl_src + "/module_builder.cpp",
+bpl_src + "/objects.cpp",
+bpl_src + "/types.cpp",
+bpl_src + "/cross_module.cpp",
+bpl_tst + "/comprehensive.cpp",
+bpl_tst + "/comprehensive.hpp",
+bpl_tst + "/comprehensive.py",
+bpl_tst + "/doctest.py",
+bpl_exa + "/abstract.cpp",
+bpl_exa + "/getting_started1.cpp",
+bpl_exa + "/getting_started2.cpp",
+bpl_exa + "/simple_vector.cpp",
+bpl_exa + "/do_it_yourself_convts.cpp",
+bpl_exa + "/nested.cpp",
+bpl_exa + "/pickle1.cpp",
+bpl_exa + "/pickle2.cpp",
+bpl_exa + "/pickle3.cpp",
+bpl_exa + "/test_abstract.py",
+bpl_exa + "/test_getting_started1.py",
+bpl_exa + "/test_getting_started2.py",
+bpl_exa + "/test_simple_vector.py",
+bpl_exa + "/test_do_it_yourself_convts.py",
+bpl_exa + "/test_nested.py",
+bpl_exa + "/test_pickle1.py",
+bpl_exa + "/test_pickle2.py",
+bpl_exa + "/test_pickle3.py",
+bpl_exa + "/noncopyable.h",
+bpl_exa + "/noncopyable_export.cpp",
+bpl_exa + "/noncopyable_import.cpp",
+bpl_exa + "/dvect.h",
+bpl_exa + "/dvect.cpp",
+bpl_exa + "/dvect_conversions.cpp",
+bpl_exa + "/dvect_defs.cpp",
+bpl_exa + "/ivect.h",
+bpl_exa + "/ivect.cpp",
+bpl_exa + "/ivect_conversions.cpp",
+bpl_exa + "/ivect_defs.cpp",
+bpl_exa + "/tst_noncopyable.py",
+bpl_exa + "/tst_dvect1.py",
+bpl_exa + "/tst_dvect2.py",
+bpl_exa + "/tst_ivect1.py",
+bpl_exa + "/tst_ivect2.py",
+bpl_exa + "/test_cross_module.py",
+bpl_exa + "/vector_wrapper.h",
+bpl_exa + "/richcmp1.cpp",
+bpl_exa + "/richcmp2.cpp",
+bpl_exa + "/richcmp3.cpp",
+bpl_exa + "/test_richcmp1.py",
+bpl_exa + "/test_richcmp2.py",
+bpl_exa + "/test_richcmp3.py",
+)
+
+defs = (
+"boost_python_test",
+"abstract",
+"getting_started1",
+"getting_started2",
+"simple_vector",
+"do_it_yourself_convts",
+"nested",
+"pickle1",
+"pickle2",
+"pickle3",
+"noncopyable_export",
+"noncopyable_import",
+"ivect",
+"dvect",
+"richcmp1",
+"richcmp2",
+"richcmp3",
+)
+
+if (__name__ == "__main__"):
+
+  import sys, os, shutil
+
+  path = sys.argv[1]
+  mode = sys.argv[2]
+  if (not mode in ("softlinks", "unlink", "cp", "rm", "copy", "del")):
+    raise RuntimeError, \
+      "usage: python filemgr.py path <softlinks|unlink|cp|rm|copy|del>"
+
+  if (mode in ("cp", "copy")):
+    for fn in files:
+      f = os.path.basename(fn)
+      print "Copying: " + f
+      shutil.copy(path + fn, ".")
+
+  elif (mode == "softlinks"):
+    for fn in files:
+      f = os.path.basename(fn)
+      if (os.path.exists(f)):
+        print "File exists: " + f
+      else:
+        print "Linking: " + f
+        os.symlink(path + fn, f)
+
+  elif (mode in ("rm", "del")):
+    for fn in files:
+      f = os.path.basename(fn)
+      if (os.path.exists(f)):
+        print "Removing: " + f
+        try: os.unlink(f)
+        except: pass
+
+  elif (mode == "unlink"):
+    for fn in files:
+      f = os.path.basename(fn)
+      if (os.path.exists(f)):
+        if (os.path.islink(f)):
+          print "Unlinking: " + f
+          try: os.unlink(f)
+          except: pass
+        else:
+          print "Not a softlink: " + f
+
+  if (mode in ("softlinks", "cp", "copy")):
+    for d in defs:
+      fn = d + ".def"
+      print "Creating: " + fn
+      f = open(fn, "w")
+      f.write("EXPORTS\n")
+      f.write("\tinit" + d + "\n")
+      f.close()
+
+  if (mode in ("unlink", "rm", "del")):
+    for d in defs:
+      fn = d + ".def"
+      if (os.path.exists(fn)):
+        print "Removing: " + fn
+        try: os.unlink(fn)
+        except: pass

build/gcc.mak

@@ -1,6 +1,17 @@
+#  Revision History
+
+#  17 Apr 01 include cross-module support, compile getting_started1 (R.W. Grosse-Kunstleve)
+#  17 Apr 01 build shared library (patch provided by Dan Nuffer)
+#  04 Mar 01 Changed library name to libboost_python.a, various cleanups,
+#            attempted Cygwin compatibility. Still needs testing on Linux
+#            (David Abrahams)
+
+
 LIBSRC = \
     classes.cpp \
     conversions.cpp \
+    cross_module.cpp \
+    errors.cpp \
     extension_class.cpp \
     functions.cpp \
     init_function.cpp \
@@ -11,18 +22,26 @@ LIBSRC = \
 LIBOBJ = $(LIBSRC:.cpp=.o)
 OBJ = $(LIBOBJ)
 
+LIBNAME = libboost_python
+# libpython2.0.dll
 
 ifeq "$(OS)" "Windows_NT"
-PYTHON_LIB=c:/tools/python/libs/python15.lib
-INC = -Ic:/cygnus/usr/include/g++-3 -Ic:/cygnus/usr/include -Ic:/boost -Ic:/tools/python/include
+ROOT=c:/cygnus
+INC = -Ic:/cygnus/usr/include/g++-3 -Ic:/cygnus/usr/include -Ic:/boost -I$(PYTHON_INC)
 MODULE_EXTENSION=dll
+PYTHON_LIB=c:/cygnus/usr/local/lib/python2.0/config/libpython2.0.dll.a
+SHARED_LIB = $(LIBNAME).dll
 else
-INC = -I/usr/local/include/python1.5
+PYTHON_INC=$(ROOT)/usr/local/Python-2.0/include/python2.0
+BOOST_INC=../../..
+INC = -I$(BOOST_INC) -I$(PYTHON_INC)
 MODULE_EXTENSION=so
+VERSION=1
+SHARED_LIB = $(LIBNAME).so.$(VERSION)
 endif
 
 %.o: ../src/%.cpp
-	g++ -fPIC -Wall -W $(INC) -o $*.o -c $<
+	g++ -fPIC -Wall -W $(INC) $(CXXFLAGS) -o $*.o -c $<
 
 %.d: ../src/%.cpp
 	@echo creating $@
@@ -31,20 +50,36 @@ endif
                 [ -s $@ ] || rm -f $@
 
 
-example1: example1.o libpycpp.a
-	g++ -shared -o ../example/hellomodule.$(MODULE_EXTENSION) $(PYHTON_LIB) example1.o -L. -lpycpp
-	python ../example/test_example1.py
+PYTHON = python
 
-example1.o: ../example/example1.cpp
-	g++ -fPIC -Wall -W $(INC) -o $*.o -c $<
+all: test $(SHARED_LIB) getting_started1
+
+test: comprehensive.o $(LIBNAME).a $(SHARED_LIB)
+	g++ $(CXXFLAGS) -shared -o ../test/boost_python_test.$(MODULE_EXTENSION) comprehensive.o -L. -lboost_python  $(PYTHON_LIB)
+	$(PYTHON) ../test/comprehensive.py
+
+comprehensive.o: ../test/comprehensive.cpp
+	g++ $(CXXFLAGS) --template-depth-32 -fPIC -Wall -W $(INC) -o $*.o -c $<
+
+
+getting_started1: getting_started1.o $(LIBNAME).a
+	g++ $(CXXFLAGS) -shared -o ../example/getting_started1.$(MODULE_EXTENSION) getting_started1.o -L. -lboost_python  $(PYTHON_LIB)
+	ln -s ../test/doctest.py ../example
+	$(PYTHON) ../example/test_getting_started1.py
+
+getting_started1.o: ../example/getting_started1.cpp
+	g++ $(CXXFLAGS) --template-depth-32 -fPIC -Wall -W $(INC) -o $*.o -c $<
 
 
 clean:
 	rm -rf *.o *.$(MODULE_EXTENSION) *.a *.d *.pyc *.bak a.out
 
-libpycpp.a: $(LIBOBJ)
-	rm -f libpycpp.a
-	ar cq libpycpp.a $(LIBOBJ)
+$(LIBNAME).a: $(LIBOBJ)
+	rm -f $@
+	ar cqs $@ $(LIBOBJ)
+
+$(SHARED_LIB): $(LIBOBJ)
+	g++ $(CXXFLAGS) -shared -o $@ -Wl,--soname=$(LIBNAME).$(MODULE_EXTENSION)
 
 DEP = $(OBJ:.o=.d)
 

build/irix_CC.mak

@@ -0,0 +1,184 @@
+# Usage:
+#
+#   Create a new empty directory anywhere (preferably not in the boost tree).
+#   Copy this Makefile to that new directory and rename it to "Makefile"
+#   Adjust the pathnames below.
+#
+#   make softlinks     Create softlinks to source code and tests
+#   make               Compile all sources
+#   make test          Run doctest tests
+#   make clean         Remove all object files
+#   make unlink        Remove softlinks
+#
+# Revision history:
+#   12 Apr 01 new macro ROOT to simplify configuration (R.W. Grosse-Kunstleve)
+#   Initial version: R.W. Grosse-Kunstleve
+
+ROOT=$(HOME)
+BOOST=$(ROOT)/boost
+
+#PYEXE=PYTHONPATH=. /usr/local/Python-1.5.2/bin/python
+#PYINC=-I/usr/local/Python-1.5.2/include/python1.5
+PYEXE=PYTHONPATH=. /usr/local_cci/Python-2.1.1/bin/python
+PYINC=-I/usr/local_cci/Python-2.1.1/include/python2.1
+STLPORTINC=-I$(BOOST)/boost/compatibility/cpp_c_headers
+
+STDOPTS=
+WARNOPTS=-woff 1001,1234,1682
+OPTOPTS=-g
+
+CPP=CC -LANG:std -n32 -mips4
+CPPOPTS=$(STLPORTINC) $(STLPORTOPTS) -I$(BOOST) $(PYINC) \
+        $(STDOPTS) $(WARNOPTS) $(OPTOPTS)
+MAKEDEP=-M
+
+LD=CC -LANG:std -n32 -mips4
+LDOPTS=-shared
+
+OBJ=classes.o conversions.o errors.o extension_class.o functions.o \
+    init_function.o module_builder.o \
+    objects.o types.o cross_module.o
+DEPOBJ=$(OBJ) \
+       comprehensive.o \
+       abstract.o \
+       getting_started1.o getting_started2.o \
+       simple_vector.o \
+       do_it_yourself_convts.o \
+       nested.o \
+       pickle1.o pickle2.o pickle3.o \
+       noncopyable_export.o noncopyable_import.o \
+       ivect.o dvect.o \
+       richcmp1.o richcmp2.o richcmp3.o
+
+.SUFFIXES: .o .cpp
+
+all: libboost_python.a \
+     boost_python_test.so \
+     abstract.so \
+     getting_started1.so getting_started2.so \
+     simple_vector.so \
+     do_it_yourself_convts.so \
+     nested.so \
+     pickle1.so pickle2.so pickle3.so \
+     noncopyable_export.so noncopyable_import.so \
+     ivect.so dvect.so \
+     richcmp1.so richcmp2.so richcmp3.so
+
+libboost_python.a: $(OBJ)
+	rm -f libboost_python.a
+	$(CPP) -ar -o libboost_python.a $(OBJ)
+
+boost_python_test.so: $(OBJ) comprehensive.o
+	$(LD) $(LDOPTS) $(OBJ) comprehensive.o -o boost_python_test.so -lm
+
+abstract.so: $(OBJ) abstract.o
+	$(LD) $(LDOPTS) $(OBJ) abstract.o -o abstract.so
+
+getting_started1.so: $(OBJ) getting_started1.o
+	$(LD) $(LDOPTS) $(OBJ) getting_started1.o -o getting_started1.so
+
+getting_started2.so: $(OBJ) getting_started2.o
+	$(LD) $(LDOPTS) $(OBJ) getting_started2.o -o getting_started2.so
+
+simple_vector.so: $(OBJ) simple_vector.o
+	$(LD) $(LDOPTS) $(OBJ) simple_vector.o -o simple_vector.so
+
+do_it_yourself_convts.so: $(OBJ) do_it_yourself_convts.o
+	$(LD) $(LDOPTS) $(OBJ) do_it_yourself_convts.o -o do_it_yourself_convts.so
+
+nested.so: $(OBJ) nested.o
+	$(LD) $(LDOPTS) $(OBJ) nested.o -o nested.so
+
+pickle1.so: $(OBJ) pickle1.o
+	$(LD) $(LDOPTS) $(OBJ) pickle1.o -o pickle1.so
+
+pickle2.so: $(OBJ) pickle2.o
+	$(LD) $(LDOPTS) $(OBJ) pickle2.o -o pickle2.so
+
+pickle3.so: $(OBJ) pickle3.o
+	$(LD) $(LDOPTS) $(OBJ) pickle3.o -o pickle3.so
+
+noncopyable_export.so: $(OBJ) noncopyable_export.o
+	$(LD) $(LDOPTS) $(OBJ) $(HIDDEN) \
+          noncopyable_export.o -o noncopyable_export.so
+
+noncopyable_import.so: $(OBJ) noncopyable_import.o
+	$(LD) $(LDOPTS) $(OBJ) $(HIDDEN) \
+          noncopyable_import.o -o noncopyable_import.so
+
+ivect.so: $(OBJ) ivect.o
+	$(LD) $(LDOPTS) $(OBJ) $(HIDDEN) ivect.o -o ivect.so
+
+dvect.so: $(OBJ) dvect.o
+	$(LD) $(LDOPTS) $(OBJ) $(HIDDEN) dvect.o -o dvect.so
+
+richcmp1.so: $(OBJ) richcmp1.o
+	$(LD) $(LDOPTS) $(OBJ) richcmp1.o -o richcmp1.so
+
+richcmp2.so: $(OBJ) richcmp2.o
+	$(LD) $(LDOPTS) $(OBJ) richcmp2.o -o richcmp2.so
+
+richcmp3.so: $(OBJ) richcmp3.o
+	$(LD) $(LDOPTS) $(OBJ) richcmp3.o -o richcmp3.so
+
+.cpp.o:
+	$(CPP) $(CPPOPTS) -c $*.cpp
+
+test:
+	$(PYEXE) comprehensive.py
+	$(PYEXE) test_abstract.py
+	$(PYEXE) test_getting_started1.py
+	$(PYEXE) test_getting_started2.py
+	$(PYEXE) test_simple_vector.py
+	$(PYEXE) test_do_it_yourself_convts.py
+	$(PYEXE) test_nested.py
+	$(PYEXE) test_pickle1.py
+	$(PYEXE) test_pickle2.py
+	$(PYEXE) test_pickle3.py
+	$(PYEXE) test_cross_module.py
+	$(PYEXE) test_richcmp1.py
+	$(PYEXE) test_richcmp2.py
+	$(PYEXE) test_richcmp3.py
+
+clean:
+	rm -f $(OBJ) libboost_python.a libboost_python.a.input
+	rm -f comprehensive.o boost_python_test.so
+	rm -f abstract.o abstract.so
+	rm -f getting_started1.o getting_started1.so
+	rm -f getting_started2.o getting_started2.so
+	rm -f simple_vector.o simple_vector.so
+	rm -f do_it_yourself_convts.o do_it_yourself_convts.so
+	rm -f nested.o nested.so
+	rm -f pickle1.o pickle1.so
+	rm -f pickle2.o pickle2.so
+	rm -f pickle3.o pickle3.so
+	rm -f noncopyable_export.o noncopyable_export.so
+	rm -f noncopyable_import.o noncopyable_import.so
+	rm -f ivect.o ivect.so
+	rm -f dvect.o dvect.so
+	rm -f richcmp1.o richcmp1.so
+	rm -f richcmp2.o richcmp2.so
+	rm -f richcmp3.o richcmp3.so
+	rm -f so_locations *.pyc
+	rm -rf ii_files
+
+softlinks:
+	$(PYEXE) $(BOOST)/libs/python/build/filemgr.py $(BOOST) softlinks
+
+unlink:
+	$(PYEXE) $(BOOST)/libs/python/build/filemgr.py $(BOOST) unlink
+
+cp:
+	$(PYEXE) $(BOOST)/libs/python/build/filemgr.py $(BOOST) cp
+
+rm:
+	$(PYEXE) $(BOOST)/libs/python/build/filemgr.py $(BOOST) rm
+
+depend:
+	@ cat Makefile.nodepend; \
+          for obj in $(DEPOBJ); \
+          do \
+            bn=`echo "$$obj" | cut -d. -f1`; \
+            $(CPP) $(CPPOPTS) $(MAKEDEP) "$$bn".cpp; \
+          done
+

build/linux_gcc.mak

@@ -0,0 +1,184 @@
+# Usage:
+#
+#   Create a new empty directory anywhere (preferably not in the boost tree).
+#   Copy this Makefile to that new directory and rename it to "Makefile"
+#   Adjust the pathnames below.
+#
+#   make softlinks     Create softlinks to source code and tests
+#   make               Compile all sources
+#   make test          Run doctest tests
+#   make clean         Remove all object files
+#   make unlink        Remove softlinks
+#
+# Revision history:
+#   12 Apr 01 new macro ROOT to simplify configuration (R.W. Grosse-Kunstleve)
+#   Initial version: R.W. Grosse-Kunstleve
+
+ROOT=$(HOME)
+BOOST=$(ROOT)/boost
+
+#PYEXE=PYTHONPATH=. /usr/bin/python
+#PYINC=-I/usr/include/python1.5
+#PYEXE=PYTHONPATH=. /usr/local/Python-1.5.2/bin/python
+#PYINC=-I/usr/local/Python-1.5.2/include/python1.5
+PYEXE=PYTHONPATH=. /usr/local_cci/Python-2.1.1/bin/python
+PYINC=-I/usr/local_cci/Python-2.1.1/include/python2.1
+
+STDOPTS=-fPIC -ftemplate-depth-21
+WARNOPTS=
+OPTOPTS=-g
+
+CPP=g++
+CPPOPTS=$(STLPORTINC) $(STLPORTOPTS) -I$(BOOST) $(PYINC) \
+        $(STDOPTS) $(WARNOPTS) $(OPTOPTS)
+MAKEDEP=-M
+
+LD=$(CPP)
+LDOPTS=-shared
+
+OBJ=classes.o conversions.o errors.o extension_class.o functions.o \
+    init_function.o module_builder.o \
+    objects.o types.o cross_module.o
+DEPOBJ=$(OBJ) \
+       comprehensive.o \
+       abstract.o \
+       getting_started1.o getting_started2.o \
+       simple_vector.o \
+       do_it_yourself_convts.o \
+       nested.o \
+       pickle1.o pickle2.o pickle3.o \
+       noncopyable_export.o noncopyable_import.o \
+       ivect.o dvect.o \
+       richcmp1.o richcmp2.o richcmp3.o
+
+.SUFFIXES: .o .cpp
+
+all: libboost_python.a \
+     boost_python_test.so \
+     abstract.so \
+     getting_started1.so getting_started2.so \
+     simple_vector.so \
+     do_it_yourself_convts.so \
+     nested.so \
+     pickle1.so pickle2.so pickle3.so \
+     noncopyable_export.so noncopyable_import.so \
+     ivect.so dvect.so \
+     richcmp1.so richcmp2.so richcmp3.so
+
+libboost_python.a: $(OBJ)
+	rm -f libboost_python.a
+	ar r libboost_python.a $(OBJ)
+
+boost_python_test.so: $(OBJ) comprehensive.o
+	$(LD) $(LDOPTS) $(OBJ) comprehensive.o -o boost_python_test.so -lm
+
+abstract.so: $(OBJ) abstract.o
+	$(LD) $(LDOPTS) $(OBJ) abstract.o -o abstract.so
+
+getting_started1.so: $(OBJ) getting_started1.o
+	$(LD) $(LDOPTS) $(OBJ) getting_started1.o -o getting_started1.so
+
+getting_started2.so: $(OBJ) getting_started2.o
+	$(LD) $(LDOPTS) $(OBJ) getting_started2.o -o getting_started2.so
+
+simple_vector.so: $(OBJ) simple_vector.o
+	$(LD) $(LDOPTS) $(OBJ) simple_vector.o -o simple_vector.so
+
+do_it_yourself_convts.so: $(OBJ) do_it_yourself_convts.o
+	$(LD) $(LDOPTS) $(OBJ) do_it_yourself_convts.o -o do_it_yourself_convts.so
+
+nested.so: $(OBJ) nested.o
+	$(LD) $(LDOPTS) $(OBJ) nested.o -o nested.so
+
+pickle1.so: $(OBJ) pickle1.o
+	$(LD) $(LDOPTS) $(OBJ) pickle1.o -o pickle1.so
+
+pickle2.so: $(OBJ) pickle2.o
+	$(LD) $(LDOPTS) $(OBJ) pickle2.o -o pickle2.so
+
+pickle3.so: $(OBJ) pickle3.o
+	$(LD) $(LDOPTS) $(OBJ) pickle3.o -o pickle3.so
+
+noncopyable_export.so: $(OBJ) noncopyable_export.o
+	$(LD) $(LDOPTS) $(OBJ) $(HIDDEN) \
+          noncopyable_export.o -o noncopyable_export.so
+
+noncopyable_import.so: $(OBJ) noncopyable_import.o
+	$(LD) $(LDOPTS) $(OBJ) $(HIDDEN) \
+          noncopyable_import.o -o noncopyable_import.so
+
+ivect.so: $(OBJ) ivect.o
+	$(LD) $(LDOPTS) $(OBJ) $(HIDDEN) ivect.o -o ivect.so
+
+dvect.so: $(OBJ) dvect.o
+	$(LD) $(LDOPTS) $(OBJ) $(HIDDEN) dvect.o -o dvect.so
+
+richcmp1.so: $(OBJ) richcmp1.o
+	$(LD) $(LDOPTS) $(OBJ) richcmp1.o -o richcmp1.so
+
+richcmp2.so: $(OBJ) richcmp2.o
+	$(LD) $(LDOPTS) $(OBJ) richcmp2.o -o richcmp2.so
+
+richcmp3.so: $(OBJ) richcmp3.o
+	$(LD) $(LDOPTS) $(OBJ) richcmp3.o -o richcmp3.so
+
+.cpp.o:
+	$(CPP) $(CPPOPTS) -c $*.cpp
+
+test:
+	$(PYEXE) comprehensive.py
+	$(PYEXE) test_abstract.py
+	$(PYEXE) test_getting_started1.py
+	$(PYEXE) test_getting_started2.py
+	$(PYEXE) test_simple_vector.py
+	$(PYEXE) test_do_it_yourself_convts.py
+	$(PYEXE) test_nested.py
+	$(PYEXE) test_pickle1.py
+	$(PYEXE) test_pickle2.py
+	$(PYEXE) test_pickle3.py
+	$(PYEXE) test_cross_module.py
+	$(PYEXE) test_richcmp1.py
+	$(PYEXE) test_richcmp2.py
+	$(PYEXE) test_richcmp3.py
+
+clean:
+	rm -f $(OBJ) libboost_python.a libboost_python.a.input
+	rm -f comprehensive.o boost_python_test.so
+	rm -f abstract.o abstract.so
+	rm -f getting_started1.o getting_started1.so
+	rm -f getting_started2.o getting_started2.so
+	rm -f simple_vector.o simple_vector.so
+	rm -f do_it_yourself_convts.o do_it_yourself_convts.so
+	rm -f nested.o nested.so
+	rm -f pickle1.o pickle1.so
+	rm -f pickle2.o pickle2.so
+	rm -f pickle3.o pickle3.so
+	rm -f noncopyable_export.o noncopyable_export.so
+	rm -f noncopyable_import.o noncopyable_import.so
+	rm -f ivect.o ivect.so
+	rm -f dvect.o dvect.so
+	rm -f richcmp1.o richcmp1.so
+	rm -f richcmp2.o richcmp2.so
+	rm -f richcmp3.o richcmp3.so
+	rm -f so_locations *.pyc
+
+softlinks:
+	$(PYEXE) $(BOOST)/libs/python/build/filemgr.py $(BOOST) softlinks
+
+unlink:
+	$(PYEXE) $(BOOST)/libs/python/build/filemgr.py $(BOOST) unlink
+
+cp:
+	$(PYEXE) $(BOOST)/libs/python/build/filemgr.py $(BOOST) cp
+
+rm:
+	$(PYEXE) $(BOOST)/libs/python/build/filemgr.py $(BOOST) rm
+
+depend:
+	@ cat Makefile.nodepend; \
+          for obj in $(DEPOBJ); \
+          do \
+            bn=`echo "$$obj" | cut -d. -f1`; \
+            $(CPP) $(CPPOPTS) $(MAKEDEP) "$$bn".cpp; \
+          done
+

build/mingw32.mak

@@ -0,0 +1,222 @@
+# Usage:
+#
+#   make copy          Copy the sources and tests
+#   make               Compile all sources
+#   make test          Run doctest tests
+#   make clean         Remove all object files
+#   make del           Remove the sources and tests
+#
+# Revision history:
+#   12 Apr 01 new macro ROOT to simplify configuration (R.W. Grosse-Kunstleve)
+#   Initial version: R.W. Grosse-Kunstleve
+
+# To install mingw32, follow instructions at:
+#   http://starship.python.net/crew/kernr/mingw32/Notes.html
+# In particular, install:
+#   ftp://ftp.xraylith.wisc.edu/pub/khan/gnu-win32/mingw32/gcc-2.95.2/gcc-2.95.2-msvcrt.exe
+#   ftp://ftp.xraylith.wisc.edu/pub/khan/gnu-win32/mingw32/gcc-2.95.2/fixes/quote-fix-msvcrt.exe
+#   http://starship.python.net/crew/kernr/mingw32/Python-1.5.2-mingw32.zip
+# Unpack the first two archives in the default locations and update your PATH.
+# Unpack the third archive in \usr.
+
+# Note: comprehensive.cpp generates compiler errors and later crashes.
+#   L:\boost\boost\python\detail\extension_class.hpp:643: warning:
+#   alignment of `vtable for class
+#   boost::python::detail::held_instance<bpl_test::Derived1>'
+#   is greater than maximum object file alignment. Using 16.
+# Could this be fixed with compiler options?
+# -fhuge-objects looks interesting, but requires recompiling the C++ library.
+#                (what exactly does that mean?)
+# -fvtable-thunks eliminates the compiler warning, but
+#                 "import boost_python_test" still causes a crash.
+
+ROOT=R:
+BOOST_WIN="$(ROOT)\boost"
+BOOST_UNIX=$(HOME)/boost
+
+PYEXE="C:\Program files\Python\python.exe"
+PYINC=-I"C:\usr\include\python1.5"
+PYLIB="C:\usr\lib\libpython15.a"
+#PYEXE="C:\Python21\python.exe"
+#PYINC=-I"C:\usr\include\python2.1"
+#PYLIB="C:\usr\lib\libpython21.a"
+
+STDOPTS=-ftemplate-depth-21
+WARNOPTS=
+OPTOPTS=-g
+
+CPP=g++
+CPPOPTS=$(STLPORTINC) $(STLPORTOPTS) -I$(BOOST_WIN) $(PYINC) \
+        $(STDOPTS) $(WARNOPTS) $(OPTOPTS)
+
+LD=g++
+LDOPTS=-shared
+
+OBJ=classes.o conversions.o errors.o extension_class.o functions.o \
+    init_function.o module_builder.o \
+    objects.o types.o cross_module.o
+
+.SUFFIXES: .o .cpp
+
+all: libboost_python.a \
+     abstract.pyd \
+     getting_started1.pyd getting_started2.pyd \
+     simple_vector.pyd \
+     do_it_yourself_convts.pyd \
+     nested.pyd \
+     pickle1.pyd pickle2.pyd pickle3.pyd \
+     noncopyable_export.pyd noncopyable_import.pyd \
+     ivect.pyd dvect.pyd \
+     richcmp1.pyd richcmp2.pyd richcmp3.pyd
+
+libboost_python.a: $(OBJ)
+	-del libboost_python.a
+	ar r libboost_python.a $(OBJ)
+
+DLLWRAPOPTS=-s --driver-name g++ -s \
+            --entry _DllMainCRTStartup@12 --target=i386-mingw32
+
+boost_python_test.pyd: $(OBJ) comprehensive.o
+	dllwrap $(DLLWRAPOPTS) \
+          --dllname boost_python_test.pyd \
+          --def boost_python_test.def \
+          $(OBJ) comprehensive.o $(PYLIB)
+
+abstract.pyd: $(OBJ) abstract.o
+	dllwrap $(DLLWRAPOPTS) \
+          --dllname abstract.pyd \
+          --def abstract.def \
+          $(OBJ) abstract.o $(PYLIB)
+
+getting_started1.pyd: $(OBJ) getting_started1.o
+	dllwrap $(DLLWRAPOPTS) \
+          --dllname getting_started1.pyd \
+          --def getting_started1.def \
+          $(OBJ) getting_started1.o $(PYLIB)
+
+getting_started2.pyd: $(OBJ) getting_started2.o
+	dllwrap $(DLLWRAPOPTS) \
+          --dllname getting_started2.pyd \
+          --def getting_started2.def \
+          $(OBJ) getting_started2.o $(PYLIB)
+
+simple_vector.pyd: $(OBJ) simple_vector.o
+	dllwrap $(DLLWRAPOPTS) \
+          --dllname simple_vector.pyd \
+          --def simple_vector.def \
+          $(OBJ) simple_vector.o $(PYLIB)
+
+do_it_yourself_convts.pyd: $(OBJ) do_it_yourself_convts.o
+	dllwrap $(DLLWRAPOPTS) \
+          --dllname do_it_yourself_convts.pyd \
+          --def do_it_yourself_convts.def \
+          $(OBJ) do_it_yourself_convts.o $(PYLIB)
+
+nested.pyd: $(OBJ) nested.o
+	dllwrap $(DLLWRAPOPTS) \
+          --dllname nested.pyd \
+          --def nested.def \
+          $(OBJ) nested.o $(PYLIB)
+
+pickle1.pyd: $(OBJ) pickle1.o
+	dllwrap $(DLLWRAPOPTS) \
+          --dllname pickle1.pyd \
+          --def pickle1.def \
+          $(OBJ) pickle1.o $(PYLIB)
+
+pickle2.pyd: $(OBJ) pickle2.o
+	dllwrap $(DLLWRAPOPTS) \
+          --dllname pickle2.pyd \
+          --def pickle2.def \
+          $(OBJ) pickle2.o $(PYLIB)
+
+pickle3.pyd: $(OBJ) pickle3.o
+	dllwrap $(DLLWRAPOPTS) \
+          --dllname pickle3.pyd \
+          --def pickle3.def \
+          $(OBJ) pickle3.o $(PYLIB)
+
+noncopyable_export.pyd: $(OBJ) noncopyable_export.o
+	dllwrap $(DLLWRAPOPTS) \
+          --dllname noncopyable_export.pyd \
+          --def noncopyable_export.def \
+          $(OBJ) noncopyable_export.o $(PYLIB)
+
+noncopyable_import.pyd: $(OBJ) noncopyable_import.o
+	dllwrap $(DLLWRAPOPTS) \
+          --dllname noncopyable_import.pyd \
+          --def noncopyable_import.def \
+          $(OBJ) noncopyable_import.o $(PYLIB)
+
+ivect.pyd: $(OBJ) ivect.o
+	dllwrap $(DLLWRAPOPTS) \
+          --dllname ivect.pyd \
+          --def ivect.def \
+          $(OBJ) ivect.o $(PYLIB)
+
+dvect.pyd: $(OBJ) dvect.o
+	dllwrap $(DLLWRAPOPTS) \
+          --dllname dvect.pyd \
+          --def dvect.def \
+          $(OBJ) dvect.o $(PYLIB)
+
+richcmp1.pyd: $(OBJ) richcmp1.o
+	dllwrap $(DLLWRAPOPTS) \
+          --dllname richcmp1.pyd \
+          --def richcmp1.def \
+          $(OBJ) richcmp1.o $(PYLIB)
+
+richcmp2.pyd: $(OBJ) richcmp2.o
+	dllwrap $(DLLWRAPOPTS) \
+          --dllname richcmp2.pyd \
+          --def richcmp2.def \
+          $(OBJ) richcmp2.o $(PYLIB)
+
+richcmp3.pyd: $(OBJ) richcmp3.o
+	dllwrap $(DLLWRAPOPTS) \
+          --dllname richcmp3.pyd \
+          --def richcmp3.def \
+          $(OBJ) richcmp3.o $(PYLIB)
+
+.cpp.o:
+	$(CPP) $(CPPOPTS) -c $*.cpp
+
+test:
+#	$(PYEXE) comprehensive.py
+	$(PYEXE) test_abstract.py
+	$(PYEXE) test_getting_started1.py
+	$(PYEXE) test_getting_started2.py
+	$(PYEXE) test_simple_vector.py
+	$(PYEXE) test_do_it_yourself_convts.py
+	$(PYEXE) test_nested.py
+	$(PYEXE) test_pickle1.py
+	$(PYEXE) test_pickle2.py
+	$(PYEXE) test_pickle3.py
+	$(PYEXE) test_cross_module.py
+	$(PYEXE) test_richcmp1.py
+	$(PYEXE) test_richcmp2.py
+	$(PYEXE) test_richcmp3.py
+
+clean:
+	-del *.o
+	-del *.a
+	-del *.pyd
+	-del *.pyc
+
+softlinks:
+	python $(BOOST_UNIX)/libs/python/build/filemgr.py $(BOOST_UNIX) softlinks
+
+unlink:
+	python $(BOOST_UNIX)/libs/python/build/filemgr.py $(BOOST_UNIX) unlink
+
+cp:
+	python $(BOOST_UNIX)/libs/python/build/filemgr.py $(BOOST_UNIX) cp
+
+rm:
+	python $(BOOST_UNIX)/libs/python/build/filemgr.py $(BOOST_UNIX) rm
+
+copy:
+	$(PYEXE) $(BOOST_WIN)\libs\python\build\filemgr.py $(BOOST_WIN) copy
+
+del:
+	$(PYEXE) $(BOOST_WIN)\libs\python\build\filemgr.py $(BOOST_WIN) del

build/rwgk1/rwgk1.dsp

@@ -1,105 +0,0 @@
-# Microsoft Developer Studio Project File - Name="rwgk1" - Package Owner=<4>
-# Microsoft Developer Studio Generated Build File, Format Version 6.00
-# ** DO NOT EDIT **
-
-# TARGTYPE "Win32 (x86) Dynamic-Link Library" 0x0102
-
-CFG=rwgk1 - Win32 Debug
-!MESSAGE This is not a valid makefile. To build this project using NMAKE,
-!MESSAGE use the Export Makefile command and run
-!MESSAGE 
-!MESSAGE NMAKE /f "rwgk1.mak".
-!MESSAGE 
-!MESSAGE You can specify a configuration when running NMAKE
-!MESSAGE by defining the macro CFG on the command line. For example:
-!MESSAGE 
-!MESSAGE NMAKE /f "rwgk1.mak" CFG="rwgk1 - Win32 Debug"
-!MESSAGE 
-!MESSAGE Possible choices for configuration are:
-!MESSAGE 
-!MESSAGE "rwgk1 - Win32 Release" (based on "Win32 (x86) Dynamic-Link Library")
-!MESSAGE "rwgk1 - Win32 Debug" (based on "Win32 (x86) Dynamic-Link Library")
-!MESSAGE 
-
-# Begin Project
-# PROP AllowPerConfigDependencies 0
-# PROP Scc_ProjName ""
-# PROP Scc_LocalPath ""
-CPP=cl.exe
-MTL=midl.exe
-RSC=rc.exe
-
-!IF  "$(CFG)" == "rwgk1 - Win32 Release"
-
-# PROP BASE Use_MFC 0
-# PROP BASE Use_Debug_Libraries 0
-# PROP BASE Output_Dir "Release"
-# PROP BASE Intermediate_Dir "Release"
-# PROP BASE Target_Dir ""
-# PROP Use_MFC 0
-# PROP Use_Debug_Libraries 0
-# PROP Output_Dir "Release"
-# PROP Intermediate_Dir "Release"
-# PROP Target_Dir ""
-# ADD BASE CPP /nologo /MT /W3 /GX /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "RWGK1_EXPORTS" /YX /FD /c
-# ADD CPP /nologo /MD /W3 /GX /O2 /I "..\..\..\.." /I "c:\tools\python\include" /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "RWGK1_EXPORTS" /YX /FD /c
-# ADD BASE MTL /nologo /D "NDEBUG" /mktyplib203 /win32
-# ADD MTL /nologo /D "NDEBUG" /mktyplib203 /win32
-# ADD BASE RSC /l 0x409 /d "NDEBUG"
-# ADD RSC /l 0x409 /d "NDEBUG"
-BSC32=bscmake.exe
-# ADD BASE BSC32 /nologo
-# ADD BSC32 /nologo
-LINK32=link.exe
-# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /dll /machine:I386
-# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /dll /machine:I386 /libpath:"c:\tools\python\libs"
-
-!ELSEIF  "$(CFG)" == "rwgk1 - Win32 Debug"
-
-# PROP BASE Use_MFC 0
-# PROP BASE Use_Debug_Libraries 1
-# PROP BASE Output_Dir "Debug"
-# PROP BASE Intermediate_Dir "Debug"
-# PROP BASE Target_Dir ""
-# PROP Use_MFC 0
-# PROP Use_Debug_Libraries 1
-# PROP Output_Dir "Debug"
-# PROP Intermediate_Dir "Debug"
-# PROP Target_Dir ""
-# ADD BASE CPP /nologo /MTd /W3 /Gm /GX /ZI /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "RWGK1_EXPORTS" /YX /FD /GZ /c
-# ADD CPP /nologo /MDd /W3 /Gm /GX /ZI /Od /I "..\..\..\.." /I "c:\tools\python\include" /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "RWGK1_EXPORTS" /YX /FD /GZ /c
-# ADD BASE MTL /nologo /D "_DEBUG" /mktyplib203 /win32
-# ADD MTL /nologo /D "_DEBUG" /mktyplib203 /win32
-# ADD BASE RSC /l 0x409 /d "_DEBUG"
-# ADD RSC /l 0x409 /d "_DEBUG"
-BSC32=bscmake.exe
-# ADD BASE BSC32 /nologo
-# ADD BSC32 /nologo
-LINK32=link.exe
-# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /dll /debug /machine:I386 /pdbtype:sept
-# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /dll /debug /machine:I386 /pdbtype:sept /libpath:"c:\tools\python\libs"
-
-!ENDIF 
-
-# Begin Target
-
-# Name "rwgk1 - Win32 Release"
-# Name "rwgk1 - Win32 Debug"
-# Begin Group "Source Files"
-
-# PROP Default_Filter "cpp;c;cxx;rc;def;r;odl;idl;hpj;bat"
-# Begin Source File
-
-SOURCE=..\..\example\rwgk1.cpp
-# End Source File
-# End Group
-# Begin Group "Header Files"
-
-# PROP Default_Filter "h;hpp;hxx;hm;inl"
-# End Group
-# Begin Group "Resource Files"
-
-# PROP Default_Filter "ico;cur;bmp;dlg;rc2;rct;bin;rgs;gif;jpg;jpeg;jpe"
-# End Group
-# End Target
-# End Project

build/test/test.dsp

@@ -1,112 +0,0 @@
-# Microsoft Developer Studio Project File - Name="test" - Package Owner=<4>
-# Microsoft Developer Studio Generated Build File, Format Version 6.00
-# ** DO NOT EDIT **
-
-# TARGTYPE "Win32 (x86) Dynamic-Link Library" 0x0102
-
-CFG=test - Win32 Debug
-!MESSAGE This is not a valid makefile. To build this project using NMAKE,
-!MESSAGE use the Export Makefile command and run
-!MESSAGE 
-!MESSAGE NMAKE /f "test.mak".
-!MESSAGE 
-!MESSAGE You can specify a configuration when running NMAKE
-!MESSAGE by defining the macro CFG on the command line. For example:
-!MESSAGE 
-!MESSAGE NMAKE /f "test.mak" CFG="test - Win32 Debug"
-!MESSAGE 
-!MESSAGE Possible choices for configuration are:
-!MESSAGE 
-!MESSAGE "test - Win32 Release" (based on "Win32 (x86) Dynamic-Link Library")
-!MESSAGE "test - Win32 Debug" (based on "Win32 (x86) Dynamic-Link Library")
-!MESSAGE 
-
-# Begin Project
-# PROP AllowPerConfigDependencies 0
-# PROP Scc_ProjName ""
-# PROP Scc_LocalPath ""
-CPP=cl.exe
-MTL=midl.exe
-RSC=rc.exe
-
-!IF  "$(CFG)" == "test - Win32 Release"
-
-# PROP BASE Use_MFC 0
-# PROP BASE Use_Debug_Libraries 0
-# PROP BASE Output_Dir "Release"
-# PROP BASE Intermediate_Dir "Release"
-# PROP BASE Target_Dir ""
-# PROP Use_MFC 0
-# PROP Use_Debug_Libraries 0
-# PROP Output_Dir "Release"
-# PROP Intermediate_Dir "Release"
-# PROP Ignore_Export_Lib 0
-# PROP Target_Dir ""
-# ADD BASE CPP /nologo /MT /W3 /GX /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "TEST_EXPORTS" /YX /FD /c
-# ADD CPP /nologo /MD /W3 /GR /GX /O2 /I "..\..\..\.." /I "c:\tools\python\include" /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "TEST_EXPORTS" /YX /FD /Zm200 /c
-# ADD BASE MTL /nologo /D "NDEBUG" /mktyplib203 /win32
-# ADD MTL /nologo /D "NDEBUG" /mktyplib203 /win32
-# ADD BASE RSC /l 0x409 /d "NDEBUG"
-# ADD RSC /l 0x409 /d "NDEBUG"
-BSC32=bscmake.exe
-# ADD BASE BSC32 /nologo
-# ADD BSC32 /nologo
-LINK32=link.exe
-# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /dll /machine:I386
-# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /dll /machine:I386 /libpath:"c:\tools\python\libs"
-
-!ELSEIF  "$(CFG)" == "test - Win32 Debug"
-
-# PROP BASE Use_MFC 0
-# PROP BASE Use_Debug_Libraries 1
-# PROP BASE Output_Dir "Debug"
-# PROP BASE Intermediate_Dir "Debug"
-# PROP BASE Target_Dir ""
-# PROP Use_MFC 0
-# PROP Use_Debug_Libraries 1
-# PROP Output_Dir "Debug"
-# PROP Intermediate_Dir "Debug"
-# PROP Ignore_Export_Lib 0
-# PROP Target_Dir ""
-# ADD BASE CPP /nologo /MTd /W3 /Gm /GX /ZI /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "TEST_EXPORTS" /YX /FD /GZ  /c
-# ADD CPP /nologo /MDd /W3 /Gm /GR /GX /ZI /Od /I "..\..\..\.." /I "c:\tools\python\include" /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "TEST_EXPORTS" /YX /FD /GZ /Zm200 /c
-# ADD BASE MTL /nologo /D "_DEBUG" /mktyplib203 /win32
-# ADD MTL /nologo /D "_DEBUG" /mktyplib203 /win32
-# ADD BASE RSC /l 0x409 /d "_DEBUG"
-# ADD RSC /l 0x409 /d "_DEBUG"
-BSC32=bscmake.exe
-# ADD BASE BSC32 /nologo
-# ADD BSC32 /nologo
-LINK32=link.exe
-# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /dll /debug /machine:I386 /pdbtype:sept
-# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /dll /debug /machine:I386 /pdbtype:sept /libpath:"c:\tools\python\libs"
-# SUBTRACT LINK32 /pdb:none
-
-!ENDIF 
-
-# Begin Target
-
-# Name "test - Win32 Release"
-# Name "test - Win32 Debug"
-# Begin Group "Source Files"
-
-# PROP Default_Filter "cpp;c;cxx;rc;def;r;odl;idl;hpj;bat"
-# Begin Source File
-
-SOURCE=..\..\test\comprehensive.cpp
-# End Source File
-# End Group
-# Begin Group "Header Files"
-
-# PROP Default_Filter "h;hpp;hxx;hm;inl"
-# Begin Source File
-
-SOURCE=..\..\test\comprehensive.hpp
-# End Source File
-# End Group
-# Begin Group "Resource Files"
-
-# PROP Default_Filter "ico;cur;bmp;dlg;rc2;rct;bin;rgs;gif;jpg;jpeg;jpe"
-# End Group
-# End Target
-# End Project

build/tru64.mak

@@ -1,51 +0,0 @@
-#
-# Tested with:
-# Compaq C++ V6.2-024 for Digital UNIX V5.0 (Rev. 910)
-#
-# Python 1.5.2 was installed without any customizations.
-# boost_all.zip vers. 1.18.1 was unpacked using unzip -aa and not modified.
-# STLport-4.1b3 was unpacked using unzip -aa and not modified.
-#
-# Initial version 2000-10-20: Ralf W. Grosse-Kunstleve, rwgk@cci.lbl.gov
-#
-
-PYINC= /usr/local/include/python1.5
-BOOSTINC= /usr/local/boost_1_18_1
-STLPORTINC= /usr/local/STLport-4.1b3/stlport
-STLPORTOPTS= \
- -D__USE_STD_IOSTREAM \
- -D__STL_NO_SGI_IOSTREAMS \
- -D__STL_NO_NEW_C_HEADERS \
- -D_RWSTD_COMPILE_INSTANTIATE=1
-
-STDOPTS= -std strict_ansi
-WARNOPTS= -msg_disable 186,450,1115
-# use -msg_display_number to obtain integer tags for -msg_disable
-
-CPP= cxx
-CPPOPTS= -I$(STLPORTINC) $(STLPORTOPTS) -I$(BOOSTINC) -I$(PYINC) \
-         $(STDOPTS) $(WARNOPTS)
-
-LD= cxx
-LDOPTS= -shared -expect_unresolved '*'
-
-OBJ = extclass.o functions.o init_function.o module.o newtypes.o \
-      objects.o py.o subclass.o
-
-.SUFFIXES: .o .cpp
-
-all: demo.so hello.so
-
-demo.so: $(OBJ) extclass_demo.o
-	$(LD) $(LDOPTS) $(OBJ) extclass_demo.o -o demo.so
-
-hello.so: $(OBJ) example1.o
-	$(LD) $(LDOPTS) $(OBJ) example1.o -o hello.so
-
-.cpp.o:
-	-$(CPP) $(CPPOPTS) $(INC) -c $*.cpp
-
-clean:
-	rm -f $(OBJ) extclass_demo.o example1.o demo.so hello.so so_locations
-	rm -rf cxx_repository
-	rm -f *.pyc

build/tru64_cxx.mak

@@ -0,0 +1,199 @@
+# Usage:
+#
+#   Create a new empty directory anywhere (preferably not in the boost tree).
+#   Copy this Makefile to that new directory and rename it to "Makefile"
+#   Adjust the pathnames below.
+#
+#   make softlinks     Create softlinks to source code and tests
+#   make               Compile all sources
+#   make test          Run doctest tests
+#   make clean         Remove all object files
+#   make unlink        Remove softlinks
+#
+# Revision history:
+#   12 Apr 01 new macro ROOT to simplify configuration (R.W. Grosse-Kunstleve)
+#   Initial version: R.W. Grosse-Kunstleve
+
+ROOT=$(HOME)
+BOOST=$(ROOT)/boost
+
+#PYEXE=PYTHONPATH=. /usr/local/Python-1.5.2/bin/python
+#PYINC=-I/usr/local/Python-1.5.2/include/python1.5
+PYEXE=PYTHONPATH=. /usr/local_cci/Python-2.1.1/bin/python
+PYINC=-I/usr/local_cci/Python-2.1.1/include/python2.1
+#STLPORTINC=-I/usr/local/STLport-4.1b3/stlport
+#STLPORTINC=-I/usr/local/STLport-4.1b4/stlport
+#STLPORTOPTS= \
+# -D__USE_STD_IOSTREAM \
+# -D__STL_NO_SGI_IOSTREAMS \
+# -D__STL_USE_NATIVE_STRING \
+# -D__STL_NO_NEW_C_HEADERS \
+# -D_RWSTD_COMPILE_INSTANTIATE=1
+STLPORTINC=-I$(BOOST)/boost/compatibility/cpp_c_headers
+
+STDOPTS=-std strict_ansi
+# use -msg_display_number to obtain integer tags for -msg_disable
+WARNOPTS=-msg_disable 186,450,1115
+OPTOPTS=-g
+
+CPP=cxx
+CPPOPTS=$(STLPORTINC) $(STLPORTOPTS) -I$(BOOST) $(PYINC) \
+        $(STDOPTS) $(WARNOPTS) $(OPTOPTS)
+MAKEDEP=-Em
+
+LD=cxx
+LDOPTS=-shared -expect_unresolved 'Py*' -expect_unresolved '_Py*'
+
+#HIDDEN=-hidden
+
+OBJ=classes.o conversions.o errors.o extension_class.o functions.o \
+    init_function.o module_builder.o \
+    objects.o types.o cross_module.o
+DEPOBJ=$(OBJ) \
+       comprehensive.o \
+       abstract.o \
+       getting_started1.o getting_started2.o \
+       simple_vector.o \
+       do_it_yourself_convts.o \
+       nested.o \
+       pickle1.o pickle2.o pickle3.o \
+       noncopyable_export.o noncopyable_import.o \
+       ivect.o dvect.o \
+       richcmp1.o richcmp2.o richcmp3.o
+
+.SUFFIXES: .o .cpp
+
+all: libboost_python.a \
+     boost_python_test.so \
+     abstract.so \
+     getting_started1.so getting_started2.so \
+     simple_vector.so \
+     do_it_yourself_convts.so \
+     nested.so \
+     pickle1.so pickle2.so pickle3.so \
+     noncopyable_export.so noncopyable_import.so \
+     ivect.so dvect.so \
+     richcmp1.so richcmp2.so richcmp3.so
+
+libboost_python.a: $(OBJ)
+	rm -f libboost_python.a
+	cd cxx_repository; \
+          ls -1 > ../libboost_python.a.input; \
+          ar r ../libboost_python.a -input ../libboost_python.a.input
+	rm -f libboost_python.a.input
+	ar r libboost_python.a $(OBJ)
+
+boost_python_test.so: $(OBJ) comprehensive.o
+	$(LD) $(LDOPTS) $(OBJ) comprehensive.o -o boost_python_test.so -lm
+
+abstract.so: $(OBJ) abstract.o
+	$(LD) $(LDOPTS) $(OBJ) abstract.o -o abstract.so
+
+getting_started1.so: $(OBJ) getting_started1.o
+	$(LD) $(LDOPTS) $(OBJ) getting_started1.o -o getting_started1.so
+
+getting_started2.so: $(OBJ) getting_started2.o
+	$(LD) $(LDOPTS) $(OBJ) getting_started2.o -o getting_started2.so
+
+simple_vector.so: $(OBJ) simple_vector.o
+	$(LD) $(LDOPTS) $(OBJ) simple_vector.o -o simple_vector.so
+
+do_it_yourself_convts.so: $(OBJ) do_it_yourself_convts.o
+	$(LD) $(LDOPTS) $(OBJ) do_it_yourself_convts.o -o do_it_yourself_convts.so
+
+nested.so: $(OBJ) nested.o
+	$(LD) $(LDOPTS) $(OBJ) nested.o -o nested.so
+
+pickle1.so: $(OBJ) pickle1.o
+	$(LD) $(LDOPTS) $(OBJ) pickle1.o -o pickle1.so
+
+pickle2.so: $(OBJ) pickle2.o
+	$(LD) $(LDOPTS) $(OBJ) pickle2.o -o pickle2.so
+
+pickle3.so: $(OBJ) pickle3.o
+	$(LD) $(LDOPTS) $(OBJ) pickle3.o -o pickle3.so
+
+noncopyable_export.so: $(OBJ) noncopyable_export.o
+	$(LD) $(LDOPTS) $(OBJ) $(HIDDEN) \
+          noncopyable_export.o -o noncopyable_export.so
+
+noncopyable_import.so: $(OBJ) noncopyable_import.o
+	$(LD) $(LDOPTS) $(OBJ) $(HIDDEN) \
+          noncopyable_import.o -o noncopyable_import.so
+
+ivect.so: $(OBJ) ivect.o
+	$(LD) $(LDOPTS) $(OBJ) $(HIDDEN) ivect.o -o ivect.so
+
+dvect.so: $(OBJ) dvect.o
+	$(LD) $(LDOPTS) $(OBJ) $(HIDDEN) dvect.o -o dvect.so
+
+richcmp1.so: $(OBJ) richcmp1.o
+	$(LD) $(LDOPTS) $(OBJ) richcmp1.o -o richcmp1.so
+
+richcmp2.so: $(OBJ) richcmp2.o
+	$(LD) $(LDOPTS) $(OBJ) richcmp2.o -o richcmp2.so
+
+richcmp3.so: $(OBJ) richcmp3.o
+	$(LD) $(LDOPTS) $(OBJ) richcmp3.o -o richcmp3.so
+
+.cpp.o:
+	$(CPP) $(CPPOPTS) -c $*.cpp
+
+test:
+	$(PYEXE) comprehensive.py
+	$(PYEXE) test_abstract.py
+	$(PYEXE) test_getting_started1.py
+	$(PYEXE) test_getting_started2.py
+	$(PYEXE) test_simple_vector.py
+	$(PYEXE) test_do_it_yourself_convts.py
+	$(PYEXE) test_nested.py
+	$(PYEXE) test_pickle1.py
+	$(PYEXE) test_pickle2.py
+	$(PYEXE) test_pickle3.py
+	$(PYEXE) test_cross_module.py
+	$(PYEXE) test_richcmp1.py
+	$(PYEXE) test_richcmp2.py
+	$(PYEXE) test_richcmp3.py
+
+clean:
+	rm -f $(OBJ) libboost_python.a libboost_python.a.input
+	rm -f comprehensive.o boost_python_test.so
+	rm -f abstract.o abstract.so
+	rm -f getting_started1.o getting_started1.so
+	rm -f getting_started2.o getting_started2.so
+	rm -f simple_vector.o simple_vector.so
+	rm -f do_it_yourself_convts.o do_it_yourself_convts.so
+	rm -f nested.o nested.so
+	rm -f pickle1.o pickle1.so
+	rm -f pickle2.o pickle2.so
+	rm -f pickle3.o pickle3.so
+	rm -f noncopyable_export.o noncopyable_export.so
+	rm -f noncopyable_import.o noncopyable_import.so
+	rm -f ivect.o ivect.so
+	rm -f dvect.o dvect.so
+	rm -f richcmp1.o richcmp1.so
+	rm -f richcmp2.o richcmp2.so
+	rm -f richcmp3.o richcmp3.so
+	rm -f so_locations *.pyc
+	rm -rf cxx_repository
+
+softlinks:
+	$(PYEXE) $(BOOST)/libs/python/build/filemgr.py $(BOOST) softlinks
+
+unlink:
+	$(PYEXE) $(BOOST)/libs/python/build/filemgr.py $(BOOST) unlink
+
+cp:
+	$(PYEXE) $(BOOST)/libs/python/build/filemgr.py $(BOOST) cp
+
+rm:
+	$(PYEXE) $(BOOST)/libs/python/build/filemgr.py $(BOOST) rm
+
+depend:
+	@ cat Makefile.nodepend; \
+          for obj in $(DEPOBJ); \
+          do \
+            bn=`echo "$$obj" | cut -d. -f1`; \
+            $(CPP) $(CPPOPTS) $(MAKEDEP) "$$bn".cpp; \
+          done
+

build/vc60.mak

@@ -0,0 +1,154 @@
+# Usage:
+#
+#   Create a new empty directory anywhere (preferably not in the boost tree).
+#   Copy this Makefile to that new directory and rename it to "Makefile"
+#   Adjust the pathnames below.
+#
+#   make copy          Copy the sources and tests
+#   make               Compile all sources
+#   make test          Run doctest tests
+#   make clean         Remove all object files
+#   make del           Remove the sources and tests
+#
+# Revision history:
+#   12 Apr 01 new macro ROOT to simplify configuration (R.W. Grosse-Kunstleve)
+#   Initial version: R.W. Grosse-Kunstleve
+
+ROOT=R:
+BOOST_WIN="$(ROOT)\boost"
+BOOST_UNIX=$(HOME)/boost
+
+#PYEXE="C:\Program files\Python\python.exe"
+#PYINC=/I"C:\Program files\Python\include"
+#PYLIB="C:\Program files\Python\libs\python15.lib"
+PYEXE="C:\Python21\python.exe"
+PYINC=/I"C:\Python21\include"
+PYLIB="C:\Python21\libs\python21.lib"
+
+STDOPTS=/nologo /MD /GR /GX /Zm300 /DBOOST_PYTHON_STATIC_LIB
+WARNOPTS=
+OPTOPTS=
+
+CPP=cl.exe
+CPPOPTS=$(STLPORTINC) $(STLPORTOPTS) /I$(BOOST_WIN) $(PYINC) \
+        $(STDOPTS) $(WARNOPTS) $(OPTOPTS)
+
+LD=link.exe
+LDOPTS=/nologo /dll /incremental:no
+
+OBJ=classes.obj conversions.obj errors.obj extension_class.obj functions.obj \
+    init_function.obj module_builder.obj \
+    objects.obj types.obj cross_module.obj
+
+.SUFFIXES: .obj .cpp
+
+all: boost_python.lib \
+     boost_python_test.pyd \
+     abstract.pyd \
+     getting_started1.pyd getting_started2.pyd \
+     simple_vector.pyd \
+     do_it_yourself_convts.pyd \
+     nested.pyd \
+     pickle1.pyd pickle2.pyd pickle3.pyd \
+     noncopyable_export.pyd noncopyable_import.pyd \
+     ivect.pyd dvect.pyd \
+     richcmp1.pyd richcmp2.pyd richcmp3.pyd
+
+boost_python.lib: $(OBJ)
+	$(LD) -lib /nologo /out:boost_python.lib $(OBJ)
+
+boost_python_test.pyd: $(OBJ) comprehensive.obj
+	$(LD) $(LDOPTS) $(OBJ) comprehensive.obj $(PYLIB) /export:initboost_python_test /out:"boost_python_test.pyd"
+
+abstract.pyd: $(OBJ) abstract.obj
+	$(LD) $(LDOPTS) $(OBJ) abstract.obj $(PYLIB) /export:initabstract /out:"abstract.pyd"
+
+getting_started1.pyd: $(OBJ) getting_started1.obj
+	$(LD) $(LDOPTS) $(OBJ) getting_started1.obj $(PYLIB) /export:initgetting_started1 /out:"getting_started1.pyd"
+
+getting_started2.pyd: $(OBJ) getting_started2.obj
+	$(LD) $(LDOPTS) $(OBJ) getting_started2.obj $(PYLIB) /export:initgetting_started2 /out:"getting_started2.pyd"
+
+simple_vector.pyd: $(OBJ) simple_vector.obj
+	$(LD) $(LDOPTS) $(OBJ) simple_vector.obj $(PYLIB) /export:initsimple_vector /out:"simple_vector.pyd"
+
+do_it_yourself_convts.pyd: $(OBJ) do_it_yourself_convts.obj
+	$(LD) $(LDOPTS) $(OBJ) do_it_yourself_convts.obj $(PYLIB) /export:initdo_it_yourself_convts /out:"do_it_yourself_convts.pyd"
+
+nested.pyd: $(OBJ) nested.obj
+	$(LD) $(LDOPTS) $(OBJ) nested.obj $(PYLIB) /export:initnested /out:"nested.pyd"
+
+pickle1.pyd: $(OBJ) pickle1.obj
+	$(LD) $(LDOPTS) $(OBJ) pickle1.obj $(PYLIB) /export:initpickle1 /out:"pickle1.pyd"
+
+pickle2.pyd: $(OBJ) pickle2.obj
+	$(LD) $(LDOPTS) $(OBJ) pickle2.obj $(PYLIB) /export:initpickle2 /out:"pickle2.pyd"
+
+pickle3.pyd: $(OBJ) pickle3.obj
+	$(LD) $(LDOPTS) $(OBJ) pickle3.obj $(PYLIB) /export:initpickle3 /out:"pickle3.pyd"
+
+noncopyable_export.pyd: $(OBJ) noncopyable_export.obj
+	$(LD) $(LDOPTS) $(OBJ) noncopyable_export.obj $(PYLIB) /export:initnoncopyable_export /out:"noncopyable_export.pyd"
+
+noncopyable_import.pyd: $(OBJ) noncopyable_import.obj
+	$(LD) $(LDOPTS) $(OBJ) noncopyable_import.obj $(PYLIB) /export:initnoncopyable_import /out:"noncopyable_import.pyd"
+
+ivect.pyd: $(OBJ) ivect.obj
+	$(LD) $(LDOPTS) $(OBJ) ivect.obj $(PYLIB) /export:initivect /out:"ivect.pyd"
+
+dvect.pyd: $(OBJ) dvect.obj
+	$(LD) $(LDOPTS) $(OBJ) dvect.obj $(PYLIB) /export:initdvect /out:"dvect.pyd"
+
+richcmp1.pyd: $(OBJ) richcmp1.obj
+	$(LD) $(LDOPTS) $(OBJ) richcmp1.obj $(PYLIB) /export:initrichcmp1 /out:"richcmp1.pyd"
+
+richcmp2.pyd: $(OBJ) richcmp2.obj
+	$(LD) $(LDOPTS) $(OBJ) richcmp2.obj $(PYLIB) /export:initrichcmp2 /out:"richcmp2.pyd"
+
+richcmp3.pyd: $(OBJ) richcmp3.obj
+	$(LD) $(LDOPTS) $(OBJ) richcmp3.obj $(PYLIB) /export:initrichcmp3 /out:"richcmp3.pyd"
+
+.cpp.obj:
+	$(CPP) $(CPPOPTS) /c $*.cpp
+
+test:
+	$(PYEXE) comprehensive.py --broken-auto-ptr 
+	$(PYEXE) test_abstract.py
+	$(PYEXE) test_getting_started1.py
+	$(PYEXE) test_getting_started2.py
+	$(PYEXE) test_simple_vector.py
+	$(PYEXE) test_do_it_yourself_convts.py
+	$(PYEXE) test_nested.py
+	$(PYEXE) test_pickle1.py
+	$(PYEXE) test_pickle2.py
+	$(PYEXE) test_pickle3.py
+	$(PYEXE) test_cross_module.py --broken-auto-ptr
+	$(PYEXE) test_richcmp1.py
+	$(PYEXE) test_richcmp2.py
+	$(PYEXE) test_richcmp3.py
+
+clean:
+	-del *.obj
+	-del *.lib
+	-del *.exp
+	-del *.idb
+	-del *.pyd
+	-del *.pyc
+
+softlinks:
+	python $(BOOST_UNIX)/libs/python/build/filemgr.py $(BOOST_UNIX) softlinks
+
+unlink:
+	python $(BOOST_UNIX)/libs/python/build/filemgr.py $(BOOST_UNIX) unlink
+
+cp:
+	python $(BOOST_UNIX)/libs/python/build/filemgr.py $(BOOST_UNIX) cp
+
+rm:
+	python $(BOOST_UNIX)/libs/python/build/filemgr.py $(BOOST_UNIX) rm
+
+copy:
+	$(PYEXE) $(BOOST_WIN)\libs\python\build\filemgr.py $(BOOST_WIN) copy
+
+del:
+	$(PYEXE) $(BOOST_WIN)\libs\python\build\filemgr.py $(BOOST_WIN) del

build/win32_mwcc.mak

@@ -0,0 +1,149 @@
+# Usage:
+#
+#   make copy          Copy the sources and tests
+#   make               Compile all sources
+#   make test          Run doctest tests
+#   make clean         Remove all object files
+#   make del           Remove the sources and tests
+#
+# Revision history:
+#   14 Dec 01 derived from vc60.mak (R.W. Grosse-Kunstleve)
+
+ROOT=R:
+BOOST_WIN="$(ROOT)\boost"
+BOOST_UNIX=$(HOME)/boost
+
+#PYEXE="C:\Program files\Python\python.exe"
+#PYINC=-I"C:\Program files\Python\include"
+#PYLIB="C:\Program files\Python\libs\python15.lib"
+PYEXE="C:\Python21\python.exe"
+PYINC=-I"C:\Python21\include"
+PYLIB="C:\Python21\libs\python21.lib"
+
+STDOPTS=-gccinc -prefix UseDLLPrefix.h -DBOOST_PYTHON_STATIC_LIB
+WARNOPTS=-warn on,nounusedexpr,nounused
+OPTOPTS=-O
+
+CPP=mwcc
+CPPOPTS=$(STDOPTS) $(WARNOPTS) $(OPTOPTS) \
+        $(STLPORTINC) $(STLPORTOPTS) -I$(BOOST_WIN) $(PYINC)
+
+LD=mwld
+LDOPTS=-export dllexport -shared
+
+OBJ=classes.obj conversions.obj errors.obj extension_class.obj functions.obj \
+    init_function.obj module_builder.obj \
+    objects.obj types.obj cross_module.obj
+
+.SUFFIXES: .obj .cpp
+
+all: libboost_python.lib \
+     boost_python_test.pyd \
+     abstract.pyd \
+     getting_started1.pyd getting_started2.pyd \
+     simple_vector.pyd \
+     do_it_yourself_convts.pyd \
+     nested.pyd \
+     pickle1.pyd pickle2.pyd pickle3.pyd \
+     noncopyable_export.pyd noncopyable_import.pyd \
+     ivect.pyd dvect.pyd \
+     richcmp1.pyd richcmp2.pyd richcmp3.pyd
+
+libboost_python.lib: $(OBJ)
+	$(LD) -library -o libboost_python.lib $(OBJ)
+
+boost_python_test.pyd: $(OBJ) comprehensive.obj
+	$(LD) $(LDOPTS) $(OBJ) comprehensive.obj $(PYLIB) -o boost_python_test.pyd
+
+abstract.pyd: $(OBJ) abstract.obj
+	$(LD) $(LDOPTS) $(OBJ) abstract.obj $(PYLIB)  -o abstract.pyd
+
+getting_started1.pyd: $(OBJ) getting_started1.obj
+	$(LD) $(LDOPTS) $(OBJ) getting_started1.obj $(PYLIB)  -o getting_started1.pyd
+
+getting_started2.pyd: $(OBJ) getting_started2.obj
+	$(LD) $(LDOPTS) $(OBJ) getting_started2.obj $(PYLIB)  -o getting_started2.pyd
+
+simple_vector.pyd: $(OBJ) simple_vector.obj
+	$(LD) $(LDOPTS) $(OBJ) simple_vector.obj $(PYLIB)  -o simple_vector.pyd
+
+do_it_yourself_convts.pyd: $(OBJ) do_it_yourself_convts.obj
+	$(LD) $(LDOPTS) $(OBJ) do_it_yourself_convts.obj $(PYLIB)  -o do_it_yourself_convts.pyd
+
+nested.pyd: $(OBJ) nested.obj
+	$(LD) $(LDOPTS) $(OBJ) nested.obj $(PYLIB)  -o nested.pyd
+
+pickle1.pyd: $(OBJ) pickle1.obj
+	$(LD) $(LDOPTS) $(OBJ) pickle1.obj $(PYLIB)  -o pickle1.pyd
+
+pickle2.pyd: $(OBJ) pickle2.obj
+	$(LD) $(LDOPTS) $(OBJ) pickle2.obj $(PYLIB)  -o pickle2.pyd
+
+pickle3.pyd: $(OBJ) pickle3.obj
+	$(LD) $(LDOPTS) $(OBJ) pickle3.obj $(PYLIB)  -o pickle3.pyd
+
+noncopyable_export.pyd: $(OBJ) noncopyable_export.obj
+	$(LD) $(LDOPTS) $(OBJ) noncopyable_export.obj $(PYLIB)  -o noncopyable_export.pyd
+
+noncopyable_import.pyd: $(OBJ) noncopyable_import.obj
+	$(LD) $(LDOPTS) $(OBJ) noncopyable_import.obj $(PYLIB)  -o noncopyable_import.pyd
+
+ivect.pyd: $(OBJ) ivect.obj
+	$(LD) $(LDOPTS) $(OBJ) ivect.obj $(PYLIB)  -o ivect.pyd
+
+dvect.pyd: $(OBJ) dvect.obj
+	$(LD) $(LDOPTS) $(OBJ) dvect.obj $(PYLIB)  -o dvect.pyd
+
+richcmp1.pyd: $(OBJ) richcmp1.obj
+	$(LD) $(LDOPTS) $(OBJ) richcmp1.obj $(PYLIB)  -o richcmp1.pyd
+
+richcmp2.pyd: $(OBJ) richcmp2.obj
+	$(LD) $(LDOPTS) $(OBJ) richcmp2.obj $(PYLIB)  -o richcmp2.pyd
+
+richcmp3.pyd: $(OBJ) richcmp3.obj
+	$(LD) $(LDOPTS) $(OBJ) richcmp3.obj $(PYLIB)  -o richcmp3.pyd
+
+.cpp.obj:
+	$(CPP) $(CPPOPTS) -c $*.cpp
+
+test:
+	$(PYEXE) comprehensive.py
+	$(PYEXE) test_abstract.py
+	$(PYEXE) test_getting_started1.py
+	$(PYEXE) test_getting_started2.py
+	$(PYEXE) test_simple_vector.py
+	$(PYEXE) test_do_it_yourself_convts.py
+	$(PYEXE) test_nested.py
+	$(PYEXE) test_pickle1.py
+	$(PYEXE) test_pickle2.py
+	$(PYEXE) test_pickle3.py
+	$(PYEXE) test_cross_module.py
+	$(PYEXE) test_richcmp1.py
+	$(PYEXE) test_richcmp2.py
+	$(PYEXE) test_richcmp3.py
+
+clean:
+	-del *.obj
+	-del *.lib
+	-del *.exp
+	-del *.idb
+	-del *.pyd
+	-del *.pyc
+
+softlinks:
+	python $(BOOST_UNIX)/libs/python/build/filemgr.py $(BOOST_UNIX) softlinks
+
+unlink:
+	python $(BOOST_UNIX)/libs/python/build/filemgr.py $(BOOST_UNIX) unlink
+
+cp:
+	python $(BOOST_UNIX)/libs/python/build/filemgr.py $(BOOST_UNIX) cp
+
+rm:
+	python $(BOOST_UNIX)/libs/python/build/filemgr.py $(BOOST_UNIX) rm
+
+copy:
+	$(PYEXE) $(BOOST_WIN)\libs\python\build\filemgr.py $(BOOST_WIN) copy
+
+del:
+	$(PYEXE) $(BOOST_WIN)\libs\python\build\filemgr.py $(BOOST_WIN) del

build/win32_mwcc_setup.bat

@@ -0,0 +1,2 @@
+call "c:\program files\metrowerks\codewarrior\other metrowerks tools\command line tools\cwenv.bat"
+set MWWinx86LibraryFiles=MSL_All-DLL_x86.lib;gdi32.lib;user32.lib;kernel32.lib

doc/boost.css

@@ -0,0 +1,59 @@
+H1
+{
+    FONT-SIZE: 200%
+    COLOR: #00007f
+}
+H2
+{
+    FONT-SIZE: 150%;
+}
+H3
+{
+    FONT-SIZE: 125%;
+}
+H4
+{
+    FONT-SIZE: 108%;
+}
+BODY
+{
+    FONT-SIZE: 100%;
+    BACKGROUND-COLOR: #ffffff
+}
+PRE
+{
+    MARGIN-LEFT: 2pc;
+    FONT-SIZE: 80%;
+    BACKGROUND-COLOR: #dfffff
+}
+CODE
+{
+    FONT-SIZE: 95%;
+     white-space: pre
+}
+.index
+{
+    TEXT-ALIGN: left
+}
+.page-index
+{
+	TEXT-ALIGN: left
+}
+.definition
+{
+	TEXT-ALIGN: left
+}
+.footnote
+{
+    FONT-SIZE: 66%;
+    VERTICAL-ALIGN: super;
+    TEXT-DECORATION: none
+}
+.function-semantics
+{
+    CLEAR: left
+}
+.metafunction-semantics
+{
+    CLEAR: left
+}

doc/building.html

@@ -1,44 +1,222 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN"
-"http://www.w3.org/TR/REC-html40/strict.dtd">
-    <title>
-      Building an Extension Module
-    </title>
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+
+    <meta name="generator" content="HTML Tidy, see www.w3.org">
+
+    <title>Building an Extension Module</title>
+
     <div>
-      <h1>
-         <img width="277" height="86" id="_x0000_i1025" align="center"
-        src="../../../c++boost.gif" alt= "c++boost.gif (8819 bytes)">Building an Extension Module
-      </h1>
-      <p>
-         Right now, the only supported configuration is one in which the BPL
-         source files are statically linked with the source for your extension
-         module. You may first build them into a library and link it with your
-         extension module source, but the effect is the same as compiling all
-         the source files together. Some users have successfully built the
-         sources into a shared library, and support for a shared library
-         build is planned, but not yet implemented. The BPL source files are:
+      <h1><img width="277" height="86" align="center" src=
+      "../../../c++boost.gif" alt="c++boost.gif (8819 bytes)">Building an
+      Extension Module</h1>
+
+      <h2>Building Boost.Python</h2>
+
+      <p>Every Boost.Python extension module must be linked with the
+      <code>boost_python</code> shared library. To build
+      <code>boost_python</code>, use <a
+      href="../../../tools/build/index.html">Boost.Build</a> in the
+      usual way from the <code>libs/python/build</code> subdirectory
+      of your boost installation (if you have already built boost from
+      the top level this may have no effect, since the work is already
+      done). 
+
+      <h3>Configuration</h3>
+        You may need to configure the following variables to point Boost.Build at your Python installation:
+
+<table border="1">
+<tr><th>Variable Name <th>Semantics <th>Default <th>Notes
+   <tr>
+        <td><code>PYTHON_ROOT</code>
+        <td>The root directory of your Python installation
+        <td>Windows:&nbsp;<code>c:/tools/python</code>
+        Unix:&nbsp;<code>/usr/local</code>
+        <td>On Unix, this is the <code>--with-prefix=</code> directory
+        used to configure Python
+
+   <tr>
+        <td><code>PYTHON_VERSION</code>
+        <td>The The 2-part python Major.Minor version number
+        <td>Windows:&nbsp;<code>2.1</code>
+        Unix:&nbsp;<code>1.5</code>
+        <td>Be sure not to include a third number, e.g. <b>not</b>
+        &quot;<code>2.2.1</code>&quot;, even if that's the version you
+        have.
+
+   <tr>
+        <td><code>PYTHON_INCLUDES</code>
+        <td>path to Python <code>#include</code> directories
+        <td>Autoconfigured from <code>PYTHON_ROOT</code>
+
+   <tr>
+        <td><code>PYTHON_LIB_PATH</code>
+        <td>path to Python library object.
+        <td>Autoconfigured from <code>PYTHON_ROOT</code>
+
+   <tr>
+        <td><code>PYTHON_STDLIB_PATH</code>
+        <td>path to Python standard library modules
+        <td>Autoconfigured from <code>PYTHON_ROOT</code>
+
+   <tr>
+        <td><code>CYGWIN_ROOT</code>
+        <td>path to the user's Cygwin installation
+        <td>
+        <td><a href="http://www.cygwin.com">Cygwin</a> only. This and the following two settings are
+        useful when building with multiple toolsets on Windows, since
+        Cygwin requires a different build of Python.
+
+   <tr>
+        <td><code>GCC_PYTHON_ROOT</code>
+        <td>path to the user's Cygwin Python installation
+        <td><code>$(CYGWIN_ROOT)/usr/local</code>
+        <td><a href="http://www.cygwin.com">Cygwin</a> only
+
+   <tr>
+        <td><code>GCC_DEBUG_PYTHON_ROOT</code>
+        <td>path to the user's Cygwin <code><a
+        href="#variants">pydebug</a></code> build
+        <td><code>$(CYGWIN_ROOT)/usr/local/pydebug</code>
+        <td><a href="http://www.cygwin.com">Cygwin</a> only
+
+</table>
+
+<h3>Results</h3>
+      <p>The build process will create a
+      <code>libs/python/build/bin-stage</code> subdirectory of the
+      boost root (or of <code>$(ALL_LOCATE_TARGET)</code>,
+      if you have set that variable), containing the built
+      libraries. The libraries are actually built to unique
+      directories for each toolset and variant elsewhere in the
+      filesystem, and copied to the
+      <code>bin-stage</code> directory as a convenience, so if you
+      build with multiple toolsets at once, the product of later
+      toolsets will overwrite that of earlier toolsets in
+      <code>bin-stage</code>.
+
+<h3>Testing</h3>
+      <p>To build and test Boost.Python from within the
+      <code>libs/python/build</code> directory, invoke
 <blockquote>
 <pre>
-<a href="../../../libs/python/src/extension_class.cpp">extclass.cpp</a>
-<a href="../../../libs/python/src/functions.cpp">functions.cpp</a>
-<a href="../../../libs/python/src/init_function.cpp">init_function.cpp</a>
-<a href="../../../libs/python/src/module_builder.cpp">module.cpp</a>
-<a href="../../../libs/python/src/types.cpp">newtypes.cpp</a>
-<a href="../../../libs/python/src/objects.cpp">objects.cpp</a>
-<a href="../../../libs/python/src/conversions.cpp">py.cpp</a>
-<a href="../../../libs/python/src/classes.cpp">subclass.cpp</a>
-         </pre>
-         </blockquote>
-               <p>
-         Next: <a href="enums.html">Enums</a>
-         Previous: <a href="under-the-hood.html">A Peek Under the Hood</a>
-         Up: <a href="index.html">Top</a>
-      <p>
-         &copy; Copyright David Abrahams 2000. Permission to copy, use, modify,
-        sell and distribute this document is granted provided this copyright
-        notice appears in all copies. This document is provided &ldquo;as
-        is&rdquo; without express or implied warranty, and with no claim as to
-        its suitability for any purpose.
-      <p>
-         Updated: Nov 26, 2000
-    </div>
+bjam -sTOOLS=<i><a href="../../../tools/build/index.html#Tools">toolset</a></i> test
+</pre>
+</blockquote>
+This will
+update all of the Boost.Python v1 test and example targets. The tests
+are relatively quiet by default. To get more-verbose output, you might try
+<blockquote>
+<pre>
+bjam -sTOOLS=<i><a href="../../../tools/build/index.html#Tools">toolset</a></i> -sPYTHON_TEST_ARGS=-v test
+</pre>
+</blockquote>
+which will print each test's Python code with the expected output as
+it passes.
 
+<h2>Building your Extension Module</h2>
+
+      Though there are other approaches, the easiest way to build an
+      extension module using Boost.Python is with Boost.Build. Until
+      Boost.Build v2 is released, cross-project build dependencies are
+      not supported, so it works most smoothly if you add a new
+      subproject to your boost installation. The
+      <code>libs/python/example</code> subdirectory of your boost
+      installation contains a minimal example (along with many extra
+      sources). To copy the example subproject:
+
+      <ol>
+      <li>Create a new subdirectory in, <code>libs/python</code>, say
+      <code>libs/python/my_project</code>.
+
+      <li>Copy <code><a
+      href="../example/Jamfile">libs/python/example/Jamfile</a></code>
+      to your new directory.
+
+      <li>Edit the Jamfile as appropriate for your project. You'll
+      want to change the &quot;<code>subproject</code>&quot; rule
+      invocation at the top, and the names of some of the source files
+      and/or targets.
+
+      </ol>
+
+      If you can't modify or copy your boost installation, the
+      alternative is to create your own Boost.Build project. A similar
+      example you can use as a starting point is available in <code><a
+      href="../example/project.zip">this archive</a></code>. You'll
+      need to edit the Jamfile and Jamrules files, depending on the
+      relative location of your Boost installation and the new
+      project. Note that automatic testing of extension modules is not
+      available in this configuration.
+
+<h2><a name="variants">Build Variants</a></h2>
+
+      Three <a
+      href="../../../tools/build/build_system.htm#variants">variant</a>
+      configurations of all python-related targets are supported, and
+      can be selected by setting the <code><a
+      href="../../../tools/build/build_system.htm#user_globals">BUILD</a></code>
+      variable:
+
+      <ul>
+        <li><code>release</code> (optimization, <tt>-DNDEBUG</tt>)
+
+        <li><code>debug</code> (no optimization <tt>-D_DEBUG</tt>)
+
+        <li><code>debug-python</code> (no optimization, <tt>-D_DEBUG
+        -DBOOST_DEBUG_PYTHON</tt>)
+      </ul>
+
+      <p>The first two variants of the <code>boost_python</code>
+      library are built by default, and are compatible with the
+      default Python distribution. The <code>debug-python</code>
+      variant corresponds to a specially-built debugging version of
+      Python. On Unix platforms, this python is built by adding
+      <code>--with-pydebug</code> when configuring the Python
+      build. On Windows, the debugging version of Python is generated
+      by the &quot;Win32 Debug&quot; target of the
+      <code>PCBuild.dsw</code> Visual C++ 6.0 project in the
+      <code>PCBuild</code> subdirectory of your Python distribution.
+
+      Extension modules built with Python debugging enabled are <b>not
+      link-compatible</b> with a non-debug build of Python. Since few
+      people actually have a debug build of Python (it doesn't come
+      with the standard distribution), the normal
+      <code>debug</code> variant builds modules which are compatible
+      with ordinary Python.
+
+
+      <p>On many windows compilers, when extension modules are built
+      with
+      <tt>-D_DEBUG</tt>, Python defaults to <i>force</i> linking with a
+      special debugging version of the Python DLL. Since this debug DLL
+      isn't supplied with the default Python installation for Windows,
+      Boost.Python uses <tt><a href=
+      "../../../boost/python/detail/wrap_python.hpp">boost/python/detail/wrap_python.hpp</a></tt>
+      to temporarily undefine <tt>_DEBUG</tt> when <tt>Python.h</tt> is
+      <tt>#include</tt>d - unless <code>BOOST_DEBUG_PYTHON</code> is defined.
+
+      <p>If you want the extra runtime checks available with the
+      debugging version of the library, <tt>#define
+      BOOST_DEBUG_PYTHON</tt> to re-enable python debuggin, and link
+      with the <code>debug-python</code> variant of
+      <tt>boost_python</tt>. 
+
+      <p>If you do not <tt>#define BOOST_DEBUG_PYTHON</tt>, be sure that
+      any source files in your extension module <tt>#include &lt;<a href=
+          "../../../boost/python/detail/wrap_python.hpp">boost/python/detail/wrap_python.hpp</a>&gt;</tt>
+      instead of the usual <tt>Python.h</tt>, or you will have link
+      incompatibilities.<br>
+
+      <hr>
+      Next: <a href="enums.html">Wrapping Enums</a> Previous: <a href=
+      "under-the-hood.html">A Peek Under the Hood</a> Up: <a href=
+      "index.html">Top</a>
+
+      <hr>
+      <p>&copy; Copyright David Abrahams 2002. Permission to copy, use, modify,
+      sell and distribute this document is granted provided this copyright
+      notice appears in all copies. This document is provided ``as is'' without
+      express or implied warranty, and with no claim as to its suitability for
+      any purpose.
+
+      <p>Updated: May 15, 2002 (David Abrahams)
+    </div>

doc/comparisons.html

@@ -6,20 +6,21 @@
     <div>
       <h1>
          <img width="277" height="86" id="_x0000_i1025" align="center"
-        src="../../../c++boost.gif" alt= "c++boost.gif (8819 bytes)">Comparisons with
+        src="../../../c++boost.gif" alt= "c++boost.gif (8819 bytes)"><br>
+        Comparisons with
         Other Systems
       </h1>
       
       <h2>CXX</h2>
       <p>
-        Like BPL, <a href="http://cxx.sourceforge.net/">CXX</a> attempts to
+        Like Boost.Python, <a href="http://cxx.sourceforge.net/">CXX</a> attempts to
         provide a C++-oriented interface to Python. In most cases, as with the
         boost library, it relieves the user from worrying about
         reference-counts. Both libraries automatically convert thrown C++
         exceptions into Python exceptions. As far as I can tell, CXX has no
         support for subclassing C++ extension types in Python. An even
         more significant difference is that a user's C++ code is still basically
-        &ldquo;dealing with Python objects&rdquo;, though they are wrapped in
+        ``dealing with Python objects'', though they are wrapped in
         C++ classes. This means such jobs as argument parsing and conversion are
         still left to be done explicitly by the user.
 
@@ -40,9 +41,15 @@
       <p>
         As far as I can tell, CXX enables one to write what is essentially
         idiomatic Python code in C++, manipulating Python objects through the
-        same fully-generic interfaces we use in Python. While you're hardly programming directly to the &ldquo;bare
-        metal&rdquo; with CXX, it basically presents a &ldquo;C++-ized&rdquo;
-        version of the Python 'C' API.
+        same fully-generic interfaces we use in Python. While you're hardly
+        programming directly to the ``bare metal'' with CXX, it basically
+        presents a ``C++-ized'' version of the Python 'C' API. Some fraction of
+        that capability is available in Boost.Python through <tt><a
+        href="../../../boost/python/objects.hpp">boost/python/objects.hpp</a></tt>,
+        which provides C++ objects corresponding to Python lists, tuples,
+        strings, and dictionaries, and through <tt><a
+        href="../../../boost/python/callback.hpp">boost/python/callback.hpp</a></tt>,
+        which allows you to call back into python with C++ arguments.
 
       <p>
         <a href="mailto:dubois1@llnl.gov">Paul F. Dubois</a>, the original
@@ -51,11 +58,11 @@
         fill in the other half. Here is his response to the commentary above:
 
 <blockquote>
-&ldquo;My intention with CXX was not to do what you are doing. It was to enable a
+``My intention with CXX was not to do what you are doing. It was to enable a
 person to write an extension directly in C++ rather than C. I figured others had
 the wrapping business covered. I thought maybe CXX would provide an easier
 target language for those making wrappers, but I never explored
-that.&rdquo;<br><i>-<a href="mailto:dubois1@llnl.gov">Paul Dubois</a></i>
+that.''<br><i>-<a href="mailto:dubois1@llnl.gov">Paul Dubois</a></i>
 </blockquote>
 
       <h2>SWIG</h2>
@@ -65,28 +72,28 @@ that.&rdquo;<br><i>-<a href="mailto:dubois1@llnl.gov">Paul Dubois</a></i>
         languages. Swig relies on a parser to read your source code and produce
         additional source code files which can be compiled into a Python (or
         Perl or Tcl) extension module. It has been successfully used to create
-        many Python extension modules. Like BPL, SWIG is trying to allow an
+        many Python extension modules. Like Boost.Python, SWIG is trying to allow an
         existing interface to be wrapped with little or no change to the
-        existing code. The documentation says &ldquo;SWIG parses a form of ANSI C
+        existing code. The documentation says ``SWIG parses a form of ANSI C
         syntax that has been extended with a number of special directives. As a
         result, interfaces are usually built by grabbing a header file and
-        tweaking it a little bit.&rdquo; For C++ interfaces, the tweaking has often
+        tweaking it a little bit.'' For C++ interfaces, the tweaking has often
         proven to amount to more than just a little bit. One user
         writes:
 
-        <blockquote> &ldquo;The problem with swig (when I used it) is that it
+        <blockquote> ``The problem with swig (when I used it) is that it
         couldnt handle templates, didnt do func overloading properly etc.  For
         ANSI C libraries this was fine.  But for usual C++ code this was a
         problem.  Simple things work.  But for anything very complicated (or
-        realistic), one had to write code by hand.  I believe BPL doesn't have
+        realistic), one had to write code by hand.  I believe Boost.Python doesn't have
         this problem[<a href="#sic">sic</a>]...  IMHO overloaded functions are very important to
-        wrap correctly.&rdquo;<br><i>-Prabhu Ramachandran</i>
+        wrap correctly.''<br><i>-Prabhu Ramachandran</i>
         </blockquote>
         
       <p>
-        By contrast, BPL doesn't attempt to parse C++ - the problem is simply
+        By contrast, Boost.Python doesn't attempt to parse C++ - the problem is simply
         too complex to do correctly. <a name="sic">Technically</a>, one does
-        write code by hand to use BPL. The goal, however, has been to make
+        write code by hand to use Boost.Python. The goal, however, has been to make
         that code nearly as simple as listing the names of the classes and
         member functions you want to expose in Python.
 
@@ -95,7 +102,7 @@ that.&rdquo;<br><i>-<a href="mailto:dubois1@llnl.gov">Paul Dubois</a></i>
         <a
         href="http://www.thekompany.com/projects/pykde/background.php3?dhtml_ok=1">SIP</a>
         is a system similar to SWIG, though seemingly more
-        C++-oriented. The author says that like BPL, SIP supports overriding
+        C++-oriented. The author says that like Boost.Python, SIP supports overriding
         extension class member functions in Python subclasses. It appears to
         have been designed specifically to directly support some features of
         PyQt/PyKDE, which is its primary client. Documentation is almost
@@ -105,15 +112,15 @@ that.&rdquo;<br><i>-<a href="mailto:dubois1@llnl.gov">Paul Dubois</a></i>
       <h2>ILU</h2>
       <p>
         <a
-        href="http://www.cl.cam.ac.uk/Research/Rainbow/projects/origami/ilu-1.8-manual">ILU</a>
+        href="ftp://ftp.parc.xerox.com/pub/ilu/ilu.html">ILU</a>
         is a very ambitious project which tries to describe a module's interface
         (types and functions) in terms of an <a
-        href="http://www.cl.cam.ac.uk/Research/Rainbow/projects/origami/ilu-1.8-manual/manual_2.html">Interface
+        href="ftp://ftp.parc.xerox.com/pub/ilu/2.0b1/manual-html/manual_2.html">Interface
         Specification Language</a> (ISL) so that it can be uniformly interfaced
         to a wide range of computer languages, including Common Lisp, C++, C,
         Modula-3, and Python. ILU can parse the ISL to generate a C++ language
         header file describing the interface, of which the user is expected to
-        provide an implementation. Unlike BPL, this means that the system
+        provide an implementation. Unlike Boost.Python, this means that the system
         imposes implementation details on your C++ code at the deepest level. It
         is worth noting that some of the C++ names generated by ILU are supposed
         to be reserved to the C++ implementation. It is unclear from the
@@ -124,7 +131,7 @@ that.&rdquo;<br><i>-<a href="mailto:dubois1@llnl.gov">Paul Dubois</a></i>
       <a
       href="http://www.python.org/workshops/1996-11/papers/GRAD/html/GRADcover.html">GRAD</a>
       is another very ambitious project aimed at generating Python wrappers for
-      interfaces written in &ldquo;legacy languages&rdquo;, among which C++ is the first one
+      interfaces written in ``legacy languages'', among which C++ is the first one
       implemented. Like SWIG, it aims to parse source code and automatically
       generate wrappers, though it appears to take a more sophisticated approach
       to parsing in general and C++ in particular, so it should do a much better
@@ -148,73 +155,77 @@ an inheritance relationship?
       <h2>Zope ExtensionClasses</h2>
       <p>
          <a href="http:http://www.digicool.com/releases/ExtensionClass">
-        ExtensionClasses in Zope</a> use the same underlying mechanism as BPL
+        ExtensionClasses in Zope</a> use the same underlying mechanism as Boost.Python
         to support subclassing of extension types in Python, including
         multiple-inheritance. Both systems support pickling/unpickling of
         extension class instances in very similar ways. Both systems rely on the
-        same &ldquo;<a
+        same ``<a
         href="http://www.python.org/workshops/1994-11/BuiltInClasses/Welcome.html">Don
-        Beaudry Hack</a>&rdquo; that also inspired Don's MESS System.
+        Beaudry Hack</a>'' that also inspired Don's MESS System.
       <p>
         The major differences are:
       <ul>
+        <li>Zope is entirely 'C' language-based. It doesn't require a C++
+        compiler, so it's much more portable than Boost.Python, which stresses
+        the limits of even some modern C++ implementations.
+
         <li>
-          BPL lifts the burden on the user to parse and convert function
+          Boost.Python lifts the burden on the user to parse and convert function
           argument types. Zope provides no such facility.
         <li>
-          BPL lifts the burden on the user to maintain Python
+          Boost.Python lifts the burden on the user to maintain Python
           reference-counts.
         <li>
-          BPL supports function overloading; Zope does not.
+          Boost.Python supports function overloading; Zope does not.
         <li>
-          BPL supplies a simple mechanism for exposing read-only and
+          Boost.Python supplies a simple mechanism for exposing read-only and
           read/write access to data members of the wrapped C++ type as Python
           attributes.
         <li>
           Writing a Zope ExtensionClass is significantly more complex than
-          exposing a C++ class to python using BPL (mostly a summary of the
+          exposing a C++ class to python using Boost.Python (mostly a summary of the
           previous 4 items). <a href= 
           "http://www.digicool.com/releases/ExtensionClass/MultiMapping.html">A
           Zope Example</a> illustrates the differences.
         <li>
-          Zope's ExtensionClasses are specifically motivated by &ldquo;the need for a
-          C-based persistence mechanism&rdquo;. BPL's are motivated by the desire
+          Zope's ExtensionClasses are specifically motivated by ``the need for a
+          C-based persistence mechanism''. Boost.Python's are motivated by the desire
           to simply reflect a C++ API into Python with as little modification as
           possible.
         <li>
-          The following Zope restriction does not apply to BPL: &ldquo;At most one
+          The following Zope restriction does not apply to Boost.Python: ``At most one
           base extension direct or indirect super class may define C data
           members. If an extension subclass inherits from multiple base
           extension classes, then all but one must be mix-in classes that
-          provide extension methods but no data.&rdquo;
+          provide extension methods but no data.''
         <li>
           Zope requires use of the somewhat funky inheritedAttribute (search for
-          &ldquo;inheritedAttribute&rdquo; on <a
+          ``inheritedAttribute'' on <a
           href="http://www.digicool.com/releases/ExtensionClass">this page</a>)
-          method to access base class methods. In BPL, base class methods can
+          method to access base class methods. In Boost.Python, base class methods can
           be accessed in the usual way by writing
-          &ldquo;<code>BaseClass.method</code>&rdquo;.
+          ``<code>BaseClass.method</code>''.
         <li>
           Zope supplies some creative but esoteric idioms such as <a href= 
           "http://www.digicool.com/releases/ExtensionClass/Acquisition.html">
-          Acquisition</a>. No specific support for this is built into BPL.
+          Acquisition</a>. No specific support for this is built into Boost.Python.
         <li>
           Zope's ComputedAttribute support is designed to be used from Python.
           <a href="special.html#getter_setter">The analogous feature of
-          BPL</a> can be used from C++ or Python. The feature is arguably
-          easier to use in BPL.
+          Boost.Python</a> can be used from C++ or Python. The feature is arguably
+          easier to use in Boost.Python.
       </ul>
       <p>
-        Next: <a href="example1.html">A Simple Example Using BPL</a>
+        Next: <a href="example1.html">A Simple Example Using Boost.Python</a>
         Previous: <a href="extending.html">A Brief Introduction to writing Python Extension Modules</a>
         Up: <a href="index.html">Top</a>
       <p>
          &copy; Copyright David Abrahams 2000. Permission to copy, use, modify,
         sell and distribute this document is granted provided this copyright
-        notice appears in all copies. This document is provided &ldquo;as is&rdquo; without
+        notice appears in all copies. This document is provided ``as is'' without
         express or implied warranty, and with no claim as to its suitability
         for any purpose.
       <p>
-         Updated: Nov 26, 2000
+         Updated: Mar 6, 2001
     </div>
 

doc/cross_module.html

@@ -0,0 +1,336 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN"
+"http://www.w3.org/TR/REC-html40/strict.dtd">
+
+<title>Cross-extension-module dependencies</title>
+
+<div>
+
+<img src="../../../c++boost.gif"
+     alt="c++boost.gif (8819 bytes)"
+     align="center"
+     width="277" height="86">
+
+<hr>
+<h1>Cross-extension-module dependencies</h1>
+
+It is good programming practice to organize large projects as modules
+that interact with each other via well defined interfaces. With
+Boost.Python it is possible to reflect this organization at the C++
+level at the Python level. This is, each logical C++ module can be
+organized as a separate Python extension module.
+
+<p>
+At first sight this might seem natural and straightforward. However, it
+is a fairly complex problem to establish cross-extension-module
+dependencies while maintaining the same ease of use Boost.Python
+provides for classes that are wrapped in the same extension module. To
+a large extent this complexity can be hidden from the author of a
+Boost.Python extension module, but not entirely.
+
+<hr>
+<h2>The recipe</h2>
+
+Suppose there is an extension module that exposes certain instances of
+the C++ <tt>std::vector</tt> template library such that it can be used
+from Python in the following manner:
+
+<pre>
+import std_vector
+v = std_vector.double([1, 2, 3, 4])
+v.push_back(5)
+v.size()
+</pre>
+
+Suppose the <tt>std_vector</tt> module is done well and reflects all
+C++ functions that are useful at the Python level, for all C++ built-in
+data types (<tt>std_vector.int</tt>, <tt>std_vector.long</tt>, etc.).
+
+<p>
+Suppose further that there is statistic module with a C++ class that
+has constructors or member functions that use or return a
+<tt>std::vector</tt>.  For example:
+
+<pre>
+class xy {
+  public:
+    xy(const std::vector&lt;double&gt;&amp; x, const std::vector&lt;double&gt;&amp; y) : m_x(x), m_y(y) {}
+    const std::vector&lt;double&gt;&amp; x() const { return m_x; }
+    const std::vector&lt;double&gt;&amp; y() const { return m_y; }
+    double correlation();
+  private:
+    std::vector&lt;double&gt; m_x;
+    std::vector&lt;double&gt; m_y;
+}
+</pre>
+
+What is more natural than reusing the <tt>std_vector</tt> extension
+module to expose these constructors or functions to Python?
+
+<p>
+Unfortunately, what seems natural needs a little work in both the
+<tt>std_vector</tt> and the <tt>statistics</tt> module.
+
+<p>
+In the <tt>std_vector</tt> extension module,
+<tt>std::vector&lt;double&gt;</tt> is exposed to Python in the usual
+way with the <tt>class_builder&lt;&gt;</tt> template.  To also enable the
+automatic conversion of <tt>std::vector&lt;double&gt;</tt> function
+arguments or return values in other Boost.Python C++ modules, the
+converters that convert a <tt>std::vector&lt;double&gt;</tt> C++ object
+to a Python object and vice versa (i.e. the <tt>to_python()</tt> and
+<tt>from_python()</tt> template functions) have to be exported. For
+example:
+
+<pre>
+  #include &lt;boost/python/cross_module.hpp&gt;
+  //...
+  class_builder&lt;std::vector&lt;double&gt; &gt; v_double(std_vector_module, &quot;double&quot;);
+  export_converters(v_double);
+</pre>
+
+In the extension module that wraps <tt>class xy</tt> we can now import
+these converters with the <tt>import_converters&lt;&gt;</tt> template.
+For example:
+
+<pre>
+  #include &lt;boost/python/cross_module.hpp&gt;
+  //...
+  import_converters&lt;std::vector&lt;double&gt; &gt; v_double_converters(&quot;std_vector&quot;, &quot;double&quot;);
+</pre>
+
+That is all. All the attributes that are defined for
+<tt>std_vector.double</tt> in the <tt>std_vector</tt> Boost.Python
+module will be available for the returned objects of <tt>xy.x()</tt>
+and <tt>xy.y()</tt>.  Similarly, the constructor for <tt>xy</tt> will
+accept objects that were created by the <tt>std_vector</tt>module.
+
+<hr>
+<h2>Placement of <tt>import_converters&lt;&gt;</tt> template instantiations</h2>
+
+<tt>import_converts&lt;&gt;</tt> can be viewed as a drop-in replacement
+for <tt>class_wrapper&lt;&gt;</tt>, and the recommendations for the
+placement of <tt>class_wrapper&lt;&gt;</tt> template instantiations
+also apply to to <tt>import_converts&lt;&gt;</tt>. In particular, it is
+important that an instantiation of <tt>class_wrapper&lt;&gt;</tt> is
+visible to any code which wraps a C++ function with a <tt>T</tt>,
+<tt>T*</tt>, const <tt>T&amp;</tt>, etc. parameter or return value.
+Therefore you may want to group all <tt>class_wrapper&lt;&gt;</tt> and
+<tt>import_converts&lt;&gt;</tt> instantiations at the top of your
+module's init function, then <tt>def()</tt> the member functions later
+to avoid problems with inter-class dependencies.
+
+<hr>
+<h2>Non-copyable types</h2>
+
+<tt>export_converters()</tt> instantiates C++ template functions that
+invoke the copy constructor of the wrapped type. For a type that is
+non-copyable this will result in compile-time error messages. In such a
+case, <tt>export_converters_noncopyable()</tt> can be used to export
+the converters that do not involve the copy constructor of the wrapped
+type.  For example:
+
+<pre>
+class_builder&lt;store&gt; py_store(your_module, &quot;store&quot;);
+export_converters_noncopyable(py_store);
+</pre>
+
+The corresponding <tt>import_converters&lt;&gt;</tt> statement does not
+need any special attention:
+
+<pre>
+import_converters&lt;store&gt; py_store(&quot;noncopyable_export&quot;, &quot;store&quot;);
+</pre>
+
+<hr>
+<h2>Python module search path</h2>
+
+The <tt>std_vector</tt> and <tt>statistics</tt> modules can now be used
+in the following way:
+
+<pre>
+import std_vector
+import statistics
+x = std_vector.double([1, 2, 3, 4])
+y = std_vector.double([2, 4, 6, 8])
+xy = statistics.xy(x, y)
+xy.correlation()
+</pre>
+
+In this example it is clear that Python has to be able to find both the
+<tt>std_vector</tt> and the <tt>statistics</tt> extension module. In
+other words, both extension modules need to be in the Python module
+search path (<tt>sys.path</tt>).
+
+<p>
+The situation is not always this obvious. Suppose the
+<tt>statistics</tt> module has a <tt>random()</tt> function that
+returns a vector of random numbers with a given length:
+
+<pre>
+import statistics
+x = statistics.random(5)
+y = statistics.random(5)
+xy = statistics.xy(x, y)
+xy.correlation()
+</pre>
+
+A naive user will not easily anticipate that the <tt>std_vector</tt>
+module is used to pass the <tt>x</tt> and <tt>y</tt> vectors around. If
+the <tt>std_vector</tt> module is in the Python module search path,
+this form of ignorance is of no harm.  On the contrary, we are glad
+that we do not have to bother the user with details like this.
+
+<p>
+If the <tt>std_vector</tt> module is not in the Python module search
+path, a Python exception will be raised:
+
+<pre>
+Traceback (innermost last):
+  File &quot;foo.py&quot;, line 2, in ?
+    x = statistics.random(5)
+ImportError: No module named std_vector
+</pre>
+
+As is the case with any system of a non-trivial complexity, it is
+important that the setup is consistent and complete.
+
+<hr>
+<h2>Two-way module dependencies</h2>
+
+Boost.Python supports two-way module dependencies. This is best
+illustrated by a simple example.
+
+<p>
+Suppose there is a module <tt>ivect</tt> that implements vectors of
+integers, and a similar module <tt>dvect</tt> that implements vectors
+of doubles. We want to be able do convert an integer vector to a double
+vector and vice versa. For example:
+
+<pre>
+import ivect
+iv = ivect.ivect((1,2,3,4,5))
+dv = iv.as_dvect()
+</pre>
+
+The last expression will implicitly import the <tt>dvect</tt> module in
+order to enable the conversion of the C++ representation of
+<tt>dvect</tt> to a Python object. The analogous is possible for a
+<tt>dvect</tt>:
+
+<pre>
+import dvect
+dv = dvect.dvect((1,2,3,4,5))
+iv = dv.as_ivect()
+</pre>
+
+Now the <tt>ivect</tt> module is imported implicitly.
+
+<p>
+Note that the two-way dependencies are possible because the
+dependencies are resolved only when needed. This is, the initialization
+of the <tt>ivect</tt> module does not rely on the <tt>dvect</tt>
+module, and vice versa.  Only if <tt>as_dvect()</tt> or
+<tt>as_ivect()</tt> is actually invoked will the corresponding module
+be implicitly imported. This also means that, for example, the
+<tt>dvect</tt> module does not have to be available at all if
+<tt>as_dvect()</tt> is never used.
+
+<hr>
+<h2>Clarification of compile-time and link-time dependencies</h2>
+
+Boost.Python's support for resolving cross-module dependencies at
+runtime does not imply that compile-time dependencies are eliminated.
+For example, the statistics extension module in the example above will
+need to <tt>#include &lt;vector&gt;</tt>. This is immediately obvious
+from the definition of <tt>class xy</tt>.
+
+<p>
+If a library is wrapped that consists of both header files and compiled
+components (e.g. <tt>libdvect.a</tt>, <tt>dvect.lib</tt>, etc.), both
+the Boost.Python extension module with the
+<tt>export_converters()</tt> statement and the module with the
+<tt>import_converters&lt;&gt;</tt> statement need to be linked against
+the object library.  Ideally one would build a shared library (e.g.
+<tt>libdvect.so</tt>, <tt>dvect.dll</tt>, etc.). However, this
+introduces the issue of having to configure the search path for the
+dynamic loading correctly. For small libraries it is therefore often
+more convenient to ignore the fact that the object files are loaded
+into memory more than once.
+
+<hr>
+<h2>Summary of motivation for cross-module support</h2>
+
+The main purpose of Boost.Python's cross-module support is to allow for
+a modular system layout. With this support it is straightforward to
+reflect C++ code organization at the Python level. Without the
+cross-module support, a multi-purpose module like <tt>std_vector</tt>
+would be impractical because the entire wrapper code would somehow have
+to be duplicated in all extension modules that use it, making them
+harder to maintain and harder to build.
+
+<p>
+Another motivation for the cross-module support is that two extension
+modules that wrap the same class cannot both be imported into Python.
+For example, if there are two modules <tt>A</tt> and <tt>B</tt> that
+both wrap a given <tt>class X</tt>, this will work:
+
+<pre>
+import A
+x = A.X()
+</pre>
+
+This will also work:
+
+<pre>
+import B
+x = B.X()
+</pre>
+
+However, this will fail:
+
+<pre>
+import A
+import B
+python: /net/cci/rwgk/boost/boost/python/detail/extension_class.hpp:866:
+static void boost::python::detail::class_registry&lt;X&gt;::register_class(boost::python::detail::extension_class_base *):
+Assertion `static_class_object == 0' failed.
+Abort
+</pre>
+
+A good solution is to wrap <tt>class X</tt> only once. Depending on the
+situation, this could be done by module <tt>A</tt> or <tt>B</tt>, or an
+additional small extension module that only wraps and exports
+<tt>class X</tt>.
+
+<p>
+Finally, there can be important psychological or political reasons for
+using the cross-module support. If a group of classes is lumped
+together with many others in a huge module, the authors will have
+difficulties in being identified with their work. The situation is
+much more transparent if the work is represented by a module with a
+recognizable name. This is not just a question of strong egos, but also
+of getting credit and funding.
+
+<hr>
+<h2>Why not use <tt>export_converters()</tt> universally?</h2>
+
+There is some overhead associated with the Boost.Python cross-module
+support. Depending on the platform, the size of the code generated by
+<tt>export_converters()</tt> is roughly 10%-20% of that generated
+by <tt>class_builder&lt;&gt;</tt>. For a large extension module with
+many wrapped classes, this could mean a significant difference.
+Therefore the general recommendation is to use
+<tt>export_converters()</tt> only for classes that are likely to
+be used as function arguments or return values in other modules.
+
+<hr>
+&copy; Copyright Ralf W. Grosse-Kunstleve 2001. Permission to copy,
+use, modify, sell and distribute this document is granted provided this
+copyright notice appears in all copies. This document is provided "as
+is" without express or implied warranty, and with no claim as to its
+suitability for any purpose.
+
+<p>
+Updated: April 2001
+
+</div>

doc/data_structures.txt

@@ -0,0 +1,192 @@
+Given a real Python class 'A', a wrapped C++ class 'B', and this definition:
+
+    class C(A, B):
+        def __init__(self):
+            B.__init__(self)
+            self.x = 1
+        ...
+
+    c = C()
+
+this diagram describes the internal structure of an instance of 'C', including
+its inheritance relationships. Note that ExtensionClass<B> is derived from
+Class<ExtensionInstance>, and is in fact identical for all intents and purposes.
+
+                                           MetaClass<ExtensionInstance>
+                 +---------+              +---------+                  
+types.ClassType: |         |              |         |                  
+                 |         |              |         |                  
+                 |         |              |         |                  
+                 +---------+              +---------+                    
+                   ^                         ^   ^
+     PyClassObject |       ExtensionClass<B> |   |
+ A: +------------+ |   B: +------------+     |   |
+    |  ob_type  -+-+      |   ob_type -+-----+   |
+    |            |   ()<--+- __bases__ |         |
+    |            |        |  __dict__ -+->{...}  |
+    |            |   'B'<-+- __name__  |         |
+    +------------+        +------------+         |
+         ^                      ^                |
+         |                      |                |
+         +-----+  +-------------+                |
+               |  |                              |
+               |  |     Class<ExtensionInstance> |
+               |  | C: +------------+            |
+               |  |    |   ob_type -+------------+
+        tuple:(*, *)<--+- __bases__ |           
+                       |  __dict__ -+->{__module__, <methods, etc.>}
+                 'C' <-+- __name__  |
+                       +------------+        
+                             ^           (in case of inheritance from more than one   
+                             |            extension class, this vector would contain  
+             +---------------+            a pointer to an instance holder for the data
+             |                            of each corresponding C++ class)            
+             |     ExtensionInstance                
+             | c: +---------------------+   std::vector<InstanceHolderBase> 
+             +----+- __class__          |  +---+--  
+                  |  m_wrapped_objects -+->| * | ...
+        {'x': 1}<-+- __dict__           |  +-|-+--   
+                  +---------------------+    |    InstanceValueHolder<B>                  
+                                             |   +--------------------------------+
+                                             +-->| (contains a C++ instance of B) |
+                                                 +--------------------------------+
+
+
+
+
+
+
+In our inheritance test cases in extclass_demo.cpp/test_extclass.py, we have the
+following C++ inheritance hierarchy:
+
+               +-----+          +----+
+               |  A1 |          | A2 |
+               +-----+          +----+
+                ^ ^ ^            ^  ^  
+                | | |            |  |
+          +-----+ | +---------+-----+
+          |       |           |  |
+          |       +---+----------+
+   .......!......     |       |
+   : A_callback :   +-+--+  +-+--+
+   :............:   | B1 |  | B2 |
+                    +----+  +----+
+                      ^
+                      |
+              +-------+---------+
+              |                 |
+            +-+-+         ......!.......
+            | C |         : B_callback :
+            +---+         :............:
+
+
+A_callback and B_callback are used as part of the wrapping mechanism but not
+represented in Python. C is also not represented in Python but is delivered
+there polymorphically through a smart pointer.
+
+This is the data structure in Python.
+
+       ExtensionClass<A1>
+  A1: +------------+                
+ ()<--+- __bases__ |                                                
+      |  __dict__ -+->{...}                                         
+      +------------+                                                
+        ^                 
+        |          ExtensionInstance                                              
+        |     a1: +---------------------+   vec     InstanceValueHolder<A1,A_callback> 
+        +---------+- __class__          |  +---+   +---------------------+ 
+        |         |  m_wrapped_objects -+->| *-+-->| contains A_callback | 
+        |         +---------------------+  +---+   +---------------------+              
+        |   
+        |          ExtensionInstance                                              
+        | pa1_a1: +---------------------+   vec     InstancePtrHolder<auto_ptr<A1>,A1>
+        +---------+- __class__          |  +---+   +---+ 
+        |         |  m_wrapped_objects -+->| *-+-->| *-+-+   A1    
+        |         +---------------------+  +---+   +---+ |  +---+
+        |                                                +->|   |
+        |          ExtensionInstance                        +---+ 
+        | pb1_a1: +---------------------+   vec     InstancePtrHolder<auto_ptr<A1>,A1>
+        +---------+- __class__          |  +---+   +---+                 
+        |         |  m_wrapped_objects -+->| *-+-->| *-+-+   B1           
+        |         +---------------------+  +---+   +---+ |  +---+        
+        |                                                +->|   |                            
+        |          ExtensionInstance                        +---+                       
+        | pb2_a1: +---------------------+   vec     InstancePtrHolder<auto_ptr<A1>,A1>
+        +---------+- __class__          |  +---+   +---+                 
+        |         |  m_wrapped_objects -+->| *-+-->| *-+-+   B2                   
+        |         +---------------------+  +---+   +---+ |  +---+        
+        |                                                +->|   | 
+        |                                                   +---+                       
+        |       ExtensionClass<A1>                                                          
+        |  A2: +------------+                                                               
+        | ()<--+- __bases__ |                                                               
+        |      |  __dict__ -+->{...}                                                        
+        |      +------------+                                                               
+        |           ^                                                                       
+        |           |  ExtensionInstance                                                    
+        |       a2: | +---------------------+   vec     InstanceValueHolder<A2>             
+        |           +-+- __class__          |  +---+   +-------------+                      
+        |           | |  m_wrapped_objects -+->| *-+-->| contains A2 |                      
+        |           | +---------------------+  +---+   +-------------+                      
+        |           |                                                                       
+        |           |  ExtensionInstance                                                    
+        |   pa2_a2: | +---------------------+   vec     InstancePtrHolder<auto_ptr<A2>,A2>  
+        |           +-+- __class__          |  +---+   +---+                                
+        |           | |  m_wrapped_objects -+->| *-+-->| *-+-+   A2                         
+        |           | +---------------------+  +---+   +---+ |  +---+                       
+        |           |                                        +->|   |                       
+        |           |  ExtensionInstance                        +---+                       
+        |   pb1_a2: | +---------------------+   vec     InstancePtrHolder<auto_ptr<A2>,A2>  
+        |           +-+- __class__          |  +---+   +---+                                
+        |           | |  m_wrapped_objects -+->| *-+-->| *-+-+   B1                         
+        |           | +---------------------+  +---+   +---+ |  +---+                       
+        |           |                                        +->|   |                       
+        |           |                                           +---+                       
+        |           |                                                                       
+        |           +---------------+------------------------------+                             
+        |                           |                              |                             
+ +------+-------------------------+-|----------------------------+ |                             
+ |                                | |                            | |                             
+ |       Class<ExtensionInstance> | |      ExtensionClass<B1>    | |      ExtensionClass<B1>     
+ | DA1: +------------+            | | B1: +------------+         | | B2: +------------+          
+(*,)<---+- __bases__ |           (*,*)<---+- __bases__ |        (*,*)<---+- __bases__ |          
+        |  __dict__ -+->{...}             |  __dict__ -+->{...}          |  __dict__ -+->{...}   
+        +------------+                    +------------+                 +------------+          
+              ^                                ^                                    ^ 
+              |        ExtensionInstance       |                                    |       
+              |  da1: +---------------------+  |    vec     InstanceValueHolder<A1,A_callback>  
+              +-------+- __class__          |  |   +---+   +---------------------+  |          
+                      |  m_wrapped_objects -+--|-->| *-+-->| contains A_callback |  |          
+                      +---------------------+  |   +---+   +---------------------+  |          
+        +--------------------------------------+                                    |
+        |  ExtensionInstance                                                        |
+    b1: | +---------------------+   vec     InstanceValueHolder<B1,B_callback>      |
+        +-+- __class__          |  +---+   +---------------------+                  |
+        | |  m_wrapped_objects -+->| *-+-->| contains B_callback |                  |
+        | +---------------------+  +---+   +---------------------+                  |
+        |                                                                           |
+        |  ExtensionInstance                                                        |
+pb1_b1: | +---------------------+   vec     InstancePtrHolder<auto_ptr<B1>,B1>      |
+        +-+- __class__          |  +---+   +---+                                    |
+        | |  m_wrapped_objects -+->| *-+-->| *-+-+   B1                             |
+        | +---------------------+  +---+   +---+ |  +---+                           |
+        |                                        +->|   |                           |
+        |  ExtensionInstance                        +---+                           |
+ pc_b1: | +---------------------+   vec     InstancePtrHolder<auto_ptr<B1>,B1>      |
+        +-+- __class__          |  +---+   +---+                                    |
+        | |  m_wrapped_objects -+->| *-+-->| *-+-+   C                              |
+        | +---------------------+  +---+   +---+ |  +---+                           |
+        |                                        +->|   |                           |
+        |                                           +---+                           |
+        |                                                                           |
+        |       Class<ExtensionInstance>    +---------------------------------------+
+        | DB1: +------------+               |  ExtensionInstance                                                    
+       (*,)<---+- __bases__ |           a2: | +---------------------+   vec     InstanceValueHolder<A2> 
+               |  __dict__ -+->{...}        +-+- __class__          |  +---+   +-------------+                      
+               +------------+                 |  m_wrapped_objects -+->| *-+-->| contains A2 |                      
+                     ^                        +---------------------+  +---+   +-------------+                      
+                     |  ExtensionInstance      
+                db1: | +---------------------+    vec     InstanceValueHolder<B1,B_callback>  
+                     +-+- __class__          |   +---+   +----------------------+ 
+                       |  m_wrapped_objects -+-->| *-+-->| contains B1_callback |              
+                       +---------------------+   +---+   +----------------------+              

doc/enums.html

@@ -6,7 +6,8 @@
     <div>
       <h1>
          <img width="277" height="86" id="_x0000_i1025" align="center"
-        src="../../../c++boost.gif" alt= "c++boost.gif (8819 bytes)">Wrapping enums
+        src="../../../c++boost.gif" alt= "c++boost.gif (8819 bytes)"><br>
+        Wrapping enums
       </h1>
 
 <p>Because there is in general no way to deduce that a value of arbitrary type T
@@ -17,24 +18,39 @@ enums). Once you have done that, you can write some simple
 <code>from_python()</code> and <code>to_python()</code> functions.
 
 <p>If you are satisfied with a Python int as a way to represent your enum
-values, we provide a shorthand for these functions. You just need to
-instantiate <code>boost::python::enum_as_int_converters&lt;EnumType&gt;</code> where
+values, we provide a shorthand for these functions. You just need to cause
+<code>boost::python::enum_as_int_converters&lt;EnumType&gt;</code> to be
+instantiated, where
 <code>EnumType</code> is your enumerated type. There are two convenient ways to do this:
 
 <ol>
-<li><blockquote>
+<li>Explicit instantiation:
+
+<blockquote><pre>
+  template class boost::python::enum_as_int_converters&lt;my_enum&gt;;
+</blockquote></pre>
+
+Some buggy C++ implementations require a class to be instantiated in the same
+namespace in which it is defined. In that case, the simple incantation above becomes:
+
+<blockquote>
 <pre>
    ...
 } // close my_namespace
+
 // drop into namespace python and explicitly instantiate
-BOOST_PYTHON_BEGIN_CONVERSION_NAMESPACE // this is a gcc 2.95.2 bug workaround
-  template class enum_as_int_converters<extclass_demo::EnumOwner::enum_type>;
-BOOST_PYTHON_END_CONVERSION_NAMESPACE
+namespace boost { namespace python {
+  template class enum_as_int_converters&lt;my_enum_type&gt;;
+}} // namespace boost::python
+
 namespace my_namespace { // re-open my_namespace
    ...
 </pre>
 </blockquote>
-<li><blockquote><pre>
+
+
+<li>If you have such an implementation, you may find this technique more convenient 
+<blockquote><pre>
 // instantiate as base class in any namespace
 struct EnumTypeConverters
     : boost::python::enum_as_int_converters&lt;EnumType&gt;
@@ -71,11 +87,12 @@ BOOST_PYTHON_END_CONVERSION_NAMESPACE
  <code>long</code> type.
 
 You may also want to add a bunch of lines like this to your module
-initialization:
+initialization. These bind the corresponding enum values to the appropriate
+names so they can be used from Python:
 
 <blockquote><pre>
-mymodule.add(boost::python::to_python(enum_value_1), "enum_value_1");
-mymodule.add(boost::python::to_python(enum_value_2), "enum_value_2");
+mymodule.add(boost::python::make_ref(enum_value_1), "enum_value_1");
+mymodule.add(boost::python::make_ref(enum_value_2), "enum_value_2");
 ...
 </pre></blockquote>
 
@@ -83,21 +100,21 @@ You can also add these to an extension class definition, if your enum happens to
 be local to a class and you want the analogous interface in Python:
 
 <blockquote><pre>
-my_class.add(boost::python::to_python(enum_value_1), "enum_value_1");
-my_class.add(boost::python::to_python(enum_value_2), "enum_value_2");
+my_class_builder.add(boost::python::to_python(enum_value_1), "enum_value_1");
+my_class_builder.add(boost::python::to_python(enum_value_2), "enum_value_2");
 ...
 </pre></blockquote>
                <p>
-         Next: <a href="pointers.html">Pointers</a>
+         Next: <a href="pointers.html">Pointers and Smart Pointers</a>
          Previous: <a href="building.html">Building an Extension Module</a>
          Up: <a href="index.html">Top</a>
       <p>
          &copy; Copyright David Abrahams 2000. Permission to copy, use, modify,
         sell and distribute this document is granted provided this copyright
-        notice appears in all copies. This document is provided &ldquo;as
-        is&rdquo; without express or implied warranty, and with no claim as to
+        notice appears in all copies. This document is provided ``as
+        is'' without express or implied warranty, and with no claim as to
         its suitability for any purpose.
       <p>
-         Updated: Nov 26, 2000
+         Updated: Mar 6, 2001
     </div>
 

doc/example1.html

@@ -1,7 +1,7 @@
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN"
 "http://www.w3.org/TR/REC-html40/strict.dtd">
     <title>
-      A Simple Example Using BPL
+      A Simple Example
     </title>
     <div>
       <h1>
@@ -9,7 +9,7 @@
         "c++boost.gif (8819 bytes)">
       </h1>
       <h1>
-         A Simple Example Using BPL
+         A Simple Example
       </h1>
       <p>
          Suppose we have the following C++ API which we want to expose in
@@ -18,104 +18,49 @@
 <pre>
 #include &lt;string&gt;
 
-namespace hello {
-  class world
-  {
-   public:
-      world(int);
-      ~world();
-      std::string greet() const { return "hi, world"; }
-    ...
-  };
-  std::size_t length(const world&amp; x) { return std::strlen(x.greet()); }
+namespace { // Avoid cluttering the global namespace.
+
+  // A couple of simple C++ functions that we want to expose to Python.
+  std::string greet() { return "hello, world"; }
+  int square(int number) { return number * number; }
 }
 
 </pre>
       </blockquote>
       <p>
-         Here is the C++ code for a python module called <code>hello</code>
-        which exposes the API using BPL:
+        Here is the C++ code for a python module called <tt>getting_started1</tt>
+        which exposes the API.
       <blockquote>
 <pre>
 #include &lt;boost/python/class_builder.hpp&gt;
-// Python requires an exported function called init&lt;module-name&gt; in every
-// extension module. This is where we build the module contents.
-extern "C"
-#ifdef _WIN32
-__declspec(dllexport)
-#endif
-void inithello()
+namespace python = boost::python;
+
+BOOST_PYTHON_MODULE_INIT(getting_started1)
 {
-    try
-    {
-       // create an object representing this extension module
-       boost::python::module_builder m("hello");
-       // Create the Python type object for our extension class
-       boost::python::class_builder&lt;hello::world&gt; world_class(m, "world");
-       // Add the __init__ function
-       world_class.def(boost::python::constructor&lt;int&gt;());
-       // Add a regular member function
-       world_class.def(&amp;hello::world::get, "get");
-       // Add a regular function to the module
-       m.def(hello::length, "length");
-    }
-    catch(...)
-    {
-       boost::python::handle_exception();    // Deal with the exception for Python
-    }
+    // Create an object representing this extension module.
+    python::module_builder this_module("getting_started1");
+
+    // Add regular functions to the module.
+    this_module.def(greet, "greet");
+    this_module.def(square, "square");
 }
-// Win32 DLL boilerplate
-#if defined(_WIN32)
-#include &lt;windows.h&gt;
-extern "C" BOOL WINAPI DllMain(HINSTANCE, DWORD, LPVOID)
-{
-    return 1;
-}
-#endif // _WIN32
 </pre>
       </blockquote>
       <p>
          That's it! If we build this shared library and put it on our <code>
-        PYTHONPATH</code> we can now access our C++ class and function from
+        PYTHONPATH</code> we can now access our C++ functions from
         Python.
       <blockquote>
 <pre>
-&gt;&gt;&gt; import hello
-&gt;&gt;&gt; hi_world = hello.world(3)
-&gt;&gt;&gt; hi_world.greet()
-'hi, world'
-&gt;&gt;&gt; hello.length(hi_world)
-9
+&gt;&gt;&gt; import getting_started1
+&gt;&gt;&gt; print getting_started1.greet()
+hello, world
+&gt;&gt;&gt; number = 11
+&gt;&gt;&gt; print number, '*', number, '=', getting_started1.square(number)
+11 * 11 = 121
 </pre>
-      </blockquote>
       <p>
-         We can even make a subclass of <code>hello.world</code>:
-      <blockquote>
-<pre>
-&gt;&gt;&gt; class my_subclass(hello.world):
-...     def greet(self):
-...         return 'hello, world'
-...
-&gt;&gt;&gt; y = my_subclass(4)
-&gt;&gt;&gt; y.greet()
-'hello, world'
-</pre>
-      </blockquote>
-      <p>
-         Pretty cool! You can't do that with an ordinary Python extension type!
-      <blockquote>
-<pre>
-&gt;&gt;&gt; hello.length(y)
-9
-</pre>
-      </blockquote>
-      <p>
-         Of course, you may now have a slightly empty feeling in the pit of
-        your little pythonic stomach. Perhaps you feel your subclass deserves
-        to have a <code>length()</code> of <code>12</code>? If so, <a href= 
-        "overriding.html">read on</a>...
-      <p>
-        Next: <a href="overriding.html">Overridable virtual functions</a>
+        Next: <a href="exporting_classes.html">Exporting Classes</a>
          Previous: <a href="comparisons.html">Comparisons with other systems</a>  Up:
         <a href="index.html">Top</a>
       <p>
@@ -125,6 +70,6 @@ extern "C" BOOL WINAPI DllMain(HINSTANCE, DWORD, LPVOID)
         express or implied warranty, and with no claim as to its suitability
         for any purpose.
       <p>
-         Updated: Nov 26, 2000
+         Updated: Mar 6, 2000
     </div>
 

doc/exporting_classes.html

@@ -0,0 +1,143 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN"
+"http://www.w3.org/TR/REC-html40/strict.dtd">
+    <title>
+      Exporting Classes
+    </title>
+    <div>
+      <h1>
+         <img width="277" height="86" id="_x0000_i1025" src="../../../c++boost.gif" alt=
+        "c++boost.gif (8819 bytes)">
+      </h1>
+      <h1>
+         Exporting Classes
+      </h1>
+      <p>
+         Now let's expose a C++ class to Python:
+
+<blockquote><pre>
+#include &lt;iostream&gt;
+#include &lt;string&gt;
+
+namespace { // Avoid cluttering the global namespace.
+
+  // A friendly class.
+  class hello
+  {
+    public:
+      hello(const std::string&amp; country) { this-&gt;country = country; }
+      std::string greet() const { return "Hello from " + country; }
+    private:
+      std::string country;
+  };
+
+  // A function taking a hello object as an argument.
+  std::string invite(const hello&amp; w) {
+    return w.greet() + "! Please come soon!";
+  }
+}
+
+</blockquote></pre>      <p>
+      To expose the class, we use a <tt>class_builder</tt> in addition to the
+      <tt>module_builder</tt> from the previous example. Class member functions
+      are exposed by using the <tt>def()</tt> member function on the
+      <tt>class_builder</tt>:
+<blockquote><pre>
+#include &lt;boost/python/class_builder.hpp&gt;
+namespace python = boost::python;
+
+BOOST_PYTHON_MODULE_INIT(getting_started2)
+{
+    // Create an object representing this extension module.
+    python::module_builder this_module("getting_started2");
+
+    // Create the Python type object for our extension class.
+    python::class_builder&lt;hello&gt; hello_class(this_module, "hello");
+
+    // Add the __init__ function.
+    hello_class.def(python::constructor&lt;std::string&gt;());
+    // Add a regular member function.
+    hello_class.def(&amp;hello::greet, "greet");
+
+    // Add invite() as a regular function to the module.
+    this_module.def(invite, "invite");
+
+    // Even better, invite() can also be made a member of hello_class!!!
+    hello_class.def(invite, "invite");
+}
+</blockquote></pre>
+      <p>
+Now we can use the class normally from Python:
+
+<blockquote><pre>
+&gt;&gt;&gt; from getting_started2 import *
+&gt;&gt;&gt; hi = hello('California')
+&gt;&gt;&gt; hi.greet()
+'Hello from California'
+&gt;&gt;&gt; invite(hi)
+'Hello from California! Please come soon!'
+&gt;&gt;&gt; hi.invite()
+'Hello from California! Please come soon!'
+</blockquote></pre>
+
+Notes:<ul>
+<li> We expose the class' constructor by calling <tt>def()</tt> on the
+      <tt>class_builder</tt> with an argument whose type is
+      <tt>constructor&lt;</tt><i>params</i><tt>&gt;</tt>, where <i>params</i>
+      matches the list of constructor argument types:
+
+
+<li>Regular member functions are defined by calling <tt>def()</tt> with a
+      member function pointer and its Python name:
+
+<li>Any function added to a class whose initial argument matches the class (or
+any base) will act like a member function in Python.
+
+<li>To define a nested class, just pass the enclosing
+<tt>class_builder</tt> (instead of a <tt>module_builder</tt>) as the
+first argument to the nested <tt>class_builder</tt>'s constructor.
+
+
+</ul>
+      <p>
+         We can even make a subclass of <code>hello.world</code>:
+
+<blockquote><pre>
+&gt;&gt;&gt; class wordy(hello):
+...     def greet(self):
+...         return hello.greet(self) + ', where the weather is fine'
+...
+&gt;&gt;&gt; hi2 = wordy('Florida')
+&gt;&gt;&gt; hi2.greet()
+'Hello from Florida, where the weather is fine'
+&gt;&gt;&gt; invite(hi2)
+'Hello from Florida! Please come soon!'
+</blockquote></pre>
+      <p>
+         Pretty cool! You can't do that with an ordinary Python extension type!
+
+         Of course, you may now have a slightly empty feeling in the pit of
+        your little pythonic stomach. Perhaps you wanted to see the following
+        <tt>wordy</tt> invitation:
+
+<blockquote><pre>
+'Hello from Florida, where the weather is fine! Please come soon!'
+</blockquote></pre>
+
+        After all, <tt>invite</tt> calls <tt>hello::greet()</tt>, and you
+        reimplemented that in your Python subclass, <tt>wordy</tt>. If so, <a
+        href= "overriding.html">read on</a>...
+
+      <p>
+        Next: <a href="overriding.html">Overridable virtual functions</a>
+         Previous: <a href="example1.html">A Simple Example</a>  Up:
+        <a href="index.html">Top</a>
+      <p>
+         &copy; Copyright David Abrahams 2000. Permission to copy, use, modify,
+        sell and distribute this document is granted provided this copyright
+        notice appears in all copies. This document is provided "as is" without
+        express or implied warranty, and with no claim as to its suitability
+        for any purpose.
+      <p>
+         Updated: Mar 6, 2001
+    </div>
+

doc/extending.html

@@ -56,10 +56,10 @@
       sublcassing the extension type. Aside from being tedious, it's not really
       the same as having a true class, because there's no way for the user to
       override a method of the extension type which is called from the
-      extension module. BPL solves this problem by taking advantage of <a
+      extension module. Boost.Python solves this problem by taking advantage of <a
       href="http://www.python.org/doc/essays/metaclasses/">Python's metaclass
       feature</a> to provide objects which look, walk, and hiss almost exactly
-      like regular Python classes. BPL classes are actually cleaner than
+      like regular Python classes. Boost.Python classes are actually cleaner than
       Python classes in some subtle ways; a more detailed discussion will
       follow (someday).</p>
     <p>Next: <a href="comparisons.html">Comparisons with Other Systems</a> Up: <a

doc/index.html

@@ -1,75 +1,124 @@
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN"
 "http://www.w3.org/TR/REC-html40/strict.dtd">
-    <meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
     <title>
-      The Boost Python Library (BPL)
+      The Boost Python Library (Boost.Python)
     </title>
     <h1>
        <img src="../../../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277"
-      align="center" height="86">The Boost Python Library (BPL)
+      align="center" height="86"><br>The Boost Python Library (Boost.Python)
     </h1>
 
 <h2>Synopsis</h2>
     <p>
       Use the Boost Python Library to quickly and easily export a C++ library to <a
-      href="http://www.pythonlabs.com/pub/www.python.org">Python</a> such that the Python interface is
+      href="http://www.python.org">Python</a> such that the Python interface is
       very similar to the C++ interface. It is designed to be minimally
       intrusive on your C++ design. In most cases, you should not have to alter
-      your C++ classes in any way in order to use them with BPL. The system
-      <em>should</em> simply &ldquo;reflect&rdquo; your C++ classes and functions into
-      Python. The major features of BPL include support for:
-<ul>
-<li><a href="inheritance.hml">Subclassing extension types in Python</a>
-<li><a href="overriding.html">Overriding virtual functions in Python</a>
-<li><a href="overloading.html">[Member] function Overloading</a>
-<li><a href="special.html#numeric_auto">Automatic wrapping of numeric operators</a>
-</ul>
-among others.
+      your C++ classes in any way in order to use them with Boost.Python. The system
+      <em>should</em> simply ``reflect'' your C++ classes and functions into
+      Python. 
 
+      <p>
+
+<table border="1">
+<tr><td> <b>Note:</b> this is the last official release of
+Boost.Python v1. Development of this version of the library has
+stopped; it will be retired soon in favor of the redesigned and
+improved version 2. A summary of the development goals is available on
+the Python <a href="http://www.python.org/sigs/c++-sig/">C++-sig</a>
+page, which also serves as a mailing list for users of both versions
+of the library. A preview of the v2 documentation is available <a
+href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/boost/boost/libs/python/doc/v2/index.html?rev=HEAD&content-type=text/html">here</a>,
+and instructions for getting started with a prerelease are available
+upon request.
+</table>
 
 <h2>Supported Platforms</h2>
-<p>BPL has been tested in the following configurations:
+<p>Boost.Python is known to have been tested
+against <a href="http://www.python/org/2.2.1">Python 2.2.1</a> using
+the following compilers:
 
 <ul>
-<li>Against Python 1.5.2 using the following compiler/library: 
-
-  <ul>
   <li><a
-  href="http://msdn.microsoft.com/vstudio/sp/vs6sp4/dnldoverview.asp">MSVC++6sp4</a> 
+  href="http://msdn.microsoft.com/vstudio/downloads/updates/sp/vs6/sp5/default.asp">MSVC++6sp5</a>.
+  All tests pass.
 
   <li><a
-  href="http://msdn.microsoft.com/vstudio/sp/vs6sp4/dnldoverview.asp">MSVC++6sp4</a>/<a
-  href="http://www.stlport.org">STLport 4.0</a> 
+  href="http://msdn.microsoft.com/vstudio/downloads/updates/sp/vs6/sp5/default.asp">MSVC++6sp5</a>
+  with <a href="http://www.stlport.org">STLPort</a>-4.5.3. A compiler bug interferes with
+  <a
+  href="../example/simple_vector.cpp">libs/python/example/simple_vector.cpp</a>. All
+  other tests pass.
 
-  <li><a href="http://gcc.gnu.org/">GCC 2.95.2</a> [by <a href="mailto:koethe@informatik.uni-hamburg.de">Ullrich
-  Koethe</a>]
+  <p>
+  <li><a href="http://msdn.microsoft.com/visualc/">MSVC++7 (Visual
+       Studio .NET)</a>. All tests pass.
 
-  <li><a href="http://gcc.gnu.org/">GCC 2.95.2</a>/<a href="http://www.stlport.org">STLport 4.0</a>
+  <p>
+  <li><a href="http://www.metrowerks.com/products/windows/">Metrowerks
+        CodeWarrior Pro7.2 and Pro7.0 for Windows</a>. All tests pass.
 
-  <li>Compaq C++ V6.2-024 for Digital UNIX V5.0 Rev. 910 (an <a
-  href="http://www.edg.com/">EDG</a>-based compiler) with <a
-  href="http://www.stlport.org/beta.html">STLport-4.1b3</a> [by <a
-  href="mailto:rwgk@cci.lbl.gov">Ralf W. Grosse-Kunstleve</a>] 
+  <p>
+  <li><a href="http://gcc.gnu.org">GCC 3.0.4</a> under <a
+       href="http://www.cygwin.com">Cygwin</a> and
+       <a href="http://www.redhat.com/">RedHat Linux 7.1</a>.
+       All tests pass.
 
-  <li>An upcoming release of <a href="http://www.metrowerks.com/products/windows/">Metrowerks CodeWarrior
-        Pro6 for Windows</a> (the first release has a bug that's fatal to BPL)
-  </ul>
-<br>
-<li>Against Python 2.0 using the following compiler/library combinations:
-<ul>
+  <p>
+  <li>Compaq C++ V6.2-024 for Digital UNIX (an <a
+      href="http://www.edg.com/">EDG</a>-based compiler).
+      All tests pass.<br>
+      Note that the Boost.Compatibility
+      library must be included (see e.g. tru64_cxx.mak in the build
+      directory).
+
+  <p>
+  <li>Silicon Graphics MIPSpro Version 7.3.1.2m (an <a
+      href="http://www.edg.com/">EDG</a>-based compiler).
+      All tests pass.<br>
+      Note that the Boost.Compatibility
+      library must be included (see e.g. irix_CC.mak in the build
+      directory).
+
+  <p>
+  <li><a href="http://gcc.gnu.org">GCC 2.95.2</a> under <a
+       href="http://www.mingw.org">MinGW</a> and <a
+       href="http://www.redhat.com/">RedHat Linux 7.1</a>.
+       Compilation succeeds, but some tests fail at runtime due to
+       exception handling bugs. It is therefore highly recommended
+       to use GCC 3.0.4 instead.
+
+  <p>
   <li><a
-  href="http://msdn.microsoft.com/vstudio/sp/vs6sp4/dnldoverview.asp">MSVC++6sp4</a> [by
-  <a href="mailto:aleaxit@yahoo.com">Alex Martelli</a>]
-</ul>
+        href="http://developer.intel.com/software/products/compilers/c50/">Intel
+        C++ 6.0</a> beta: Comprehensive test fails to link due to a
+        linker bug. Other tests seem to work.
+
+  <p>
+  <li><a
+        href="http://developer.intel.com/software/products/compilers/c50/">Intel
+        C++ 5.0</a> Comprehensive test fails at runtime due to an
+        exception-handling bug. Other tests seem to work.
+
 </ul>
 
+<p>
+Note that pickling doesn't work with Python 2.2
+due to a core language bug. This is fixed in
+<a href="http://www.python/org/2.2.1">2.2.1</a>.
+
+<p>
+Boost.Python has also been used with other versions of Python back to
+Python 1.5.2. It is expected that the older Python releases still work,
+but we are not regularly testing for backward compatibility.
+
 <h2>Credits</h2>
 <ul>
       <li><a href="../../../people/dave_abrahams.htm">David Abrahams</a> originated
-      and wrote the library.
+      and wrote most of the library, and continues to coordinate development.
 
       <li><a href="mailto:koethe@informatik.uni-hamburg.de">Ullrich Koethe</a>
-      had independently developed a similar system. When he discovered BPL,
+      had independently developed a similar system. When he discovered Boost.Python,
       he generously contributed countless hours of coding and much insight into
       improving it. He is responsible for an early version of the support for <a
       href="overloading.html">function overloading</a> and wrote the support for
@@ -78,16 +127,22 @@ among others.
       Python and C++, and has designed an extremely easy-to-use way of 
       exposing <a href="special.html#numeric">numeric operators</a>, including
       a way to avoid explicit coercion by means of overloading.
+      
+      <li><a href="http://cci.lbl.gov/staff/ralf_grosse-kunstleve.html">Ralf W.
+      Grosse-Kunstleve</a> contributed <a href="pickle.html">pickle support</a>
+      and numerous other small improvements. He's working on a way to allow
+      types exported by multiple modules to interact.
 
       <li>The members of the boost mailing list and the Python community
       supplied invaluable early feedback. In particular, Ron Clarke, Mark Evans,
-      Anton Gluck, Ralf W. Grosse-Kunstleve, Chuck Ingold, Prabhu Ramachandran,
-      and Barry Scott took the brave step of trying to use BPL while it was
-      still in early stages of development.
+      Anton Gluck, Chuck Ingold, Prabhu Ramachandran, and Barry Scott took the
+      brave step of trying to use Boost.Python while it was still in early
+      stages of development.
 
-      <li>The development of BPL wouldn't have been
-      possible without the generous support of <a href="http://www.dragonsys.com/">Dragon Systems/Lernout and
-      Hauspie, Inc</a> who supported its development as an open-source project.
+      <li>The development of Boost.Python wouldn't have been possible without
+      the generous support of <a href="http://www.dragonsys.com/">Dragon
+      Systems/Lernout and Hauspie, Inc</a> who supported its development as an
+      open-source project.
 </ul>
 
     <h2>Table of Contents</h2>
@@ -96,10 +151,12 @@ among others.
       <li><a href="extending.html">A Brief Introduction to writing Python
         extension modules</a>
 
-      <li><a href="comparisons.html">Comparisons between BPL and other
+      <li><a href="comparisons.html">Comparisons between Boost.Python and other
         systems for extending Python</a>
 
-      <li><a href="example1.html">A Simple Example Using BPL</a>
+      <li><a href="example1.html">A Simple Example</a>
+
+      <li><a href="exporting_classes.html">Exporting Classes</a>
 
       <li><a href="overriding.html">Overridable Virtual Functions</a>
 
@@ -111,48 +168,38 @@ among others.
 
       <li><a href="under-the-hood.html">A Peek Under the Hood</a>
 
-      <li><a href="building.html">Building a Module with BPL</a>
+      <li><a href="building.html">Building an Extension Module</a>
 
-      <li>Advanced Topics
+      <li><a href="pickle.html">Pickle Support</a>
 
-        <ol>
-          <li>Pickling
+      <li><a href="cross_module.html">Cross-Extension-Module Dependencies</a>
 
-          <li>class_builder&lt;&gt;
+      <li><a href="enums.html">Wrapping Enums</a>
 
-          <li><a href="enums.html">enums</a>
+      <li><a href="pointers.html">Pointers and Smart Pointers</a>
 
-          <li>References
-
-          <li><a href="pointers.html">Pointers and Smart Pointers</a>
-
-          <li>Built-in Python Types
-
-          <li>Other Extension Types
-
-          <li>Templates
-        </ol>
+      <li><a href="data_structures.txt">Internal Data Structures</a>
           
 </ol>  
  
     <p>
       Documentation is a major ongoing project; assistance is greatly
-      appreciated! In the meantime, useful examples of every BPL feature should
+      appreciated! In the meantime, useful examples of every Boost.Python feature should
       be evident in the regression test files <code>test/comprehensive.[<a
       href="../test/comprehensive.py">py</a>/<a
       href="../test/comprehensive.hpp">hpp</a>/<a
       href="../test/comprehensive.cpp">cpp</a>]</code>
 
     <p>
-       Questions should be directed to <a href= 
-      "http://www.egroups.com/list/boost">the boost mailing list</a>.
+       Questions should be directed to the <a href= 
+      "http://www.python.org/sigs/c++-sig/">Python C++ SIG</a>.
 
     <p>
-       &copy; Copyright David Abrahams 2000. Permission to copy, use, modify,
+       &copy; Copyright David Abrahams 2001. Permission to copy, use, modify,
       sell and distribute this document is granted provided this copyright
-      notice appears in all copies. This document is provided &ldquo;as is&rdquo; without
+      notice appears in all copies. This document is provided ``as is'' without
       express or implied warranty, and with no claim as to its suitability for
       any purpose.
     <p>
-       Updated: Nov 26, 2000
+       Updated: Apr 2002
 

doc/inheritance.html

@@ -12,10 +12,10 @@
 <h2>Inheritance in Python</h2>
 
       <p>
-         BPL extension classes support single and multiple-inheritance in
+         Boost.Python extension classes support single and multiple-inheritance in
          Python, just like regular Python classes. You can arbitrarily mix
          built-in Python classes with extension classes in a derived class'
-         tuple of bases. Whenever a BPL extension class is among the bases for a
+         tuple of bases. Whenever a Boost.Python extension class is among the bases for a
          new class in Python, the result is an extension class:
 <blockquote>
 <pre>
@@ -37,7 +37,7 @@
 
 <h2><a name="implicit_conversion">Reflecting C++ Inheritance Relationships</a></h2>
       <p>
-        BPL also allows us to represent C++ inheritance relationships so that
+        Boost.Python also allows us to represent C++ inheritance relationships so that
         wrapped derived classes may be passed where values, pointers, or
         references to a base class are expected as arguments. The
         <code>declare_base</code> member function of
@@ -76,32 +76,21 @@ int get_derived_x(const Derived& d) {
 // namespace alias for code brevity
 namespace python = boost::python;
 
-extern "C"
-#ifdef _WIN32
-__declspec(dllexport)
-#endif
-void initmy_module()
+BOOST_PYTHON_MODULE_INIT(my_module)
 {
-    try
-    {
-       python::module_builder my_module("my_module");
-
-       python::class_builder&lt;Base&gt; base_class(my_module, "Base");
-       base_class.def(python::constructor&lt;void&gt;());
-
-       python::class_builder&lt;Derived&gt; derived_class(my_module, "Derived");
-       derived_class.def(python::constructor&lt;void&gt;());
-       <b>// Establish the inheritance relationship between Base and Derived
-       derived_class.declare_base(base_class);</b>
-
-       my_module.def(derived_as_base, "derived_as_base");
-       my_module.def(get_name, "get_name");
-       my_module.def(get_derived_x, "get_derived_x");
-    }
-    catch(...)
-    {
-       python::handle_exception();    // Deal with the exception for Python
-    }
+    python::module_builder my_module("my_module");                            
+                                                                              
+    python::class_builder&lt;Base&gt; base_class(my_module, "Base");          
+    base_class.def(python::constructor&lt;&gt;());                        
+                                                                              
+    python::class_builder&lt;Derived&gt; derived_class(my_module, "Derived"); 
+    derived_class.def(python::constructor&lt;&gt;());                     
+    <b>// Establish the inheritance relationship between Base and Derived     
+    derived_class.declare_base(base_class);</b>                               
+                                                                              
+    my_module.def(derived_as_base, "derived_as_base");                        
+    my_module.def(get_name, "get_name");                                      
+    my_module.def(get_derived_x, "get_derived_x"); 
 }
 </pre>
 </blockquote>
@@ -115,11 +104,19 @@ void initmy_module()
 &gt;&gt;&gt; derived = Derived()
 &gt;&gt;&gt; get_name(base)
 'Base'
-</pre><i>objects of wrapped class Derived may be passed where Base is expected</i><pre>
+</pre>
+</blockquote>
+<i>objects of wrapped class Derived may be passed where Base is expected</i>
+<blockquote>
+<pre>
 &gt;&gt;&gt; get_name(derived) 
 'Derived'
-</pre><i>objects of wrapped class Derived can be passed where Derived is 
-expected but where type information has been lost.</i><pre>
+</pre>
+</blockquote>
+<i>objects of wrapped class Derived can be passed where Derived is 
+expected but where type information has been lost.</i>
+<blockquote>
+<pre>
 &gt;&gt;&gt; get_derived_x(derived_as_base()) 
 -1
 </pre>
@@ -140,10 +137,10 @@ struct Derived2 { int f(); };
 <hr>
    ...
    python::class_builder&lt;Base&gt; base2_class(my_module, "Base2");
-   base2_class.def(python::constructor&lt;void&gt;());
+   base2_class.def(python::constructor&lt;&gt;());
 
    python::class_builder&lt;Derived2&gt; derived2_class(my_module, "Derived2");
-   derived2_class.def(python::constructor&lt;void&gt;());
+   derived2_class.def(python::constructor&lt;&gt;());
    derived_class.declare_base(base_class, <b>python::without_downcast</b>);
 </pre>
 </blockquote>

doc/new-conversions.html

@@ -0,0 +1,326 @@
+<html>
+
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
+<title>A New Type Conversion Mechanism for Boost.Python</title>
+</head>
+
+<body bgcolor="#FFFFFF" text="#000000">
+
+<p><img border="0" src="../../../c++boost.gif" width="277" height="86"
+alt="boost logo"></p>
+
+<h1>A New Type Conversion Mechanism for Boost.Python</h1>
+
+<p>By <a href="../../../people/dave_abrahams.htm">David Abrahams</a>.
+
+<h2>Introduction</h2>
+
+This document describes a redesign of the mechanism for automatically
+converting objects between C++ and Python. The current implementation
+uses two functions for any type <tt>T</tt>:
+
+<blockquote><pre>
+U from_python(PyObject*, type&lt;T&gt;);
+void to_python(V);
+</pre></blockquote>
+
+where U is convertible to T and T is convertible to V. These functions
+are at the heart of C++/Python interoperability in Boost.Python, so
+why would we want to change them? There are many reasons:
+
+<h3>Bugs</h3>
+<p>Firstly, the current mechanism relies on a common C++ compiler
+bug. This is not just embarrassing: as compilers get to be more
+conformant, the library stops working. The issue, in detail, is the
+use of inline friend functions in templates to generate
+conversions. It is a very powerful, and legal technique as long as
+it's used correctly:
+
+<blockquote><pre>
+template &lt;class Derived&gt;
+struct add_some_functions
+{
+     friend <i>return-type</i> some_function1(..., Derived <i>cv-*-&amp;-opt</i>, ...);
+     friend <i>return-type</i> some_function2(..., Derived <i>cv-*-&amp;-opt</i>, ...);
+};
+
+template &lt;class T&gt;
+struct some_template : add_some_functions&lt;some_template&lt;T&gt; &gt;
+{
+};
+</pre></blockquote>
+
+The <tt>add_some_functions</tt> template generates free functions
+which operate on <tt>Derived</tt>, or on related types. Strictly
+speaking the related types are not just cv-qualified <tt>Derived</tt>
+values, pointers and/or references. Section 3.4.2 in the standard
+describes exactly which types you must use as parameters to these
+functions if you want the functions to be found
+(there is also a less-technical description in section 11.5.1 of
+C++PL3 <a href="#ref_1">[1]</a>). Suffice it to say that
+with the current design, the <tt>from_python</tt> and
+<tt>to_python</tt> functions are not supposed to be callable under any
+conditions!
+
+<h3>Compilation and Linking Time</h3>
+
+The conversion functions generated for each wrapped class using the
+above technique are not function templates, but regular functions. The
+upshot is that they must <i>all</i> be generated regardless of whether
+they are actually used. Generating all of those functions can slow
+down module compilation, and resolving the references can slow down
+linking.
+
+<h3>Efficiency</h3>
+
+The conversion functions are primarily used in (member) function
+wrappers to convert the arguments and return values. Being functions,
+converters have no interface which allows us to ask &quot;will the
+conversion succeed?&quot; without calling the function. Since the
+return value of the function must be the object to be passed as an
+argument, Boost.Python currently uses C++ exception-handling to detect
+an unsuccessful conversion. It's not a particularly good use of
+exception-handling, since the failure is not handled very far from
+where it occurred. More importantly, it means that C++ exceptions are
+thrown during overload resolution as we seek an overload that matches
+the arguments passed. Depending on the implementation, this approach
+can result in significant slowdowns.
+
+<p>It is also unclear that the current library generates a minimal
+amount of code for any type conversion. Many of the conversion
+functions are nontrivial, and partly because of compiler limitations,
+they are declared <tt>inline</tt>. Also, we could have done a better
+job separating the type-specific conversion code from the code which
+is type-independent.
+
+<h3>Cross-module Support</h3>
+
+The current strategy requires every module to contain the definition
+of conversions it uses. In general, a new module can never supply
+conversion code which is used by another module. Ralf Grosse-Kunstleve
+designed a clever system which imports conversions directly from one
+library into another using some explicit declarations, but it has some
+disadvantages also:
+
+<ol>
+<li>The system Ullrich Koethe designed for implicit conversion between
+wrapped classes related through inheritance does not currently work if
+the classes are defined in separate modules.
+
+<li>The writer of the importing module is required to know the name of
+the module supplying the imported conversions.
+
+<li>There can be only one way to extract any given C++ type from a
+Python object in a given module.
+</ol>
+
+The first item might be addressed by moving Boost.Python into a shared
+library, but the other two cannot. Ralf turned the limitation in item
+two into a feature: the required module is loaded implicitly when a
+conversion it defines is invoked. We will probably want to provide
+that functionality anyway, but it's not clear that we should require
+the declaration of all such conversions. The final item is a more
+serious limitation. If, for example, new numeric types are defined in
+separate modules, and these types can all be converted to
+<tt>double</tt>s, we have to choose just one conversion method.
+
+<h3>Ease-of-use</h3>
+
+One persistent source of confusion for users of Boost.Python has been
+the fact that conversions for a class are not be visible at
+compile-time until the declaration of that class has been seen. When
+the user tries to expose a (member) function operating on or returning
+an instance of the class in question, compilation fails...even though
+the user goes on to expose the class in the same translation unit!
+
+<p>
+The new system lifts all compile-time checks for the existence of
+particular type conversions and replaces them with runtime checks, in
+true Pythonic style. While this might seem cavalier, the compile-time
+checks are actually not much use in the current system if many classes
+are wrapped in separate modules, since the checks are based only on
+the user's declaration that the conversions exist.
+
+<h2>The New Design</h2>
+
+<h3>Motivation</h3>
+
+The new design was heavily influenced by a desire to generate as
+little code as possible in extension modules. Some of Boost.Python's
+clients are enormous projects where link time is proportional to the
+amount of object code, and there are many Python extension modules. As
+such, we try to keep type-specific conversion code out of modules
+other than the one the converters are defined in, and rely as much as
+possible on centralized control through a shared library.
+
+<h3>The Basics</h3>
+
+The library contains a <tt>registry</tt> which maps runtime type
+identifiers (actually an extension of <tt>std::type_info</tt> which
+preserves references and constness) to entries containing type
+converters. An <tt>entry</tt> can contain only one converter from C++ to Python
+(<tt>wrapper</tt>), but many converters from Python to C++
+(<tt>unwrapper</tt>s). <font color="#ff0000">What should happen if
+multiple modules try to register wrappers for the same type?</font>. Wrappers
+and unwrappers are known as <tt>body</tt> objects, and are accessed
+by the user and the library (in its function-wrapping code) through
+corresponding <tt>handle</tt> (<tt>wrap&lt;T&gt;</tt> and
+<tt>unwrap&lt;T&gt;</tt>) objects. The <tt>handle</tt> objects are
+extremely lightweight, and delegate <i>all</i> of their operations to
+the corresponding <tt>body</tt>.
+
+<p>
+When a <tt>handle</tt> object is constructed, it accesses the
+registry to find a corresponding <tt>body</tt> that can convert the
+handle's constructor argument. Actually the registry record for any
+type
+<tt>T</tt>used in a module is looked up only once and stored in a
+static <tt>registration&lt;T&gt;</tt> object for efficiency. For
+example, if the handle is an <tt>unwrap&lt;Foo&amp;&gt;</tt> object,
+the <tt>entry</tt> for <tt>Foo&amp;</tt> is looked up in the
+<tt>registry</tt>, and each <tt>unwrapper</tt> it contains is queried
+to determine if it can convert the
+<tt>PyObject*</tt> with which the <tt>unwrap</tt> was constructed. If
+a body object which can perform the conversion is found, a pointer to
+it is stored in the handle. A body object may at any point store
+additional data in the handle to speed up the conversion process.
+
+<p>
+Now that the handle has been constructed, the user can ask it whether
+the conversion can be performed. All handles can be tested as though
+they were convertible to <tt>bool</tt>; a <tt>true</tt> value
+indicates success. If the user forges ahead and tries to do the
+conversion without checking when no conversion is possible, an
+exception will be thrown as usual. The conversion itself is performed
+by the body object. 
+
+<h3>Handling complex conversions</h3>
+
+<p>Some conversions may require a dynamic allocation. For example,
+when a Python tuple is converted to a <tt>std::vector&lt;double&gt;
+const&amp;</tt>, we need some storage into which to construct the
+vector so that a reference to it can be formed. Furthermore, multiple
+conversions of the same type may need to be &quot;active&quot;
+simultaneously, so we can't keep a single copy of the storage
+anywhere. We could keep the storage in the <tt>body</tt> object, and
+have the body clone itself in case the storage is used, but in that
+case the storage in the body which lives in the registry is never
+used. If the storage was actually an object of the target type (the
+safest way in C++), we'd have to find a way to construct one for the
+body in the registry, since it may not have a default constructor.
+
+<p>
+The most obvious way out of this quagmire is to allocate the object using a
+<i>new-expression</i>, and store a pointer to it in the handle. Since
+the <tt>body</tt> object knows everything about the data it needs to
+allocate (if any), it is also given responsibility for destroying that
+data. When the <tt>handle</tt> is destroyed it asks the <tt>body</tt>
+object to tear down any data it may have stored there. In many ways,
+you can think of the <tt>body</tt> as a &quot;dynamically-determined
+vtable&quot; for the handle.
+
+<h3>Eliminating Redundancy</h3>
+
+If you look at the current Boost.Python code, you'll see that there
+are an enormous number of conversion functions generated for each
+wrapped class. For a given class <tt>T</tt>, functions are generated
+to extract the following types <tt>from_python</tt>:
+
+<blockquote><pre>
+T*
+T const*
+T const* const&amp;
+T* const&amp;
+T&amp;
+T const&amp;
+T
+std::auto_ptr&lt;T&gt;&amp;
+std::auto_ptr&lt;T&gt;
+std::auto_ptr&lt;T&gt; const&amp;
+boost::shared_ptr&lt;T&gt;&amp;
+boost::shared_ptr&lt;T&gt;
+boost::shared_ptr&lt;T&gt; const&amp;
+</pre></blockquote>
+
+Most of these are implemented in terms of just a few conversions, and
+<t>if you're lucky</t>, they will be inlined and cause no extra
+overhead. In the new system, however, a significant amount of data
+will be associated with each type that needs to be converted. We
+certainly don't want to register a separate unwrapper object for all
+of the above types.
+
+<p>Fortunately, much of the redundancy can be eliminated. For example,
+if we generate an unwrapper for <tt>T&</tt>, we don't need an
+unwrapper for <tt>T const&</tt> or <tt>T</tt>. Accordingly, the user's
+request to wrap/unwrap a given type is translated at compile-time into
+a request which helps to eliminate redundancy. The rules used to
+<tt>unwrap</tt> a type are:
+
+<ol>
+<li> Treat built-in types specially: when unwrapping a value or
+   constant reference to one of these, use a value for the target
+   type. It will bind to a const reference if neccessary, and more
+   importantly, avoids having to dynamically allocate room for
+   an lvalue of types which can be cheaply copied.
+<li>
+ Reduce everything else to a reference to an un-cv-qualified type
+   where possible. Since cv-qualification is lost on Python
+   anyway, there's no point in trying to convert to a
+   <tt>const&amp;</tt>. <font color="#ff0000">What about conversions
+   to values like the tuple-&gt;vector example above? It seems to me
+   that we don't want to make a <tt>vector&lt;double&gt;&amp;</tt>
+   (non-const) converter available for that case. We may need to
+   rethink this slightly.</font>
+</ol>
+
+<p>To handle the problem described above in item 2, we modify the
+procedure slightly. To unwrap any non-scalar <tt>T</tt>, we seek an
+unwrapper for <tt>add_reference&lt;T&gt;::type</tt>. Unwrappers for
+<tt>T&nbsp;const&amp;</tt> always return <tt>T&amp;</tt>, and are
+registered under both <tt>T&nbsp;&amp;</tt> and
+<tt>T&nbsp;const&amp;</tt>.
+
+<p>For compilers not supporting partial specialization, unwrappers for
+<tt>T&nbsp;const&amp;</tt> must return <tt>T&nbsp;const&amp;</tt>
+(since constness can't be stripped), but a separate unwrapper object
+need to be registered for <tt>T&nbsp;&amp;</tt> and
+<tt>T&nbsp;const&amp;</tt> anyway, for the same reasons.
+
+<font color="#ff0000">We may want to make it possible to compile as
+though partial specialization were unavailable even on compilers where
+it is available, in case modules could be compiled by different
+compilers with compatible ABIs (e.g. Intel C++ and MSVC6).</font>
+
+<h3>Efficient Argument Conversion</h3>
+
+Since type conversions are primarily used in function wrappers, an
+optimization is provided for the case where a group of conversions are
+used together. Each <tt>handle</tt> class has a corresponding
+&quot;<tt>_more</tt>&quot; class which does the same job, but has a
+trivial destructor. Instead of asking each &quot;<tt>_more</tt>&quot;
+handle to destroy its own body, it is linked into an endogenous list
+managed by the first (ordinary) handle. The <tt>wrap</tt> and
+<tt>unwrap</tt> destructors are responsible for traversing that list
+and asking each <tt>body</tt> class to tear down its
+<tt>handle</tt>. This mechanism is also used to determine if all of
+the argument/return-value conversions can succeed with a single
+function call in the function wrapping code. <font color="#ff0000">We
+might need to handle return values in a separate step for Python
+callbacks, since the availablility of a conversion won't be known
+until the result object is retrieved.</font>
+
+<br>
+<hr>
+<h2>References</h2>
+
+<p><a name="ref_1">[1]</a>B. Stroustrup, The C++ Programming Language
+Special Edition Addison-Wesley, ISBN 0-201-70073-5.
+
+<hr>
+<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B %Y" startspan -->19 December 2001<!--webbot bot="Timestamp" endspan i-checksum="31283" --></p>
+<p>© Copyright David Abrahams, 2001</p>
+
+</body>
+
+</html>

doc/new-conversions.txt

@@ -0,0 +1,111 @@
+This hierarchy contains converter handle classes.
+
+
+                +-------------+
+                | noncopyable |
+                +-------------+
+                      ^
+                      |            A common base class used so that
+             +--------+--------+   conversions can be linked into a
+             | conversion_base |   chain for efficient argument
+             +-----------------+   conversion
+                      ^
+                      |
+            +---------+-----------+
+            |                     |
++-----------+----+         +------+-------+  only used for
+| unwrap_more<T> |         | wrap_more<T> |  chaining, and don't manage any
++----------------+         +--------------+  resources.
+         ^                         ^
+         |                         |
+   +-----+-----+           +-------+-+  These converters are what users
+   | unwrap<T> |           | wrap<T> |  actually touch, but they do so
+   +-----------+           +---------+  through a type generator which
+                                        minimizes the number of converters
+                                        that must be generated, so they
+
+
+Each unwrap<T>, unwrap_more<T>, wrap<T>, wrap_more<T> converter holds
+a reference to an appropriate converter object
+
+This hierarchy contains converter body classes
+
+                                          Exposes use/release which
+                                          are needed in case the converter
+                           +-----------+  in the registry needs to be
+                           | converter |  cloned. That occurs when a
+                           +-----------+  unwrap target type is not
+                                 ^        contained within the Python object.
+                                 |
+              +------------------+-----+
+              |                        |
+     +--------+-------+ Exposes        |
+     | unwrapper_base | convertible()  |
+     +----------------+                |
+              ^                        |
+              |                        |
+     +--------+----+             +-----+-----+
+     | unwrapper<T>|             | wrapper<T>|
+     +-------------+             +-----------+
+ Exposes T convert(PyObject*)    Exposes PyObject* convert(T)
+
+
+unwrap:
+
+    constructed with a PyObject*, whose reference count is
+    incremented.
+
+    find the registry entry for the target type
+
+    look in the collection of converters for one which claims to be
+    able to convert the PyObject to the target type.
+
+    stick a pointer to the unwrapper in the unwrap object
+
+    when unwrap is queried for convertibility, it checks to see
+    if it has a pointer to an unwrapper.
+
+    on conversion, the unwrapper is asked to allocate an
+    implementation if the unwrap object isn't already holding
+    one. The unwrap object "takes ownership" of the unwrapper's
+    implementation. No memory allocation will actually take place
+    unless this is a value conversion.
+
+    on destruction, the unwrapper is asked to free any implementation
+    held by the unwrap object. No memory deallocation actually
+    takes place unless this is a value conversion
+
+    on destruction, the reference count on the held PyObject is
+    decremented.
+
+    We need to make sure that by default, you can't instantiate
+    callback<> for reference and pointer return types: although the
+    unwrappers may exist, they may convert by-value, which would cause
+    the referent to be destroyed upon return.
+
+wrap:
+
+    find the registry entry for the source type
+
+    see if there is a converter. If found, stick a pointer to it in
+    the wrap object.
+
+    when queried for convertibility, it checks to see if it has a
+    pointer to a converter.
+
+    on conversion, a reference to the target PyObject is held by the
+    converter. Generally, the PyObject will have been created by the
+    converter, but in certain cases it may be a pre-existing object,
+    whose reference count will have been incremented.
+
+    when a wrap<T> x is used to return from a C++ function,
+    x.release() is returned so that x no longer holds a reference to
+    the PyObject when destroyed.
+
+    Otherwise, on destruction, any PyObject still held has its
+    reference-count decremented.
+
+
+When a converter is created by the user, the appropriate element must
+be added to the registry; when it is destroyed, it must be removed
+from the registry.

doc/overloading.html

@@ -29,7 +29,7 @@ private:
 };
   ...
 
-void initoverload_demo()
+BOOST_PYTHON_MODULE_INIT(overload_demo)
 {
     try
     {
@@ -118,12 +118,12 @@ namespace scope as Python member functions.
         <ul>
 
         <li>Attribute lookup for extension classes proceeds in <a
-        href="http://www.pythonlabs.com/pub/www.python.org/doc/current/tut/node11.html#SECTION0011510000000000000000">the
+        href="http://www.python.org/doc/current/tut/node11.html#SECTION0011510000000000000000">the
         usual Python way</a> using a depth-first, left-to-right search. When a
         class is found which has a matching attribute, only functions overloaded
         in the context of that class are candidates for overload resolution. In
         this sense, overload resolution mirrors the C++ mechanism, where a name
-        in a derived class &ldquo;hides&rdquo; all functions with the same name from a base
+        in a derived class ``hides'' all functions with the same name from a base
         class.
         <p>
 
@@ -132,11 +132,11 @@ namespace scope as Python member functions.
         <code>def()</code>ed. The first function whose signature can be made to
         match each argument passed is the one which is ultimately called. 
         This means in particular that you cannot overload the same function on 
-        both &ldquo;<code>int</code>&rdquo; and &ldquo;<code>float</code>&rdquo; because Python 
+        both ``<code>int</code>'' and ``<code>float</code>'' because Python 
         automatically converts either of the two types into the other one. 
-        If the &ldquo;<code>float</code>&rdquo; overload is found first, it is used 
-        also used for arguments of type &ldquo;<code>int</code>&rdquo; as well, and the 
-        &ldquo;<code>int</code>&rdquo; version of the function is never invoked.
+        If the ``<code>float</code>'' overload is found first, it is used 
+        also used for arguments of type ``<code>int</code>'' as well, and the 
+        ``<code>int</code>'' version of the function is never invoked.
         </ul>
 
       <p>
@@ -144,12 +144,12 @@ namespace scope as Python member functions.
          Previous: <a href="overriding.html">Overridable Virtual Functions</a>
          Up: <a href="index.html">Top</a>
       <p>
-         &copy; Copyright David Abrahams 2000. Permission to copy, use, modify,
+         &copy; Copyright David Abrahams 2001. Permission to copy, use, modify,
         sell and distribute this document is granted provided this copyright
-        notice appears in all copies. This document is provided &ldquo;as
-        is&rdquo; without express or implied warranty, and with no claim as to
+        notice appears in all copies. This document is provided ``as
+        is'' without express or implied warranty, and with no claim as to
         its suitability for any purpose.
       <p>
-         Updated: Nov 26, 2000
+         Updated: Mar 6, 2001
     </div>
 

doc/overriding.html

@@ -9,7 +9,7 @@
     <h1>Overridable Virtual Functions</h1>
 
 <p> 
-  In the <a href="example1.html">previous example</a> we exposed a simple
+  In the <a href="exporting_classes.html">previous example</a> we exposed a simple
   C++ class in Python and showed that we could write a subclass. We even
   redefined one of the functions in our derived class. Now we will learn
   how to make the function behave virtually <em>when called from C++</em>. 
@@ -17,16 +17,17 @@
 
 <h2><a name="overriding_example">Example</a></h2>
 
-<p>In this example, it is assumed that <code>world::greet()</code> is a virtual
+<p>In this example, it is assumed that <code>hello::greet()</code> is a virtual
 member function:
 
 <blockquote><pre>
-class world
+class hello
 {
  public:
-    world(int);
-    virtual ~world();
-    <b>virtual</b> std::string greet() const { return "hi, world"; }
+    hello(const std::string&amp; country) { this-&gt;country = country; }
+    <b>virtual</b> std::string greet() const { return "Hello from " + country; }
+    virtual ~hello(); // Good practice 
+    ...
 };
 </pre></blockquote>
 
@@ -37,21 +38,28 @@ class world
 
 <ol>
 
-  <li><a name="derived_1">A</a> <code>PyObject*</code> data member that holds a
-  reference to the corresponding Python object.
+  <li><a name="derived_1">A</a> <code>PyObject*</code> data member (usually
+  called <tt>self</tt>) that holds a pointer to the Python object corresponding
+  to our C++ <tt>hello</tt> instance.
 
-  <li><a name="derived_2">A</a> constructor for each exposed constructor of the
-  base class which stores an additional initial <code>PyObject*</code> argument
-  in the data member described above.
+  <li><a name="derived_2">For</a>  each exposed constructor of the
+  base class <tt>T</tt>, a constructor which takes the same parameters preceded by an initial
+  <code>PyObject*</code> argument. The initial argument should be stored in the <tt>self</tt> data
+  member described above. 
 
-  <li><a name="derived_3">An</a> implementation of each virtual function you may
+  <li><a name="derived_3">If</a> the class being wrapped is ever returned <i>by
+  value</i> from a wrapped function, be sure you do the same for the
+  <tt>T</tt>'s copy constructor: you'll need a constructor taking arguments
+  <tt>(PyObject*,&nbsp;const&nbsp;T&amp;)</tt>.
+
+  <li><a name="derived_4">An</a> implementation of each virtual function you may
   wish to override in Python which uses
-  <code>boost::python::callback&lt<i>return-type</i>&gt;::call_method()</code> to call
+  <tt>callback&lt</tt><i>return-type</i><tt>&gt;::call_method(self,&nbsp;&quot;</tt><i>name</i><tt>&quot;,&nbsp;</tt><i>args...</i><tt>)</tt> to call
   the Python override.
 
-  <li><a name="derived_4">For</a> each non-pure virtual function meant to be
+  <li><a name="derived_5">For</a> each non-pure virtual function meant to be
   overridable from Python, a static member function (or a free function) taking
-  a reference or pointer to the base type as the first parameter and which
+  a reference or pointer to the <tt>T</tt> as the first parameter and which
   forwards any additional parameters neccessary to the <i>default</i>
   implementation of the virtual function. See also <a href="#private">this
   note</a> if the base class virtual function is private.
@@ -59,52 +67,60 @@ class world
 </ol>
 
 <blockquote><pre>
-struct world_callback : world
+struct hello_callback : hello
 {
-    world_callback(PyObject* self, int x) // <a href="#derived_2">2</a>
-        : world(x),
-          m_self(self) {}
+    // hello constructor storing initial self_ parameter
+    hello_callback(PyObject* self_, const std::string&amp; x) // <a href="#derived_2">2</a>
+        : hello(x), self(self_) {}
 
-    std::string greet() const // <a href="#derived_3">3</a>
-        { return boost::python::callback&lt;std::string&gt;::call_method(m_self, "get"); }
+    // In case hello is returned by-value from a wrapped function
+    hello_callback(PyObject* self_, const hello&amp; x) // <a href="#derived_3">3</a>
+        : hello(x), self(self_) {}
 
-    static std::string <a name= "default_implementation">default_get</a>(const hello::world& self) const // <a href="#derived_4">4</a>
-        { return self.world::greet(); }
+    // Override greet to call back into Python
+    std::string greet() const // <a href="#derived_4">4</a>
+        { return boost::python::callback&lt;std::string&gt;::call_method(self, "greet"); }
+
+    // Supplies the default implementation of greet
+    static std::string <a name= "default_implementation">default_greet</a>(const hello& self_) const // <a href="#derived_5">5</a>
+        { return self_.hello::greet(); }
  private:
-    PyObject* m_self; // <a href="#derived_1">1</a>
+    PyObject* self; // <a href="#derived_1">1</a>
 };
 </pre></blockquote>
 
 <p>
-  Finally, we add <code>world_callback</code> to the <code>
-  class_builder&lt;&gt;</code> declaration in our module initialization
-  function, and when we define the function, we must tell py_cpp about the default
+  Finally, we add <tt>hello_callback</tt> to the <tt>
+  class_builder&lt;&gt;</tt> declaration in our module initialization
+  function, and when we define the function, we must tell Boost.Python about the default
   implementation:
 
 <blockquote><pre>
 // Create the <a name=
-"world_class">Python type object</a> for our extension class
-boost::python::class_builder&lt;hello::world<strong>,world_callback&gt;</strong> world_class(hello, "world");
+"hello_class">Python type object</a> for our extension class
+boost::python::class_builder&lt;hello<strong>,hello_callback&gt;</strong> hello_class(hello, "hello");
 // Add a virtual member function
-world_class.def(&amp;world::get, "get", &amp;<b>world_callback::default_get</b>);
+hello_class.def(&amp;hello::greet, "greet", &amp;<b>hello_callback::default_greet</b>);
 </pre></blockquote>
 
 <p>
- Now our subclass of <code>hello.world</code> behaves as expected:
+ Now our Python subclass of <tt>hello</tt> behaves as expected:
 
 <blockquote><pre>
-&gt;&gt;&gt; class my_subclass(hello.world):
+&gt;&gt;&gt; class wordy(hello):
 ...     def greet(self):
-...         return 'hello, world'
+...         return hello.greet(self) + ', where the weather is fine'
 ...
-&gt;&gt;&gt; hello.length(my_subclass())
-12
+&gt;&gt;&gt; hi2 = wordy('Florida')
+&gt;&gt;&gt; hi2.greet()
+'Hello from Florida, where the weather is fine'
+&gt;&gt;&gt; invite(hi2)
+'Hello from Florida, where the weather is fine! Please come soon!'
 </pre></blockquote>
-
     <p>
       <a name="why_derived">*</a>You may ask, "Why do we need this derived
       class? This could have been designed so that everything gets done right
-      inside of <code>hello::world</code>." One of the goals of py_cpp is to be
+      inside of <tt>hello</tt>." One of the goals of Boost.Python is to be
       minimally intrusive on an existing C++ design. In principle, it should be
       possible to expose the interface for a 3rd party library without changing
       it. To unintrusively hook into the virtual functions so that a Python
@@ -117,37 +133,27 @@ world_class.def(&amp;world::get, "get", &amp;<b>world_callback::default_get</b>)
       deal with than a virtual function with a default implementation. First of
       all, you obviously don't need to <a href="#default_implementation"> supply
       a default implementation</a>. Secondly, you don't need to call
-      <code>def()</code> on the <code>extension_class&lt;&gt;</code> instance
+      <tt>def()</tt> on the <tt>extension_class&lt;&gt;</tt> instance
       for the virtual function. In fact, you wouldn't <em>want</em> to: if the
       corresponding attribute on the Python class stays undefined, you'll get an
-      <code>AttributeError</code> in Python when you try to call the function,
+      <tt>AttributeError</tt> in Python when you try to call the function,
       indicating that it should have been implemented. For example:
     <blockquote>
 <pre>
 struct baz {
     <strong>virtual</strong> int pure(int) = 0;
+    int calls_pure(int x) { return pure(x) + 1000; }
 };
 
 struct baz_callback {
     int pure(int x) { boost::python::callback&lt;int&gt;::call_method(m_self, "pure", x); }
 };
 
-extern "C"
-#ifdef _WIN32
-__declspec(dllexport)
-#endif
-initfoobar()
+BOOST_PYTHON_MODULE_INIT(foobar)
 {
-    try
-    {
-       boost::python::module_builder foobar("foobar");
-       boost::python::class_builder&lt;baz,baz_callback&gt; baz_class("baz");
-       baz_class.def(&amp;baz::pure, "pure");
-    }
-    catch(...)
-    {
-       boost::python::handle_exception();    // Deal with the exception for Python
-    }
+     boost::python::module_builder foobar("foobar");                          
+     boost::python::class_builder&lt;baz,baz_callback&gt; baz_class("baz");   
+     baz_class.def(&amp;baz::calls_pure, "calls_pure"); 
 }
 </pre>
     </blockquote>
@@ -161,12 +167,18 @@ initfoobar()
 Traceback (innermost last):
   File "&lt;stdin&gt;", line 1, in ?
 AttributeError: pure
+&gt;&gt;&gt; x.calls_pure(1)
+Traceback (innermost last):
+  File "&lt;stdin&gt;", line 1, in ?
+AttributeError: pure
 &gt;&gt;&gt; class mumble(baz):
 ...    def pure(self, x): return x + 1
 ...
 &gt;&gt;&gt; y = mumble()
 &gt;&gt;&gt; y.pure(99)
 100
+&gt;&gt;&gt; y.calls_pure(99)
+1100
 </pre></blockquote>
 
 <a name="private"><h2>Private Non-Pure Virtual Functions</h2></a>
@@ -180,16 +192,17 @@ this limited way without breaking binary compatibility (though it will certainly
 break the <a
 href="http://cs.calvin.edu/c++/C++Standard-Nov97/basic.html#basic.def.odr">ODR</a>).
 
+<hr>
     <p>
       Next: <a href="overloading.html">Function Overloading</a>
-      Previous: <a href="example1.html">A Simple Example Using py_cpp</a>
+      Previous: <a href="exporting_classes.html">Exporting Classes</a>
       Up: <a href="index.html">Top</a>
     <p>
-      &copy; Copyright David Abrahams 2000. Permission to copy, use, modify,
+      &copy; Copyright David Abrahams 2001. Permission to copy, use, modify,
       sell and distribute this document is granted provided this copyright
       notice appears in all copies. This document is provided "as is" without
       express or implied warranty, and with no claim as to its suitability for
       any purpose.
     <p>
-      Updated: Nov 26, 2000
+      Updated: Mar 21, 2001
 

doc/pickle.html

@@ -0,0 +1,272 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN"
+"http://www.w3.org/TR/REC-html40/strict.dtd">
+
+<title>Boost.Python Pickle Support</title>
+
+<div>
+
+<img src="../../../c++boost.gif"
+     alt="c++boost.gif (8819 bytes)"
+     align="center"
+     width="277" height="86">
+
+<hr>
+<h1>Boost.Python Pickle Support</h1>
+
+Pickle is a Python module for object serialization, also known
+as persistence, marshalling, or flattening.
+
+<p>
+It is often necessary to save and restore the contents of an object to
+a file. One approach to this problem is to write a pair of functions
+that read and write data from a file in a special format. A powerful
+alternative approach is to use Python's pickle module. Exploiting
+Python's ability for introspection, the pickle module recursively
+converts nearly arbitrary Python objects into a stream of bytes that
+can be written to a file.
+
+<p>
+The Boost Python Library supports the pickle module by emulating the
+interface implemented by Jim Fulton's ExtensionClass module that is
+included in the
+<a href="http://www.zope.org/"
+>ZOPE</a>
+distribution.
+This interface is similar to that for regular Python classes as
+described in detail in the
+<a href="http://www.python.org/doc/current/lib/module-pickle.html"
+>Python Library Reference for pickle.</a>
+
+<hr>
+<h2>The Boost.Python Pickle Interface</h2>
+
+At the user level, the Boost.Python pickle interface involves three special
+methods:
+
+<dl>
+<dt>
+<strong><tt>__getinitargs__</tt></strong>
+<dd>
+  When an instance of a Boost.Python extension class is pickled, the
+  pickler tests if the instance has a <tt>__getinitargs__</tt> method.
+  This method must return a Python tuple (it is most convenient to use
+  a boost::python::tuple). When the instance is restored by the
+  unpickler, the contents of this tuple are used as the arguments for
+  the class constructor.
+
+  <p>
+  If <tt>__getinitargs__</tt> is not defined, the class constructor
+  will be called without arguments.
+
+<p>
+<dt>
+<strong><tt>__getstate__</tt></strong>
+
+<dd>
+  When an instance of a Boost.Python extension class is pickled, the
+  pickler tests if the instance has a <tt>__getstate__</tt> method.
+  This method should return a Python object representing the state of
+  the instance.
+
+  <p>
+  If <tt>__getstate__</tt> is not defined, the instance's
+  <tt>__dict__</tt> is pickled (if it is not empty).
+
+<p>
+<dt>
+<strong><tt>__setstate__</tt></strong>
+
+<dd>
+  When an instance of a Boost.Python extension class is restored by the
+  unpickler, it is first constructed using the result of
+  <tt>__getinitargs__</tt> as arguments (see above). Subsequently the
+  unpickler tests if the new instance has a <tt>__setstate__</tt>
+  method. If so, this method is called with the result of
+  <tt>__getstate__</tt> (a Python object) as the argument.
+
+  <p>
+  If <tt>__setstate__</tt> is not defined, the result of
+  <tt>__getstate__</tt> must be a Python dictionary. The items of this
+  dictionary are added to the instance's <tt>__dict__</tt>.
+
+</dl>
+
+If both <tt>__getstate__</tt> and <tt>__setstate__</tt> are defined,
+the Python object returned by <tt>__getstate__</tt> need not be a
+dictionary. The <tt>__getstate__</tt> and <tt>__setstate__</tt> methods
+can do what they want.
+
+<hr>
+<h2>Pitfalls and Safety Guards</h2>
+
+In Boost.Python extension modules with many extension classes,
+providing complete pickle support for all classes would be a
+significant overhead. In general complete pickle support should only be
+implemented for extension classes that will eventually be pickled.
+However, the author of a Boost.Python extension module might not
+anticipate correctly which classes need support for pickle.
+Unfortunately, the pickle protocol described above has two important
+pitfalls that the end user of a Boost.Python extension module might not
+be aware of:
+
+<dl>
+<dt>
+<strong>Pitfall 1:</strong>
+Both <tt>__getinitargs__</tt> and <tt>__getstate__</tt> are not defined.
+
+<dd>
+  In this situation the unpickler calls the class constructor without
+  arguments and then adds the <tt>__dict__</tt> that was pickled by
+  default to that of the new instance.
+
+  <p>
+  However, most C++ classes wrapped with Boost.Python will have member
+  data that are not restored correctly by this procedure. To alert the
+  user to this problem, a safety guard is provided. If both
+  <tt>__getinitargs__</tt> and <tt>__getstate__</tt> are not defined,
+  Boost.Python tests if the class has an attribute
+  <tt>__dict_defines_state__</tt>. An exception is raised if this
+  attribute is not defined:
+
+<pre>
+    RuntimeError: Incomplete pickle support (__dict_defines_state__ not set)
+</pre>
+
+  In the rare cases where this is not the desired behavior, the safety
+  guard can deliberately be disabled. The corresponding C++ code for
+  this is, e.g.:
+
+<pre>
+    class_builder&lt;your_class&gt; py_your_class(your_module, "your_class");
+    py_your_class.dict_defines_state();
+</pre>
+
+  It is also possible to override the safety guard at the Python level.
+  E.g.:
+
+<pre>
+    import your_bpl_module
+    class your_class(your_bpl_module.your_class):
+      __dict_defines_state__ = 1
+</pre>
+
+<p>
+<dt>
+<strong>Pitfall 2:</strong>
+<tt>__getstate__</tt> is defined and the instance's <tt>__dict__</tt> is not empty.
+
+<dd>
+  The author of a Boost.Python extension class might provide a
+  <tt>__getstate__</tt> method without considering the possibilities
+  that:
+
+  <p>
+  <ul>
+  <li>
+    his class is used in Python as a base class. Most likely the
+    <tt>__dict__</tt> of instances of the derived class needs to be
+    pickled in order to restore the instances correctly.
+
+  <p>
+  <li>
+    the user adds items to the instance's <tt>__dict__</tt> directly.
+    Again, the <tt>__dict__</tt> of the instance then needs to be
+    pickled.
+
+  </ul>
+  <p>
+
+  To alert the user to this highly unobvious problem, a safety guard is
+  provided. If <tt>__getstate__</tt> is defined and the instance's
+  <tt>__dict__</tt> is not empty, Boost.Python tests if the class has
+  an attribute <tt>__getstate_manages_dict__</tt>. An exception is
+  raised if this attribute is not defined:
+
+<pre>
+    RuntimeError: Incomplete pickle support (__getstate_manages_dict__ not set)
+</pre>
+
+  To resolve this problem, it should first be established that the
+  <tt>__getstate__</tt> and <tt>__setstate__</tt> methods manage the
+  instances's <tt>__dict__</tt> correctly. Note that this can be done
+  both at the C++ and the Python level. Finally, the safety guard
+  should intentionally be overridden.  E.g. in C++:
+
+<pre>
+    class_builder&lt;your_class&gt; py_your_class(your_module, "your_class");
+    py_your_class.getstate_manages_dict();
+</pre>
+
+  In Python:
+
+<pre>
+    import your_bpl_module
+    class your_class(your_bpl_module.your_class):
+      __getstate_manages_dict__ = 1
+      def __getstate__(self):
+        # your code here
+      def __setstate__(self, state):
+        # your code here
+</pre>
+</dl>
+
+<hr>
+<h2>Practical Advice</h2>
+
+<ul>
+<li>
+  Avoid using <tt>__getstate__</tt> if the instance can also be
+  reconstructed by way of <tt>__getinitargs__</tt>. This automatically
+  avoids Pitfall 2.
+
+<p>
+<li>
+  If <tt>__getstate__</tt> is required, include the instance's
+  <tt>__dict__</tt> in the Python object that is returned.
+
+</ul>
+
+<hr>
+<h2>Examples</h2>
+
+There are three files in <tt>boost/libs/python/example</tt> that
+show how so provide pickle support.
+
+<h3><a href="../example/pickle1.cpp"><tt>pickle1.cpp</tt></a></h3>
+
+    The C++ class in this example can be fully restored by passing the
+    appropriate argument to the constructor. Therefore it is sufficient
+    to define the pickle interface method <tt>__getinitargs__</tt>.
+
+<h3><a href="../example/pickle2.cpp"><tt>pickle2.cpp</tt></a></h3>
+
+    The C++ class in this example contains member data that cannot be
+    restored by any of the constructors. Therefore it is necessary to
+    provide the <tt>__getstate__</tt>/<tt>__setstate__</tt> pair of
+    pickle interface methods.
+
+    <p>
+    For simplicity, the <tt>__dict__</tt> is not included in the result
+    of <tt>__getstate__</tt>. This is not generally recommended, but a
+    valid approach if it is anticipated that the object's
+    <tt>__dict__</tt> will always be empty. Note that the safety guards
+    will catch the cases where this assumption is violated.
+
+<h3><a href="../example/pickle3.cpp"><tt>pickle3.cpp</tt></a></h3>
+
+    This example is similar to <a
+    href="../example/pickle2.cpp"><tt>pickle2.cpp</tt></a>. However, the
+    object's <tt>__dict__</tt> is included in the result of
+    <tt>__getstate__</tt>.  This requires more code but is unavoidable
+    if the object's <tt>__dict__</tt> is not always empty.
+
+<hr>
+&copy; Copyright Ralf W. Grosse-Kunstleve 2001. Permission to copy,
+use, modify, sell and distribute this document is granted provided this
+copyright notice appears in all copies. This document is provided "as
+is" without express or implied warranty, and with no claim as to its
+suitability for any purpose.
+
+<p>
+Updated: March 21, 2001
+</div>

doc/pointers.html

@@ -13,7 +13,7 @@
 
       <p>
 In general, raw pointers passed to or returned from functions are problematic
-for BPL because pointers have too many potential meanings. Is it an iterator?
+for Boost.Python because pointers have too many potential meanings. Is it an iterator?
 A pointer to a single element? An array? When used as a return value, is the
 caller expected to manage (delete) the pointed-to object or is the pointer
 really just a reference? If the latter, what happens to Python references to the
@@ -34,10 +34,10 @@ converted from/to Python strings.
 <h3>Can you avoid the problem?</h3>
 
 <p>My first piece of advice to anyone with a case not covered above is
-&ldquo;find a way to avoid the problem.&rdquo; For example, if you have just one
+``find a way to avoid the problem.'' For example, if you have just one
 or two functions that return a pointer to an individual <code>const
-T</code>, and <code>T</code> is a wrapped class, you may be able to write a &ldquo;thin
-converting wrapper&rdquo; over those two functions as follows:
+T</code>, and <code>T</code> is a wrapped class, you may be able to write a ``thin
+converting wrapper'' over those two functions as follows:
 
 <blockquote><pre>
 const Foo* f(); // original function
@@ -46,7 +46,7 @@ const Foo& f_wrapper() { return *f(); }
 my_module.def(f_wrapper, "f");
 </pre></blockquote>
 <p>
-Foo must have a public copy constructor for this technique to work, since BPL
+Foo must have a public copy constructor for this technique to work, since Boost.Python
 converts <code>const T&</code> values <code>to_python</code> by copying the <code>T</code>
 value into a new extension instance.
 
@@ -85,12 +85,12 @@ code before the last Python reference to it disappears:
 BOOST_PYTHON_BEGIN_CONVERSION_NAMESPACE // this is a gcc 2.95.2 bug workaround
   PyObject* to_python(Foo* p)
   {
-      return boost::python::PyExtensionClassConverters<Foo>::ptr_to_python(p);
+      return boost::python::python_extension_class_converters&lt;Foo&gt;::smart_ptr_to_python(p);
   }
 
   PyObject* to_python(const Foo* p)
   {
-      return to_python(const_cast<Foo*>(p));
+      return to_python(const_cast&lt;Foo*&gt;(p));
   }
 BOOST_PYTHON_END_CONVERSION_NAMESPACE
 </pre></blockquote>

doc/richcmp.html

@@ -0,0 +1,106 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN"
+"http://www.w3.org/TR/REC-html40/strict.dtd">
+
+<title>Rich Comparisons</title>
+
+<div>
+
+<img src="../../../c++boost.gif"
+     alt="c++boost.gif (8819 bytes)"
+     align="center"
+     width="277" height="86">
+
+<hr>
+<h1>Rich Comparisons</h1>
+
+<hr>
+In Python versions up to and including Python 2.0, support for
+implementing comparisons on user-defined classes and extension types
+was quite simple. Classes could implement a <tt>__cmp__</tt> method
+that was given two instances of a class as arguments, and could only
+return <tt>0</tt> if they were equal or <tt>+1</tt> or <tt>-1</tt> if
+they were not. The method could not raise an exception or return
+anything other than an integer value.
+In Python 2.1, <b>Rich Comparisons</b> were added (see
+<a href="http://python.sourceforge.net/peps/pep-0207.html">PEP 207</a>).
+Python classes can now individually overload each of the &lt;, &lt;=,
+&gt;, &gt;=, ==, and != operations.
+
+<p>
+For more detailed information, search for "rich comparison"
+<a href="http://www.python.org/doc/current/ref/customization.html"
+>here</a>.
+
+<p>
+Boost.Python supports both automatic overloading and manual overloading
+of the Rich Comparison operators. The <b>compile-time</b> support is
+independent of the Python version that is used when compiling
+Boost.Python extension modules. That is, <tt>op_lt</tt> for example can
+always be used, and the C++ <tt>operator&lt;</tt> will always be bound
+to the Python method <tt>__lt__</tt>. However, the <b>run-time</b>
+behavior will depend on the Python version.
+
+<p>
+With Python versions before 2.1, the Rich Comparison operators will not
+be called by Python when any of the six comparison operators
+(<tt>&lt;</tt>, <tt>&lt;=</tt>, <tt>==</tt>, <tt>!=</tt>,
+<tt>&gt;</tt>, <tt>&gt;=</tt>) is used in an expression. The only way
+to access the corresponding methods is to call them explicitly, e.g.
+<tt>a.__lt__(b)</tt>. Only with Python versions 2.1 or higher will
+expressions like <tt>a &lt; b</tt> work as expected.
+
+<p>
+To support Rich Comparisions, the Python C API was modified between
+Python versions 2.0 and 2.1. A new slot was introduced in the
+<tt>PyTypeObject</tt> structure: <tt>tp_richcompare</tt>. For backwards
+compatibility, a flag (<tt>Py_TPFLAGS_HAVE_RICHCOMPARE</tt>) has to be
+set to signal to the Python interpreter that Rich Comparisions are
+supported by a particular type.
+There is only one flag for all the six comparison operators.
+When any of the six operators is wrapped automatically or
+manually, Boost.Python will set this flag. Attempts to use comparison
+operators at the Python level that are not defined at the C++ level
+will then lead to an <tt>AttributeError</tt> when the Python 2.1
+(or higher) interpreter tries, e.g., <tt>a.__lt__(b)</tt>. That
+is, in general all six operators should be supplied. Automatically
+wrapped operators and manually wrapped operators can be mixed. For
+example:<pre>
+    boost::python::class_builder&lt;code&gt; py_code(this_module, "code");
+
+    py_code.def(boost::python::constructor&lt;&gt;());
+    py_code.def(boost::python::constructor&lt;int&gt;());
+    py_code.def(boost::python::operators&lt;(  boost::python::op_eq
+                                          | boost::python::op_ne)&gt;());
+    py_code.def(NotImplemented, "__lt__");
+    py_code.def(NotImplemented, "__le__");
+    py_code.def(NotImplemented, "__gt__");
+    py_code.def(NotImplemented, "__ge__");
+</pre>
+
+<tt>NotImplemented</tt> is a simple free function that (currently) has
+to be provided by the user. For example:<pre>
+  boost::python::ref
+  NotImplemented(const code&amp;, const code&amp;) {
+    return
+    boost::python::ref(Py_NotImplemented, boost::python::ref::increment_count);
+  }
+</pre>
+
+See also:
+<ul>
+<li><a href="../example/richcmp1.cpp"><tt>../example/richcmp1.cpp</tt></a>
+<li><a href="../example/richcmp2.cpp"><tt>../example/richcmp2.cpp</tt></a>
+<li><a href="../example/richcmp3.cpp"><tt>../example/richcmp3.cpp</tt></a>
+</ul>
+
+<hr>
+&copy; Copyright Nicholas K. Sauter &amp; Ralf W. Grosse-Kunstleve 2001.
+Permission to copy, use, modify, sell and distribute this document is
+granted provided this copyright notice appears in all copies. This
+document is provided "as is" without express or implied warranty, and
+with no claim as to its suitability for any purpose.
+
+<p>
+Updated: July 2001
+
+</div>

doc/special.html

@@ -1,11 +1,10 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN"
-"http://www.w3.org/TR/REC-html40/strict.dtd">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
     <title>
       Special Method and Operator Support
     </title>
     <div>
       <h1>
-         <img width="277" height="86" id="_x0000_i1025" align="center" src= 
+         <img width="277" height="86" id="_x0000_i1025" align="middle" src= 
         "../../../c++boost.gif" alt="c++boost.gif (8819 bytes)">Special Method and
         Operator Support
       </h1>
@@ -13,8 +12,8 @@
          Overview
       </h2>
       <p>
-         BPL supports all of the standard <a href=
-        "http://www.pythonlabs.com/pub/www.python.org/doc/current/ref/specialnames.html">
+         Boost.Python supports all of the standard <a href=
+        "http://www.python.org/doc/current/ref/specialnames.html">
         special method names</a> supported by real Python class instances <em>
         except</em> <code>__complex__</code> (more on the reasons <a href=
         "#reasons">below</a>). In addition, it can quickly and easily expose
@@ -34,19 +33,24 @@
       Python provides a number of special operators for basic customization of a
       class. Only a brief description is provided below; more complete
       documentation can be found <a
-      href="http://www.pythonlabs.com/pub/www.python.org/doc/current/ref/customization.html">here</a>.
+      href="http://www.python.org/doc/current/ref/customization.html">here</a>.
 
       <dl>
         <dt>
           <b><tt class='method'>__init__</tt></b>(<i>self</i>)
         <dd>
           Initialize the class instance. For extension classes not subclassed in
-          Python, this is provided by the
-          <code>boost::python::constructor<...>()</code> construct and should <i>not</i> be explicitly <code>def</code>ed.
+          Python, <code> __init__</code> is defined by 
+          
+          <pre>    my_class.def(boost::python::constructor<...>())</pre> 
+          
+          (see section <a href="example1.html">"A Simple Example Using Boost.Python"</a>).<p>
         <dt>
           <b><tt class='method'>__del__</tt></b>(<i>self</i>)
         <dd>
-          Called when the extension instance is about to be destroyed.
+          Called when the extension instance is about to be destroyed. For extension classes 
+          not subclassed in Python, <code> __del__</code> is always defined automatically by 
+          means of the class' destructor.
         <dt>
           <b><tt class='method'>__repr__</tt></b>(<i>self</i>)
         <dd>
@@ -56,13 +60,27 @@
           <b><tt class='method'>__str__</tt></b>(<i>self</i>)
         <dd>
           Create a string representation which is suitable for printing.
+        <dt>
+          <b><tt class='method'>__lt__</tt></b>(<i>self, other</i>)
+        <dt>
+          <b><tt class='method'>__le__</tt></b>(<i>self, other</i>)
+        <dt>
+          <b><tt class='method'>__eq__</tt></b>(<i>self, other</i>)
+        <dt>
+          <b><tt class='method'>__ne__</tt></b>(<i>self, other</i>)
+        <dt>
+          <b><tt class='method'>__gt__</tt></b>(<i>self, other</i>)
+        <dt>
+          <b><tt class='method'>__ge__</tt></b>(<i>self, other</i>)
+        <dd>
+	  Rich Comparison methods.
+          New in Python 2.1.
+          See <a href="richcmp.html">Rich Comparisons</a>.
         <dt>
           <b><tt class='method'>__cmp__</tt></b>(<i>self, other</i>)
         <dd>
-          Three-way compare function, used to implement comparison operators
-          (&lt; etc.) Should return a negative integer if <code> self < other
-          </code> , zero if <code> self == other </code> , a positive integer if
-          <code> self > other </code>.
+	  Three-way compare function.
+          See <a href="richcmp.html">Rich Comparisons</a>.
         <dt>
           <b><tt class='method'>__hash__</tt></b>(<i>self</i>)
         <dd>
@@ -78,7 +96,7 @@
         <dt>
         <b><tt class='method'>__call__</tt></b> (<var>self</var><big>[</big><var>, args...</var><big>]</big>)
 <dd>
-Called when the instance is &ldquo;called&rdquo; as a function; if this method
+Called when the instance is ``called'' as a function; if this method
 is defined, <code><var>x</var>(arg1, arg2, ...)</code> is a shorthand for
 <code><var>x</var>.__call__(arg1, arg2, ...)</code>.
       </dl>
@@ -100,7 +118,7 @@ std::string to_string(Foo const&amp; f)
 boost::python::class_builder&lt;Foo&gt; foo_class(my_module, "Foo");
 foo_class.def(&amp;to_string, "__str__");
 </pre></blockquote>
-      Note that BPL also supports <em>automatic wrapping</em> of
+      Note that Boost.Python also supports <em>automatic wrapping</em> of
       <code>__str__</code> and <code>__cmp__</code>. This is explained in the <a
       href="#numeric">next section</a> and the <a href="#numeric_table">Table of
       Automatically Wrapped Methods</a>.
@@ -110,10 +128,10 @@ foo_class.def(&amp;to_string, "__str__");
 <p>
       Numeric operators can be exposed manually, by <code>def</code>ing C++
       [member] functions that support the standard Python <a
-      href="http://www.pythonlabs.com/pub/www.python.org/doc/current/ref/numeric-types.html">numeric
-      protocols</a>. This is the basic same technique used to expose
+      href="http://www.python.org/doc/current/ref/numeric-types.html">numeric
+      protocols</a>. This is the same basic technique used to expose
       <code>to_string()</code> as <code>__str__()</code> above, and is <a
-      href="#numeric_manual">covered in detail below</a>.  BPL also supports
+      href="#numeric_manual">covered in detail below</a>.  Boost.Python also supports
       <i>automatic wrapping</i> of numeric operators whenever they have already
       been defined in C++.
 
@@ -121,7 +139,7 @@ foo_class.def(&amp;to_string, "__str__");
 
 <p>
 Supose we wanted to expose a C++ class
-      <code>BigNum</code> which supports addition, so that we can write (in C++):
+      <code>BigNum</code> which supports addition. That is, in C++ we can write:
 <blockquote><pre>
 BigNum a, b, c;
 ...
@@ -143,7 +161,7 @@ bignum_class.def(boost::python::operators&lt;boost::python::op_add&gt;());
 
       Since BigNum also supports subtraction, multiplication, and division, we
       want to export those also. This can be done in a single command by
-      &ldquo;or&rdquo;ing the operator identifiers together (a complete list of these
+      ``or''ing the operator identifiers together (a complete list of these
       identifiers and the corresponding operators can be found in the <a href= 
       "#numeric_table">Table of Automatically Wrapped Methods</a>):
 <blockquote><pre>
@@ -170,7 +188,7 @@ a = i + b;
 bignum_class.def(boost::python::operators&lt;boost::python::op_add&gt;(), boost::python::right_operand&lt;int&gt;());
 bignum_class.def(boost::python::operators&lt;boost::python::op_add&gt;(), boost::python::left_operand&lt;int&gt;());
 </pre></blockquote>
-      BPL uses overloading to register several variants of the same
+      Boost.Python uses overloading to register several variants of the same
       operation (more on this in the context of <a href="#coercion">
       coercion</a>). Again, several operators can be exported at once: 
 <blockquote><pre>
@@ -181,7 +199,7 @@ bignum_class.def(boost::python::operators&lt;(boost::python::op_sub | boost::pyt
 </pre></blockquote>
       The type of the operand not mentioned is taken from the class being wrapped. In
       our example, the class object is <code>bignum_class</code>, and thus the
-      other operand's type is &ldquo;<code>BigNum const&amp;</code>&rdquo;. You can override
+      other operand's type is ``<code>BigNum const&amp;</code>''. You can override
       this default by explicitly specifying a type in the <code>
       operators</code> template: 
 <blockquote><pre>
@@ -189,15 +207,18 @@ bignum_class.def(boost::python::operators&lt;boost::python::op_add, BigNum&gt;()
 </pre></blockquote>
       <p>
         Note that automatic wrapping uses the <em>expression</em>
-        &ldquo;<code>left + right</code>&rdquo; and can be used uniformly
+        ``<code>left + right</code>'' and can be used uniformly
         regardless of whether the C++ operators are supplied as free functions
-        <blockquote><pre>
+
+ <blockquote><pre>
 BigNum operator+(BigNum, BigNum)
 </pre></blockquote>
-        or as member
-        functions <blockquote><pre>
+
+        or as member functions
+
+<blockquote><pre>
 BigNum::operator+(BigNum).
-</blockquote></pre>
+</pre></blockquote>
 
       <p>
         For the Python built-in functions <code>pow()</code> and
@@ -218,8 +239,7 @@ namespace boost { namespace python {
       <p>
         In some cases, automatic wrapping of operators may be impossible or
         undesirable. Suppose, for example, that the modulo operation for BigNums
-        is defined by a set of functions <code>mod()</code> (for automatic
-        wrapping, we would need <code>operator%()</code>):
+        is defined by a set of functions called <code>mod()</code>:
 
 <blockquote><pre>
 BigNum mod(BigNum const&amp; left, BigNum const&amp; right);
@@ -228,8 +248,9 @@ BigNum mod(int left, BigNum const&amp; right);
 </pre></blockquote>
 
      <p>
-       In order to create the Python operator "__mod__" from these functions, we
-       have to wrap them manually:
+        For automatic wrapping of the modulo function, <code>operator%()</code> would be needed.
+        Therefore, the <code>mod()</code>-functions must be wrapped manually. That is, we have 
+        to export them explicitly with the Python special name "__mod__":
 
 <blockquote><pre>
 bignum_class.def((BigNum (*)(BigNum const&amp;, BigNum const&amp;))&amp;mod, "__mod__");
@@ -237,8 +258,8 @@ bignum_class.def((BigNum (*)(BigNum const&amp;, int))&amp;mod, "__mod__");
 </pre></blockquote>
 
 <p>
-      The third form (with <code>int</code> as left operand) cannot be wrapped
-      this way. We must first create a function <code>rmod()</code> with the
+      The third form of <code>mod()</code> (with <code>int</code> as left operand) cannot 
+      be wrapped directly. We must first create a function <code>rmod()</code> with the
       operands reversed: 
 
 <blockquote><pre>
@@ -248,7 +269,7 @@ BigNum rmod(BigNum const&amp; right, int left)
 }
 </pre></blockquote>
 
-      This function must be wrapped under the name "__rmod__": 
+      This function must be wrapped under the name "__rmod__" (standing for "reverse mod"): 
 
 <blockquote><pre>
 bignum_class.def(&amp;rmod,  "__rmod__");
@@ -261,28 +282,57 @@ bignum_class.def(&amp;rmod,  "__rmod__");
       <p>
         Automatic and manual wrapping can be mixed arbitrarily. Note that you
         cannot overload the same operator for a given extension class on both
-        &ldquo;<code>int</code>&rdquo; and &ldquo;<code>float</code>&rdquo;, because Python implicitly
+        ``<code>int</code>'' and ``<code>float</code>'', because Python implicitly
         converts these types into each other. Thus, the overloaded variant
-        found first (be it &ldquo;<code>int</code>&ldquo; or &ldquo;<code>float</code>&rdquo;) will be
+        found first (be it ``<code>int</code>`` or ``<code>float</code>'') will be
         used for either of the two types.
 
+<h3><a name="inplace">Inplace Operators</a></h3>
+<p>
+        Boost.Python can also be used to expose inplace numeric operations
+        (i.e., <code>+=</code> and so forth).  These operators must be wrapped
+        manually, as described in the previous section.  For example, suppose
+        the class BigNum has an <code>operator+=</code>:
+
+<blockquote><pre>
+BigNum& operator+= (BigNum const&amp; right);
+</pre></blockquote>
+
+      This can be exposed by first writing a wrapper function:
+
+<blockquote><pre>
+BigNum& iadd (BigNum&amp; self, const BigNum&amp; right)
+{
+  return self += right;
+}
+</pre></blockquote>
+
+      and then exposing the wrapper with
+
+<blockquote><pre>
+bignum_class.def(&amp;iadd, "__iadd__");
+</pre></blockquote>
+
+
+
+
 <h3><a name="coercion">Coercion</a></h3>
 
 
       Plain Python can only execute operators with identical types on the left
       and right hand side. If it encounters an expression where the types of
-      the left and right operand differ, it tries to coerce these type to a
+      the left and right operand differ, it tries to coerce these types to a
       common type before invoking the actual operator. Implementing good
       coercion functions can be difficult if many type combinations must be
       supported. 
       <p>
-        BPL solves this problem the same way that C++ does: with <em><a
+        Boost.Python solves this problem the same way that C++ does: with <em><a
         href="overloading.html">overloading</a></em>. This technique drastically
         simplifies the code neccessary to support operators: you just register
-        operators for all desired type combinations, and BPL automatically
+        operators for all desired type combinations, and Boost.Python automatically
         ensures that the correct function is called in each case; there is no
         need for user-defined coercion functions. To enable operator
-        overloading, BPL provides a standard coercion which is <em>implicitly
+        overloading, Boost.Python provides a standard coercion which is <em>implicitly
         registered</em> whenever automatic operator wrapping is used.
       <p>
         If you wrap all operator functions manually, but still want to use
@@ -295,7 +345,7 @@ bignum_class.def_standard_coerce();
 </pre></blockquote>
 
       If you encounter a situation where you absolutely need a customized
-      coercion, you can overload the "__coerce__" operator itself. The signature
+      coercion, you can still define the "__coerce__" operator manually. The signature
       of a coercion function should look like one of the following (the first is
       the safest):
 
@@ -310,13 +360,22 @@ PyObject* custom_coerce(PyObject* left, PyObject* right);
       converted to the same type. Such a function is wrapped as usual: 
 
 <blockquote><pre>
+// this must be called before any use of automatic operator  
+// wrapping or a call to some_class.def_standard_coerce()
 some_class.def(&amp;custom_coerce, "__coerce__");
 </pre></blockquote>
 
-      Note that the later use of automatic operator wrapping on a
-      <code>class_builder</code> or a call to
-      &ldquo;<code>some_class.def_standard_coerce()</code>&rdquo; will cause any
-      custom coercion function to be replaced by the standard one.
+     Note that the standard coercion (defined by use of automatic 
+     operator wrapping on a <code>class_builder</code> or a call to
+     <code>class_builder::def_standard_coerce()</code>) will never be applied if
+     a custom coercion function has been registered. Therefore, in 
+     your coercion function you should call 
+
+<blockquote><pre>
+boost::python::standard_coerce(left, right);
+</pre></blockquote>
+
+     for all cases that you don't want to handle yourself.
 
 <h3><a name="ternary_pow">The Ternary <code>pow()</code> Operator</a></h3>
 
@@ -330,7 +389,7 @@ some_class.def(&amp;custom_coerce, "__coerce__");
       this is done as usual: 
 
 <blockquote><pre>
-BigNum power(BigNum const&amp; first, BigNum const&amp; second, BigNum const&amp; module);
+BigNum power(BigNum const&amp; first, BigNum const&amp; second, BigNum const&amp; modulus);
 typedef BigNum (ternary_function1)(const BigNum&amp;, const BigNum&amp;, const BigNum&amp;);
 ...
 bignum_class.def((ternary_function1)&amp;power,  "__pow__");
@@ -353,19 +412,19 @@ bignum_class.def((ternary_function2)&amp;power,  "__pow__");
 </pre></blockquote>
 
       In the second variant, however, <code>BigNum</code> appears only as second
-      argument, and in the last one it is the third argument. These functions
-      must be presented to BPL such that that the <code>BigNum</code>
+      argument, and in the last one it's the third argument. These functions
+      must be presented to Boost.Python such that that the <code>BigNum</code>
       argument appears in first position:
 
 <blockquote><pre>
 BigNum rpower(BigNum const&amp; second, int first, int modulus)
 {
-    return power(first, second, third);
+    return power(first, second, modulus);
 }
 
-BigNum rrpower(BigNum const&amp; third, int first, int second)
+BigNum rrpower(BigNum const&amp; modulus, int first, int second)
 {
-    return power(first, second, third);
+    return power(first, second, modulus);
 }
 </pre></blockquote>
 
@@ -381,8 +440,8 @@ Note that "__rrpow__" is an extension not present in plain Python.
 
 <h2><a name="numeric_table">Table of Automatically Wrapped Methods</a></h2>
       <p>
-         BPL can automatically wrap the following <a href=
-         "http://www.pythonlabs.com/pub/www.python.org/doc/current/ref/specialnames.html">
+         Boost.Python can automatically wrap the following <a href=
+         "http://www.python.org/doc/current/ref/specialnames.html">
          special methods</a>:
 
       <p>
@@ -528,17 +587,42 @@ Note that "__rrpow__" is an extension not present in plain Python.
             <code>__cmp__, __rcmp__</code>
           <td>
             <code>cmp(left, right)</code><br>
-             <code>left &lt; right</code><br>
-             <code>left &lt;= right</code><br>
-             <code>left &gt; right</code><br>
-             <code>left &gt;= right</code><br>
-             <code>left == right</code><br>
-             <code>left != right</code>
+            <br>See <a href="richcmp.html">Rich Comparisons</a>.
           <td>
             <code>op_cmp</code>
           <td>
             <code>cpp_left &lt; cpp_right </code>
         <br><code>cpp_right &lt; cpp_left</code>
+        <tr>
+          <td>
+                <code>__lt__</code>
+            <br><code>__le__</code>
+            <br><code>__eq__</code>
+            <br><code>__ne__</code>
+            <br><code>__gt__</code>
+            <br><code>__ge__</code>
+          <td>
+                <code>left &lt; right</code>
+            <br><code>left &lt;= right</code>
+            <br><code>left == right</code>
+            <br><code>left != right</code>
+            <br><code>left &gt; right</code>
+            <br><code>left &gt;= right</code>
+            <br>See <a href="richcmp.html">Rich Comparisons</a>
+          <td>
+                <code>op_lt</code>
+            <br><code>op_le</code>
+            <br><code>op_eq</code>
+            <br><code>op_ne</code>
+            <br><code>op_gt</code>
+            <br><code>op_ge</code>
+          <td>
+                <code>cpp_left &lt; cpp_right </code>
+            <br><code>cpp_left &lt;= cpp_right </code>
+            <br><code>cpp_left == cpp_right </code>
+            <br><code>cpp_left != cpp_right </code>
+            <br><code>cpp_left &gt; cpp_right </code>
+            <br><code>cpp_left &gt;= cpp_right </code>
 
         <tr>
           <td>
@@ -630,15 +714,16 @@ Note that "__rrpow__" is an extension not present in plain Python.
       to Python's iteration and access protocols. These protocols differ
       considerably from the ones found in C++. For example, Python's typical
       iteration idiom looks like
+
 <blockquote><pre>
 for i in S:
-</blockquote></pre>
+</pre></blockquote>
 
-while in C++ one writes
+      while in C++ one writes
 
 <blockquote><pre>
-for (iterator i = S.begin(), end = S.end(); i != end)
-</blockquote></pre>
+for (iterator i = S.begin(), end = S.end(); i != end; ++i)
+</pre></blockquote>
 
 <p>One could try to wrap C++ iterators in order to carry the C++ idiom into
       Python. However, this does not work very well because 
@@ -655,12 +740,12 @@ for (iterator i = S.begin(), end = S.end(); i != end)
 
       <p>
         It is a better idea to support the standard <a
-        href="http://www.pythonlabs.com/pub/www.python.org/doc/current/ref/sequence-types.html">Python
+        href="http://www.python.org/doc/current/ref/sequence-types.html">Python
         sequence and mapping protocols</a> for your wrapped containers. These
         operators have to be wrapped manually because there are no corresponding
         C++ operators that could be used for automatic wrapping. The Python
         documentation lists the relevant <a href=
-        "http://www.pythonlabs.com/pub/www.python.org/doc/current/ref/sequence-types.html">
+        "http://www.python.org/doc/current/ref/sequence-types.html">
         container operators</a>. In particular, expose __getitem__, __setitem__
         and remember to raise the appropriate Python exceptions
         (<code>PyExc_IndexError</code> for sequences,
@@ -683,13 +768,13 @@ void throw_key_error_if_end(
     if (p == m.end())
     {
         PyErr_SetObject(PyExc_KeyError, boost::python::converters::to_python(key));
-        throw boost::python::error_already_set();
+        boost::python::throw_error_already_set();
     }
 }
 
 // Define some simple wrapper functions which match the Python  protocol
 // for __getitem__, __setitem__, and __delitem__.  Just as in Python, a
-// free function with a &ldquo;self&rdquo; first parameter makes a fine class method.
+// free function with a ``self'' first parameter makes a fine class method.
 
 const std::string&amp; get_item(const StringMap&amp; self, std::size_t key)
 {
@@ -755,13 +840,13 @@ KeyError: 2
 <h2><a name="getter_setter">Customized Attribute Access</a></h2>
 
       <p>
-        Just like built-in Python classes, BPL extension classes support <a
-        href="http://www.pythonlabs.com/pub/www.python.org/doc/current/ref/attribute-access.html">special
+        Just like built-in Python classes, Boost.Python extension classes support <a
+        href="http://www.python.org/doc/current/ref/attribute-access.html">special
         the usual attribute access methods</a> <code>__getattr__</code>,
         <code>__setattr__</code>, and <code>__delattr__</code>.
         Because writing these functions can
         be tedious in the common case where the attributes being accessed are
-        known statically, BPL checks the special names
+        known statically, Boost.Python checks the special names
 
       <ul>
         <li>
@@ -774,10 +859,10 @@ KeyError: 2
 
       to provide functional access to the attribute <em>&lt;name&gt;</em>. This
       facility can be used from C++ or entirely from Python. For example, the
-      following shows how we can implement a &ldquo;computed attribute&rdquo; in Python: 
+      following shows how we can implement a ``computed attribute'' in Python: 
       <blockquote>
 <pre>
-&gt;&gt;&gt; class Range(AnyBPLExtensionClass):
+&gt;&gt;&gt; class Range(AnyBoost.PythonExtensionClass):
 ...    def __init__(self, start, end):
 ...        self.start = start
 ...        self.end = end
@@ -793,7 +878,7 @@ KeyError: 2
          Direct Access to Data Members
       </h4>
       <p>
-         BPL uses the special <code>
+         Boost.Python uses the special <code>
         __xxxattr__<em>&lt;name&gt;</em>__</code> functionality described above
         to allow direct access to data members through the following special
         functions on <code>class_builder&lt;&gt;</code> and <code>
@@ -880,7 +965,7 @@ Up: <a href= "index.html">Top</a>
          &copy; Copyright David Abrahams and Ullrich K&ouml;the 2000.
         Permission to copy, use, modify, sell and distribute this document is
         granted provided this copyright notice appears in all copies. This
-        document is provided &ldquo;as is&rdquo; without express or implied
+        document is provided ``as is'' without express or implied
         warranty, and with no claim as to its suitability for any purpose.
       <p>
          Updated: Nov 26, 2000

doc/template.html

@@ -1,26 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN"
-"http://www.w3.org/TR/REC-html40/strict.dtd">
-    <title>
-      The Title Of This Page
-    </title>
-    <div>
-      <h1>
-         <img width="277" height="86" id="_x0000_i1025" align="center"
-        src="../../../c++boost.gif" alt= "c++boost.gif (8819 bytes)">The Title Of This
-        Page
-      </h1>
-      <p>
-      <p>
-         Prev: <a href="prev.html">Previous</a>
-         Next: <a href="next.html">Next</a>
-         Up: <a href="index.html">Top</a>
-      <p>
-         &copy; Copyright David Abrahams 2000. Permission to copy, use, modify,
-        sell and distribute this document is granted provided this copyright
-        notice appears in all copies. This document is provided "as is" without
-        express or implied warranty, and with no claim as to its suitability
-        for any purpose.
-      <p>
-         Updated: Nov 26, 2000
-    </div>
-

doc/under-the-hood.html

@@ -22,7 +22,7 @@
       "example1.html#add_world_class">add it to the module</a> it goes into the
       module's dictionary to be looked up under the name "world".
     <p>
-      BPL uses C++'s template argument deduction mechanism to determine the
+      Boost.Python uses C++'s template argument deduction mechanism to determine the
       types of arguments to functions (except constructors, for which we must
       <a href="example1.html#Constructor_example">provide an argument list</a>
       because they can't be named in C++). Then, it calls the appropriate
@@ -35,8 +35,7 @@
       "example1.html#world_class"><code>extension_class&lt;T&gt;</code></a>
       template defines a whole raft of these conversions (for <code>T, T*,
       T&amp;, std::auto_ptr&lt;T&gt;</code>, etc.), using the same inline
-      friend function technique employed by <a href= 
-      "http://www.boost.org/libs/utility/operators.htm">the boost operators
+      friend function technique employed by <a href="../../utility/operators.htm">the boost operators
       library</a>.
     <p>
       Because the <code>to_python</code> and <code>from_python</code> functions
@@ -48,7 +47,7 @@
       the top of your module's init function, then <code>def</code> the member
       functions later to avoid problems with inter-class dependencies.
     <p>
-      Next: <a href="building.html">Building a Module with BPL</a>
+      Next: <a href="building.html">Building a Module with Boost.Python</a>
       Previous: <a href="special.html">Special Method and Operator Support</a>
       Up: <a href="index.html">Top</a>
     <p>

doc/v2/Apr2002.html

@@ -0,0 +1,163 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+<link rel="stylesheet" type="text/css" href="../boost.css">
+<title>Boost.Python - April 2002 Progress Report</title>
+</head>
+<body link="#0000ff" vlink="#800080">
+<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+  <tr> 
+    <td valign="top" width="300"> 
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+    </td>
+    <td valign="top"> 
+      <h1 align="center">Boost.Python</h1>
+      <h2 align="center">April 2002 Progress Report</h2>
+    </td>
+  </tr>
+</table>
+<hr>
+<h2>Contents</h2>
+<dl class="index">
+  <dt><a href="#accomplishments">Accomplishments</a></dt>
+  <dl class="index">
+    <dt><a href="#arity">Arbitrary Arity Support</a></dt>
+    <dt><a href="#callbacks">New Callback Interface</a></dt>
+    <dt><a href="#policies">Call Policies for Construtors</a></dt>
+    <dt><a href="#bugs">Real Users, Real Bugs</a></dt>
+    <dt><a href="#insights">New Insights</a></dt>
+    <dt><a href="#v1">Boost.Python V1 Maintenance</a></dt>
+  </dl>
+
+  <dt><a href="#missing">What's Missing</a></dt>
+
+</dl>
+
+<h2><a name="accomplishments">Accomplishments</a></h2>
+
+April was a short month as far as Boost.Python was concerned, since
+the spring ISO C++ Committee Meeting (and associated vacation)
+occupied me for the 2nd half of the month. However, a suprising amount
+of work got done...
+
+<h3><a name="arity">Arbitrary Arity Support</a></h3>
+
+I began using the <a
+href="../../../preprocessor/doc/index.htm">Boost.Preprocessor</a>
+metaprogramming library to generate support for functions and member
+functions of arbitrary arity, which was, to say the least, quite an
+adventure. The feedback cycle resulting from my foray into
+Boost.Preprocessor resulted in several improvements to the library,
+most notably in its documentation. 
+
+<p>
+
+Boost.Python now supports calls of up to 17 arguments on most
+compilers. Because most EDG-based compilers have dismal preprocessor
+performance, I had to &quot;manually&quot; expand the metaprograms for
+arities from zero to fifteen arguments, and EDG-based compilers with
+<code>__EDG_VERSION__&nbsp;&lt;=&nbsp;245</code> only support 15
+arguments by default. If some crazy program finds a need for more than
+the default arity support, users can increase the base support by
+setting the <code>BOOST_PYTHON_MAX_ARITY</code> preprocessor symbol.
+
+<h3><a name="callbacks">New Callback Interface</a></h3>
+
+I mentioned in <a href="Mar2002.html">last month's report</a> that I
+wasn't pleased with the interface for the interface for calling into
+Python, so now it has been redesigned. The new interface is outlined
+in <a
+href="http://mail.python.org/pipermail/c++-sig/2002-April/000953.html">this
+message</a> (though the GCC 2.95.3 bugs have been fixed).
+
+<h3><a name="policies">Call Policies for Constructors</a></h3>
+
+On April 2nd, I <a
+href="http://mail.python.org/pipermail/c++-sig/2002-April/000916.html">announced</a>
+support for the use of call policies with constructors.
+
+<h3><a name="bugs">Real Users, Real Bugs</a></h3>
+
+At least two people outside of Kull began actually using Boost.Python
+v2 in earnest this month. Peter Bienstman and Pearu Pearson both
+provided valuable real-world bug reports that helped me to improve the
+library's robustness.
+
+<h3><a name="insights">New Insights</a></h3>
+
+<a
+href="http://mail.python.org/pipermail/c++-sig/2002-May/001010.html"
+>Answering some of Pearu's questions</a> about explicitly converting
+objects between Python and C++ actually led me to a new understanding
+of the role of the current conversion facilities. In Boost.Python v1,
+all conversions between Python and C++ were handled by a single family
+of functions, called <code>to_python()</code> and
+<code>from_python()</code>. Since the primary role of Boost.Python is
+to wrap C++ functions in Python, I used these names for the first kind
+of converters I needed: those that extract C++ objects to be used as
+function arguments and which C++ function return values to
+Python. The better-considered approach in Boost.Python v2 uses a
+completely different mechanism for conversions used when calling
+Python from C++, as in wrapped virtual function implementations. I
+usually think of this as a &quot;callback&quot;, as in &quot;calling
+back into Python&quot;, and I named the converters used in callbacks
+accordingly: <code>to_python_callback</code> and
+<code>from_python_callback</code>. However, as it turns out, the
+behavior of the &quot;callback&quot; converters is the appropriate one
+for users who want to explicitly extract a C++ value from a Python
+object, or create a Python object from a C++ value. The upshot is that
+it probably makes sense to change the name of the existing <code>to_python</code> and
+<code>from_python</code> so those names are available for the
+user-friendly explicit converters.
+
+<p>
+<a
+href="http://mail.python.org/pipermail/c++-sig/2002-May/001013.html">Another
+of Pearu's questions</a> pushes momentum further in the direction of a
+more-sophisticated overloading mechanism than the current
+simple-minded &quot;first match&quot; approach, as I suggested <a
+href="Mar2002.html#implicit_conversions">last month</a>.
+
+<h3><a name="v1">Boost.Python V1 Maintenance</a></h3>
+
+As much as I'm looking forward to retiring Boost.Python v1, a
+significant amount of effort has been being spent dealing with support
+problems; the saying that code rots when left alone is true, and
+Boost.Python is no exception. Eventually it became obvious to me that
+we were going to have to invest some effort in keeping V1 healthy
+while working on V2. Ralf and I have expanded support for various
+compilers and stabilized the V1 codebase considerably. We discarded
+the obsolete Visual Studio projects which were causing so much
+confusion. Still to do before the next Boost release:
+<ol>
+<li>Update the build/test documentation with detailed instructions for
+configuring various toolsets.
+<li>Provide some links to Boost.Python v2 to let people know what's
+coming.
+</ol>
+
+
+<h2><a name="missing">What's Missing</a></h2>
+
+Last month I announced that I would implement the following which are
+not yet complete:
+<ol>
+<li>Document all implemented features
+<li>Implement conversions for <code>char</code> types. This is
+implemented but not tested, so we have to assume it doesn't work.
+</ol>
+
+These are my first priority for this month (especially the
+documentation).
+
+<p>Revised 
+  <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+  3 May, 2002 
+  <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+</p>
+<p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave Abrahams</a> 
+  2002. All Rights Reserved.</i></p>
+</body>
+</html>

doc/v2/CallPolicies.html

@@ -0,0 +1,124 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+<link rel="stylesheet" type="text/css" href="../../../boost.css">
+<title>Boost.Python - CallPolicies Concept</title>
+</head>
+<body link="#0000ff" vlink="#800080">
+<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+  <tr> 
+    <td valign="top" width="300"> 
+      <h3><a href="../../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+    </td>
+    <td valign="top"> 
+      <h1 align="center">Boost.Python</h1>
+      <h2 align="center">CallPolicies Concept</h2>
+    </td>
+  </tr>
+</table>
+<hr>
+<dl class="page-index"> 
+  <dt><a href="#introduction">Introduction</a></dt>
+  <dt><a href="#composition">CallPolicies Composition</a></dt>
+  <dt><a href="#concept-requirements">Concept Requirements</a></dt>
+  <dl class="page-index"> 
+    <dt><a href="#CallPolicies-concept">CallPolicies Concept</a></dt>
+  </dl>
+</dl>
+
+<h2><a name="introduction"></a>Introduction</h2>
+
+<p>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:
+<ol>
+<li> <code>precall</code> - Python argument tuple management before
+the wrapped object is invoked
+<li> <code>result_converter</code> - C++ return value handling
+<li> <code>postcall</code> - Python argument tuple and result
+management after the wrapped object is invoked
+</ol>
+
+<h2><a name="composition"></a>CallPolicies Composition</h2>
+
+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, <code>Base</code> which defaults to <a
+href="default_call_policies.html#default_call_policies-spec">
+<code>default_call_policies</code></a>.  By convention, the
+<code>precall</code> function of the
+<code>Base</code> is invoked <i>after</i> the <code>precall</code>
+function supplied by the outer template, and the <code>postcall</code>
+function of the <code>Base</code> is invoked <i>before</i> the
+<code>postcall</code> function of the outer template. If a
+<code>result_converter</code> is supplied by the outer template, it
+<i>replaces</i> any <code>result_converter</code> supplied by the
+<code>Base</code>. For an example, see <a
+href="return_internal_reference.html#return_internal_reference-spec">
+<code>return_internal_reference</code></a>.
+
+<h2><a name="concept-requirements"></a>Concept Requirements</h2>
+<h3><a name="CallPolicies-concept"></a>CallPolicies Concept</h3>
+
+<p>In the table below, <code><b>x</b></code> denotes an object whose
+type <code><b>P</b></code> is a model of CallPolicies,
+<code><b>a</b></code> denotes a <code>PyObject*</code> pointing to
+a Python argument tuple object, and <code><b>r</b></code> denotes a
+<code>PyObject*</code> referring to a &quot;preliminary&quot; result
+object.
+
+<table summary="CallPolicies expressions" border="1" cellpadding="5">
+
+  <tr> 
+    <td><b>Expression</b></td>
+    <td><b>Type</b></td>
+    <td><b>Result/Semantics</b></td>
+  </tr>
+
+  <tr> 
+    <td valign="top"><code>x.precall(a)</code></td>
+    <td>convertible  to <code>bool</code>
+    <td>returns <code>false</code> and <code><a
+    href="http://www.python.org/doc/2.2/api/exceptionHandling.html#l2h-71">PyErr_Occurred</a>()&nbsp;!=&nbsp;0</code>
+    upon failure, <code>true</code> otherwise.
+
+  <tr> 
+    <td valign="top"><code>P::result_converter</code></td>
+    <td>A model of <a href="ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a>.
+    <td>An MPL unarymetafunction object used produce the
+    &quot;preliminary&quot result object.
+
+  <tr> 
+    <td valign="top"><code>x.postcall(a, r)</code></td>
+    <td>convertible  to <code>PyObject*</code>
+    <td>0 <code>0</code> and <code><a
+    href="http://www.python.org/doc/2.2/api/exceptionHandling.html#l2h-71">PyErr_Occurred</a>()&nbsp;!=&nbsp;0</code>
+    upon failure. Must &quot;conserve references&quot; even in the
+    event of an exception. In other words, if <code>r</code> is not
+    returned, its reference count must be decremented; if another
+    existing object is returned, its reference count must be
+    incremented.
+</table>
+
+Models of CallPolicies are required to be <a
+href="../../../utility/CopyConstructible.html">CopyConstructible</a>.
+
+<hr>
+<p>Revised 
+  <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+  19 May, 2002
+  <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+</p>
+    <p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
+    Abrahams</a> 2002. All Rights Reserved.</i>
+
+<p>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.
+</body>
+</html>

doc/v2/Dereferenceable.html

@@ -0,0 +1,66 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+<link rel="stylesheet" type="text/css" href="../../../boost.css">
+<title>Boost.Python - Dereferenceable Concept</title>
+</head>
+<body link="#0000ff" vlink="#800080">
+<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+  <tr> 
+    <td valign="top" width="300"> 
+      <h3><a href="../../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+    </td>
+    <td valign="top"> 
+      <h1 align="center">Boost.Python</h1>
+      <h2 align="center">Dereferenceable Concept</h2>
+    </td>
+  </tr>
+</table>
+<hr>
+<dl class="page-index"> 
+  <dt><a href="#introduction">Introduction</a></dt>
+  <dt><a href="#concept-requirements">Concept Requirements</a></dt>
+  <dl class="page-index"> 
+    <dt><a href="#Dereferenceable-concept">Dereferenceable Concept</a></dt>
+  </dl>
+</dl>
+
+<h2><a name="introduction"></a>Introduction</h2>
+
+<p>Instances of a dereferenceable type can be used like a pointer to access an lvalue.
+
+<h2><a name="concept-requirements"></a>Concept Requirements</h2>
+<h3><a name="Dereferenceable-concept"></a>Dereferenceable Concept</h3>
+
+<p>In the table below, <code><b>x</b></code> denotes an object whose
+type is a model of Dereferenceable.
+
+<table summary="Dereferenceable expressions" border="1" cellpadding="5">
+
+  <tr> 
+    <td><b>Expression</b></td>
+    <td><b>Requirements</b></td>
+  </tr>
+
+  <tr> 
+    <td valign="top"><code>*x</code></td>
+    <td>An lvalue
+  </tr>
+</table>
+
+<hr>
+<p>Revised 
+  <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+  10 May, 2002
+  <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+</p>
+    <p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
+    Abrahams</a> 2002. All Rights Reserved.</i>
+
+<p>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.
+</body>
+</html>

doc/v2/Extractor.html

@@ -0,0 +1,93 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+<link rel="stylesheet" type="text/css" href="../../../boost.css">
+<title>Boost.Python - Extractor Concept</title>
+</head>
+<body link="#0000ff" vlink="#800080">
+<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+  <tr> 
+    <td valign="top" width="300"> 
+      <h3><a href="../../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+    </td>
+    <td valign="top"> 
+      <h1 align="center">Boost.Python</h1>
+      <h2 align="center">Extractor Concept</h2>
+    </td>
+  </tr>
+</table>
+<hr>
+<dl class="page-index"> 
+  <dt><a href="#introduction">Introduction</a></dt>
+  <dt><a href="#concept-requirements">Concept Requirements</a></dt>
+  <dl class="page-index"> 
+    <dt><a href="#Extractor-concept">Extractor Concept</a></dt>
+  </dl>
+  <dt><a href="#notes">Notes</a></dt>
+</dl>
+
+<h2><a name="introduction"></a>Introduction</h2>
+
+<p>An Extractor is a class which Boost.Python can use to extract C++
+objects from Python objects, and is typically used by facilities that
+define <code>from_python</code> conversions for
+&quot;traditional&quot; Python extension types. 
+
+<h2><a name="concept-requirements"></a>Concept Requirements</h2>
+<h3><a name="Extractor-concept"></a>Extractor Concept</h3>
+
+<p>In the table below, <code><b>X</b></code> denotes a model of
+Extractor and <code><b>a</b></code> denotes an instance of a Python
+object type.
+
+<table summary="Extractor expressions" border="1" cellpadding="5">
+
+  <tr> 
+    <td><b>Expression</b></td>
+    <td><b>Type</b></td>
+    <td><b>Semantics</b></td>
+  </tr>
+
+  <tr> 
+    <td valign="top"><code>X::execute(a)</code></td>
+    <td>non-void
+    <td>Returns the C++ object being extracted. The
+    <code>execute</code> function must not be overloaded.
+  </tr>
+
+  <tr> 
+    <td valign="top"><code>&amp;a.ob_type</code>
+    <td><code><a
+        href="http://www.python.org/doc/2.2/ext/dnt-type-methods.html">PyTypeObject</a>**</code>
+    <td>Points to the <code>ob_type</code> field of an object which is
+    layout-compatible with <code>PyObject</code>
+  </tr>
+
+  </tr>
+
+</table>
+
+<h2><a name="notes"></a>Notes</h2>
+
+Informally, an Extractor's <code>execute</code> member must be a
+non-overloaded static function whose single argument is a Python
+object type. Acceptable Python object types include those publicly (and
+unambiguously) derived from <code>PyObject</code>, and POD types which
+are layout-compatible with PyObject.
+
+<hr>
+<p>Revised 
+  <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+  22 May, 2002
+  <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+</p>
+    <p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
+    Abrahams</a> 2002. All Rights Reserved.</i>
+
+<p>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.
+</body>
+</html>

doc/v2/HolderGenerator.html

@@ -0,0 +1,71 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+<link rel="stylesheet" type="text/css" href="../../../boost.css">
+<title>Boost.Python - Holder Concept</title>
+</head>
+<body link="#0000ff" vlink="#800080">
+<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+  <tr> 
+    <td valign="top" width="300"> 
+      <h3><a href="../../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+    </td>
+    <td valign="top"> 
+      <h1 align="center">Boost.Python</h1>
+      <h2 align="center">HolderGenerator Concept</h2>
+    </td>
+  </tr>
+</table>
+<hr>
+<dl class="page-index"> 
+  <dt><a href="#introduction">Introduction</a></dt>
+  <dt><a href="#concept-requirements">Concept Requirements</a></dt>
+  <dl class="page-index"> 
+    <dt><a href="#HolderGenerator-concept">HolderGenerator Concept</a></dt>
+  </dl>
+</dl>
+
+<h2><a name="introduction"></a>Introduction</h2>
+
+<p>A HolderGenerator is a unary metafunction class which returns types
+suitable for holding instances of its argument in a wrapped C++ class
+instance.
+
+<h2><a name="concept-requirements"></a>Concept Requirements</h2>
+<h3><a name="HolderGenerator-concept"></a>HolderGenerator Concept</h3>
+
+<p>In the table below, <code><b>G</b></code> denotes an type which
+models HolderGenerator, and <code><b>X</b></code> denotes a class
+type.
+
+<table summary="Holder expressions" border="1" cellpadding="5">
+
+  <tr> 
+    <td><b>Expression</b></td>
+    <td><b>Requirements</b></td>
+  </tr>
+
+  <tr> 
+    <td valign="top"><code>G::apply&lt;X&gt;::type</code></td>
+    <td>A concrete subclass of <a
+    href="instance_holder.html#instance_holder-spec">instance_holder</a>
+    which can hold objects of type <code>X</code>.
+  </tr>
+</table>
+
+<hr>
+<p>Revised 
+  <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+  20 May, 2002
+  <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+</p>
+    <p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
+    Abrahams</a> 2002. All Rights Reserved.</i>
+
+<p>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.
+</body>
+</html>

doc/v2/Jun2002.html

@@ -0,0 +1,226 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+<link rel="stylesheet" type="text/css" href="../boost.css">
+<title>Boost.Python - June 2002 Progress Report</title>
+</head>
+<body link="#0000ff" vlink="#800080">
+<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+  <tr> 
+    <td valign="top" width="300"> 
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+    </td>
+    <td valign="top"> 
+      <h1 align="center">Boost.Python</h1>
+      <h2 align="center">June 2002 Progress Report</h2>
+    </td>
+  </tr>
+</table>
+<hr>
+<h2>Contents</h2>
+<dl class="index">
+  <dt><a href="#intro">Introduction</a></dt>
+  <dt><a href="#handle"><code>handle&lt;T&gt;</code></a></dt>
+  <dt><a href="#object"><code>object</code></a></dt>
+  <dl class="index">
+    <dt><a href="#operators"><code>object</code> operators</a></dt>
+    <dt><a href="#conversions"><code>object</code> conversions</a></dt>
+  </dl>
+  <dt><a href="#list"><code>list</code></a></dt>
+  <dt><a href="#numerics"><code>Numerics</code></a></dt>
+  <dt><a href="#community">Community</a></dt>
+  <dt><a href="#next">What's Next</a></dt>
+</dl>
+
+<h2><a name="intro">Introduction</a></h2>
+
+July was mostly focused on allowing expressive manipulation of
+individual Python objects, or what Ralf Grosse-Kunstleve calls
+&quot;Writing Python in C++&quot;. The work began with this <a
+href="http://mail.python.org/pipermail/c++-sig/2002-June/001311.html">posting</a>,
+which outlines the issues and intention.
+
+<h2><a name="handle"><code>handle&lt;T&gt;</code></a></h2>
+
+The most basic element needed was a replacement for the
+<code>reference&lt;&gt;</code> class template and the
+<code>ref</code> typedef from Boost.Python v1, a simple smart
+pointer to a Python object. The old v1 typedef
+&quot;<code>ref</code>&quot; (for
+<code>reference&lt;PyObject&gt;</code>) had to be retired because I
+thought it would be too confusing given the importance of <code><a
+href="../../../bind/ref.html">boost::ref</a>()</code> to this
+library. I began a <a
+href="http://mail.python.org/pipermail/c++-sig/2002-June/001311.html">discussion</a>of
+possible names, and it was eventually <a
+href="http://mail.python.org/pipermail/c++-sig/2002-June/001337.html">decided</a>
+to rename <code>reference</code> to <code>handle</code> and supply a
+default argument so that <code>ref</code> could be spelled
+<code>handle&lt;&gt;</code> without an additional typedef. There
+were also some interface changes to make it safer and more-efficient
+to interface with the raw
+<code>PyObject*</code>s forced on us by Python's 'C' API. A
+discussion of those protocols can be found <a
+href="http://mail.python.org/pipermail/c++-sig/2002-June/001401.html">here</a>.
+
+<h2><a name="handle"><code>object</code></a></h2>
+
+It is intended that users will seldom need or want to work with
+<code>handle&lt;&gt;</code>; its major distinguishing features are
+that it gives direct access to the underlying object representation
+through <code>operator*</code> and <code>operator-&gt;</code>, and
+that can be <code>NULL</code>, both sources of danger. Instead the
+library provides a class called <code>object</code>, which
+encapsulates a valid Python object and provides a similar interface to
+Python's.
+
+<h3><a name="operators"><code>object</code> operators</a></h3>
+
+The first challenge was to provide support for object manipulations
+using a Python-like syntax, mostly in the form of operator overloads:
+
+<table border="1">
+<tr><th>Python <th>C++
+
+<tr>
+  <td><code>y = x.foo</code>  <td><code>y = x.attr(&quot;foo&quot;); 
+<tr>
+  <td><code>x.foo = 1</code>  <td><code>x.attr(&quot;foo&quot;) = 1; 
+
+<tr>
+  <td><code>y = x[z]</code>  <td><code>y = x[z];
+<tr>
+  <td><code>x[z] = 1</code>  <td><code>x[z] = 1; 
+
+<tr>
+  <td><code>y = x[3:-1]</code>  <td><code>y = x.slice(3,-1); 
+
+<tr>
+  <td><code>y = x[3:]</code>  <td><code>y = x.slice(3,_); 
+
+<tr>
+  <td><code>y = x[:-2]</code>  <td><code>y = x.slice(_,-2); 
+
+<tr>
+  <td><code>z = x(1, y)</code>  <td><code>z = x(1, y);
+<tr>
+  <td><code>z = x.f(1, y)</code>  <td><code>z = x.attr(&quot;f&quot;)(1, y);
+
+<tr>
+  <td><code>not x</code>  <td><code>!x
+
+<tr>
+  <td><code>x and y</code>  <td><code>x and y
+</table>
+
+I'm still a unsatisfied with the interface for attribute access. There
+original proposal  used a syntax like this one:
+<pre>
+y = x._(&quot;foo&quot;); 
+x._(&quot;foo&quot;) = 1; 
+</pre>
+
+which was only marginally better than what we've got. Niki Spahiev
+then <a
+href="http://mail.python.org/pipermail/c++-sig/2002-June/001447.html">pointed
+out</a> a potential conflict with the macro which GNU Gettext <a
+href="http://www.gnu.org/manual/gettext/html_mono/gettext.html#SEC6">suggests</a>
+people define. This unfortunate state of affairs forced us into using
+<code>attr</code> instead. I'd still like to find a better interface,
+but the lack of overloadable C++ operators which aren't already used
+in Python is an obstacle. The comma operator is still a possibility,
+but it has the wrong precedence:
+<pre>
+y = x,&quot;foo&quot;    // error
+x,&quot;foo&quot; = 1;   // error
+
+y = (x,&quot;foo&quot;); // ok
+(x,&quot;foo&quot;) = 1; // ok
+</pre>
+
+Well, I guess we could consider adding that to the interface without
+removing <code>attr()</code>, to see how it plays out...
+
+<h3><a name="operators"><code>object</code> conversions</a></h3>
+
+The <code>object</code> class also provided an opportunity to replace
+Boost.Python v1's <code>to_python()</code> as a user-level
+interface. Instead, <code>object</code> has a templated constructor
+which can be used to convert any C++ object to Python using the same
+underlying mechanisms used for the arguments to <code><a
+href="call.html">call</a>&lt;&gt;</code>.
+
+<p>Incidentally, the implementation of operator and conversion support
+for object uncovered an inordinate number of compiler bugs in our
+targeted platforms. It was a lot more &quot;interesting&quot; than it
+should have been.
+
+<h2><a name="list"><code>list</code></a></h2>
+
+With <code>object</code> implemented, it was time to begin replacing
+the ad-hoc implementations of <code>list</code>, <code>string</code>,
+and <code>dictionary</code> supplied by Boost.Python v1 with something
+more robust. I started with <code>list</code> as an example. Because
+<code>object</code> already provides all of the requisite operators,
+publicly deriving <code>list</code> from object seemed like a good
+choice. The remaining issues were what do do about the one-argument
+list constructor (which in Python attempts to convert its argument to
+a list), and how to deal converting with <code>list</code> arguments
+to wrapped functions. Some of the issues are laid out in <a
+href="http://mail.python.org/pipermail/c++-sig/2002-June/001551.html">this
+thread</a>. Ultimately, it was decided that <code>list(x)</code>
+should do the same thing in C++ as in Python (conversion), while
+<code>list</code> arguments should only match Python
+<code>list</code>s (and <code>list</code> subclasses). The
+implementation worked well, and provided a <a
+href="http://mail.python.org/pipermail/c++-sig/2002-June/001586.html">roadmap</a>
+for the protocol to be used for implementation of the other built-in
+types.
+
+<h2><a name="numerics">Numerics</a></h2>
+
+Support for C++ <code>long long</code> and <code>unsigned long
+long</code>
+(and <code>__int64</code> on MSVC) to/from python conversions was
+added this month. We also improved handling of numeric overflows when
+converting, e.g., a Python int to a type with a more limited range of
+representation.
+
+<h2><a name="community">Community</a></h2>
+
+<ul>
+<li>Ralf W. Grosse-Kunstleve and Nick Sauter have implemented
+<a href="http://cci.lbl.gov/boost/">multiplatform nightly
+build-and-test</a> runs for Boost.Python V2 at LBL.
+
+<li>Dave Hawkes has made significant progress on generating the
+Python <a
+href="http://mail.python.org/pipermail/c++-sig/2002-June/001503.html">built-in
+function and API wrappers</a>
+
+<li>Achim Domma has agreed to take up the job of implementing the
+<code>str</code>, <code>dict</code>, and <code>tuple</code> classes.
+</ul>
+
+Deep thanks to all the Boost.Python contributors! This project
+wouldn't be possible without your participation.
+
+  <h2><a name="next">What's Next</a></h2>
+
+As I write this we are already well into the month of July, so I
+suggest you consult the <a
+href="http://mail.python.org/pipermail/c++-sig/2002-July/">Mailing
+List Archive</a> if you want to know what's been happening. Otherwise
+you'll just have to wait till next month (hopefully the beginning).
+
+<p>Revised 
+  <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+  19 July, 2002 
+  <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+</p>
+<p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave Abrahams</a> 
+  2002. All Rights Reserved.</i></p>
+</body>
+</html>

doc/v2/Mar2002.html

@@ -0,0 +1,234 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+<link rel="stylesheet" type="text/css" href="../boost.css">
+<title>Boost.Python - March 2002 Progress Report</title>
+</head>
+<body link="#0000ff" vlink="#800080">
+<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+  <tr> 
+    <td valign="top" width="300"> 
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+    </td>
+    <td valign="top"> 
+      <h1 align="center">Boost.Python</h1>
+      <h2 align="center">March 2002 Progress Report</h2>
+    </td>
+  </tr>
+</table>
+<hr>
+<h2>Contents</h2>
+<dl class="index">
+  <dt><a href="#accomplishments">Accomplishments</a></dt>
+  <dl class="index">
+    <dt><a href="#calling_python">Calling Python from C++</a></dt>
+    <dt><a href="#virtual_functions">Virtual Functions</a></dt>
+    <dt><a href="#abstract_classes">Abstract Classes</a></dt>
+    <dt><a href="#implicit_conversions">C++ Implicit Conversions</a></dt>
+    <dt><a href="#data_members">C++ Data Members</a></dt>
+    <dt><a href="#miscellaneous">Miscellaneous</a></dt>
+  </dl>
+
+  <dt><a href="#future">The Near future</a></dt>
+
+  <dt><a href="#notes">Notes</a></dt>
+
+</dl>
+
+<h2><a name="accomplishments">Accomplishments</a></h2>
+
+March was mostly devoted to the reimplementation of features from
+Boost.Python v1, and some new features. Re-examination of the features
+from Boost.Python v1 allowed me to make significant improvements.
+
+<h3><a name="calling_python">Calling Python from C++</a></h3>
+
+The ability to call Python from C++ is crucial for virtual function
+support. Implementing this feature well for V2 proved to be more
+interesting than I expected. You can review most of the relevant
+design decisions
+<a href="callbacks.txt">here</a>.
+
+<p>
+One point which <i>isn't</i> emphasized in that document is that there
+are subtle differences in the way <code>from_python</code> conversions
+work when used for C++ function arguments and Python function return
+values. In particular, while <code>T const&amp;</code> arguments may
+invoke rvalue converters, a reference-to-const return value requires
+an lvalue converter, since a temporary conversion result would leave
+the returned reference dangling.
+
+<p>I'm not particularly pleased with the current callback interface,
+since it usually results in constructs like:
+<pre>
+<u>return returning</u>&lt;X&amp;&gt;::call(f, obj);
+</pre>
+However, I think the following may be possible and I plan to investigate:
+<pre>
+return apply&lt;X&amp;&gt;(f, obj);
+</pre>
+I'm open to suggestion for better names (and syntaxes)!
+
+<h3><a name="virtual_functions">Virtual Functions</a></h3>
+
+Once Python callbacks were implemented, it was just a short step to
+implementing virtual functions. Python extension class exposing a C++
+class whose virtual functions are overridable in Python must actually
+hold a C++ instance of a class <i>derived</i> from the one exposed to
+Python. Needing some way for users to specify that class, I added an
+optional template argument to <code>value_holder_generator</code> and
+<code>pointer_holder_generator&lt;&gt;</code> to specify the class
+actually held. This move began to put pressure on the
+<code>class_&lt;&gt;</code> interface, since the need for the user to
+produce complicated instantations of
+<code>class_&lt;&gt;</code> was increased:
+
+<pre>
+class&lt;Foo, bases&lt;&gt;, value_holder_generator&lt;Foo_callback&gt; &gt;(&quot;Foo&quot;)
+.def(&quot;hello&quot;, &amp;Foo::hello)
+...
+</pre>
+
+<h3><a name="abstract_classes">Abstract Classes</a></h3>
+
+Normally when a C++ class is exposed to Python, the library registers
+a conversion function which allows users to wrap functions returning
+values of that type. Naturally, these return values are temporaries,
+so the conversion function must make a copy in some
+dynamically-allocated storage (a &quot;holder&quot;) which is managed
+by the corresponding Python object.
+
+<p>Unfortunately, in the case of abstract classes (and other types
+without a publicly-accessible copy constructor), instantiating this
+conversion function causes a compilation error.  In order to support
+non-copyable classes, there had to be some way to prevent the library
+from trying to instantiate the conversion function. The only practical
+approach I could think of was to add an additional template parameter
+to the <code>class_&lt;&gt;</code> interface. When the number of
+template parameters with useful defaults begins to grow, it is often
+hard to choose an order which allows users to take advantage of the
+defaults.
+
+<p>
+
+This was the straw that broke the
+<code>class_&lt;&gt;</code> interface's back and caused the redesign
+whose outcome is detailed <a
+href="http://mail.python.org/pipermail/c++-sig/2002-March/000892.html">here</a>.
+The approach allows the user to supply the optional parameters in an
+arbitrary order. It was inspired by the use of <a
+href="../../../utility/iterator_adaptors.htm#named_tempalte_parameters">named
+template parameters</a> in the <a
+href="../../../utility/iterator_adaptors.htm">Boost Iterator Adaptor
+Library</a>, though in this case it is possible to deduce the meaning
+of the template parameters entirely from their type properties,
+resulting in a simpler interface. Although the move from a
+policy-based design to what resembles a configuration DSL usually
+implies a loss of flexibility, in this case I think any costs are far
+outweighed by the advantages.
+
+<p>Note: working around the limitations of the various compilers I'm
+supporting was non-trivial, and resulted in a few messy implementation
+details. It might be a good idea to switch to a more-straightforward
+approach once Metrowerks CodeWarrior Pro8 is released.
+
+<h3><a name="implicit_conversions">C++ Implicit Conversions</a></h3>
+
+Support for C++ implicit conversion involves creating
+<code>from_python</code> converters for a type <code>U</code> which in
+turn use <code>from_python</code> converters registered for a type
+<code>T</code> where there exists a implicit conversion from
+<code>T</code> to <code>U</code>. The current implementation is
+subject to two inefficiencies:
+<ol>
+
+<li>Because an rvalue <code>from_python</code> converter produces two
+pieces of data (a function and a <code>void*</code>) from its
+<code>convertible()</code> function, we end up calling the function
+for <code>T</code> twice: once when the converter is looked up in the
+registry, and again when the conversion is actually performed. 
+
+<li>A vector is used to mark the "visited" converters, preventing
+infinite recursion as <code>T</code> to
+<code>U</code> and <code>U</code> to <code>T</code> converters
+continually search through one-another.
+
+</ol>
+
+I consider the former to be a minor issue. The second may or may not
+prove to be computationally significant, but I believe that
+architecturally, it points toward a need for more sophisticated
+overload resolution. It may be that we want CLOS-style multimethod
+dispatching along with C++ style rules that prevent more than one
+implicit conversion per argument.
+
+<h3><a name="data_members">C++ Data Members</a></h3>
+
+To supply the ability to directly access data members, I was able to
+hijack the new Python <a
+href="http://www.python.org/2.2/descrintro.html#property">property</a>
+type. I had hoped that I would also be able to re-use the work of <a
+href="make_function.html">make_function</a> to create callable python
+objects from C++ functions which access a data member of a given
+class. C++ facilities for specifying data member pointer non-type
+template arguments require the user to explicitly specify the type of
+the data member and this under-utilized feature is also not
+well-implemented on all compilers, so passing the member pointer as a
+runtime value is the only practical approach. The upshot is that any
+such entity would actually have to be a function <i>object</i>, and I
+haven't implemented automatic wrapping of C++ callable function
+objects yet, so there is less re-use in the implementation than I'd
+like. I hope to implement callable object wrapping and refactor this
+code one day. I also hope to implement static data member support,
+for which Python's property will not be an appropriate descriptor.
+
+<h3><a name="miscellaneous">Miscellaneous</a></h3>
+<ul>
+<li>Moved <code>args&lt;&gt;</code> and <code>bases&lt;&gt;</code> from unnamed namespace to <code>boost::python</code> in their own header files.
+<li>Convert <code>NULL</code> pointers returned from wrapped C++ functions to <code>None</code>.
+<li>Improved some compile-time error checks.
+<li>Eliminated <code>boost/python/detail/eval.hpp</code> in favor of
+more-general <code>boost/mpl/apply.hpp</code>.
+<li>General code cleanup and refactoring.
+<li>Works with Microsoft Visual C++ 7.0
+<li>Warning suppression for many compilers
+<li>Elegant interface design for exporting <code>enum</code> types.
+</ul>
+<hr>
+
+<h2><a name="future">The Near Future</a></h2>
+
+Before April 15th I plan to 
+<ol>
+<li>Document all implemented features
+<li>Implement a <code>CallPolicy</code> interface for constructors of wrapped
+classes
+<li>Implement conversions for <code>char</code> types.
+<li>Implement automated code generation for all headers containing
+families of overloaded functions to handle arbitrary arity.
+</ol>
+
+I also hope to implement a mechanism for generating conversions
+between arbitrary Python sequences and C++ containers, if time permits
+(and others haven't already done it)!
+
+<h2><a name="notes">Notes</a></h2>
+
+The older version of KCC used by Kull is generating lots of warnings
+about a construct I use to instantiate static members of various class
+templates. I'm thinking of moving to an idiom which uses a function
+template to suppress it, but worry about bloating the size of debug
+builds. Since KCC users may be moving to GCC, I'm not sure that it's
+worth doing anything about it.
+
+<p>Revised 
+  <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+  1 April, 2002 
+  <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+</p>
+<p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave Abrahams</a> 
+  2002. All Rights Reserved.</i></p>
+</body>
+</html>

doc/v2/May2002.html

@@ -0,0 +1,309 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+<link rel="stylesheet" type="text/css" href="../boost.css">
+<title>Boost.Python - May 2002 Progress Report</title>
+</head>
+<body link="#0000ff" vlink="#800080">
+<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+  <tr> 
+    <td valign="top" width="300"> 
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+    </td>
+    <td valign="top"> 
+      <h1 align="center">Boost.Python</h1>
+      <h2 align="center">May 2002 Progress Report</h2>
+    </td>
+  </tr>
+</table>
+<hr>
+<h2>Contents</h2>
+<dl class="index">
+  <dt><a href="#intro">Introduction</a></dt>
+  <dt><a href="#features">New Features</a></dt>
+  <dl>
+    <dt><a href="#aix_shared">Shared Library Support for AIX</a><dd>
+    <dt><a href="#class_enhancements">Class Enhancements</a><dd>
+    <dl>
+      <dt><a href="#operators">Operators</a><dd>
+      <dt><a href="#iterators">Iterators</a><dd>
+      <dt><a href="#properties">Properties</a><dd>
+      <dt><a href="#setattr">setattr</a><dd>
+      <dt><a href="#module">__module__ Attribute</a><dd>
+    </dl>
+    <dt><a href="#back_reference">back_reference</a><dd>
+ </dl>
+
+  <dt><a href="#documentation">Documentation</a></dt>
+   <dt><a href="#misc">Miscellaneous</a></dt>
+  <dl class="index">
+    <dt><a href="#converters">Converters</a></dt>
+    <dt><a href="#checkins">Checkins Mailing List</a></dt>
+    <dt><a href="#shared">Shared Libraries</a></dt>
+  </dl>
+
+  <dt><a href="#next">What's Next</a></dt>
+</dl>
+
+<h2><a name="intro">Introduction</a></h2>
+
+Aside from library development, work on Boost.Python in May was
+focused on reducing the support burden. In recent weeks, responding to
+requests for support, espcially surrounding building the library, had
+begun to impede progress on development. There was a major push to
+release a stable 1.28.0 of Boost, including documentation of <a
+href="../../../../tools/build/index.html">Boost.Build</a> and specific
+<a href="../building.html">instructions</a> for building Boost.Python
+v1. The documentation for Boost.Python v2 was also updated as
+described <a href="#documentation">here</a>.
+
+<h2><a name="features">New Features</a></h2>
+
+  <h3><a name="aix_shared">Shared Library Support for AIX</a></h3>
+
+  The Kull group required the ability to build and test Boost.Python
+  extensions on AIX, a platform with &quot;creatively designed&quot;
+  shared library semantics. Making this work was a multi-pronged
+  effort, involving changes to Boost.Build and some great research by
+  Martin Casado which uncovered the key mechanism required to allow
+  shared libraries to use functions from the Python executable. The
+  current solution used in Boost.Build relies on a <a
+  href="../../../../tools/build/gen_aix_import_file.py">Python
+  Script</a> as part of the build process. This is not a problem for
+  Boost.Python, as Python will be available. However, the commands
+  issued by the script are so simple that a 100%-pure-Boost.Jam
+  solution is surely possible. Linking on AIX is sufficiently
+  interesting to have skewed the Boost.Python development schedule a
+  bit.
+
+  <h3><a name="class_enhancements">Class Enhancements</a></h3>
+
+      <h4><a name="operators">Operators</a></h4>
+
+Support for exposing C++ operators and functions as the corresponding
+Python special methods was added. Thinking that the Boost.Python
+<a href="../special.html#numeric">v1 interface</a> was a little too
+esoteric (especially the use of
+<code>left_operand&lt;...&gt;/right_operand&lt;...&gt;</code> for
+asymmetric operands), I introduced a simple form of <a
+href="http://osl.iu.edu/~tveldhui/papers/Expression-Templates/exprtmpl.html">expression
+templates</a> which allow users to simply write the expressions that
+should be wrapped, as in this <a href="operators.html#examples">example</a>.
+
+      <h4><a name="iterators">Iterators</a></h4>
+
+Python iterator support as required by the Kull project resulted in a
+highly flexible interface allowing:
+
+<dl>
+
+<dt>Direct exposure of a class' <code>begin()</code> and
+<code>end()</code> functions:
+
+<pre>
+    ...
+    .def(&quot;__iter__&quot;, iterator&lt;list_int&gt;())
+</pre>
+<dd>
+
+<dt>Creation of iterators from member functions...
+<pre>
+    ...
+    .def(&quot;__iter__&quot;
+         , range(&amp;my_class::x_begin, &amp;my_class::x_end))
+    )
+</pre>
+<dd>
+
+<dt>...and member data:
+<pre>
+    ...
+    .def(&quot;__iter__&quot;
+         , range(&amp;std::pair&lt;char*,char*&gt;::first, &amp;std::pair&lt;char*,char*&gt;::second))
+    )
+</pre>
+<dd>
+
+<dt>The ability to specify <a
+href="CallPolicies.html">CallPolicies</a>, e.g. to prevent copying of
+heavyweight values:
+
+<pre>
+    ...
+    .def(&quot;__iter__&quot;, 
+         , range&lt;return_value_policy&lt;copy_non_const_reference&gt; &gt;(
+               &amp;my_sequence&lt;heavy&gt;::begin
+             , &amp;my_sequence&lt;heavy&gt;::end))
+</pre>
+<dd>
+
+</dl>
+
+      <h4><a name="properties">Properties</a></h4>
+
+The Kull iteration interfaces also required the ability to iterate
+over a sequence specified by an instance's attribute:
+<pre>
+&gt;&gt;&gt; f = field()
+&gt;&gt;&gt; for e in f.elements:
+...     print e,
+</pre>
+
+This forced the exposure of the <a
+      href="http://www.python.org/2.2/descrintro.html#property"><code>property</code></a>
+      interface used internally to implement the data member exposure
+      facility described in <a
+      href="Mar2002#data_members">March</a>. Properties are an
+      incredibly useful idiom, so it's good to be able to provide them
+      at little new development cost.
+
+      <h4><a name="setattr">setattr</a></h4>
+
+<code>class_&lt;&gt;</code> acquired a <code>setattr</code> member
+function which allows users to easily add new Python objects as class
+attributes.
+
+      <h4><a name="module">__module__ Attribute</a></h4>
+
+Ralf Grosse-Kunstleve has been working on pickling support for v2. To
+make it work correctly, he had to make sure that a class'
+<code>__module__</code> attribute was set correctly.
+
+<h3><a name="back_reference"><code>back_reference</code></a></h3>
+
+The new <code>back_reference&lt;T&gt;</code> template can be used as a
+function parameter when the user needs access to both a <code>T</code>
+argument and to the Python object which manages it. The function will
+only match in the overload resolution process if it would match the
+same function signature with <code>T</code> substituted for
+<code>back_reference&lt;T&gt;</code>. This feature is not yet
+documented.
+
+<h2><a name="documentation">Documentation</a></h2>
+
+In a major effort to prepare Boost.Python v2 to replace v1, many pages
+of new reference documentation were added:
+
+<blockquote>
+
+<dl>
+        <dt><a href="CallPolicies.html">CallPolicies.html</a><dd>
+        <dt><a href="Dereferenceable.html">Dereferenceable.html</a><dd>
+        <dt><a href="Extractor.html">Extractor.html</a><dd>
+        <dt><a href="HolderGenerator.html">HolderGenerator.html</a><dd>
+        <dt><a href="ResultConverter.html">ResultConverter.html</a><dd>
+        <dt><a href="call_method.html">call_method.html</a><dd>
+        <dt><a href="callbacks.html">callbacks.html</a><dd>
+        <dt><a href="data_members.html">data_members.html</a><dd>
+        <dt><a href="has_back_reference.html">has_back_reference.html</a><dd>
+        <dt><a href="implicit.html">implicit.html</a><dd>
+        <dt><a href="instance_holder.html">instance_holder.html</a><dd>
+        <dt><a href="operators.html">operators.html</a><dd>
+        <dt><a href="ptr.html">ptr.html</a><dd>
+        <dt><a href="type_id.html">type_id.html</a><dd>
+        <dt><a href="with_custodian_and_ward.html">with_custodian_and_ward.html</a><dd>
+</dl>
+
+</blockquote>
+Major updates were made to the following pages:
+
+
+<blockquote>
+<dl>
+        <dt><a href="call.html">call.html</a><dd> <dt><a href="updated">updated</a><dd>
+        <dt><a href="class.html">class.html</a><dd>
+        <dt><a href="reference.html">reference.html</a><dd>
+</dl>
+</blockquote>
+
+         As usual, careful documentation forces one to consider the
+         interface again, and there were many interface changes
+         associated with this effort, including the elevation of the
+         following components from implementation detail to
+         first-class library citizen:
+
+<blockquote>
+<dl>
+        <dt>type_id.hpp<dd>
+        <dt>pointee.hpp<dd>
+        <dt>lvalue_from_pytype.hpp<dd></dl>
+</dl>
+</blockquote>
+
+<h2><a name="misc">Miscellaneous</a></h2>
+
+    <h3><a name="converters">Converters</a></h3>
+
+It appears that the world of C++ &lt;==&gt; Python conversion rules is
+an endlessly-rich area of exploration. Completing the conversions for
+<code>char</code> and <code>char const*</code> types, as described at
+the end of <a href="Apr2002.html#missing">April's report</a>,
+uncovered some interesting new shades to the problem. It turns out to
+be worth distinguishing mutable and immutable lvalue conversions,
+because despite the fact that Python doesn't understand
+<code>const</code>, it does understand immutability (c.f. Python
+strings, which expose an immutable <code>char</code> pointer). It is
+also worth recognizing types which represent lvalue <i>sequences</i>,
+to prevent Python <code>&quot;foobar&quot;</code> from being silently
+truncated to C++ <code>'f'</code>. More details on this insight can be
+found in the mailing list <a
+href="http://mail.python.org/pipermail/c++-sig/2002-May/001023.html">
+archive</a>. I don't plan to do anything about this immediately, but I
+do think it's the right direction to go in the long run.
+
+    <h3><a name="checkins">Checkins Mailing List</a></h3>
+
+In order to better coordinate changes made by multiple developers, I
+enabled <a
+href="http://sourceforge.net/docman/display_doc.php?docid=772&group_id=1">syncmail</a>
+for the Boost.Python CVS trees, and established an associated <a
+href="http://lists.sourceforge.net/lists/listinfo/boost-python-cvs">mailing
+list</a>. Subscribe to this list to receive notices of each new
+checkin.
+
+    <h3><a name="shared">Shared Libraries</a></h3>
+
+Beyond the vagaries of dynamic linking on AIX, I have been
+participating in a more-general discussion of dynamic linking for
+C++. Needless to say, C++ dynamic linking is of critical importance to
+Boost.Python: all extension modules are normally built as shared
+libraries, and Boost.Python extension modules share a common library
+as well. 
+
+In fact, there are at least two separate conversations. One
+in the C++ standard extensions mailing list concerns what can be
+standardized for C++ and shared libraries; the other, mostly on the <a
+href="http://gcc.gnu.org/ml/gcc/">gcc</a> mailing list, concerns the
+behavior of GCC on Posix/ELF platforms. 
+
+Some of the GCC threads are here:
+
+<blockquote>
+<a
+href="http://gcc.gnu.org/ml/gcc/2002-05/msg02002.html">http://gcc.gnu.org/ml/gcc/2002-05/msg02002.html</a><br>
+<a
+href="http://gcc.gnu.org/ml/gcc/2002-05/msg02945.html">http://gcc.gnu.org/ml/gcc/2002-05/msg02945.html</a><br>
+<a href="http://gcc.gnu.org/ml/gcc/2002-05/msg01758.html">http://gcc.gnu.org/ml/gcc/2002-05/msg01758.html</a>
+</blockquote>
+
+  <h2><a name="next">What's Next</a></h2>
+
+Development is focused on what's needed to be able to retire
+Boost.Python v1. At the moment, that means deciding the user-friendly
+interfaces for to_/from_python conversion, and formally exposing the
+Python object smart pointers and object wrapper classes. Quite a few
+questions have also been showing up recently about how to embed Python
+with Boost.Python, and how to link with it statically; the solutions
+to these issues will probably have to be formalized before long.
+
+<p>Revised 
+  <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+  11 June, 2002 
+  <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+</p>
+<p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave Abrahams</a> 
+  2002. All Rights Reserved.</i></p>
+</body>
+</html>

doc/v2/ResultConverter.html

@@ -0,0 +1,110 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+<link rel="stylesheet" type="text/css" href="../../../boost.css">
+<title>Boost.Python - ResultConverter Concept</title>
+</head>
+<body link="#0000ff" vlink="#800080">
+<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+  <tr> 
+    <td valign="top" width="300"> 
+      <h3><a href="../../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+    </td>
+    <td valign="top"> 
+      <h1 align="center">Boost.Python</h1>
+      <h2 align="center">ResultConverter Concept</h2>
+    </td>
+  </tr>
+</table>
+<hr>
+<dl class="page-index"> 
+  <dt><a href="#introduction">Introduction</a></dt>
+  <dt><a href="#concept-requirements">Concept Requirements</a></dt>
+  <dl class="page-index"> 
+    <dt><a href="#ResultConverter-concept">ResultConverter Concept</a></dt>
+    <dt><a href="#ResultConverterGenerator-concept">ResultConverterGenerator Concept</a></dt>
+  </dl>
+</dl>
+
+<h2><a name="introduction"></a>Introduction</h2>
+
+<p>A ResultConverter for a type <code>T</code> is a type whose
+instances can be used to convert C++ return values of type
+<code>T</code> <code>to_python</code>. A ResultConverterGenerator is
+an MPL unary metafunction class which, given the return type of a C++
+function, returns a ResultConverter for that type. ResultConverters in
+Boost.Python generally inspect library's registry of converters to
+find a suitable converter, but converters which don't use the registry
+are also possible.
+
+<h2><a name="concept-requirements"></a>Concept Requirements</h2>
+<h3><a name="ResultConverter-concept"></a>ResultConverter Concept</h3>
+
+<p>In the table below, <code><b>C</b></code> denotes a ResultConverter
+type for a type <b><code>R</code></b> , <code><b>c</b></code> denotes
+an object of type <code><b>C</b></code> , and <code><b>r</b></code>
+denotes an object of type <code><b>R</b></code>.
+
+<table summary="ResultConverter expressions" border="1" cellpadding="5">
+
+  <tr> 
+    <td><b>Expression</b></td>
+    <td><b>Type</b></td>
+    <td><b>Semantics</b></td>
+  </tr>
+
+  <tr> 
+    <td valign="top"><code>C c;</code></td>
+    <td>
+    <td>Constructs a <code>C</code> object.
+  </tr>
+
+  <tr> 
+    <td valign="top"><code>c.convertible()</code></td>
+    <td>convertible to <code>bool</code></td>
+    <td><code>false</code> iff no conversion from any <code>R</code> value
+    to a Python object is possible.</td>
+  </tr>
+
+  <tr> 
+    <td valign="top"><code>c(r)</code></td>
+    <td>convertible to <code>PyObject*</code></td>
+    <td>A pointer to a Python object corresponding to <code>r</code>,
+    or <code>0</code> iff <code>r</code> could not be converted
+    <code>to_python</code>, in which case <a
+    href="http://www.python.org/doc/current/api/exceptionHandling.html#l2h-71">PyErr_Occurred</a>
+    should return non-zero.</td>
+  </tr>
+</table>
+
+<h3><a name="ResultConverterGenerator-concept"></a>ResultConverterGenerator Concept</h3>
+<p>In the table below, <code><b>G</b></code> denotes a
+ResultConverterGenerator type and <code><b>R</b></code> denotes a possible
+C++ function return type.
+
+<table summary="ResultConverterGenerator expressions" border="1" cellpadding="5">
+  <tr> 
+    <td><b>Expression</b></td>
+    <td><b>Requirements</b></td>
+  </tr>
+  <tr> 
+    <td valign="top"><code>G::apply&lt;R&gt;::type</code></td>
+    <td>A ResultConverter type for <code>R</code>.</td>
+</table>
+
+<hr>
+<p>Revised 
+  <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+  09 May, 2002    <!--Luann's birthday! -->
+  <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+</p>
+    <p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
+    Abrahams</a> 2002. All Rights Reserved.</i>
+
+<p>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.
+</body>
+</html>

doc/v2/acknowledgments.html

@@ -0,0 +1,32 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+<link rel="stylesheet" type="text/css" href="../boost.css">
+<title>Boost.Python - Acknowledgments</title>
+</head>
+<body link="#0000ff" vlink="#800080">
+<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+  <tr> 
+    <td valign="top" width="300"> 
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+    </td>
+    <td valign="top"> 
+      <h1 align="center">Boost.Python</h1>
+      <h2 align="center">Acknowledgments</h2>
+    </td>
+  </tr>
+</table>
+<hr>
+{{text}}
+<hr>
+<p>Revised 
+  <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+  05 November, 2002 
+  <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+</p>
+<p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave Abrahams</a> 
+  2002. All Rights Reserved.</i></p>
+</body>
+</html>

doc/v2/bibliography.html

@@ -0,0 +1,32 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+<link rel="stylesheet" type="text/css" href="../boost.css">
+<title>Boost.Python - Bibliography</title>
+</head>
+<body link="#0000ff" vlink="#800080">
+<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+  <tr> 
+    <td valign="top" width="300"> 
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+    </td>
+    <td valign="top"> 
+      <h1 align="center">Boost.Python</h1>
+      <h2 align="center">Bibliography</h2>
+    </td>
+  </tr>
+</table>
+<hr>
+{{bibliographical information}}
+<hr>
+<p>Revised 
+  <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+  05 November, 2002 
+  <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+</p>
+<p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave Abrahams</a> 
+  2002. All Rights Reserved.</i></p>
+</body>
+</html>

doc/v2/call.html

@@ -0,0 +1,82 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+<link rel="stylesheet" type="text/css" href="../boost.css">
+<title>Boost.Python - &lt;call.hpp&gt;</title>
+</head>
+<body link="#0000ff" vlink="#800080">
+<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+  <tr> 
+    <td valign="top" width="300"> 
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+    </td>
+    <td valign="top"> 
+      <h1 align="center">Boost.Python</h1>
+      <h2 align="center">Header &lt;call.hpp&gt;</h2>
+    </td>
+  </tr>
+</table>
+<hr>
+<h2>Contents</h2>
+<dl class="page-index"> 
+  <dt><a href="#introduction">Introduction</a></dt>
+  <dt><a href="#functions">Functions</a></dt>
+  <dl class="page-index">
+    <dt><a href="#call-spec">call</a></dt>
+  </dl>
+
+  <dt><a href="#examples">Example(s)</a></dt>
+
+</dl>
+<hr>
+<h2><a name="introduction"></a>Introduction</h2>
+<p>
+  <code>&lt;boost/python/call.hpp&gt;</code> defines the <a
+  href="#call-spec"><code>call</code></a> family of overloaded function
+  templates, used to invoke Python callable objects from C++.
+
+<h2><a name="functions"></a>Functions</h2>
+<pre>
+<a name="call-spec">template &lt;class R, class A1, class A2, ... class A<i>n</i>&gt;</a>
+R call(PyObject* callable, A1 const&amp;, A2 const&amp;, ... A<i>n</i> const&amp;)
+</pre>
+<dl class="function-semantics"> 
+  <dt><b>Requires:</b> <code>R</code> is a pointer type, reference
+  type, or a complete type with an accessible copy constructor</dt>
+
+  <dt><b>Effects:</b> Invokes <code>callable(a1,&nbsp;a2,&nbsp;...a<i>n</i>)</code> in
+  Python, where <code>a1</code>...<code>a<i>n</i></code> are the arguments to
+  <code>call()</code>, converted to Python objects.
+  <dt><b>Returns:</b> The result of the Python call, converted to the C++ type <code>R</code>.</dt>
+
+</dt>
+  <dt><b>Rationale:</b> For a complete semantic description and
+  rationale, see <a href="callbacks.html">this page</a>.
+</dt>
+</dl>
+
+<h2><a name="examples"></a>Example(s)</h2>
+
+The following C++ function applies a Python callable object to its two
+arguments and returns the result. If a Python exception is raised or
+the result can't be converted to a <code>double</code>, an exception
+is thrown.
+
+<pre>
+double apply2(PyObject* func, double x, double y)
+{
+   return boost::python::call&lt;double&gt;(func, x, y);
+}
+</pre>
+
+<p>Revised 
+  <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+  9 May, 2002 <!-- Luann's birthday! -->
+  <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+</p>
+<p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave Abrahams</a> 
+  2002. All Rights Reserved.</i></p>
+</body>
+</html>

doc/v2/call_method.html

@@ -0,0 +1,141 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+<link rel="stylesheet" type="text/css" href="../boost.css">
+<title>Boost.Python - &lt;call_method.hpp&gt;</title>
+</head>
+<body link="#0000ff" vlink="#800080">
+<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+  <tr> 
+    <td valign="top" width="300"> 
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+    </td>
+    <td valign="top"> 
+      <h1 align="center">Boost.Python</h1>
+      <h2 align="center">Header &lt;call_method.hpp&gt;</h2>
+    </td>
+  </tr>
+</table>
+<hr>
+<h2>Contents</h2>
+<dl class="page-index"> 
+  <dt><a href="#introduction">Introduction</a></dt>
+  <dt><a href="#functions">Functions</a></dt>
+  <dl class="page-index">
+    <dt><a href="#call_method-spec">call_method</a></dt>
+  </dl>
+
+  <dt><a href="#examples">Example(s)</a></dt>
+
+</dl>
+<hr>
+<h2><a name="introduction"></a>Introduction</h2>
+<p>
+  <code>&lt;boost/python/call_method.hpp&gt;</code> defines the <a
+  href="#call_method-spec"><code>call_method</code></a> family of overloaded function
+  templates, used to invoke callable attributes of Python objects from C++.
+
+<h2><a name="functions"></a>Functions</h2>
+<pre>
+<a name="call_method-spec">template &lt;class R, class A1, class A2, ... class A<i>n</i>&gt;</a>
+R call_method(PyObject* self, char const* method, A1 const&amp;, A2 const&amp;, ... A<i>n</i> const&amp;)
+</pre>
+<dl class="function-semantics"> 
+  <dt><b>Requires:</b> <code>R</code> is a pointer type, reference
+  type, or a complete type with an accessible copy constructor</dt>
+
+  <dt><b>Effects:</b> Invokes <code>self.<i>method</i>(a1,&nbsp;a2,&nbsp;...a<i>n</i>)</code> in
+  Python, where <code>a1</code>...<code>a<i>n</i></code> are the arguments to
+  <code>call_method()</code>, converted to Python objects. For a
+  complete semantic description, see <a href="callbacks.html">this
+  page</a>.
+
+  <dt><b>Returns:</b> The result of the Python call, converted to the
+  C++ type <code>R</code>.</dt>
+
+</dt>
+  <dt><b>Rationale:</b> <code>call_method</code> is critical to
+  implementing C++ virtual functions which are overridable in Python,
+  as shown by the example below.
+</dt>
+</dl>
+
+<h2><a name="examples"></a>Example(s)</h2>
+
+The following C++ illustrates the use of <code>call_method</code> in
+wrapping a class with a virtual function that can be overridden in
+Python:
+
+<h3>C++ Module Definition</h3>
+<pre>
+#include &lt;boost/python/module.hpp&gt;
+#include &lt;boost/python/class.hpp&gt;
+#include &lt;boost/utility.hpp&gt;
+#include &lt;cstring&gt;
+
+// class to be wrapped
+class Base
+{
+ public:
+   virtual char const* class_name() const { return &quot;Base&quot;; }
+   virtual ~Base();
+};
+
+bool is_base(Base* b)
+{
+   return !std::strcmp(b-&gt;class_name(), &quot;Base&quot;);
+}
+
+// Wrapper code begins here
+using namespace boost::python;
+
+// Callback class
+class Base_callback : public Base
+{
+ public:
+   Base_callback(PyObject* self) : m_self(self) {}
+
+   char const* class_name() const { return <b>call_method</b>(m_self, &quot;class_name&quot;); }
+   char const* Base_name() const { return Base::class_name(); }
+ private:
+   PyObject* m_self;
+};
+
+using namespace boost::python;
+BOOST_PYTHON_MODULE_INIT(my_module)
+{
+   module("my_module")
+      .def(&quot;is_base&quot;, is_base)
+      .add(
+         class_&lt;Base,Base_callback, noncopyable&gt;(&quot;Base&quot;)
+             .def(&quot;class_name&quot;, &#24;Base_callback::Base_name);
+         )
+       ;
+}
+</pre>
+
+<h3>Python Code</h3>
+<pre>
+&gt;&gt;&gt; from my_module import *
+&gt;&gt;&gt; class Derived(Base):
+...    def __init__(self):
+...       Base.__init__(self)
+...    def class_name(self):
+...       return self.__class__.__name__
+...
+&gt;&gt;&gt; is_base(Base()) # calls the class_name() method from C++
+1
+&gt;&gt;&gt; is_base(Derived())
+0
+</pre>
+<p>Revised 
+  <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+  10 May, 2002 
+  <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+</p>
+<p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave Abrahams</a> 
+  2002. All Rights Reserved.</i></p>
+</body>
+</html>

doc/v2/callbacks.html

@@ -0,0 +1,246 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+<link rel="stylesheet" type="text/css" href="../boost.css">
+<title>Boost.Python - Calling Python Functions and Methods</title>
+</head>
+<body link="#0000ff" vlink="#800080">
+<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+  <tr> 
+    <td valign="top" width="300"> 
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+    </td>
+    <td valign="top"> 
+      <h1 align="center">Boost.Python</h1>
+      <h2 align="center">Calling Python Functions and Methods</h2>
+    </td>
+  </tr>
+</table>
+<hr>
+<h2>Contents</h2>
+<dl class="page-index"> 
+  <dt><a href="#introduction">Introduction</a></dt>
+  <dt><a href="#argument_handling">Argument Handling</a></dt>
+  <dt><a href="#result_handling">Result Handling</a></dt>
+  <dt><a href="#result_handling">Rationale</a></dt>
+</dl>
+<hr>
+
+<h2><a name="introduction">Introduction</a></h2>
+<p>
+Boost.Python provides two families of function templates,
+<code><a href="call.html#call-spec">call</a></code> and <code><a
+href="call_method.html#call_method-spec">call_method</a></code>, for
+invoking Python functions and methods respectively. The interface for
+calling a Python function object (or any Python callable object) looks
+like:
+
+<pre>
+call&lt;ResultType&gt;(callable_object, a1, a2... a<i>N</i>);
+</pre>
+
+Calling a method of a Python object is similarly easy:
+
+<pre>
+call_method&lt;ResultType&gt;(self_object, &quot;<i>method-name</i>&quot;, a1, a2... a<i>N</i>);
+</pre>
+
+
+<h2><a name="argument_handling">Argument Handling</a></h2>
+<p>
+
+Arguments are converted to Python according to their type. By default,
+the arguments <code>a1</code>...<code>a<i>N</i></code> are copied into
+new Python objects, but this behavior can be overridden by the use of
+<code><a href="ptr.html#ptr-spec">ptr()</a></code> and <a
+href="../../../bind/ref.html#reference_wrapper">ref()</a>:
+
+<pre>
+class X : boost::noncopyable
+{
+   ...
+};
+
+void apply(PyObject* callable, X&amp; x)
+{
+   // Invoke callable, passing a Python object which holds a reference to x
+   boost::python::call&lt;void&gt;(callable, boost::ref(x));
+}
+</pre>
+
+In the table below, <code><b>x</b></code> denotes the actual argument
+object and <code><b>cv</b></code> denotes an optional
+<i>cv-qualification</i>: &quot;<code>const</code>&quot;,
+&quot;<code>volatile</code>&quot;, or &quot;<code>const
+volatile</code>&quot;.
+
+    <table border="1" summary="class_ template parameters">
+      <tr>
+        <th>Argument Type
+
+        <th>Behavior
+
+      <tr>
+        <td><code>T cv&amp;</code><br>
+        <code>T cv</code>
+
+        <td>The Python argument is created by the same means used 
+        for the return value of a wrapped C++ function returning
+        <code>T</code>. When
+        <code>T</code> is a class type, that normally means
+        <code>*x</code> is copy-constructed into the new Python
+        object. 
+
+      <tr>
+        <td><code>T*</code> 
+
+        <td>If <code>x&nbsp;==&nbsp;0</code>, the Python argument will
+        be <code><a
+        href="http://www.python.org/doc/current/lib/bltin-null-object.html">None</a></code>. Otherwise,
+        the Python argument is created by the same means used for the
+        return value of a wrapped C++ function returning
+        <code>T</code>. When
+        <code>T</code> is a class type, that normally means
+        <code>*x</code> is copy-constructed into the new Python
+        object. 
+
+      <tr>
+        <td><code><a
+        href="../../../bind/ref.html#reference_wrapper">boost::reference_wrapper</a>&lt;T&gt; </code>
+
+        <td>The Python argument contains a pointer to, rather than a
+        copy of, <code>x.get()</code>. Note: failure to ensure that no
+        Python code holds a reference to the resulting object beyond
+        the lifetime of <code>*x.get()</code> <b>may result in a
+        crash!</b> 
+
+      <tr>
+        <td><code><a
+        href="ptr.html#pointer_wrapper-spec">pointer_wrapper</a>&lt;T&gt;</code>
+
+        <td>If <code>x.get()&nbsp;==&nbsp;0</code>, the Python
+        argument will be <code><a
+        href="http://www.python.org/doc/current/lib/bltin-null-object.html">None</a></code>.
+        Otherwise, the Python argument contains a pointer to, rather
+        than a copy of, <code>*x.get()</code>. Note: failure to ensure
+        that no Python code holds a reference to the resulting object
+        beyond the lifetime of <code>*x.get()</code> <b>may result in
+        a crash!</b>  
+
+    </table>
+
+<h2><a name="result_handling">Result Handling</a></h2>
+
+In general, <code>call&lt;ResultType&gt;()</code> and
+<code>call_method&lt;ResultType&gt;()</code> return
+<code>ResultType</code> by exploiting all lvalue and rvalue
+<code>from_python</code> converters registered for ResultType and
+returning a copy of the result. However, when
+<code>ResultType</code> is a pointer or reference type, Boost.Python
+searches only for lvalue converters. To prevent dangling pointers and
+references, an exception will be thrown if the Python result object
+has only a single reference count.
+
+<h2><a name="rationale">Rationale</a></h2>
+
+In general, to get Python arguments corresponding to
+<code>a1</code>...<code>a<i>N</i></code>, a new Python object must be
+created for each one; should the C++ object be copied into that Python
+object, or should the Python object simply hold a reference/pointer to
+the C++ object? In general, the latter approach is unsafe, since the
+called function may store a reference to the Python object
+somewhere. If the Python object is used after the C++ object is
+destroyed, we'll crash Python.
+
+<p>In keeping with the philosophy that users on the Python side
+shouldn't have to worry about crashing the interpreter, the default
+behavior is to copy the C++ object, and to allow a non-copying
+behavior only if the user writes <code><a
+href="../../../bind/ref.html">boost::ref</a>(a1)</code> instead of a1
+directly. At least this way, the user doesn't get dangerous behavior
+&quot;by accident&quot;. It's also worth noting that the non-copying
+(&quot;by-reference&quot;) behavior is in general only available for
+class types, and will fail at runtime with a Python exception if used
+otherwise[<a href="#1">1</a>].
+
+<p>
+However, pointer types present a problem: one approach is to refuse
+to compile if any aN has pointer type: after all, a user can always pass
+<code>*aN</code> to pass &quot;by-value&quot; or <code>ref(*aN)</code>
+to indicate a pass-by-reference behavior. However, this creates a
+problem for the expected null pointer to
+<code>None</code> conversion: it's illegal to dereference a null
+pointer value.
+
+<p>
+
+The compromise I've settled on is this: 
+
+<ol>
+<li>The default behavior is pass-by-value. If you pass a non-null
+   pointer, the pointee is copied into a new Python object; otherwise
+   the corresponding Python argument will be None.
+
+<li>if you want by-reference behavior, use <code>ptr(aN)</code> if
+   <code>aN</code> is a pointer and <code>ref(aN)</code> otherwise. If
+   a null pointer is passed to <code>ptr(aN)</code>, the corresponding
+   Python argument will be <code>None</code>.
+   </ol>
+
+<p>
+As for results, we have a similar problem: if <code>ResultType</code>
+is allowed to be a pointer or reference type, the lifetime of the
+object it refers to is probably being managed by a Python object. When
+that Python object is destroyed, our pointer dangles. The problem is
+particularly bad when the <code>ResultType</code> is char const* - the
+corresponding Python String object is typically uniquely-referenced,
+meaning that the pointer dangles as soon as <code>call&lt;char
+const*&gt;(...)</code> returns.
+
+<p>
+The old Boost.Python v1 deals with this issue by refusing to compile
+any uses of <code>call&lt;char const*&gt;()</code>, but this goes both
+too far and not far enough. It goes too far because there are cases
+where the owning Python string object survives beyond the call (just
+for instance, when it's the name of a Python class), and it goes not
+far enough because we might just as well have the same problem with a
+returned pointer or reference of any other type.
+
+<p>
+
+In Boost.Python v2 this is dealt with by:
+
+<ol>
+   <li> lifting the compile-time restriction on const
+    char* callback returns
+
+   
+   <li> detecting the case when the reference count on the result
+    Python object is 1 and throwing an exception inside of
+    <code>call&lt;U&gt;(...)</code> when <code>U</code> is a pointer
+    or reference type.
+</ol>
+
+This should be acceptably safe because users have to explicitly
+specify a pointer/reference for <code>U</code> in
+<code>call&lt;U&gt;</code>, and they will be protected against dangles
+at runtime, at least long enough to get out of the
+<code>call&lt;U&gt;(...)</code> invocation.
+
+<hr>
+
+<a name="1">[1]</a> It would be possible to make it fail at compile-time for non-class
+types such as int and char, but I'm not sure it's a good idea to impose
+this restriction yet.
+
+<p>Revised 
+  <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+  17 April, 2002 
+  <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+</p>
+<p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave Abrahams</a> 
+  2002. All Rights Reserved.</i></p>
+</body>
+</html>

doc/v2/callbacks.txt

@@ -0,0 +1,88 @@
+Here's the plan:
+
+I aim to provide an interface similar to that of Boost.Python v1's
+callback<>::call(...) for dealing with callbacks. The interface will
+look like:
+
+    returning<ResultType>::call("method_name", self_object, a1, a2...);
+
+or
+
+    returning<ResultType>::call(callable_object, a1, a2...);
+
+ARGUMENT HANDLING
+
+There is an issue concerning how to make Python objects from the
+arguments a1...aN. A new Python object must be created; should the C++
+object be copied into that Python object, or should the Python object
+simply hold a reference/pointer to the C++ object? In general, the
+latter approach is unsafe, since the called function may store a
+reference to the Python object somewhere. If the Python object is used
+after the C++ object is destroyed, we'll crash Python.
+
+I plan to make the copying behavior the default, and to allow a
+non-copying behavior if the user writes boost::ref(a1) instead of a1
+directly. At least this way, the user doesn't get dangerous behavior "by
+accident". It's also worth noting that the non-copying ("by-reference")
+behavior is in general only available for class types, and will fail at
+runtime with a Python exception if used otherwise**
+
+However, pointer types present a problem: My first thought is to refuse
+to compile if any aN has pointer type: after all, a user can always pass
+*aN to pass "by-value" or ref(*aN) to indicate a pass-by-reference
+behavior. However, this creates a problem for the expected NULL pointer
+=> None conversion: it's illegal to dereference a null pointer value.
+
+We could use another construct, say "ptr(aN)", to deal with null
+pointers, but then what does it mean? We know what it does when aN is
+NULL, but it might either have by-value or by-reference behavior when aN
+is non-null.
+
+The compromise I've settled on is this: 
+
+1. The default behavior is pass-by-value. If you pass a non-null
+   pointer, the pointee is copied into a new Python object; otherwise
+   the corresponding Python argument will be None.
+
+2. if you want by-reference behavior, use ptr(aN) if aN is a pointer
+   and ref(aN) otherwise. If a null pointer is passed to ptr(aN), the
+   corresponding Python argument will be None.
+
+RESULT HANDLING
+
+As for results, we have a similar problem: if ResultType is allowed to
+be a pointer or reference type, the lifetime of the object it refers to
+is probably being managed by a Python object. When that Python object is
+destroyed, our pointer dangles. The problem is particularly bad when the
+ResultType is char const* - the corresponding Python String object is
+typically uniquely-referenced, meaning that the pointer dangles as soon
+as returning<char const*>::call() returns.
+
+Boost.Python v1 deals with this issue by refusing to compile any uses of
+callback<char const*>::call(), but IMO this goes both too far and not
+far enough. It goes too far because there are cases where the owning
+String object survives beyond the call (just for instance when it's the
+name of a Python class), and it goes not far enough because we might
+just as well have the same problem with any returned pointer or
+reference.
+
+I propose to address this in Boost.Python v2 by
+
+    1. lifting the compile-time restriction on const
+    char* callback returns
+
+    2. detecting the case when the reference count on the
+    result Python object is 1 and throwing an exception
+    inside of returning<U>::call() when U is a pointer or
+    reference type.
+
+I think this is acceptably safe because users have to explicitly specify
+a pointer/reference for U in returning<U>, and they will be protected
+against dangles at runtime, at least long enough to get out of the
+returning<U>::call() invocation.
+
+-Dave
+
+**It would be possible to make it fail at compile-time for non-class
+types such as int and char, but I'm not sure it's a good idea to impose
+this restriction yet.

doc/v2/class.html

@@ -0,0 +1,589 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+    <meta name="generator" content="HTML Tidy, see www.w3.org">
+    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+    <link rel="stylesheet" type="text/css" href="../boost.css">
+
+    <title>Boost.Python - &lt;boost/python/class.hpp&gt;,
+    &lt;boost/python/class_fwd.hpp&gt;</title>
+
+    <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+      <tr>
+        <td valign="top" width="300">
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+
+        <td valign="top">
+          <h1 align="center">Boost.Python</h1>
+
+          <h2 align="center">Headers &lt;boost/python/class.hpp&gt;,
+          &lt;boost/python/class_fwd.hpp&gt;</h2>
+    </table>
+    <hr>
+
+    <h2>Contents</h2>
+
+    <dl class="page-index">
+      <dt><a href="#introduction">Introduction</a>
+
+      <dt><a href="#classes">Classes</a>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#class_-spec">Class template <code>class_</code></a>
+
+          <dd>
+            <dl class="page-index">
+              <dt><a href="#class_-spec-synopsis">Class <code>class_</code>
+              synopsis</a>
+
+              <dt><a href="#class_-spec-ctors">Class <code>class_</code>
+              constructors</a>
+
+              <dt><a href="#class_-spec-modifiers">Class <code>class_</code>
+              modifier functions</a>
+
+              <dt><a href="#class_-spec-observers">Class <code>class_</code>
+              observer functions</a>
+            </dl>
+
+          <dt><a href="#bases-spec">Class template <code>bases</code></a>
+
+          <dd>
+            <dl class="page-index">
+              <dt><a href="#bases-spec-synopsis">Class <code>bases</code>
+              synopsis</a>
+            </dl>
+
+          <dt><a href="#args-spec">Class template <code>args</code></a>
+
+          <dd>
+            <dl class="page-index">
+              <dt><a href="#args-spec-synopsis">Class <code>args</code>
+              synopsis</a>
+            </dl>
+        </dl>
+
+      <dt><a href="#examples">Example(s)</a>
+    </dl>
+    <hr>
+
+    <h2><a name="introduction"></a>Introduction</h2>
+
+    <p><code>&lt;boost/python/class.hpp&gt;</code> defines the interface
+    through which users expose their C++ classes to Python. It declares the
+    <code>class_</code> class template, which is parameterized on the
+    class type being exposed. It also exposes the <code>args</code>
+    and <code>bases</code> utility class templates, which are used in
+    conjunction with <code>class_</code>.
+
+    <p><code>&lt;boost/python/class_fwd.hpp&gt;</code> contains a forward
+    declaration of the <code>class_</code> class template.
+
+  <h2><a name="classes"></a>Classes</h2>
+
+    <h3><a name="class_-spec"></a>Class template <code>class_&lt;T, <font color="#007f00">Bases, HeldType, NonCopyable</font>&gt;</code></h3>
+
+    <p>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 <font color="#007f00"><b>in any
+    order</b></font>; Boost.Python determines the role of the argument
+    from its type.<br>
+    <br>
+
+    <table border="1" summary="class_ template parameters">
+      <tr>
+        <th>Template Parameter
+
+        <th>Requirements
+
+        <th>Semantics
+
+        <th>Default
+
+      <tr>
+        <td><code>T</code> 
+
+        <td>A class type.
+
+        <td>The class being wrapped
+
+      <tr>
+        <td><code><font color="#007f00">Bases</font></code> 
+
+        <td>A specialization of <a
+        href="#bases-spec"><code>bases&lt;...&gt;</code></a> which
+        specifies previously-exposed C++ base classes of <code>T</code><a href="#footnote_1">[1]</a>.
+
+        <td>Registers <code>from_python</code> conversions from
+        wrapped <code>T</code> instances to each of its exposed direct
+        and indirect bases. For each polymorphic base <code>B</code>,
+        registers conversions from indirectly-held wrapped
+        <code>B</code> instances to <code>T</code>.
+
+        <td><code><a href="#bases">bases&lt;&gt;</a></code>
+
+      <tr>
+        <td><code><font color="#007f00">HeldType</font></code> 
+
+        <td>Must be <code>T</code>, a class derived
+           from <code>T</code>, or a <a
+           href="Dereferenceable.html">Dereferenceable</a> type for which
+           <code><a
+           href="pointee.html#pointee-spec">pointee</a>&lt;HeldType&gt;::type</code>
+           is <code>T</code> or a class derived from <code>T</code>.
+         </dl>
+
+        <td>Specifies the type which is actually embedded in a Python
+        object wrapping a <code>T</code> instance. More details <a
+        href="#HeldType">below</a>.
+
+        <td><code>T</code> 
+
+      <tr>
+        <td><code><font color="#007f00">NonCopyable</font></code> 
+
+        <td>If supplied, must be <a
+        href="../../../utility/utility.htm#Class noncopyable">boost::noncopyable</a>.
+
+        <td> Suppresses automatic registration of <code>to_python</code>
+        conversions which copy
+        <code>T</code> instances. Required when <code>T</code> has no
+        publicly-accessible copy constructor.
+
+        <td>An unspecified type other than <code>boost::noncopyable</code>.
+
+    </table>
+
+<h4><a name="#HeldType">HeldType Semantics</a></h4>
+
+<ol>
+<li>
+    If <code>HeldType</code> is derived from T, its
+    exposed constructor(s) must accept an initial
+    <code>PyObject*</code> argument which refers back to the Python
+    object that contains it, as shown in <a
+    href="call_method.html#example">this example</a>. This argument is
+    not included in the argument list type passed to <a
+    href="#def_init-spec"><code>def_init()</code></a>, below, nor is
+    it passed explicitly by users when Python instances of
+    <code>T</code> 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
+    <code>T</code> to be passed to wrapped C++ functions expecting
+    <code>HeldType</code> arguments.
+
+<li>Because Boost.Python will always allow
+  wrapped instances of <code>T</code> to be passed in place of
+  <code>HeldType</code> arguments, specifying a smart pointer for
+  <code>HeldType</code> allows users to pass Python
+  <code>T</code> instances where a smart pointer-to-<code>T</code> is
+  expected. Smart pointers such as <code>std::auto_ptr&lt;&gt;</code>
+  or <code><a
+  href="../../../smart_ptr/shared_ptr.htm">boost::shared_ptr&lt;&gt;</a></code>
+  which contain a nested type <code>element_type</code> designating
+  the referent type are automatically supported; additional smart
+  pointer types can be supported by specializing <a
+  href="pointee.html#pointee-spec">pointee&lt;HeldType&gt;</a>.
+
+<li>
+  As in case 1 above, when <code>HeldType</code> is a smart pointer to
+  a class derived from <code>T</code>, the initial
+  <code>PyObject*</code> argument must be supplied by all exposed
+  constructors.
+
+<li>
+   Except in cases 1 and 3, users may optionally specify that T itself
+   gets initialized with a similar initial <code>PyObject*</code>
+   argument by specializing <a
+   href="has_back_reference.html#has_back_reference-spec">has_back_reference<T></a>.
+</ol>
+
+      <h4><a name="class_-spec-synopsis"></a>Class template
+      <code>class_</code> synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+  template &lt;class T
+<font color="#007f00">            , class Bases = bases&lt;&gt;
+            , class HeldType = T
+            , class NonCopyable = <i>unspecified</i>
+           &gt;
+</font>  class class_
+  {
+    class_();
+    class_(char const* name);
+
+    // exposing constructors
+    class_&amp; def_init();
+
+    template &lt;class Args&gt;
+    class_&amp; def_init(Args const&amp; = Args());
+
+    template &lt;class Args, class CallPolicy&gt;
+    class_&amp; def_init(Args const&amp;, CallPolicy policy);
+
+    // exposing member functions
+    template &lt;class F&gt;
+    class_&amp; def(char const* name, F f);
+
+    template &lt;class Fn, class CallPolies&gt;
+    class_&amp; def(char const* name, Fn fn, CallPolies);
+
+    // exposing operators
+    template &lt;<i>unspecified</i>&gt;
+    class_&amp; def(<a href="operators.html#operator_-spec">detail::operator_</a>&lt;unspecified&gt;);
+
+    // exposing data members
+    template &lt;class D&gt;
+    class_&amp; def_readonly(char const* name, D T::*pm);
+
+    template &lt;class D&gt;
+    class_&amp; 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&amp; fget);
+    void add_property(char const* name, ref const&amp; fget, ref const&amp; fset);
+
+    // accessing the Python class object
+    ref object() const;
+  };
+}}
+</pre>
+
+    <h4><a name="class_-spec-ctors"></a>Class template <code>class_</code> constructors</h4>
+
+<pre>
+class_();
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Requires:</b> The platform's <code>std::type_info::name()</code>
+      implementation produces a string which corresponds to the type's
+      declaration in C++
+
+      <dt><b>Effects:</b> Constructs a <code>class_</code> object which
+      generates a Boost.Python extension class with the same name as
+      <code>T</code>.
+
+      <dt><b>Rationale:</b> Many platforms can generate reasonable names for
+      Python classes without user intervention.
+    </dl>
+<pre>
+class_(char const* name);
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Requires:</b> <code>name</code> is a ntbs which conforms to
+      Python's <a href=
+      "http://www.python.org/doc/2.2/ref/identifiers.html">identifier
+      naming rules</a>.
+
+      <dt><b>Effects:</b> Constructs a <code>class_</code> object which
+      generates a Boost.Python extension class named <code>name</code>.
+
+      <dt><b>Rationale:</b> Gives the user full control over class naming.
+    </dl>
+
+    <h4><a name="class_-spec-modifiers"></a>Class template <code>class_</code>
+    modifier functions</h4>
+
+<pre>
+class_&amp; def_init();
+
+template &lt;class Args&gt;
+class_&amp; def_init(Args const&amp; argument_types);
+
+template &lt;class Args, class CallPolicies&gt;
+class_&amp; def_init(Args const&amp; argument_types, CallPolicies policies);
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Requires:</b> <code>Args</code> is an <a
+      href="../../../mpl/doc/Sequences.html">MPL sequence</a> of C++ argument
+      types (<i>A1, A2,... AN</i>) such that if
+      <code>a1, a2</code>... <code>aN</code> are objects of type
+      <i>A1, A2,... AN</i> respectively, the expression
+      <code>T(a1, a2</code>... <code>aN</code>) is valid. In the first form,
+      the expression <code>T()</code> must be valid.
+
+      <dt><b>Effects:</b> Adds the result of 
+
+<code><a href=
+      "make_function.html#make_constructor-spec">make_constructor</a>&lt;args&lt;&gt;,Holder&gt;()</code>,
+
+<code><a href=
+      "make_function.html#make_constructor-spec">make_constructor</a>&lt;Args,Holder&gt;()</code>, or
+
+<code><a href=
+      "make_function.html#make_constructor-spec">make_constructor</a>&lt;Args,Holder&gt;(policies)</code>,
+      respectively, to the Boost.Python extension class being defined under the name
+      "__init__". <code>Holder</code> is a concrete subclass of <a
+      href="instance_holder.html#instance_holder-spec">instance_holder</a>
+      which holds the <code>HeldType</code>. If the extension class
+      already has an "__init__" attribute, the usual <a
+      href="http:overloading.html">overloading procedure</a> applies.
+
+      <dt><b>Returns:</b> <code>*this</code>
+
+      <dt><b>Rationale:</b> Allows users to easily expose a class' constructor
+      to Python.
+    </dl>
+
+<br>
+
+<pre>
+template &lt;class F&gt;
+class_&amp; def(char const* name, F f);
+
+template &lt;class Fn, class CallPolicies&gt;
+class_&amp; def(char const* name, Fn f, CallPolicies policies);
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Requires:</b> <code>f</code> is a non-null
+      pointer-to-function or pointer-to-member-function, or a callable
+      Python object passed as a <code>PyObject*</code> or <a
+      href="reference_hpp.html#ref-spec"><code>ref</code></a>. <code>name</code>
+      is a ntbs which conforms to Python's <a href=
+      "http://www.python.org/doc/2.2/ref/identifiers.html">identifier
+      naming rules</a>. In the first form, the return type of
+      <code>f</code> is not a reference and is not a pointer other
+      than <code>char const*</code> or <code>PyObject*</code>. In the
+      second form <code>policies</code> is a model of <a
+      href="CallPolicies.html">CallPolicies</a>.
+
+      <dt><b>Effects:</b> Adds the result of <code><a href=
+      "make_function.html#make_function-spec">make_function</a>(f)</code> or <code><a href=
+      "make_function.html#make_function-spec">make_function</a>(f,&nbsp;policies)</code> to
+      the Boost.Python extension class being defined, with the given
+      <code>name</code>. If the extension class already has an attribute named
+      <code><i>name</i></code>, the usual <a href=
+      "overloading.html">overloading procedure</a> applies.
+
+      <dt><b>Returns:</b> <code>*this</code>
+    </dl>
+
+<pre>
+template &lt;<i>unspecified</i>&gt;
+class_&amp; def(<a href="operators.html#operator_-spec">detail::operator_</a>&lt;unspecified&gt;);
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Effects:</b> Adds a Python <a
+    href="http://www.python.org/doc/ref/specialnames.html">special
+    method</a> as described <a href="operators.html">here</a>.
+
+      <dt><b>Returns:</b> <code>*this</code>
+    </dl>
+
+<pre>
+template &lt;class F&gt;
+class_&amp; setattr(char const* name, ref x);
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Requires:</b> <code>name</code> is a ntbs which conforms to
+      Python's <a href=
+      "http://www.python.org/doc/2.2/ref/identifiers.html">identifier
+      naming rules</a>. 
+
+      <dt><b>Effects:</b> <code><a href="http://www.python.org/doc/current/api/object.html#l2h-166">PyObject_SetAttrString</a>(this->object(),&nbsp;name,&nbsp;x.get());</code>
+
+      <dt><b>Returns:</b> <code>*this</code>
+    </dl>
+
+<br>
+
+<pre>
+void add_property(char const* name, ref const&amp; fget);
+void add_property(char const* name, ref const&amp; fget, ref const&amp; fset);
+</pre>
+    <dl class="function-semantics">
+
+      <dt><b>Requires:</b> <code>name</code> is a ntbs which conforms to
+      Python's <a href=
+      "http://www.python.org/doc/2.2/ref/identifiers.html">identifier
+      naming rules</a>. 
+
+      <dt><b>Effects:</b> Creates a new Python <a
+      href="http://www.python.org/2.2/descrintro.html#property"><code>property</code></a>
+      class instance, passing <code>fget.get()</code> (and
+      <code>fset.get()</code> in the second form) to its constructor,
+      then adds that property to the Python class object under
+      construction with the given attribute <code>name</code>.
+
+      <dt><b>Returns:</b> <code>*this</code>
+
+      <dt><b>Rationale:</b> Allows users to easily expose a class'
+      data member such that it can be inspected from Python with a
+      natural syntax.
+    </dl>
+
+<br>
+<pre>
+    template &lt;class D&gt;
+    class_&amp; def_readonly(char const* name, D T::*pm);
+</pre>
+
+    <dl class="function-semantics">
+
+      <dt><b>Requires:</b> <code>name</code> is a ntbs which conforms to
+      Python's <a href=
+      "http://www.python.org/doc/2.2/ref/identifiers.html">identifier
+      naming rules</a>. 
+
+      <dt><b>Effects:</b> 
+<pre>
+this-&gt;add_property(name, ref(<a href="data_members.html#make_getter-spec">make_getter</a>(pm)));
+</pre>
+
+      <dt><b>Returns:</b> <code>*this</code>
+
+      <dt><b>Rationale:</b> Allows users to easily expose a class'
+      data member such that it can be inspected from Python with a
+      natural syntax.
+    </dl>
+
+<br>
+
+<pre>
+template &lt;class D&gt;
+class_&amp; def_readwrite(char const* name, D T::*pm);
+</pre>
+
+    <dl class="function-semantics">
+
+      <dt><b>Effects:</b> 
+<pre>
+ref fget(<a href="data_members.html#make_getter-spec">make_getter</a>(pm));
+ref fset(<a href="data_members.html#make_setter-spec">make_setter</a>(pm));
+this-&gt;add_property(name, fget, fset);
+</pre>
+
+      <dt><b>Returns:</b> <code>*this</code>
+
+      <dt><b>Rationale:</b> Allows users to easily expose a class'
+      data member such that it can be inspected and set from Python with a
+      natural syntax.
+
+    <h4><a name="class_-spec-observers"></a>Class template <code>class_</code>
+    observer functions</h4>
+<pre>
+ref object() const;
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Returns:</b> A <code>ref</code> object which holds a reference to
+      the Boost.Python extension class object created by the
+      <code>class_</code> constructor.
+
+      <dt><b>Rationale:</b> Mostly not needed by users, since <code><a href=
+      "module.html#add-spec">module::add</a>()</code> uses this to insert the
+      extension class in the module.
+    </dl>
+
+    <h3><a name="args-spec"></a>Class template
+    <code>args&lt;T1, T2,</code>...<code>TN&gt;</code></h3>
+
+    <p>A conveniently-named <a
+      href="../../../mpl/doc/Sequences.html">MPL sequence</a> which
+      users pass to <code><a
+      href="#class_-spec-modifiers">def_init</a></code> calls to make
+      their code more readable.  
+
+    <h4><a name="args-spec-synopsis"></a>Class template <code>args</code>
+    synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+  template &lt;T1 = <i>unspecified</i>,...TN = <i>unspecified</i>&gt;
+  struct args
+  {};
+}}
+</pre>
+
+    <h3><a name="bases-spec"></a>Class template
+    <code>bases&lt;T1, T2,</code>...<code>TN&gt;</code></h3>
+
+    <p>An <a
+      href="../../../mpl/doc/Sequences.html">MPL sequence</a>  which
+      can be used in <code>class_&lt;</code>...<code>&gt;</code>
+      instantiations indicate a list of base classes. Although users
+      can pass any MPL sequence in place of args, above, the use of
+      <code>bases</code> to indicate base classes is mandatory.
+
+    <h4><a name="bases-spec-synopsis"></a>Class template <code>bases</code>
+    synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+  template &lt;T1 = <i>unspecified</i>,...TN = <i>unspecified</i>&gt;
+  struct bases
+  {};
+}}
+</pre>
+
+    <h2><a name="examples"></a>Example(s)</h2>
+
+    <p>Given a C++ class declaration:
+<pre>
+class Foo : public Bar, public Baz
+{
+ public:
+   Foo(int, char const*);
+   Foo(double);
+
+   std::string const&amp; name() { return m_name; }
+   void name(char const*);
+
+   double value; // public data
+ private:
+   ...
+};
+</pre>
+
+   A corresponding Boost.Python extension class can be created with: 
+<pre>
+using namespace boost::python;
+
+ref foo = class_&lt;Foo,bases&lt;Bar,Baz&gt; &gt;()
+   .def_init(args&lt;int,char const*&gt;())
+   .def_init(args&lt;double&gt;())
+   .def("get_name", &amp;Foo::get_name, return_internal_reference&lt;&gt;())
+   .def("set_name", &amp;Foo::set_name)
+   .def_readwrite("value", &amp;Foo::value)
+   .object();
+</pre>
+
+<hr>
+
+<a name="footnote_1">[1]</a> By &quot;previously-exposed&quot; we mean that the for each
+<code>B</code> in <code>bases</code>, an instance of
+<code>class_&lt;B&gt;</code> 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
+<i>full-expressions</i>, rather than chaining consecutive definitions with
+&quot;<code>.add(...)</code>.
+
+<pre>
+module m(&quot;module_name&quot;);
+m.add(class_&lt;Base&gt;()
+        .def_init());
+m.add(class_&lt;Derived, bases&lt;Base&gt;&gt;()
+        .def_init());
+</pre>
+
+    Revised 
+    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+     09 May, 2002 <!-- Luann's birthday! --> 
+    <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+     
+
+    <p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
+    Abrahams</a> 2002. All Rights Reserved.</i>
+

doc/v2/configuration.html

@@ -0,0 +1,91 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+<link rel="stylesheet" type="text/css" href="../boost.css">
+<title>Boost.Python - Configuration</title>
+</head>
+<body link="#0000ff" vlink="#800080">
+<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+  <tr> 
+    <td valign="top" width="300"> 
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+    </td>
+    <td valign="top"> 
+      <h1 align="center">Boost.Python</h1>
+      <h2 align="center">Configuration</h2>
+    </td>
+  </tr>
+</table>
+<hr>
+<dl class="page-index">
+  <dt><a href="#introduction">Introduction</a></dt>
+  <dt><a href="#app-defined">Application Defined Macros</a></dt>
+  <dt><a href="#lib-defined-public">Public Library Defined Macros</a></dt>
+  <dt><a href="#lib-defined-impl">Library Defined Implementation Macros</a></dt>
+</dl>
+<h2><a name="introduction"></a>Introduction</h2>
+<p>Boost.Python uses several configuration macros in <a href="http://www.boost.org/libs/config/config.htm">&lt;boost/config.hpp&gt;</a>, 
+  as well as configuration macros meant to be supplied by the application. These 
+  macros are documented here.</p>
+<h2><a name="app-defined"></a>Application Defined Macros</h2>
+<p>These are the macros that may be defined by an application using Boost.Python.</p>
+<table summary="application defined macros" cellspacing="10" width="100%">
+  <tr>
+    <td><b>Macro</b></td>
+    <td><b>Meaning</b></td>
+  </tr>
+  <tr>
+    <td>{{macro}}</td>
+	<td>{{meaning}}</td>
+  </tr>
+  <tr>
+    <td>{{macro}}</td>
+	<td>{{meaning}}</td>
+  </tr>
+</table>
+<h2><a name="lib-defined-public"></a>Public Library Defined Macros</h2>
+<p>These macros are defined by Boost.Python but are expected to be used by application 
+  code.</p>
+<table summary="public library defined macros" cellspacing="10" width="100%">
+  <tr>
+    <td><b>Macro</b></td>
+    <td><b>Meaning</b></td>
+  </tr>
+  <tr>
+    <td>{{macro}}</td>
+	<td>{{meaning}}</td>
+  </tr>
+  <tr>
+    <td>{{macro}}</td>
+	<td>{{meaning}}</td>
+  </tr>
+</table>
+<h2><a name="lib-defined-impl"></a>Library Defined Implementation Macros</h2>
+<p>These macros are defined by Boost.Python and are implementation details of interest 
+  only to implementers.</p>
+<table summary="library defined implementation macros" cellspacing="10" width="100%">
+  <tr>
+    <td><b>Macro</b></td>
+    <td><b>Meaning</b></td>
+  </tr>
+  <tr>
+    <td>{{macro}}</td>
+	<td>{{meaning}}</td>
+  </tr>
+  <tr>
+    <td>{{macro}}</td>
+	<td>{{meaning}}</td>
+  </tr>
+</table>
+<hr>
+<p>Revised 
+  <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+  05 November, 2002 
+  <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+</p>
+<p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave Abrahams</a> 
+  2002. All Rights Reserved.</i></p>
+</body>
+</html>

doc/v2/copy_const_reference.html

@@ -0,0 +1,135 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+    <meta name="generator" content="HTML Tidy, see www.w3.org">
+    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+    <link rel="stylesheet" type="text/css" href="../boost.css">
+
+    <title>Boost.Python - &lt;boost/python/copy_const_reference.hpp&gt;</title>
+
+    <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+      <tr>
+        <td valign="top" width="300">
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+
+        <td valign="top">
+          <h1 align="center">Boost.Python</h1>
+
+          <h2 align="center">Header
+          &lt;boost/python/copy_const_reference.hpp&gt;</h2>
+    </table>
+    <hr>
+
+    <h2>Contents</h2>
+
+    <dl class="page-index">
+      <dt><a href="#classes">Classes</a>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#copy_const_reference-spec">Class
+          <code>copy_const_reference</code></a>
+
+          <dd>
+            <dl class="page-index">
+              <dt><a href="#copy_const_reference-spec-synopsis">Class
+              <code>copy_const_reference</code> synopsis</a>
+
+              <dt><a href="#copy_const_reference-spec-metafunctions">Class
+              <code>copy_const_reference</code> metafunctions</a>
+            </dl>
+        </dl>
+
+      <dt><a href="#examples">Example</a>
+    </dl>
+    <hr>
+
+    <h2><a name="classes"></a>Classes</h2>
+
+    <h3><a name="copy_const_reference-spec"></a>Class
+    <code>copy_const_reference</code></h3>
+
+    <p><code>copy_const_reference</code> is a model of <a href=
+    "ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a> which can be
+    used to wrap C++ functions returning a reference-to-const type such that
+    the referenced value is copied into a new Python object.
+
+    <h4><a name="copy_const_reference-spec-synopsis"></a>Class
+    <code>copy_const_reference</code> synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+    struct copy_const_reference
+    {
+        template &lt;class T&gt; struct apply;
+    };
+}}
+</pre>
+
+    <h4><a name="copy_const_reference-spec-metafunctions"></a>Class
+    <code>copy_const_reference</code> metafunctions</h4>
+<pre>
+template &lt;class T&gt; struct apply
+</pre>
+
+    <dl class="metafunction-semantics">
+      <dt><b>Requires:</b> <code>T</code> is <code>U const&amp;</code> for some
+      <code>U</code>.
+
+      <dt><b>Returns:</b> <code>typedef <a href=
+      "to_python_value.html#to_python_value-spec">to_python_value</a>&lt;T&gt;
+      type;</code>
+    </dl>
+
+    <h2><a name="examples"></a>Example</h2>
+
+<h3>C++ Module Definition</h3>
+<pre>
+#include &lt;boost/python/module.hpp&gt;
+#include &lt;boost/python/class.hpp&gt;
+#include &lt;boost/python/copy_const_reference.hpp&gt;
+#include &lt;boost/python/return_value_policy.hpp&gt;
+
+// classes to wrap
+struct Bar { int x; }
+
+struct Foo {
+   Foo(int x) : { b.x = x; }
+   Bar const&amp; get_bar() const { return b; }
+ private:
+   Bar b;
+};
+
+// Wrapper code
+using namespace boost::python;
+BOOST_PYTHON_MODULE_INIT(my_module)
+{
+   module m("my_module")
+      .add(
+         class_&lt;Bar&gt;()
+         )
+      .add(
+         class_&lt;Foo&gt;()
+            .def_init(args&lt;int&gt;())
+            .def("get_bar", &amp;Foo::get_bar
+                , return_value_policy&lt;copy_const_reference&gt;())
+         )
+       ;
+}
+</pre>
+<h3>Python Code</h3>
+<pre>
+&gt;&gt;&gt; from my_module import *
+&gt;&gt;&gt; f = Foo(3)         # create a Foo object
+&gt;&gt;&gt; b = f.get_bar()    # make a copy of the internal Bar object
+</pre>
+
+    <p>Revised 
+    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+     15 February, 2002
+    <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+
+
+    <p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
+    Abrahams</a> 2002. All Rights Reserved.</i>
+

doc/v2/copy_non_const_reference.html

@@ -0,0 +1,135 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+    <meta name="generator" content="HTML Tidy, see www.w3.org">
+    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+    <link rel="stylesheet" type="text/css" href="../boost.css">
+
+    <title>Boost.Python -
+    &lt;boost/python/copy_non_const_reference.hpp&gt;</title>
+
+    <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+      <tr>
+        <td valign="top" width="300">
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+
+        <td valign="top">
+          <h1 align="center">Boost.Python</h1>
+
+          <h2 align="center">Header
+          &lt;boost/python/copy_non_const_reference.hpp&gt;</h2>
+    </table>
+    <hr>
+
+    <h2>Contents</h2>
+
+    <dl class="page-index">
+      <dt><a href="#classes">Classes</a>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#copy_non_const_reference-spec">Class
+          <code>copy_non_const_reference</code></a>
+
+          <dd>
+            <dl class="page-index">
+              <dt><a href="#copy_non_const_reference-spec-synopsis">Class
+              <code>copy_non_const_reference</code> synopsis</a>
+
+              <dt><a href="#copy_non_const_reference-spec-metafunctions">Class
+              <code>copy_non_const_reference</code> metafunctions</a>
+            </dl>
+        </dl>
+
+      <dt><a href="#examples">Example</a>
+    </dl>
+    <hr>
+
+    <h2><a name="classes"></a>Classes</h2>
+
+    <h3><a name="copy_non_const_reference-spec"></a>Class
+    <code>copy_non_const_reference</code></h3>
+
+    <p><code>copy_non_const_reference</code> is a model of <a href=
+    "ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a> which can be
+    used to wrap C++ functions returning a reference-to-non-const type such
+    that the referenced value is copied into a new Python object.
+
+    <h4><a name="copy_non_const_reference-spec-synopsis"></a>Class
+    <code>copy_non_const_reference</code> synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+    struct copy_non_const_reference
+    {
+        template &lt;class T&gt; struct apply;
+    };
+}}
+</pre>
+
+    <h4><a name="copy_non_const_reference-spec-metafunctions"></a>Class
+    <code>copy_non_const_reference</code> metafunctions</h4>
+<pre>
+template &lt;class T&gt; struct apply
+</pre>
+
+    <dl class="metafunction-semantics">
+      <dt><b>Requires:</b> <code>T</code> is <code>U&amp;</code> for some
+      non-const <code>U</code>.
+
+      <dt><b>Returns:</b> <code>typedef <a href=
+      "to_python_value.html#to_python_value-spec">to_python_value</a>&lt;T&gt;
+      type;</code>
+    </dl>
+
+    <h2><a name="examples"></a>Example</h2>
+
+    <p>C++ code:
+<pre>
+#include &lt;boost/python/module.hpp&gt;
+#include &lt;boost/python/class.hpp&gt;
+#include &lt;boost/python/copy_non_const_reference.hpp&gt;
+#include &lt;boost/python/return_value_policy.hpp&gt;
+
+// classes to wrap
+struct Bar { int x; }
+
+struct Foo {
+   Foo(int x) : { b.x = x; }
+   Bar&amp; get_bar() { return b; }
+ private:
+   Bar b;
+};
+
+// Wrapper code
+using namespace boost::python;
+BOOST_PYTHON_MODULE_INIT(my_module)
+{
+   module("my_module")
+      .add(
+         class_&lt;Bar&gt;()
+         )
+      .add(
+         class_&lt;Foo&gt;()
+            .def_init(args&lt;int&gt;())
+            .def("get_bar", &amp;Foo::get_bar
+                , return_value_policy&lt;copy_non_const_reference&gt;())
+         );
+}
+</pre>
+    Python Code: 
+<pre>
+&gt;&gt;&gt; from my_module import *
+&gt;&gt;&gt; f = Foo(3)         # create a Foo object
+&gt;&gt;&gt; b = f.get_bar()    # make a copy of the internal Bar object
+</pre>
+
+    <p>Revised 
+    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+     05 November, 2001 
+    <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+
+
+    <p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
+    Abrahams</a> 2002. All Rights Reserved.</i>
+

doc/v2/data_members.html

@@ -0,0 +1,150 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+    <meta name="generator" content="HTML Tidy, see www.w3.org">
+    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+    <link rel="stylesheet" type="text/css" href="../boost.css">
+
+    <title>Boost.Python - &lt;boost/python/data_members.hpp&gt;</title>
+
+    <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+      <tr>
+        <td valign="top" width="300">
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+
+        <td valign="top">
+          <h1 align="center">Boost.Python</h1>
+
+          <h2 align="center">Header &lt;boost/python/data_members.hpp&gt;</h2>
+    </table>
+    <hr>
+
+    <h2>Contents</h2>
+
+    <dl class="page-index">
+      <dt><a href="#introduction">Introduction</a>
+
+      <dt><a href="#functions">Functions</a>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#make_getter-spec">make_getter</a>
+
+          <dt><a href="#make_setter-spec">make_setter</a>
+        </dl>
+
+      <dt><a href="#examples">Example</a>
+    </dl>
+    <hr>
+
+    <h2><a name="introduction"></a>Introduction</h2>
+
+    <p><code><a href="#make_getter-spec">make_getter</a>()</code> and
+    <code><a href="#make_setter-spec">make_setter</a>()</code> are
+    the functions used internally by <code>class_&lt;&gt;::<a href=
+    "class.html#class_-spec-modifiers">def_readonly</a></code> and
+    <code>class_&lt;&gt;::<a href=
+    "class.html#class_-spec-modifiers">def_readwrite</a></code> to
+    produce Python callable objects which wrap C++ data members.
+
+    <h2><a name="functions"></a>Functions</h2>
+
+<pre>
+<a name="make_getter-spec">template &lt;class C, class D&gt;</a>
+objects::function* make_getter(D C::*pm);
+
+template &lt;class C, class D, class Policies&gt;
+objects::function* make_getter(D C::*pm, Policies const&amp; policies);
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Requires:</b> <code>Policies</code> is a model of <a
+      href="CallPolicies.html">CallPolicies</a>.
+
+      <dt><b>Effects:</b> Creates a Python callable object which
+      accepts a single argument that can be converted
+      <code>from_python</code> to <code>C*</code>, and returns the
+      corresponding member <code>D</code> member of the <code>C</code>
+      object, converted <code>to_python</code>. If
+      <code>policies</code> is supplied, it will be applied to the
+      function as described <a href=
+      "CallPolicies.html">here</a>.
+
+      <dt><b>Returns:</b> A pointer convertible to <code>PyObject*</code> which
+      refers to the new Python callable object.
+    </dl>
+<pre>
+<a name="make_setter-spec">template &lt;class C, class D&gt;</a>
+objects::function* make_setter(D C::*pm);
+
+template &lt;class C, class D, class Policies&gt;
+objects::function* make_setter(D C::*pm, Policies const&amp; policies);
+</pre>
+
+    <dl class="function*-semantics">
+      <dt><b>Requires:</b> <code>Policies</code> is a model of <a
+      href="CallPolicies.html">CallPolicies</a>.
+
+      <dt><b>Effects:</b> Creates a Python callable object which, when
+      called from Python, expects two arguments which can be converted
+      <code>from_python</code> to <code>C*</code> and
+      <code>D&nbsp;const&amp;</code>, respectively, and sets the
+      corresponding <code>D</code> member of the <code>C</code>
+      object. If <code>policies</code> is supplied, it will be applied
+      to the function as described <a
+      href="CallPolicies.html">here</a>.
+
+      <dt><b>Returns:</b> A pointer convertible to
+      <code>PyObject*</code> which refers to the new Python callable
+      object.
+    </dl>
+
+    <h2><a name="examples"></a>Example</h2>
+
+    <p>The code below uses make_getter and make_setter to expose a
+    data member as functions:
+
+<pre>
+#include &lt;boost/python/data_members.hpp&gt;
+#include &lt;boost/python/module.hpp&gt;
+#include &lt;boost/python/class.hpp&gt;
+
+struct X
+{
+    X(int x) : y(x) {}
+    int y;
+};
+
+using namespace boost::python;
+
+BOOST_PYTHON_MODULE_INIT(data_members_example)
+{
+    module("data_members_example")
+        .add(
+            class_&lt;X&gt;(&quot;X&quot;)
+               .def_init(args&lt;int&gt;())
+               .def(&quot;get&quot;, make_getter(&amp;X::y))
+               .def(&quot;set&quot;, make_setter(&amp;X::y))
+        )
+        ;
+}
+</pre>
+    It can be used this way in Python: 
+<pre>
+&gt;&gt;&gt; from data_members_example import *
+&gt;&gt;&gt; x = X(1)
+&gt;&gt;&gt; x.get()
+1
+&gt;&gt;&gt; x.set(2)
+&gt;&gt;&gt; x.get()
+2
+</pre>
+
+    <p>
+    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+    8 May 2002 <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+
+
+    <p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
+    Abrahams</a> 2002. All Rights Reserved.</i>
+

doc/v2/default_call_policies.html

@@ -0,0 +1,170 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+    <meta name="generator" content="HTML Tidy, see www.w3.org">
+    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+    <link rel="stylesheet" type="text/css" href="../boost.css">
+
+    <title>Boost.Python -
+    &lt;boost/python/default_call_policies.hpp&gt;</title>
+
+    <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+      <tr>
+        <td valign="top" width="300">
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+
+        <td valign="top">
+          <h1 align="center">Boost.Python</h1>
+
+          <h2 align="center">Header
+          &lt;boost/python/default_call_policies.hpp&gt;</h2>
+    </table>
+    <hr>
+
+    <h2>Contents</h2>
+
+    <dl class="page-index">
+      <dt><a href="#classes">Classes</a>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#default_call_policies-spec">Class
+          <code>default_call_policies</code></a>
+
+          <dd>
+            <dl class="page-index">
+              <dt><a href="#default_call_policies-spec-synopsis">Class
+              <code>default_call_policies</code> synopsis</a>
+
+              <dt><a href="#default_call_policies-spec-statics">Class
+              <code>default_call_policies</code> static functions</a>
+            </dl>
+
+          <dt><a href="#default_result_converter-spec">Class
+          <code>default_result_converter</code></a>
+
+          <dd>
+            <dl class="page-index">
+              <dt><a href="#default_result_converter-spec-synopsis">Class
+              <code>default_result_converter</code> synopsis</a>
+
+              <dt><a href="#default_result_converter-spec-metafunctions">Class
+              <code>default_result_converter</code> metafunctions</a>
+            </dl>
+        </dl>
+
+      <dt><a href="#examples">Example</a>
+    </dl>
+    <hr>
+
+    <h2><a name="classes"></a>Classes</h2>
+
+    <h3><a name="default_call_policies-spec"></a>Class
+    <code>default_call_policies</code></h3>
+
+    <p><code>default_call_policies</code> is a model of <a href=
+    "CallPolicies.html">CallPolicies</a> with no <code>precall</code> or
+    <code>postcall</code> behavior and a <code>result_converter</code> which
+    handles by-value returns. Wrapped C++ functions and member functions use
+    <code>default_call_policies</code> unless otherwise specified. You may find
+    it convenient to derive new models of <a href=
+    "CallPolicies.html">CallPolicies</a> from
+    <code>default_call_policies</code>.
+
+    <h4><a name="default_call_policies-spec-synopsis"></a>Class
+    <code>default_call_policies</code> synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+    struct default_call_policies
+    {
+        static bool precall(PyObject*);
+        static PyObject* postcall(PyObject*, PyObject* result);
+        typedef <a href=
+"#default_result_converter-spec">default_result_converter</a> result_converter;
+    };
+}}
+</pre>
+
+    <h4><a name="default_call_policies-spec-statics"></a>Class
+    <code>default_call_policies</code> static functions</h4>
+<pre>
+bool precall(PyObject*);
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Returns:</b> <code>true</code>
+
+      <dt><b>Throws:</b> nothing
+    </dl>
+<pre>
+PyObject* postcall(PyObject*, PyObject* result);
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Returns:</b> <code>result</code>
+
+      <dt><b>Throws:</b> nothing
+    </dl>
+
+    <h3><a name="default_result_converter-spec"></a>Class
+    <code>default_result_converter</code></h3>
+
+    <p><code>default_result_converter</code> is a model of <a href=
+    "ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a> which can be
+    used to wrap C++ functions returning non-pointer types, <code>char
+    const*</code>, and <code>PyObject*</code>, by-value.
+
+    <h4><a name="default_result_converter-spec-synopsis"></a>Class
+    <code>default_result_converter</code> synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+    struct default_result_converter
+    {
+        template &lt;class T&gt; struct apply;
+    };
+}}
+</pre>
+
+    <h4><a name="default_result_converter-spec-metafunctions"></a>Class
+    <code>default_result_converter</code> metafunctions</h4>
+<pre>
+template &lt;class T&gt; struct apply
+</pre>
+
+    <dl class="metafunction-semantics">
+      <dt><b>Requires:</b> <code>T</code> is not a reference type. If
+      <code>T</code> is a pointer type, <code>T</code> is <code>const
+      char*</code> or <code>PyObject*</code>.
+
+      <dt><b>Returns:</b> <code>typedef <a href=
+      "to_python_value.html#to_python_value-spec">to_python_value</a>&lt;T
+      const&amp;&gt; type;</code>
+    </dl>
+
+    <h2><a name="examples"></a>Example</h2>
+
+    <p>This example comes from the Boost.Python implementation itself. Because
+    the <a href=
+    "return_value_policy.html#return_value_policy-spec">return_value_policy</a>
+    class template does not implement <code>precall</code> or
+    <code>postcall</code> behavior, its default base class is
+    <code>default_call_policies</code>:
+<pre>
+template &lt;class Handler, class Base = default_call_policies&gt;
+struct return_value_policy : Base
+{
+   typedef Handler result_converter;
+};
+</pre>
+
+    <p>Revised 
+    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+     05 November, 2001 
+    <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+
+
+    <p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
+    Abrahams</a> 2002. All Rights Reserved.</i>
+

doc/v2/definitions.html

@@ -0,0 +1,35 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+<link rel="stylesheet" type="text/css" href="../boost.css">
+<title>Boost.Python - Definitions</title>
+</head>
+<body link="#0000ff" vlink="#800080">
+<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+  <tr> 
+    <td valign="top" width="300"> 
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+    </td>
+    <td valign="top"> 
+      <h1 align="center">Boost.Python</h1>
+      <h2 align="center">Definitions</h2>
+    </td>
+  </tr>
+</table>
+<hr>
+<dl class="definitions">
+  <dt><b>{{term}}:</b> {{definition}}</dt>
+  <dt><b>{{term}}:</b> {{definition}}</dt>
+</dl>
+<hr>
+<p>Revised 
+  <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+  05 November, 2002 
+  <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+</p>
+<p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave Abrahams</a> 
+  2002. All Rights Reserved.</i></p>
+</body>
+</html>

doc/v2/errors.html

@@ -0,0 +1,241 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+    <meta name="generator" content="HTML Tidy, see www.w3.org">
+    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+    <link rel="stylesheet" type="text/css" href="../boost.css">
+
+    <title>Boost.Python - &lt;boost/python/errors.hpp&gt;</title>
+
+    <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+      <tr>
+        <td valign="top" width="300">
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+
+        <td valign="top">
+          <h1 align="center">Boost.Python</h1>
+
+          <h2 align="center">Header &lt;boost/python/errors.hpp&gt;</h2>
+    </table>
+    <hr>
+
+    <h2>Contents</h2>
+
+    <dl class="page-index">
+      <dt><a href="#introduction">Introduction</a>
+
+      <dt><a href="#classes">Classes</a>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#error_already_set-spec">Class <code>error_already_set</code></a>
+
+          <dd>
+            <dl class="page-index">
+              <dt><a href="#error_already_set-spec-synopsis">Class
+              <code>error_already_set</code> synopsis</a>
+            </dl>
+        </dl>
+
+      <dt><a href="#functions">Functions</a>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#handle_exception-spec">handle_exception</a>
+
+          <dt><a href="#expect_non_null-spec">expect_non_null</a>
+          <dt><a href="#throw_error_already_set-spec">throw_error_already_set</a>
+        </dl>
+
+      <dt><a href="#examples">Examples</a>
+    </dl>
+    <hr>
+
+    <h2><a name="introduction"></a>Introduction</h2>
+
+    <p><code>&lt;boost/python/errors.hpp&gt;</code> provides types and
+    functions for managing and translating between Python and C++ exceptions.
+    This is relatively low-level functionality that is mostly used internally
+    by Boost.Python. Users should seldom need it.
+
+    <h2><a name="classes"></a>Classes</h2>
+
+    <h3><a name="error_already_set-spec"></a>Class
+    <code>error_already_set</code></h3>
+
+    <p><code>error_already_set</code> is an exception type which can be thrown
+    to indicate that a Python error has occurred. If thrown, the precondition
+    is that <a href=
+    "http://www.python.org/doc/2.2/api/exceptionHandling.html#l2h-71">PyErr_Occurred()</a>
+    returns a value convertible to <code>true</code>.
+
+    <h4><a name="error_already_set-spec-synopsis"></a>Class error_already_set synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+    class error_already_set {};
+}}
+</pre>
+
+    <h2><a name="functions"></a>Functions</h2>
+<pre>
+<a name=
+"handle_exception-spec">template &lt;class T&gt; bool handle_exception</a>(T f) throw();
+
+void handle_exception() throw();
+</pre>
+
+    <dl class="handle_exception-semantics">
+      <dt><b>Requires:</b> The first form requires that the expression <code><a
+      href=
+      "../../../function/doc/reference.html#functionN">function0</a>&lt;void&gt;(f)</code>
+      is valid. The second form requires that a C++ exception is currently
+      being handled (see section 15.1 in the C++ standard).
+
+      <dt><b>Effects:</b> The first form calls <code>f()</code> inside a
+      <code>try</code> block whose <code>catch</code> clauses set an
+      appropriate Python exception for the C++ exception caught, returning
+      <code>true</code> if an exception was caught, <code>false</code>
+      otherwise. The second form passes a function which rethrows the exception
+      currently being handled to the first form.
+
+      <dt><b>Postconditions:</b> No exception is being handled
+
+      <dt><b>Throws:</b> nothing
+
+      <dt><b>Rationale:</b> At inter-language boundaries it is important to
+      ensure that no C++ exceptions escape, since the calling language usually
+      doesn't have the equipment neccessary to properly unwind the stack. Use
+      <code>handle_exception</code> to manage exception translation whenever
+      your C++ code is called directly from the Python API. This is done for
+      you automatically by the usual function wrapping facilities: <a href=
+      "make_function.html#make_function-spec">make_function()</a>, <a href=
+      "make_function.html#make_constructor-spec">make_constructor()</a>, <a
+      href="module.html#def-spec">module::def</a> and <a href=
+      "class.html#def-spec">class_::def</a>). The second form can be more
+      convenient to use (see the <a href="#examples">example</a> below), but
+      various compilers have problems when exceptions are rethrown from within
+      an enclosing <code>try</code> block.
+    </dl>
+<pre>
+<a name="expect_non_null-spec">template &lt;class T&gt; T* expect_non_null(T* x);</a>
+</pre>
+
+    <dl class="expect_non_null-semantics">
+      <dt><b>Returns:</b> <code>x</code>
+
+      <dt><b>Throws:</b> <code><a href=
+      "#error_already_set-spec">error_already_set()</a></code> iff <code>x ==
+      0</code>.
+
+      <dt><b>Rationale:</b> Simplifies error-handling when calling many
+      functions in the <a href=
+      "http://www.python.org/doc/2.2/api/api.html">Python/C API</a>, which
+      return 0 on error.
+    </dl>
+
+<pre>
+<a name="throw_error_already_set-spec">void throw_error_already_set();</a>
+</pre>
+
+    <dl class="throw_error_already_set-semantics">
+
+      <dt><b>Effects:</b> <code>throw&nbsp;<a href=
+      "#error_already_set-spec">error_already_set</a>();</code> 
+    </dl>
+
+    <h2><a name="examples"></a>Examples</h2>
+<pre>
+#include &lt;string&gt;
+#include &lt;boost/python/errors.hpp&gt;
+#include &lt;boost/python/reference.hpp&gt;
+
+// Returns a std::string which has the same value as obj's "__name__"
+// attribute.
+std::string get_name(boost::python::ref obj)
+{
+   // throws if there's no __name__ attribute
+   PyObject* p = boost::python::expect_non_null(
+      PyObject_GetAttrString(obj.get(), "__name__"));
+
+   // throws if it's not a Python string
+   std::string result(
+      boost::python::expect_non_null(
+         PyString_AsString(p)));
+
+   Py_XDECREF(p); // Done with p
+   
+   return result;
+}
+
+//
+// Demonstrate form 1 of handle_exception
+//
+
+// Place a Python Int object whose value is 1 if a and b have
+// identical "__name__" attributes, 0 otherwise.
+void same_name_impl(PyObject*&amp; result, PyObject* a, PyObject* b)
+{
+   result = PyInt_FromLong(
+      get_name(boost::python::ref(a1)) == get_name(boost::python::ref(a2)));
+}
+
+// This is an example Python 'C' API interface function
+extern "C" PyObject*
+same_name(PyObject* args, PyObject* keywords)
+{
+   PyObject* a1;
+   PyObject* a2;
+   PyObject* result = 0;
+
+   if (!PyArg_ParseTuple(args, const_cast&lt;char*&gt;("OO"), &amp;a1, &amp;a2))
+      return 0;
+   
+   // Use boost::bind to make an object compatible with
+   // boost::Function0&lt;void&gt;
+   if (boost::python::handle_exception(
+         boost::bind&lt;void&gt;(same_name_impl, boost::ref(result), a1, a2)))
+   {
+      // an exception was thrown; the Python error was set by
+      // handle_exception()
+      return 0;
+   }
+
+   return result;
+}
+
+//
+// Demonstrate form 2 of handle_exception. Not well-supported by all
+// compilers.
+//
+extern "C" PyObject*
+same_name2(PyObject* args, PyObject* keywords)
+{
+   PyObject* a1;
+   PyObject* a2;
+   PyObject* result = 0;
+
+   if (!PyArg_ParseTuple(args, const_cast&lt;char*&gt;("OO"), &amp;a1, &amp;a2))
+      return 0;
+   try {
+      return PyInt_FromLong(
+         get_name(boost::python::ref(a1)) == get_name(boost::python::ref(a2)));
+   }
+   catch(...)
+   {
+      // If an exception was thrown, translate it to Python
+      boost::python::handle_exception();
+      return 0;
+   }
+}
+</pre>
+
+    <p>Revised 
+    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+     17 November, 2002
+    <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+
+
+    <p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
+    Abrahams</a> 2002. All Rights Reserved.</i>
+

doc/v2/faq.html

@@ -0,0 +1,39 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+<link rel="stylesheet" type="text/css" href="../boost.css">
+<title>Boost.Python - FAQ</title>
+</head>
+<body link="#0000ff" vlink="#800080">
+<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+  <tr> 
+    <td valign="top" width="300"> 
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+    </td>
+    <td valign="top"> 
+      <h1 align="center">Boost.Python</h1>
+      <h2 align="center">Frequently Asked Questions (FAQs)</h2>
+    </td>
+  </tr>
+</table>
+<hr>
+<dl class="page-index">
+  <dt><a href="#question1">{{question}}</a></dt>
+  <dt><a href="#question2">{{question}}</a></dt>
+</dl>
+<h2><a name="question1"></a>{{question}}</h2>
+<p>{{answer}}</p>
+<h2><a name="question2"></a>{{question}}</h2>
+<p>{{answer}}</p>
+<hr>
+<p>Revised 
+  <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+  05 November, 2002 
+  <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+</p>
+<p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave Abrahams</a> 
+  2002. All Rights Reserved.</i></p>
+</body>
+</html>

doc/v2/feb2002.html

@@ -0,0 +1,366 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+    <meta http-equiv="Content-Type" content=
+    "text/html; charset=iso-8859-1">
+    <link rel="stylesheet" type="text/css" href="../boost.css">
+
+    <title>Boost.Python - February 2002 Progress Report</title>
+<style type="text/css">
+ :link { color: #0000ff }
+ :visited { color: #800080 }
+ p.c3 {font-style: italic}
+ h2.c2 {text-align: center}
+ h1.c1 {text-align: center}
+</style>
+
+    <table border="0" cellpadding="7" cellspacing="0" width=
+    "100%" summary="header">
+      <tr>
+        <td valign="top" width="300">
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+
+        <td valign="top">
+          <h1 class="c1">Boost.Python</h1>
+
+          <h2 class="c2">February 2002 Progress Report</h2>
+    </table>
+    <hr>
+
+    <h2>Contents</h2>
+
+    <dl class="index">
+      <dt><a href="#Python10">Python10 Conference Report</a>
+
+      <dt><a href="#progress">Boost.Python v2 Progress</a>
+
+      <dd>
+        <dl class="index">
+          <dt><a href="#documentation">Documentation</a>
+
+          <dt><a href="#conversion">Overhaul of
+          <code>to_python</code>/<code>from_python</code>
+          conversion mechanism</a>
+
+          <dt><a href="#miscellaneous">Miscellaneous</a>
+        </dl>
+    </dl>
+
+    <h2><a name="Python10">Python10 Conference Report</a></h2>
+    I spent the first week of February at the Python10 conference
+    in Alexandria, VA. I&#39;m including this experience report
+    for two reasons: firstly, it documents where my time was
+    used. Secondly, a public presence for Boost.Python and
+    interaction between the Python and C++ communities is
+    important to the future of Boost.Python, which in turn is
+    important to the Kull Project. 
+
+    <p>Andy Koenig, of all people, was the keynote speaker of
+    this year&#39;s opening plenary session. He presented his
+    &quot;impressions of a polyglot outsider&quot;, which
+    studiously avoided any mention of C++ until the end of his
+    talk, when he was asked about standardization. I was
+    surprised to learn that the C++ community at large wanted a
+    few more years before beginning but when ANSI accepted
+    HP&#39;s request for a standard, the process was forced to
+    start: it was a matter of participating or having
+    standardization proceed without one&#39;s input. Andy managed
+    to highlight very effectively the balance of strengths in
+    Python, one of the most important being its support for
+    extension via libraries. In many ways that makes Python a
+    good analogue for C++ in the interpreted world
+
+    <p>There were several kind mentions of the Boost.Python
+    library from people who found it indispensable. I was
+    particularly happy that Karl MacMillan, Michael Droettboom,
+    and Ichiro Fujinaga from Johns Hopkins is using it to do OCR
+    on a vast library of music notation, since in a previous life
+    I was an author of music notation software. These guys are
+    also drawing on Ullrich Koethe&#39;s VIGRA library for image
+    manipulation (Ullrich has been a major contributor to
+    Boost.Python). They also have a system for writing the
+    Boost.Python wrapper code in C++ comments, which allows them
+    to keep all of the code in one place. I&#39;ve asked them to
+    send me some information on that.
+
+    <p>The development of Swig has been gaining momentum again
+    (the basic description at
+    www.boost.org/libs/python/doc/comparisons.html still
+    applies). The talk given about it by David Beazly was very
+    well-attended, and they appear to have quite a few users.
+    Swig&#39;s strengths (coverage of many langauages) and
+    weaknesses (incomplete C++ language support) haven&#39;t
+    changed, although the C++ support seems to have improved
+    considerably - they now claim to have a complete model of the
+    C++ type system. It seems to be mostly geared at wrapping
+    what Walter Landry calls &quot;C-Tran&quot;: C++ code which
+    traffics in built-in types with little use of abstraction.
+    I&#39;m not knocking that, either: I&#39;m sure a lot of that
+    code exists, so it&#39;s a valuable service. One feature Swig
+    has which I&#39;d like to steal is the ability to unwrap a
+    single Python argument into multiple C++ arguments, for
+    example, by converting a Python string into a pointer and
+    length. When his talk was over, David approached me about a
+    possible joint workshop on language binding, which sounds
+    like a fun idea to me.
+
+    <p>I spent some considerable time talking with Steven Knight,
+    the leader of the Scons build tool effort. We had a lot to
+    share with one another, and I gained a much better
+    appreciation for many of the Scons design decisions. Scons
+    seems to be concentrating on being the ultimate build system
+    substrate, and Steve seemed to think that we were on the
+    right track with our high-level design. We both hope that the
+    Boost.Build V2 high-level architecture can eventually be
+    ported to run on top of Scons.
+
+    <p>They also have a highly-refined and successful development
+    procedure which I&#39;d like to emulate for Boost.Build V2.
+    Among many other things they do, their source-control system
+    automatically ensures that when you check in a new test, it
+    is automatically run on the currently checked-in state of the
+    code, and is expected to fail -- a relatively obvious good
+    idea which I&#39;ve never heard before.
+
+    <p>Guido Van Rossum&#39;s &quot;State of the Python
+    Union&quot; address was full of questions for the community
+    about what should be done next, but the one idea Guido seemed
+    to stress was that core language stability and continuing
+    library development would be a good idea (sound familiar?) I
+    mentioned the Boost model as a counterpoint to the idea of
+    something like CPAN (the massive Perl library archives), and
+    it seemed to generate some significant interest. I&#39;ve
+    offered to work with anyone from the Python community who
+    wants to set up something like Boost.
+
+    <p>There was some discussion of &quot;string
+    interpolation&quot; (variable substitution in strings), and
+    Guido mentioned that he had some thoughts about the
+    strengths/weaknesses of Python&#39;s formatting interface. It
+    might be useful for those working on formatting for boost to
+    contact him and find out what he has to say.
+
+    <p>Ka-Ping Yee demoed a Mailman discussion thread weaver.
+    This tool weaves the various messages in a discussion thread
+    into a single document so you can follow the entire
+    conversation. Since we&#39;re looking very seriously at
+    moving Boost to Mailman, this could be a really useful thing
+    for us to have. If we do this, we&#39;ll move the yahoogroups
+    discussions into the mailman archive so old discussions can
+    be easily accessed in the same fashion.
+
+    <p>And, just because it&#39;s cool, though perhaps not
+    relevant: http://homepages.ulb.ac.be/~arigo/psyco/ is a
+    promising effort to accelerate the execution of Python code
+    to speeds approaching those of compiled languages. It
+    reminded me a lot of Todd Veldhuizen&#39;s research into
+    moving parts of C++ template compilation to runtime, only
+    coming from the opposite end of things.
+
+    <h2><a name="progress">Boost.Python v2 Progress</a></h2>
+    Here&#39;s what actually got accomplished. 
+
+    <h3><a name="documentation">Documentation</a></h3>
+
+    <p>My first priority upon returning from Python10 was to get
+    some documentation in place. After wasting an unfortunate
+    amount of time looking at automatic documentation tools which
+    don&#39;t quite work, I settled down to use Bill Kempf&#39;s
+    HTML templates designed to be a boost standard. While they
+    are working well, it is highly labor-intensive.
+
+    <p>I decided to begin with the high-level reference material,
+    as opposed to tutorial, narrative, or nitty-gritty details of
+    the framework. It seemed more important to have a precise
+    description of the way the commonly-used components work than
+    to have examples in HTML (since we already have some test
+    modules), and since the low-level details are much
+    less-frequently needed by users it made sense for me to
+    simply respond to support requests for the time being.
+
+    <p>After completing approximately 60% of the high-level docs
+    (currently checked in to libs/python/doc/v2), I found myself
+    ready to start documenting the mechanisms for creating
+    to-/from-python converters. This caused a dilemma: I had
+    realized during the previous week that a much simpler,
+    more-efficient, and easier-to-use implementation was
+    possible, but I hadn&#39;t planned on implementing it right
+    away, since what was already in place worked adequately. I
+    had also received my first query on the C++-sig about how to
+    write such a converter
+
+    <p>Given the labor-intensive nature of documentation writing,
+    I decided it would be a bad idea to document the conversion
+    mechanism if I was just going to rewrite it. Often the best
+    impetus for simplifying a design is the realization that
+    understandably documenting its current state would be too
+    difficult, and this was no exception.
+
+    <h3><a name="conversion">Overhaul of
+    <code>to_python</code>/<code>from_python</code> conversion
+    mechanism</a></h3>
+
+    <p>There were two basic realizations involved here:
+
+    <ol>
+      <li><code>to_python</code> conversion could be a one-step
+      process, once an appropriate conversion function is found.
+      This allows elimination of the separate indirect
+      convertibility check
+
+      <li>There are basically two categories of from_python
+      conversions: those which lvalues stored within or held by
+      the Python object (essentially extractions), like what
+      happens when an instance of a C++ class exposed with class_
+      is used as the target of a wrapped member function), and
+      those in which a new rvalue gets created, as when a Python
+      Float is converted to a C++
+      <code>complex&lt;double&gt;</code> or a Python tuple is
+      converted to a C++ <code>std::vector&lt;&gt;</code>. From
+      the client side, there are two corresponding categories of
+      conversion: those which demand an lvalue conversion and
+      those which can accept an lvalue or an rvalue conversion.
+    </ol>
+    The latter realization allowed the following collapse, which
+    considerably simplified things: 
+
+    <blockquote>
+      <table border="1" summary="Conversion protocol">
+        <tr>
+          <th>Target Type
+
+          <th>Eligible Converters
+
+        <tr>
+          <td><code>T</code> 
+
+          <td rowspan="5"><code>T</code> rvalue or lvalue
+
+        <tr>
+          <td><code>T const</code> 
+
+        <tr>
+          <td><code>T volatile</code> 
+
+        <tr>
+          <td><code>T const volatile</code> 
+
+        <tr>
+          <td><code>T const&amp;</code> 
+
+        <tr>
+          <td><code>T const*</code> 
+
+          <td rowspan="9"><code>T</code> lvalue
+
+        <tr>
+          <td><code>T volatile*</code> 
+
+        <tr>
+          <td><code>T const volatile*</code> 
+
+        <tr>
+          <td><code>T&amp;</code> 
+
+        <tr>
+          <td><code>T volatile&amp;</code> 
+
+        <tr>
+          <td><code>T const volatile&amp;</code> 
+
+        <tr>
+          <td><code>T* const&amp;</code> 
+
+        <tr>
+          <td><code>T const* const&amp;</code> 
+
+        <tr>
+          <td><code>T volatile*const&amp;</code> 
+
+        <tr>
+          <td><code>T const volatile*const&amp;</code> 
+      </table>
+    </blockquote>
+    This job included the following additional enhancements: 
+
+    <ul>
+      <li>Elimination of virtual functions, which cause object
+      code bloat
+
+      <li>Registration of a single converter function for all
+      lvalue conversions, two for all rvalue conversions
+
+      <li>Killed lots of unneeded code
+
+      <li>Increased opacity of registry interface
+
+      <li>Eliminated all need for decorated runtime type
+      identifiers
+
+      <li>Updated test modules to reflect new interface
+
+      <li>Eliminated the need for users to worry about converter
+      lifetime issues Additional Builtin Conversion Enhancements
+
+      <li>Support for complex&lt;float&gt;,
+      complex&lt;double&gt;, and complex&lt;long double&gt;
+      conversions
+
+      <li>Support for bool conversions
+
+      <li>NULL pointers representable by None in Python
+
+      <li>Support for conversion of Python classic classes to
+      numeric types
+    </ul>
+
+    <h3><a name="miscellaneous">Miscellaneous</a></h3>
+    These don&#39;t fit easily under a large heading: 
+
+    <ul>
+      <li>Support CallPolicies for class member functions
+
+      <li>from_python_data.hpp: revamped type alignment
+      metaprogram so that it&#39;s fast enough for KCC
+
+      <li>classfwd.hpp header forward-declares class_&lt;T&gt;
+
+      <li>indirect_traits.hpp:
+
+      <li>added is_pointer_to_reference
+
+      <li>fixed bugs
+
+      <li>Reduced recompilation dependencies
+
+      <li>msvc_typeinfo works around broken MS/Intel typeid()
+      implementation
+
+      <li>Many fixes and improvements to the type_traits library
+      in order to work around compiler bugs and suppress warnings
+
+      <li>Eliminated the need for explicit acquisition of
+      converter registrations
+
+      <li>Expanded constructor support to 6 arguments
+
+      <li>Implemented generalized pointer lifetime support
+
+      <li>Updated code generation for returning.hpp
+
+      <li>Tracked down and fixed cycle GC bugs
+
+      <li>Added comprehensive unit tests for destroy_reference,
+      pointer_type_id, select_from_python, complex&lt;T&gt;,
+      bool, and classic class instance conversions
+    </ul>
+
+    <p>Revised 
+    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+     4 April, 2002 
+    <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+
+
+    <p class="c3">&copy; Copyright <a href= 
+    "../../../../people/dave_abrahams.htm">Dave Abrahams</a>
+    2002. All Rights Reserved.
+

doc/v2/from_python.html

@@ -0,0 +1,166 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+    <meta name="generator" content="HTML Tidy, see www.w3.org">
+    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+    <link rel="stylesheet" type="text/css" href="../boost.css">
+
+    <title>Boost.Python - &lt;boost/python/from_python.hpp&gt;</title>
+
+    <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+      <tr>
+        <td valign="top" width="300">
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+
+        <td valign="top">
+          <h1 align="center">Boost.Python</h1>
+
+          <h2 align="center">Header &lt;boost/python/from_python.hpp&gt;</h2>
+    </table>
+    <hr>
+
+    <h2>Contents</h2>
+
+    <dl class="page-index">
+      <dt><a href="#introduction">Introduction</a>
+
+      <dt><a href="#classes">Classes</a>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#from_python-spec">Class
+          Template<code>from_python</code></a>
+
+          <dd>
+            <dl class="page-index">
+              <dt><a href="#from_python-spec-synopsis">Class Template
+              <code>from_python</code> synopsis</a>
+
+              <dt><a href="#from_python-spec-ctors">Class Template
+              <code>from_python</code> constructor</a>
+
+              <dt><a href="#from_python-spec-observers">Class Template
+              <code>from_python</code> observer functions</a>
+            </dl>
+        </dl>
+
+      <dt><a href="#examples">Example</a>
+    </dl>
+    <hr>
+
+    <h2><a name="introduction"></a>Introduction</h2>
+
+    <p><code>&lt;boost/python/from_python.hpp&gt;</code> introduces a class
+    template <code>from_python&lt;T&gt;</code> for extracting a C++ object of
+    type <code>T</code> from a Python object.
+
+    <h2><a name="classes"></a>Classes</h2>
+
+    <h3><a name="from_python-spec"></a>Class Template
+    <code>from_python&lt;class T&gt;</code></h3>
+
+    <p><code>from_python&lt;T&gt;</code> is the type used internally by
+    Boost.Python to extract C++ function arguments from a Python argument tuple
+    when calling a wrapped function. It can also be used directly to make
+    similar conversions in other contexts.
+
+    <h4><a name="from_python-spec-synopsis"></a>Class Template
+    <code>from_python</code> synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+   template &lt;class T&gt;
+   struct from_python : private <a href=
+"../../../utility/utility.htm#Class noncopyable">boost::noncopyable</a> // Exposition only.
+       // from_python&lt;T&gt; meets the <a href=
+"NonCopyable.html">NonCopyable</a> requirements
+   {
+      from_python(PyObject*);
+      bool convertible() const;
+      <i>convertible-to-T</i> operator()(PyObject*) const;
+   };
+}
+</pre>
+
+    <h4><a name="from_python-spec-ctors"></a>Class Template
+    <code>from_python</code> constructor</h4>
+<pre>
+from_python(PyObject* p);
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Requires:</b> <code>p != 0</code>
+
+      <dt><b>Effects:</b> Constructs a <code>from_python</code> object suitable
+      for extracting a C++ object of type <code>T</code> from <code>p</code>.
+    </dl>
+
+    <h4><a name="from_python-spec-observers"></a>Class Template
+    <code>from_python</code> observer functions</h4>
+<pre>
+bool convertible() const;
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Returns:</b> <code>false</code> if the conversion cannot succeed.
+      This indicates that either:
+
+      <dd>
+        <ol>
+          <li>No <code>from_python_converter</code> was registered for
+          <code>T</code>, or
+
+          <li>any such converter rejected the constructor argument
+          <code>p</code> by returning <code>0</code> from its
+          <code>convertible()</code> function
+        </ol>
+        Note that conversion may still fail in <code>operator()</code> due to
+        an exception. 
+
+      <dt><b>Throws:</b> nothing
+
+      <dt><b>Rationale:</b> Because <code>from_python&lt;&gt;</code> is used in
+      overload resolution, and throwing an exception can be slow, it is useful
+      to be able to rule out a broad class of unsuccessful conversions without
+      throwing an exception.
+    </dl>
+<pre>
+<i>convertible-to-T</i> operator()(PyObject* p) const;
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Requires:</b> <code>*p</code> refers to the same object which was
+      passed to the constructor, and <code>convertible()</code> returns
+      <code>true</code>.
+
+      <dt><b>Effects:</b> performs the conversion
+
+      <dt><b>Returns:</b> an object convertible to <code>T</code>.
+    </dl>
+
+    <h2><a name="examples"></a>Example</h2>
+<pre>
+#include &lt;string&gt;
+#include &lt;boost/python/from_python.hpp&gt;
+
+// If a std::string can be extracted from p, return its
+// length. Otherwise, return 0.
+std::size_t length_if_string(PyObject* p)
+{
+   from_python&lt;std::string&gt; converter(p);
+   if (!converter.convertible())
+      return 0;
+   else
+      return converter(p).size();
+}
+</pre>
+
+    <p>Revised 
+    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+     05 November, 2001 
+    <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+
+
+    <p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
+    Abrahams</a> 2002. All Rights Reserved.</i>
+

doc/v2/has_back_reference.html

@@ -0,0 +1,217 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+
+    <meta name="generator" content="HTML Tidy, see www.w3.org">
+    <meta http-equiv="Content-Type" content=
+    "text/html; charset=iso-8859-1">
+    <link rel="stylesheet" type="text/css" href="../boost.css">
+
+    <title>Boost.Python -
+    &lt;boost/python/has_back_reference.hpp&gt;</title>
+<style type="text/css">
+ p.c3 {font-style: italic}
+ h2.c2 {text-align: center}
+ h1.c1 {text-align: center}
+</style>
+
+    <table border="0" cellpadding="7" cellspacing="0" width=
+    "100%" summary="header">
+      <tr>
+        <td valign="top" width="300">
+          <h3><a href="../../../../index.htm"><img height="86"
+          width="277" alt="C++ Boost" src= 
+          "../../../../c++boost.gif" border="0"></a></h3>
+
+        <td valign="top">
+          <h1 class="c1">Boost.Python</h1>
+
+          <h2 class="c2">Header
+          &lt;boost/python/has_back_reference.hpp&gt;</h2>
+    </table>
+    <hr>
+
+    <h2>Contents</h2>
+
+    <dl class="page-index">
+      <dt><a href="#introduction">Introduction</a>
+
+      <dt><a href="#classes">Classes</a>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#has_back_reference-spec">Class template
+          <code>has_back_reference</code></a>
+
+          <dd>
+            <dl class="page-index">
+              <dt><a href=
+              "#has_back_reference-spec-synopsis">Class template
+              <code>has_back_reference</code> synopsis</a>
+            </dl>
+
+          <dt><a href="#examples">Example(s)</a>
+        </dl>
+    </dl>
+    <hr>
+
+    <h2><a name="introduction"></a>Introduction</h2>
+
+    <p><code>&lt;boost/python/has_back_reference.hpp&gt;</code>
+    defines the traits class template
+    <code>has_back_reference&lt;&gt;</code>, which can be
+    specialized by the user to indicate that a wrapped class
+    instance holds a <code>PyObject*</code> corresponding to a
+    Python object.
+
+    <h2><a name="classes"></a>Classes</h2>
+
+    <h3><a name="has_back_reference-spec"></a>Class template
+    <code>has_back_reference</code></h3>
+
+    <p>A unary metafunction whose <code>value</code> is true iff
+    its argument is a <code>pointer_wrapper&lt;&gt;</code>.
+
+    <h4><a name="has_back_reference-spec-synopsis"></a>Class
+    template <code>has_back_reference</code> synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+    template&lt;class WrappedClass&gt; class has_back_reference
+    { 
+        static <i>unspecified</i> value = false;
+    };
+}}
+</pre>
+
+    <p>A &quot;<a href= 
+    "../../../../more/generic_programming.html#traits">traits
+    class</a>&quot; which is inspected by Boost.Python to
+    determine how wrapped classes can be constructed.
+
+    <dl class="traits-semantics">
+
+      <dt><code>value</code> is an integral constant convertible
+      to bool of unspecified type.
+
+      <dt>Specializations may substitute a value convertible to
+ <code>true</code> for <code>value</code> iff for each invocation of
+ <code>class_&lt;WrappedClass&gt;::def_init(args&lt;</code><i>type-sequence...</i><code>&gt;())</code>,
+ there exists a corresponding constructor
+ <code>WrappedClass::WrappedClass(PyObject*,&nbsp;</code><i>type-sequence...</i><code>)</code>. If
+ such a specialization exists, the <code>WrappedClass</code>
+ constructors will be called with a &quot;back reference&quot; pointer
+ to the corresponding Python object whenever they are invoked from
+ Python.
+
+    </dl>
+
+    <h2><a name="examples"></a>Example</h2>
+
+<h3>C++ module definition</h3>
+
+<pre>
+#include &lt;boost/python/class.hpp&gt;
+#include &lt;boost/python/module.hpp&gt;
+#include &lt;boost/python/has_back_reference.hpp&gt;
+#include &lt;boost/shared_ptr.hpp&gt;
+
+using namespace boost::python;
+
+struct X
+{
+    X(PyObject* self) : m_self(self), m_x(0) {}
+    X(PyObject* self, int x) : m_self(self), m_x(x) {}
+    
+    PyObject* self() { return m_self; }
+    int get() { return m_x; }
+    void set(int x) { m_x = x; }
+
+    PyObject* m_self;
+    int x;
+};
+
+// specialize has_back_reference for X
+namespace boost { namespace python
+{
+  template &lt;&gt;
+  struct has_back_reference&lt;X&gt;
+  {
+     enum { value = true; }
+  }
+}}
+
+struct Y
+{
+    Y() : m_x(0) {}
+    Y(int x) : m_x(x) {}
+    int get() { return m_x; }
+    void set(int x) { m_x = x; }
+
+    int x;
+};
+
+boost::shared_ptr&lt;Y&gt; Y_self(boost::shared_ptr&lt;Y&gt; self) const { return self; }
+
+BOOST_PYTHON_MODULE_INIT(back_references)
+{
+    module(&quot;back_references&quot;)
+        .add(
+            class_&lt;X&gt;(&quot;X&quot;)
+               .def_init()
+               .def_init(args&lt;int&gt;())
+               .def(&quot;self&quot;, &amp;X::self)
+               .def(&quot;get&quot;, &amp;X::get)
+               .def(&quot;set&quot;, &amp;X::set)
+            )
+        .add(
+            class_&lt;Y, shared_ptr&lt;Y&gt; &gt;(&quot;Y&quot;)
+               .def_init()
+               .def_init(args&lt;int&gt;())
+               .def(&quot;get&quot;, &amp;Y::get)
+               .def(&quot;set&quot;, &amp;Y::set)
+               .def(&quot;self&quot;, Y_self)
+            )
+        ;
+}
+</pre>
+
+The following Python session illustrates that <code>x.self()</code>
+returns the same Python object on which it is invoked, while
+<code>y.self()</code> must create a new Python object which refers to
+the same Y instance.
+
+<h3>Python code</h3>
+
+<pre>
+&gt;&gt;&gt; from back_references import *
+&gt;&gt;&gt; x = X(1)
+&gt;&gt;&gt; x2 = x.self()
+&gt;&gt;&gt; x2 is x
+<b>1</b>
+&gt;&gt;&gt; (x.get(), x2.get())
+(1, 1)
+&gt;&gt;&gt; x.set(10)
+&gt;&gt;&gt; (x.get(), x2.get())
+(10, 10)
+&gt;&gt;&gt;
+&gt;&gt;&gt;
+&gt;&gt;&gt; y = Y(2)
+&gt;&gt;&gt; y2 = y.self()
+&gt;&gt;&gt; y2 is y
+<b>0</b>
+&gt;&gt;&gt; (y.get(), y2.get())
+(2, 2)
+&gt;&gt;&gt; y.set(20)
+&gt;&gt;&gt; (y.get(), y2.get())
+(20, 20)
+</pre>
+
+    <p>Revised 
+    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+     07 May, 2002 
+    <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+
+
+    <p class="c3">&copy; Copyright <a href= 
+    "../../../../people/dave_abrahams.htm">Dave Abrahams</a>
+    2002. All Rights Reserved. 
+

doc/v2/header.html

@@ -0,0 +1,288 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+    <meta name="generator" content="HTML Tidy, see www.w3.org">
+    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+    <link rel="stylesheet" type="text/css" href="../boost.css">
+
+    <title>Boost.Python - &lt;{{header}}&gt;</title>
+
+    <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+      <tr>
+        <td valign="top" width="300">
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+
+        <td valign="top">
+          <h1 align="center">Boost.Python</h1>
+
+          <h2 align="center">Header &lt;{{header}}&gt;</h2>
+    </table>
+    <hr>
+
+    <h2>Contents</h2>
+
+    <dl class="page-index">
+      <dt><a href="#introduction">Introduction</a>
+
+      <dt><a href="#macros">Macros</a>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#macro-spec">{{macro name}}</a>
+        </dl>
+
+      <dt><a href="#values">Values</a>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#value-spec">{{value name}}</a>
+        </dl>
+
+      <dt><a href="#types">Types</a>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#type-spec">{{type name}}</a>
+        </dl>
+
+      <dt><a href="#classes">Classes</a>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#class-spec">Class <code>{{name}}</code></a>
+
+          <dd>
+            <dl class="page-index">
+              <dt><a href="#class-spec-synopsis">Class <code>{{name}}</code> synopsis</a>
+
+              <dt><a href="#class-spec-ctors">Class <code>{{name}}</code>
+              constructors and destructor</a>
+
+              <dt><a href="#class-spec-comparisons">Class <code>{{name}}</code> comparison functions</a>
+
+              <dt><a href="#class-spec-modifiers">Class <code>{{name}}</code> modifier functions</a>
+
+              <dt><a href="#class-spec-observers">Class <code>{{name}}</code> observer functions</a>
+
+              <dt><a href="#class-spec-statics">Class <code>{{name}}</code> static functions</a>
+            </dl>
+        </dl>
+
+      <dt><a href="#functions">Functions</a>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#function-spec">{{function name}}</a>
+        </dl>
+
+      <dt><a href="#objects">Objects</a>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#object-spec">{{object name}}</a>
+        </dl>
+
+      <dt><a href="#examples">Example(s)</a>
+    </dl>
+    <hr>
+
+    <h2><a name="introduction"></a>Introduction</h2>
+
+    <p>{{Introductory text}}
+
+    <h2><a name="macros"></a>Macros</h2>
+
+    <p><a name="macro-spec"></a>{{Macro specifications}}
+
+    <h2><a name="values"></a>Values</h2>
+
+    <p><a name="value-spec"></a>{{Value specifications}}
+
+    <h2><a name="types"></a>Types</h2>
+
+    <p><a name="type-spec"></a>{{Type specifications}}
+
+    <h2><a name="classes"></a>Classes</h2>
+
+    <h3><a name="class-spec"></a>Class <code>{{name}}</code></h3>
+
+    <p>{{class overview text}}
+
+    <h4><a name="class-spec-synopsis"></a>Class <code>{{name}}</code> synopsis</h4>
+<pre>
+namespace boost
+{
+    class {{name}}
+  {
+  };
+};
+</pre>
+
+    <h4><a name="class-spec-ctors"></a>Class <code>{{name}}</code> constructors and
+    destructor</h4>
+<pre>
+{{constructor}}
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Requires:</b> {{text}}
+
+      <dt><b>Effects:</b> {{text}}
+
+      <dt><b>Postconditions:</b> {{text}}
+
+      <dt><b>Returns:</b> {{text}}
+
+      <dt><b>Throws:</b> {{text}}
+
+      <dt><b>Complexity:</b> {{text}}
+
+      <dt><b>Rationale:</b> {{text}}
+    </dl>
+<pre>
+{{destructor}}
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Requires:</b> {{text}}
+
+      <dt><b>Effects:</b> {{text}}
+
+      <dt><b>Postconditions:</b> {{text}}
+
+      <dt><b>Returns:</b> {{text}}
+
+      <dt><b>Throws:</b> {{text}}
+
+      <dt><b>Complexity:</b> {{text}}
+
+      <dt><b>Rationale:</b> {{text}}
+    </dl>
+
+    <h4><a name="class-spec-comparisons"></a>Class <code>{{name}}</code> comparison
+    functions</h4>
+<pre>
+{{function}}
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Requires:</b> {{text}}
+
+      <dt><b>Effects:</b> {{text}}
+
+      <dt><b>Postconditions:</b> {{text}}
+
+      <dt><b>Returns:</b> {{text}}
+
+      <dt><b>Throws:</b> {{text}}
+
+      <dt><b>Complexity:</b> {{text}}
+
+      <dt><b>Rationale:</b> {{text}}
+    </dl>
+
+    <h4><a name="class-spec-modifiers"></a>Class <code>{{name}}</code> modifier
+    functions</h4>
+<pre>
+{{function}}
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Requires:</b> {{text}}
+
+      <dt><b>Effects:</b> {{text}}
+
+      <dt><b>Postconditions:</b> {{text}}
+
+      <dt><b>Returns:</b> {{text}}
+
+      <dt><b>Throws:</b> {{text}}
+
+      <dt><b>Complexity:</b> {{text}}
+
+      <dt><b>Rationale:</b> {{text}}
+    </dl>
+
+    <h4><a name="class-spec-observers"></a>Class <code>{{name}}</code> observer
+    functions</h4>
+<pre>
+{{function}}
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Requires:</b> {{text}}
+
+      <dt><b>Effects:</b> {{text}}
+
+      <dt><b>Postconditions:</b> {{text}}
+
+      <dt><b>Returns:</b> {{text}}
+
+      <dt><b>Throws:</b> {{text}}
+
+      <dt><b>Complexity:</b> {{text}}
+
+      <dt><b>Rationale:</b> {{text}}
+    </dl>
+
+    <h4><a name="class-spec-statics"></a>Class <code>{{name}}</code> static functions</h4>
+<pre>
+{{function}}
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Requires:</b> {{text}}
+
+      <dt><b>Effects:</b> {{text}}
+
+      <dt><b>Postconditions:</b> {{text}}
+
+      <dt><b>Returns:</b> {{text}}
+
+      <dt><b>Throws:</b> {{text}}
+
+      <dt><b>Complexity:</b> {{text}}
+
+      <dt><b>Rationale:</b> {{text}}
+    </dl>
+
+    <h2><a name="functions"></a>Functions</h2>
+<pre>
+
+
+<a name="function-spec"></a>{{function}}
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Requires:</b> {{text}}
+
+      <dt><b>Effects:</b> {{text}}
+
+      <dt><b>Postconditions:</b> {{text}}
+
+      <dt><b>Returns:</b> {{text}}
+
+      <dt><b>Throws:</b> {{text}}
+
+      <dt><b>Complexity:</b> {{text}}
+
+      <dt><b>Rationale:</b> {{text}}
+    </dl>
+
+    <h2><a name="objects"></a>Objects</h2>
+
+    <p><a name="object-spec"></a>{{Object specifications}}
+
+    <h2><a name="examples"></a>Example(s)</h2>
+
+    <p>{{Example(s)}}
+
+    <p>Revised 
+    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+     05 November, 2001 
+    <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+
+
+    <p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
+    Abrahams</a> 2002. All Rights Reserved.</i>
+

doc/v2/implicit.html

@@ -0,0 +1,149 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+    <meta name="generator" content="HTML Tidy, see www.w3.org">
+    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+    <link rel="stylesheet" type="text/css" href="../boost.css">
+
+    <title>Boost.Python - &lt;boost/python/implicit.hpp&gt;</title>
+
+    <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+      <tr>
+        <td valign="top" width="300">
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+
+        <td valign="top">
+          <h1 align="center">Boost.Python</h1>
+
+          <h2 align="center">Header &lt;boost/python/implicit.hpp&gt;</h2>
+    </table>
+    <hr>
+
+    <h2>Contents</h2>
+
+    <dl function="page-index">
+      <dt><a href="#introduction">Introduction</a>
+
+
+      <dt><a href="#functions">Functions</a>
+
+      <dd>
+        <dl function="page-index">
+          <dt><a href="#implicitly_convertible-spec">Function Template <code>implicitly_convertible</code></a>
+
+        </dl>
+
+      <dt><a href="#examples">Example</a>
+    </dl>
+    <hr>
+
+    <h2><a name="introduction"></a>Introduction</h2>
+
+    <code>implicitly_convertible</code> allows Boost.Python to
+    implicitly take advantage of a C++ implicit or explicit conversion
+    when matching Python objects to C++ argument types.
+
+    <h2><a name="functions"></a>Functions</h2>
+
+    <h3><a name="implicitly_convertible-spec"></a>Function template <code>implicitly_convertible</code></h3>
+<pre>
+template &lt;class Source, class Target&gt;
+void implicitly_convertible();
+</pre>
+
+    <table border="1" summary="implicitly_convertible template parameters">
+      <caption>
+        <b><code>implicitly_convertible</code> template parameters</b><br>
+      </caption>
+      <tr>
+        <th>Parameter
+        <th>Description
+
+      <tr>
+        <td><code>Source</code> 
+        <td>The source type of the implicit conversion
+
+      <tr>
+        <td><code>Target</code> 
+        <td>The target type of the implicit conversion
+      <tr>
+    </table>
+
+    <dl class="function-semantics">
+      <dt><b>Requires:</b> The expression <code>Target(s)</code>,
+      where <code>s</code> is of type <code>Source</code>, is valid.
+
+      <dt><b>Effects:</b> registers an rvalue <code>from_python</code>
+      converter to <code>Target</code> which can succeed for any
+      <code>PyObject*&nbsp;p</code> iff there exists any registered
+      converter which can produce <code>Source</code> rvalues
+
+      <dt><b>Rationale:</b> C++ users expect to be able to take
+      advantage of the same sort of interoperability in Python as they
+      do in C++.
+    </dl>
+
+
+    <h2><a name="examples"></a>Example</h2>
+
+
+<h3>C++ module definition</h3>
+
+<pre>
+#include &lt;boost/python/class.hpp&gt;
+#include &lt;boost/python/implicit.hpp&gt;
+#include &lt;boost/python/module.hpp&gt;
+
+using namespace boost::python;
+
+struct X
+{
+    X(int x) : v(x) {}
+    operator int() { return v; }
+    int v;
+};
+
+int x_value(X const&amp; x)
+{
+    return x.v;
+}
+
+X make_x(int n) { return X(n); }
+
+BOOST_PYTHON_MODULE_INIT(implicit_ext)
+{
+    module(&quot;implicit_ext&quot;)
+        .def(&quot;x_value&quot;, x_value)
+        .def(&quot;make_x&quot;, make_x)
+        .add(
+            class_&lt;X&gt;(&quot;X&quot;)
+            .def_init(args&lt;int&gt;())
+            )
+        ;
+    implicitly_convertible&lt;X,int&gt;();
+    implicitly_convertible&lt;int,X&gt;();
+}
+</pre>
+
+<h3>Python code</h3>
+
+<pre>
+&gt;&gt;&gt; from implicit_ext import *
+&gt;&gt;&gt; x_value(X(42))
+42
+&gt;&gt;&gt; x_value(42)
+42
+&gt;&gt;&gt; x = make_x(X(42))
+&gt;&gt;&gt; x_value(x)
+42
+</pre>
+
+    <p>Revised 
+    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+     08 May, 2002 
+    <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+
+
+    <p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
+    Abrahams</a> 2002. All Rights Reserved.</i>
+

doc/v2/index.html

@@ -0,0 +1,43 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+<link rel="stylesheet" type="text/css" href="../boost.css">
+<title>Boost.Python</title>
+</head>
+<body link="#0000ff" vlink="#800080">
+<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+  <tr> 
+    <td valign="top" width="300"> 
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+    </td>
+    <td valign="top"> 
+      <h1 align="center">Boost.Python</h1>
+      <h2 align="center">Index</h2>
+    </td>
+  </tr>
+</table>
+<hr>
+<h2>Contents</h2>
+<dl class="index">
+  <dt><a href="overview.html">Overview</a></dt>
+  <dt><a href="reference.html">Reference</a></dt>
+  <dt><a href="configuration.html">Configuration Information</a></dt>
+  <dt><a href="rationale.html">Rationale</a></dt>
+  <dt><a href="definitions.html">Definitions</a></dt>
+  <dt><a href="faq.html">Frequently Asked Questions (FAQs)</a></dt>
+  <dt><a href="progress_reports.html">Progress Reports</a></dt>
+  <dt><a href="bibliography.html">Bibliography</a></dt>
+  <dt><a href="acknowledgments.html">Acknowledgments</a></dt>
+</dl>
+<hr>
+<p>Revised 
+  <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+  05 November, 2002 
+  <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+</p>
+<p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave Abrahams</a> 
+  2002. All Rights Reserved.</i></p>
+</body>
+</html>

doc/v2/instance_holder.html

@@ -0,0 +1,209 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+
+    <meta name="generator" content="HTML Tidy, see www.w3.org">
+    <meta http-equiv="Content-Type" content=
+    "text/html; charset=iso-8859-1">
+    <link rel="stylesheet" type="text/css" href="../boost.css">
+
+    <title>Boost.Python - &lt;boost/python/instance_holder.hpp&gt;</title>
+<style type="text/css">
+ p.c4 {font-style: italic}
+ span.c3 {color: #ff0000}
+ h2.c2 {text-align: center}
+ h1.c1 {text-align: center}
+</style>
+
+    <table border="0" cellpadding="7" cellspacing="0" width="100%"
+    summary="header">
+      <tr>
+        <td valign="top" width="300">
+          <h3><a href="../../../../index.htm"><img height="86" width= 
+          "277" alt="C++ Boost" src="../../../../c++boost.gif" border=
+          "0"></a></h3>
+
+        <td valign="top">
+          <h1 class="c1">Boost.Python</h1>
+
+          <h2 class="c2">Header &lt;boost/python/instance_holder.hpp&gt;</h2>
+    </table>
+    <hr>
+
+    <h2>Contents</h2>
+
+    <dl class="page-index">
+      <dt><a href="#introduction">Introduction</a>
+
+      <dt><a href="#classes">Classes</a>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#instance_holder-spec">Class
+          <code>instance_holder</code></a>
+
+          <dd>
+            <dl class="page-index">
+              <dt><a href="#instance_holder-spec-synopsis">Class
+              <code>instance_holder</code> synopsis</a>
+
+              <dt><a href="#instance_holder-spec-ctors">Class
+              <code>instance_holder</code> destructor</a>
+
+              <dt><a href="#instance_holder-spec-modifiers">Class
+              <code>instance_holder</code> modifier functions</a>
+
+              <dt><a href="#instance_holder-spec-observers">Class
+              <code>instance_holder</code> observer functions</a>
+            </dl>
+        </dl>
+
+      <dt><a href="#examples">Example</a>
+    </dl>
+    <hr>
+
+    <h2><a name="introduction"></a>Introduction</h2>
+
+    <p><code>&lt;boost/python/instance_holder.hpp&gt;</code> provides
+    <code>class&nbsp;instance_holder</code>, the base class for types
+    which hold C++ instances of wrapped classes.
+
+    <h2><a name="classes"></a>Classes</h2>
+
+    <h3><a name="instance_holder-spec"></a>Class <code>instance_holder</code></h3>
+
+    <p><code>instance_holder</code> is an abstract base class whose
+    concrete derived classes hold C++ class instances within their
+    Python object wrappers. To allow multiple inheritance in Python
+    from C++ class wrappers, each such Python object contains a chain
+    of <code>instance_holder</code>s. When an <code>__init__</code>
+    function for a wrapped C++ class is invoked, a new
+    <code>instance_holder</code> instance is created and installed in
+    the Python object using its <code><a
+    href="#instance_holder-spec-modifiers">install</a></code>()
+    function. Each concrete class derived from
+    <code>instance_holder</code> must provide a <code><a
+    href="#instance_holder-spec-observers">holds</a>()</code>
+    implementation which allows Boost.Python to query it for the
+    type(s) it is holding. In order to support the held type's wrapped
+    constructor(s), the class must also provide constructors that can
+    accept an initial <code>PyObject*</code> argument referring to the
+    owning Python object, and which forward the rest of their
+    arguments to the constructor of the held type. The initial
+    argument is needed to enable virtual function overriding in
+    Python, and may be ignored, depending on the specific
+    <code>instance_holder</code> subclass.
+
+    <h4><a name="instance_holder-spec-synopsis"></a>Class instance_holder
+    synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+  class instance_holder : <a href="../../../utility/utility.htm#Class noncopyable">noncopyable</a>
+  {
+   public:
+      // destructor
+      virtual ~instance_holder();
+
+      // instance_holder modifiers
+      void install(PyObject* inst) throw();
+
+      // instance_holder observers
+      virtual void* holds(type_info) = 0;
+  };
+}}
+</pre>
+
+    <h4><a name="instance_holder-spec-ctors">Class <code>instance_holder</code>
+    destructor</a></h4>
+<pre>
+virtual ~instance_holder();
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Effects:</b> destroys the object
+    </dl>
+
+    <h4><a name="instance_holder-spec-modifiers">Class
+    <code>instance_holder</code> modifiers</a></h4>
+<pre>
+void install(PyObject* inst) throw();
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Requires:</b> <code>inst</code> is a Python instance of a
+      wrapped C++ class type, or is a type derived from a wrapped C++
+      class type.
+      <dt><b>Effects:</b> installs the new instance at the head of the
+      Python object's chain of held instances.
+      <dt><b>Throws:</b> nothing
+    </dl>
+
+    <h4><a name="instance_holder-spec-observers">Class <code>instance_holder</code>
+    observers</a></h4>
+<pre>
+virtual void* holds(type_info x) = 0;
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Returns:</b> A pointer to an object of the type described
+      by <code>x</code> if <code>*this</code> contains such an object,
+      0 otherwise.
+    </dl>
+
+    <h2><a name="examples"></a>Example</h2> 
+
+The following is a simplified version of the instance holder template
+used by Boost.Python to wrap classes held by smart pointers:
+<pre>
+template &lt;class SmartPtr, class Value&gt;
+struct pointer_holder : instance_holder
+{
+   // construct from the SmartPtr type
+   pointer_holder(SmartPtr p)
+       :m_p(p)
+
+   // Forwarding constructors for the held type
+   pointer_holder(PyObject*)
+       :m_p(new Value())
+   {
+   }
+
+   template&lt;class A0&gt;
+   pointer_holder(PyObject*,A0 a0)
+       :m_p(new Value(a0))
+   {
+   }
+
+   template&lt;class A0,class A1&gt;
+   pointer_holder(PyObject*,A0 a0,A1 a1)
+       :m_p(new Value(a0,a1))
+   {
+   }
+   ...
+
+ private: // required holder implementation
+   void* holds(type_info dst_t)
+   {
+       // holds an instance of the SmartPtr type...
+       if (dst_t == python::type_id&lt;SmartPtr&gt;())
+           return &amp;this-&gt;m_p;
+
+       // ...and an instance of the SmartPtr's element_type, if the
+       // pointer is non-null
+       return python::type_id&lt;Value&gt;() == dst_t ? &amp;*this-&gt;m_p : 0;
+   }
+
+ private: // data members
+   SmartPtr m_p;
+};
+</pre>
+
+    <p>Revised 
+    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+     29 May, 2002 
+    <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+
+
+    <p class="c4">&copy; Copyright <a href= 
+    "../../../../people/dave_abrahams.htm">Dave Abrahams</a> 2002. All
+    Rights Reserved.
+

doc/v2/iterator.html

@@ -0,0 +1,364 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+    <meta name="generator" content="HTML Tidy, see www.w3.org">
+    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+    <link rel="stylesheet" type="text/css" href="../boost.css">
+
+    <title>Boost.Python - &lt;boost/python/iterator.hpp&gt;</title>
+
+    <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+      <tr>
+        <td valign="top" width="300">
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+
+        <td valign="top">
+          <h1 align="center">Boost.Python</h1>
+
+          <h2 align="center">Header &lt;boost/python/iterator.hpp&gt;</h2>
+    </table>
+    <hr>
+
+    <h2>Contents</h2>
+
+    <dl class="page-index">
+      <dt><a href="#introduction">Introduction</a>
+
+      <dt><a href="#classes">Classes</a>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#iterator-spec">Class template <code>iterator</code></a>
+
+          <dd>
+            <dl class="page-index">
+              <dt><a href="#iterator-spec-synopsis">Class
+              <code>iterator</code> synopsis</a>
+
+              <dt><a href="#iterator-spec-ctors">Class template <code>iterator</code>
+              constructor</a>
+            </dl>
+         </dl>
+
+        <dl class="page-index">
+          <dt><a href="#iterators-spec">Class template <code>iterators</code></a>
+
+          <dd>
+            <dl class="page-index">
+              <dt><a href="#iterators-spec-synopsis">Class
+              <code>iterators</code> synopsis</a>
+              <dt><a href="#iterators-spec-types">Class template
+              <code>iterators</code> nested types</a>
+              <dt><a href="#iterators-spec-statics">Class template
+              <code>iterators</code> static functions</a>
+            </dl>
+        </dl>
+
+      <dt><a href="#functions">Functions</a>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#range-spec">range</a>
+        </dl>
+
+      <dt><a href="#examples">Examples</a>
+    </dl>
+    <hr>
+
+    <h2><a name="introduction"></a>Introduction</h2>
+
+    <p><code>&lt;boost/python/iterator.hpp&gt;</code> provides types
+    and functions for creating <a
+    href="http://www.python.org/doc/current/lib/typeiter.html">Python
+    iterators</a> from <a
+    href="http://www.sgi.com/tech/stl/Container.html">C++
+    Containers</a> and <a
+    href="http://www.sgi.com/tech/stl/Iterators.html">Iterators</a>. Note
+    that if your <code>class_</code> supports random-access iterators,
+    implementing 
+    <code><a
+    href="http://www.python.org/doc/current/ref/sequence-types.html#l2h-128">__getitem__</a></code>
+    (also known as the Sequence Protocol) may serve you better than
+    using this facility: Python will automatically create an iterator
+    type for you (see <a
+    href="http://www.python.org/doc/current/lib/built-in-funcs.html#l2h-35">iter()</a>),
+    and each access can be range-checked, leaving no possiblity of
+    accessing through an invalidated C++ iterator.
+
+    <h2><a name="classes"></a>Classes</h2>
+
+    <h3><a name="iterator-spec"></a>Class Template <code>iterator</code></h3>
+
+    <p>Instances of <code>iterator&lt;C,P&gt;</code> hold a reference
+    to a callable Python object which, when invoked from Python,
+    expects a single argument <code>c</code> convertible to
+    <code>C</code> and creates a Python iterator that traverses
+    [<code>c.begin()</code>,
+    <code>c.end()</code>). The optional <a
+    href="CallPolicies.html">CallPolicies</a>
+    <code>P</code> can be used to control how elements are returned
+    during iteration.
+
+    <p>In the table below, <code><b>c</b></code> is an instance of <code>Container</code>.
+
+    <table border="1" summary="iterator template parameters">
+      <tr>
+        <th>Template Parameter
+
+        <th>Requirements
+
+        <th>Semantics
+
+        <th>Default
+
+      <tr>
+        <td><code>Container</code> 
+
+        <td>[c.begin(),c.end()) is a valid <a
+        href="http://www.sgi.com/tech/stl/Iterators.html">Iterator
+        range</a>.
+
+        <td>The result will convert its argument to
+        <code>c</code> and call
+        <code>c.begin()</code> and <code>c.end()</code> to acquire
+        iterators. To invoke <code>Container</code>'s
+        <code>const</code> <code>begin()</code> and <code>end()</code>
+        functions, make it <code>const</code>.
+
+
+      <tr>
+        <td><code>NextPolicies</code> 
+
+        <td>A default-constructible model of <a
+        href="CallPolicies.html#CallPolicies-concept">CallPolicies</a>.
+
+        <td>Applied to the resulting iterators' <code>next()</code> method.
+
+        <td>An unspecified model of <a
+        href="CallPolicies.html#CallPolicies-concept">CallPolicies</a>
+        which always makes a copy of the
+        result of deferencing the underlying C++ iterator
+
+    </table>
+
+    <h4><a name="iterator-spec-synopsis"></a>Class Template iterator synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+  template &lt;class Container
+             , class NextPolicies = <i>unspecified</i>&gt;
+  struct iterator : reference&lt;PyObject*&gt;
+  {
+      iterator();
+  };
+}}
+</pre>
+    <h4><a name="iterator-spec-constructors"></a>Class Template
+    iterator constructor</h4>
+
+<pre>
+iterator()
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Effects:</b> Initializes its base class with the result
+      of:
+<pre>
+range&lt;NextPolicies&gt;(&amp;iterators&lt;Container&gt;::begin, &amp;iterators&lt;Container&gt;::end)
+</pre>
+
+      <dt><b>Postconditions:</b> <code>this-&gt;get()</code> points to
+      a Python callable object which creates a Python iterator as
+      described above.
+
+      <dt><b>Rationale:</b> Provides an easy way to create iterators
+      for the common case where a C++ class being wrapped provides
+      <code>begin()</code> and <code>end()</code>.
+    </dl>
+
+<!-- -->
+
+    <h3><a name="iterators-spec"></a>Class Template <code>iterators</code></h3>
+
+    <p>A utility class template which provides a way to reliably call
+    its argument's <code>begin()</code> and <code>end()</code> member
+    functions. Note that there is no portable way to take the address
+    of a member function of a C++ standard library container, so
+    <code>iterators&lt;&gt;</code> can be particularly helpful when
+    wrapping them.
+    
+
+    <p>In the table below, <code><b>x</b></code> is an instance of <code>C</code>.
+
+    <table border="1" summary="iterator template parameters">
+      <tr>
+        <th>Required Valid Expression
+
+        <th>Type
+
+      <tr>
+        <td><code>x.begin()</code>
+        
+        <td>Convertible to <code>C::const_iterator</code> if <code>C</code> is a
+        <code>const</code> type; convertible to <code>C::iterator</code> otherwise.
+
+      <tr>
+        <td><code>x.end()</code>
+        
+        <td>Convertible to <code>C::const_iterator</code> if <code>C</code> is a
+        <code>const</code> type; convertible to <code>C::iterator</code> otherwise.
+
+    </table>
+
+    <h4><a name="iterators-spec-synopsis"></a>Class Template iterators synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+  template &lt;class C&gt;
+  struct iterators
+  {
+      typedef typename C::[const_]iterator iterator;
+      static iterator begin(C&amp; x);
+      static iterator end(C&amp; x);
+  };
+}}
+
+</pre>
+    <h4><a name="iterators-spec-types"></a>Class Template
+    iterators nested types</h4>
+
+If C is a <code>const</code> type,
+<pre>
+typedef typename C::const_iterator iterator;
+</pre>
+Otherwise:
+<pre>
+typedef typename C::iterator iterator;
+</pre>
+
+    <h4><a name="iterators-spec-statics"></a>Class Template
+    iterators static functions</h4>
+
+<pre>
+static iterator begin(C&amp;);
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Returns:</b> <code>x.begin()</code>
+    </dl>
+
+<pre>
+static iterator end(C&amp;);
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Returns:</b> <code>x.end()</code>
+    </dl>
+
+<!-- -->
+
+    <h2><a name="functions"></a>Functions</h2>
+<pre>
+<a name=
+"range-spec">template</a> &lt;class NextPolicies, class Target, class Accessor1, class Accessor2&gt;
+reference&lt;PyObject*&gt range(Accessor1 start, Accessor2 finish);
+
+template &lt;class NextPolicies, class Accessor1, class Accessor2&gt;
+reference&lt;PyObject*&gt range(Accessor1 start, Accessor2 finish);
+
+template &lt;class Accessor1, class Accessor2&gt;
+reference&lt;PyObject*&gt range(Accessor1 start, Accessor2 finish);
+</pre>
+
+    <dl class="range-semantics">
+      <dt><b>Requires:</b> <code>NextPolicies</code> is a
+        default-constructible model of <a
+        href="CallPolicies.html#CallPolicies-concept">CallPolicies</a>.
+
+      <dt><b>Effects:</b> <dl>
+
+The first form creates a Python callable
+      object which, when invoked, converts its argument to a
+      <code>Target</code> object
+      <code>x</code>, and creates a Python iterator which traverses
+       [<code><a
+       href="../../../bind/bind.html">bind</a>(start,_1)(x)</code>,&nbsp;<code><a
+       href="../../../bind/bind.html">bind</a>(finish,_1)(x)</code>),
+       applying <code>NextPolicies</code> to the iterator's
+       <code>next()</code> function. 
+<dd>
+       <dt>The second form is identical to
+       the first, except that <code>Target</code> is deduced from
+       <code>Accessor1</code> as follows:
+       <ol>
+       <li>If <code>Accessor1</code> is a function type,
+       <code>Target</code> is the type of its first argument.
+       <li>If <code>Accessor1</code> is a data member pointer of the
+       form <code>R&nbsp;(T::*)</code>, <code>Target</code> is
+       identical to <code>T</code>.
+       <li>If <code>Accessor1</code> is a member function pointer of
+       the form
+       <code>R&nbsp;(T::*)(</code><i>arguments...</i><code>)</code>&nbsp;<i>cv-opt</i>,
+       where <i>cv-opt</i> is an optional <code>cv-qualifier</code>,
+       <code>Target</code> is identical to <code>T</code>.
+        </ol>
+<dd>
+
+       <dt>The third form is identical to the second, except that
+       <code>NextPolicies</code> is an unspecified model of <a
+        href="CallPolicies.html#CallPolicies-concept">CallPolicies</a>
+        which always makes a copy of the
+        result of deferencing the underlying C++ iterator<dd>
+</dl>
+
+
+      <dt><b>Rationale:</b> The use of <code><a
+      href="../../../bind/bind.html">boost::bind</a>()</code> allows
+      C++ iterators to be accessed through functions, member functions
+      or data member pointers. Customization of
+      <code>NextPolicies</code> (e.g. using <code><a
+      href="return_internal_reference.html#return_internal_reference-spec"
+      >return_internal_reference</a></code>) is useful when it is
+      expensive to copy sequence elements of a wrapped class
+      type. Customization of <code>Target</code> is useful when
+      <code>Accessor1</code> is a function object, or when a base
+      class of the intended target type would otherwise be deduced.
+    </dl>
+
+    <h2><a name="examples"></a>Examples</h2>
+
+<pre>
+#include &lt;boost/python/module.hpp&gt;
+#include &lt;boost/python/class.hpp&gt;
+#include &lt;boost/python/return_internal_reference.hpp&gt;
+#include &lt;vector&gt;
+
+using namespace boost::python;
+BOOST_PYTHON_MODULE_INIT(demo)
+{
+   module(&quot;demo&quot;)
+      .add(
+         class_&lt;std::vector&lt;double&gt; &gt;(&quot;dvec&quot;)
+            .def(&quot;__iter__&quot;, iterator&lt;std::vector&lt;double&gt; &gt;())
+            ...
+         )
+      ;
+}
+</pre>
+
+A more comprehensive example can be found in:
+<code><dl>
+<dt><a href="../../test/iterator.cpp">libs/python/test/iterator.cpp</a><dd>
+<dt><a href="../../test/input_iterator.cpp">libs/python/test/input_iterator.cpp</a><dd>
+<dt><a href="../../test/iterator.py">libs/python/test/input_iterator.py</a><dd>
+</code>
+
+    <p>Revised 
+    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+     17 May, 2002
+    <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+
+
+    <p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
+    Abrahams</a> 2002. All Rights Reserved.</i>
+

doc/v2/lvalue_from_pytype.html

@@ -0,0 +1,283 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+    <meta name="generator" content="HTML Tidy, see www.w3.org">
+    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+    <link rel="stylesheet" type="text/css" href="../boost.css">
+
+    <title>Boost.Python - &lt;boost/python/lvalue_from_python.hpp&gt;</title>
+
+    <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+      <tr>
+        <td valign="top" width="300">
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+
+        <td valign="top">
+          <h1 align="center">Boost.Python</h1>
+
+          <h2 align="center">Header &lt;boost/python/lvalue_from_pytype.hpp&gt;</h2>
+    </table>
+    <hr>
+
+    <h2>Contents</h2>
+
+    <dl class="page-index">
+      <dt><a href="#introduction">Introduction</a>
+
+
+      <dt><a href="#classes">Classes</a>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#lvalue_from_pytype-spec">Class Template <code>lvalue_from_pytype</code></a>
+
+          <dd>
+            <dl class="page-index">
+
+              <dt><a href="#lvalue_from_pytype-spec-synopsis">Class Template
+              <code>lvalue_from_pytype</code> synopsis</a>
+
+              <dt><a href="#lvalue_from_pytype-spec-ctors">Class Template
+              <code>lvalue_from_pytype</code> constructor</a>
+            </dl>
+        </dl>
+
+        <dl class="page-index">
+          <dt><a href="#extract_identity-spec">Class Template <code>extract_identity</code></a>
+          <dd>
+            <dl class="page-index">
+
+              <dt><a href="#extract_identity-spec-synopsis">Class Template
+              <code>extract_identity</code> synopsis</a>
+
+              <dt><a href="#extract_identity-spec-statics">Class Template
+              <code>extract_identity</code> static functions</a>
+            </dl>
+          <dt><a href="#extract_member-spec">Class Template <code>extract_member</code></a>
+          <dd>
+            <dl class="page-index">
+
+              <dt><a href="#extract_member-spec-synopsis">Class Template
+              <code>extract_member</code> synopsis</a>
+
+              <dt><a href="#extract_member-spec-statics">Class Template
+              <code>extract_member</code> static functions</a>
+            </dl>
+        </dl>
+
+      <dt><a href="#examples">Example</a>
+    </dl>
+    <hr>
+
+    <h2><a name="introduction"></a>Introduction</h2>
+
+    <code>&lt;boost/python/lvalue_from_pytype.hpp&gt;</code> supplies
+    a facility for extracting C++ objects from within Python instances
+    of a given type. This is typically useful for dealing with
+    &quot;traditional&quot; Python extension types.
+
+    <h2><a name="classes"></a>Classes</h2>
+
+    <h3><a name="lvalue_from_pytype-spec"></a>Class template <code>lvalue_from_pytype</code></h3>
+
+    <p>Class template <code>lvalue_from_pytype</code> will register
+    from_python converters which, given an object of the given Python
+    type, can extract references and pointers to a particular C++
+    type. Its template arguments are:
+
+    <p>
+
+
+    <table border="1" summary="lvalue_from_pytype template parameters">
+      <caption>
+        <b><code>lvalue_from_pytype</code> Requirements</b><br>
+
+        In the table below, <b><code>x</code></b> denotes an object of type <code>PythonObject&amp;</code>
+
+      </caption>
+      <tr>
+        <th>Parameter
+        
+        <th>Requirements
+
+        <th>Semantics
+
+      <tr>
+        <td><code>Extractor</code> 
+
+        <td>a model of <a
+        href="Extractor.html#Extractor-concept">Extractor</a> whose
+        execute function returns a reference type.
+
+        <td>Extracts the lvalue from the Python object once its type has been confirmed
+
+      <tr>
+        <td><code>python_type</code> 
+
+        <td>A compile-time constant <code><a
+        href="http://www.python.org/doc/2.2/ext/dnt-type-methods.html">PyTypeObject</a>*</code>
+
+        <td>The Python type of instances convertible by this
+        converter. Python subtypes are also convertible.
+
+    </table>
+
+    <h4><a name="lvalue_from_pytype-spec-synopsis"></a>Class template <code>lvalue_from_pytype</code> synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+   template &lt;class Extractor, PyTypeObject const* python_type&gt;
+   struct lvalue_from_pytype
+   {
+       lvalue_from_pytype();
+   };
+}}
+</pre>
+
+    <h4><a name="lvalue_from_pytype-spec-ctors"></a>Class template <code>lvalue_from_pytype</code> constructor</h4>
+<pre>
+lvalue_from_pytype();
+</pre>
+
+    <dl class="function-semantics">
+
+      <dt><b>Effects:</b> Registers converters which can convert
+      Python objects of the given type to lvalues of the type returned
+      by <code>Extractor::execute</code>.
+
+    </dl>
+
+    <h3><a name="extract_identity-spec"></a>Class template <code>extract_identity</code></h3>
+
+    <p><code>extract_identity</code> is a model of <a
+    href="Extractor.html#Extractor-concept">Extractor</a> which can be
+    used in the common case where the C++ type to be extracted is the
+    same as the Python object type.
+
+    <h4><a name="extract_identity-spec-synopsis"></a>Class template
+    <code>extract_identity</code> synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+   template &lt;class InstanceType&gt;
+   struct extract_identity
+   {
+      static InstanceType&amp; execute(InstanceType&amp; c);
+   };
+}}
+</pre>
+
+    <h4><a name="extract_identity-spec-statics"></a>Class template <code>extract_identity</code> static functions</h4>
+<pre>
+InstanceType&amp; execute(InstanceType&amp; c);
+</pre>
+
+    <dl class="function-semantics">
+
+      <dt><b>Returns:</b> <code>c</code>
+
+    </dl>
+
+
+    <h3><a name="extract_member-spec"></a>Class template <code>extract_member</code></h3>
+
+    <p><code>extract_member</code> is a model of <a
+    href="Extractor.html#Extractor-concept">Extractor</a> which can be
+    used in the common case in the common case where the C++
+    type to be extracted is a member of the Python object.
+
+    <h4><a name="extract_member-spec-synopsis"></a>Class template <code>extract_member</code> synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+   template &lt;class InstanceType, class MemberType, MemberType (InstanceType::*member)&gt;
+   struct extract_member
+   {
+      static MemberType&amp; execute(InstanceType&amp; c);
+   };
+}}
+</pre>
+
+    <h4><a name="extract_member-spec-statics"></a>Class template <code>extract_member</code> static functions</h4>
+<pre>
+static MemberType&amp; execute(InstanceType&amp; c);
+</pre>
+
+    <dl class="function-semantics">
+
+      <dt><b>Returns:</b> <code>c.*member</code>
+
+    </dl>
+
+    <h2><a name="examples"></a>Example</h2>
+
+This example presumes that someone has implemented the standard <a
+href="http://www.python.org/doc/2.2/ext/dnt-basics.html">noddy
+example module</a> from the Python documentation, and we want to build
+a module which manipulates <code>Noddy</code>s. Since
+<code>noddy_NoddyObject</code> is so simple that it carries no
+interesting information, the example is a bit contrived: it assumes
+you want to keep track of one particular object for some reason. This
+module would have to be dynamically linked to the module which defines
+<code>noddy_NoddyType</code>.
+
+<h3>C++ module definition</h3>
+
+<pre>
+#include &lt;boost/python/reference.hpp&gt;
+#include &lt;boost/python/module.hpp&gt;
+
+// definition lifted from the Python docs
+typedef struct {
+   PyObject_HEAD
+} noddy_NoddyObject;
+
+using namespace boost::python;
+static reference&lt;PyObject&gt; cache;
+
+bool is_cached(noddy_NoddyObject* x)
+{
+   return x == cache.get();
+}
+
+void set_cache(noddy_NoddyObject* x)
+{
+   cache.reset((PyObject*)x, ref::increment_count);
+}
+
+BOOST_PYTHON_MODULE_INIT(noddy_cache)
+{
+   module noddy_cache(&quot;noddy_cache&quot;)
+      .def(&quot;is_cached&quot;, is_cached)
+      .def(&quot;set_cache&quot;, set_cache)
+      ;
+
+   // register Noddy lvalue converter
+   lvalue_from_pytype&lt;extract_identity&lt;noddy_NoddyObject&gt;,&amp;noddy_NoddyType&gt;();
+}
+</pre>
+
+<h3>Python code</h3>
+
+<pre>
+&gt;&gt;&gt; import noddy
+&gt;&gt;&gt; n = noddy.new_noddy()
+&gt;&gt;&gt; import noddy_cache
+&gt;&gt;&gt; noddy_cache.is_cached(n)
+0
+&gt;&gt;&gt; noddy_cache.set_cache(n)
+&gt;&gt;&gt; noddy_cache.is_cached(n)
+1
+&gt;&gt;&gt; noddy_cache.is_cached(noddy.new_noddy())
+0
+</pre>
+
+    <p>Revised 
+    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+     05 November, 2001 
+    <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+
+
+    <p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
+    Abrahams</a> 2002. All Rights Reserved.</i>
+

doc/v2/make_function.html

@@ -0,0 +1,155 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+    <meta name="generator" content="HTML Tidy, see www.w3.org">
+    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+    <link rel="stylesheet" type="text/css" href="../boost.css">
+
+    <title>Boost.Python - &lt;boost/python/make_function.hpp&gt;</title>
+
+    <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+      <tr>
+        <td valign="top" width="300">
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+
+        <td valign="top">
+          <h1 align="center">Boost.Python</h1>
+
+          <h2 align="center">Header &lt;boost/python/make_function.hpp&gt;</h2>
+    </table>
+    <hr>
+
+    <h2>Contents</h2>
+
+    <dl class="page-index">
+      <dt><a href="#introduction">Introduction</a>
+
+      <dt><a href="#functions">Functions</a>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#make_function-spec">make_function</a>
+
+          <dt><a href="#make_constructor-spec">make_constructor</a>
+        </dl>
+
+      <dt><a href="#examples">Example</a>
+    </dl>
+    <hr>
+
+    <h2><a name="introduction"></a>Introduction</h2>
+
+    <p><code><a href="#make_function-spec">make_function</a>()</code> and
+    <code><a href="#make_constructor-spec">make_constructor</a>()</code> are
+    the functions used internally by <code>class_&lt;&gt;::<a href=
+    "class.html#class_-spec-modifiers">def</a></code>, <code>class_&lt;&gt;::<a
+    href="module.html#module-spec-modifiers">def</a></code>, and
+    <code>class_&lt;&gt;::<a href=
+    "class.html#class_-spec-modifiers">def_init</a></code> to produce Python
+    callable objects which wrap C++ functions and member functions.
+
+    <h2><a name="functions"></a>Functions</h2>
+<pre>
+<a name="make_function-spec">template &lt;class F&gt;</a>
+objects::function* make_function(F f)
+
+template &lt;class F, class Policies&gt;
+objects::function* make_function(F f, Policies const&amp; policies)
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Requires:</b> <code>F</code> is a function pointer or member
+      function pointer type
+
+      <dt><b>Effects:</b> Creates a Python callable object which, when called
+      from Python, converts its arguments to C++ and calls <code>f</code>. If
+      <code>F</code> is a pointer-to-member-function type, the target object of
+      the function call (<code>*this</code>) will be taken from the first
+      Python argument, and subsequent Python arguments will be used as the
+      arguments to <code>f</code>. If <code>policies</code> are supplied, it
+      must be a model of <a href="CallPolicies.html">CallPolicies</a>, and will
+      be applied to the function as described <a href=
+      "CallPolicies.html">here</a>.
+
+      <dt><b>Returns:</b> A pointer convertible to <code>PyObject*</code> which
+      refers to the new Python callable object.
+    </dl>
+<pre>
+<a name=
+"make_constructor-spec">template &lt;class T, class ArgList, class Generator&gt;
+objects::function* make_constructor();</a>
+
+template &lt;class ArgList, class Generator, class Policies&gt;
+objects::function* make_constructor(Policies const&amp; policies)
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Requires:</b> <code>T</code> is a class
+      type. <code>Policies</code> is a model of <a
+      href="CallPolicies.html">CallPolicies</a>. <code>ArgList</code>
+      is an <a href="../../../mpl/doc/Sequences.html">MPL sequence</a>
+      of C++ argument types (<i>A1, A2,... AN</i>) such that if
+      <code>a1, a2</code>... <code>aN</code> are objects of type
+      <i>A1, A2,... AN</i> respectively, the expression <code>new
+      Generator::apply&lt;T&gt;::type(a1, a2</code>... <code>aN</code>) is
+      valid. Generator is a model of <a href=
+      "HolderGenerator.html">HolderGenerator</a>.
+
+      <dt><b>Effects:</b> Creates a Python callable object which, when called
+      from Python, expects its first argument to be a Boost.Python extension
+      class object. It converts its remaining its arguments to C++ and passes
+      them to the constructor of a dynamically-allocated
+      <code>Generator::apply&lt;T&gt;::type</code> object, which is
+      then installed in the extension class object. In the second
+      form, the <code>policies</code> are applied to the arguments and
+      result (<a
+      href="http://www.python.org/doc/current/lib/bltin-null-object.html">None</a>)
+      of the Python callable object
+
+      <dt><b>Returns:</b> The new Python callable object
+    </dl>
+
+    <h2><a name="examples"></a>Example</h2>
+
+    <p>C++ function exposed below returns a callable object wrapping one of two
+    functions.
+<pre>
+#include &lt;boost/python/make_function.hpp&gt;
+#include &lt;boost/python/module.hpp&gt;
+
+char const* foo() { return "foo"; }
+char const* bar() { return "bar"; }
+
+PyObject* choose_function(bool selector)
+{
+    if (selector)
+        return boost::python::make_function(foo);
+    else
+        return boost::python::make_function(bar);
+}
+
+BOOST_PYTHON_MODULE_INIT(make_function_test)
+{
+    module("make_function_test")
+        .def("choose_function", choose_function);
+}
+</pre>
+    It can be used this way in Python: 
+<pre>
+&gt;&gt;&gt; from make_function_test import *
+&gt;&gt;&gt; f = choose_function(1)
+&gt;&gt;&gt; g = choose_function(0)
+&gt;&gt;&gt; f()
+'foo'
+&gt;&gt;&gt; g()
+'bar'
+</pre>
+
+    <p>
+    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+    14 February 2002 <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+
+
+    <p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
+    Abrahams</a> 2002. All Rights Reserved.</i>
+

doc/v2/manage_new_object.html

@@ -0,0 +1,130 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+    <meta name="generator" content="HTML Tidy, see www.w3.org">
+    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+    <link rel="stylesheet" type="text/css" href="../boost.css">
+
+    <title>Boost.Python - &lt;boost/python/manage_new_object.hpp&gt;</title>
+
+    <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+      <tr>
+        <td valign="top" width="300">
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+
+        <td valign="top">
+          <h1 align="center">Boost.Python</h1>
+
+          <h2 align="center">Header
+          &lt;boost/python/manage_new_object.hpp&gt;</h2>
+    </table>
+    <hr>
+
+    <h2>Contents</h2>
+
+    <dl class="page-index">
+      <dt><a href="#classes">Classes</a>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#manage_new_object-spec">Class
+          <code>manage_new_object</code></a>
+
+          <dd>
+            <dl class="page-index">
+              <dt><a href="#manage_new_object-spec-synopsis">Class
+              <code>manage_new_object</code> synopsis</a>
+
+              <dt><a href="#manage_new_object-spec-metafunctions">Class
+              <code>manage_new_object</code> metafunctions</a>
+            </dl>
+        </dl>
+
+      <dt><a href="#examples">Example</a>
+    </dl>
+    <hr>
+
+    <h2><a name="classes"></a>Classes</h2>
+
+    <h3><a name="manage_new_object-spec"></a>Class
+    <code>manage_new_object</code></h3>
+
+    <p><code>manage_new_object</code> is a model of <a href=
+    "ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a> which can be
+    used to wrap C++ functions which return a pointer to an object allocated
+    with a <i>new-expression</i>, and expect the caller to take responsibility
+    for deleting that object.
+
+    <h4><a name="manage_new_object-spec-synopsis"></a>Class
+    <code>manage_new_object</code> synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+    struct manage_new_object
+    {
+        template &lt;class T&gt; struct apply;
+    };
+}}
+</pre>
+
+    <h4><a name="manage_new_object-spec-metafunctions"></a>Class
+    <code>manage_new_object</code> metafunctions</h4>
+<pre>
+template &lt;class T&gt; struct apply
+</pre>
+
+    <dl class="metafunction-semantics">
+      <dt><b>Requires:</b> <code>T</code> is <code>U*</code> for some
+      <code>U</code>.
+
+      <dt><b>Returns:</b> <code>typedef <a href=
+      "to_python_indirect.html#to_python_indirect-spec">to_python_indirect</a>&lt;T&gt;
+      type;</code>
+    </dl>
+
+    <h2><a name="examples"></a>Example</h2>
+
+    <p>In C++:
+<pre>
+#include &lt;boost/python/module.hpp&gt;
+#include &lt;boost/python/class.hpp&gt;
+#include &lt;boost/python/manage_new_object.hpp&gt;
+#include &lt;boost/python/return_value_policy.hpp&gt;
+
+
+struct Foo {
+   Foo(int x) : x(x){}
+   int get_x() { return x; }
+   int x;
+};
+
+Foo* make_foo(int x) { return new Foo(x); }
+
+// Wrapper code
+using namespace boost::python;
+BOOST_PYTHON_MODULE_INIT(my_module)
+{
+   module("my_module")
+      .def("make_foo", make_foo, return_value_policy&lt;manage_new_object&gt;)
+      .add(
+         class_&lt;Foo&gt;()
+            .def("get_x", &amp;Foo::get_x)
+         )
+}
+</pre>
+In Python: 
+<pre>
+&gt;&gt;&gt; from my_module import *
+&gt;&gt;&gt; f = make_foo(3)     # create a Foo object
+&gt;&gt;&gt; f.get_x()
+3
+</pre>
+
+    <p>Revised 
+    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+     14 February 2002 <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+
+
+    <p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
+    Abrahams</a> 2002. All Rights Reserved.</i>
+

doc/v2/module.html

@@ -0,0 +1,263 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+    <meta name="generator" content="HTML Tidy, see www.w3.org">
+    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+    <link rel="stylesheet" type="text/css" href="../boost.css">
+
+    <title>Boost.Python - &lt;boost/python/module.hpp&gt;</title>
+
+    <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+      <tr>
+        <td valign="top" width="300">
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+
+        <td valign="top">
+          <h1 align="center">Boost.Python</h1>
+
+          <h2 align="center">Header &lt;boost/python/module.hpp&gt;</h2>
+    </table>
+    <hr>
+
+    <h2>Contents</h2>
+
+    <dl class="page-index">
+      <dt><a href="#introduction">Introduction</a>
+
+      <dt><a href="#macros">Macros</a>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href=
+          "#BOOST_PYTHON_MODULE_INIT-spec">BOOST_PYTHON_MODULE_INIT</a>
+        </dl>
+
+      <dt><a href="#classes">Classes</a>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#module-spec">Class <code>module</code></a>
+
+          <dd>
+            <dl class="page-index">
+              <dt><a href="#module-spec-synopsis">Class <code>module</code>
+              synopsis</a>
+
+              <dt><a href="#module-spec-ctors">Class <code>module</code>
+              constructor</a>
+
+              <dt><a href="#module-spec-modifiers">Class <code>module</code>
+              modifier functions</a>
+
+              <dt><a href="#module-spec-observers">Class <code>module</code>
+              observer functions</a>
+            </dl>
+        </dl>
+
+      <dt><a href="#examples">Example(s)</a>
+    </dl>
+    <hr>
+
+    <h2><a name="introduction"></a>Introduction</h2>
+
+    <p>This header provides the basic facilities needed to create an
+    extension module.
+
+    <h2><a name="macros"></a>Macros</h2>
+
+    <p><a name=
+    "BOOST_PYTHON_MODULE_INIT-spec"><code>BOOST_PYTHON_MODULE_INIT(name)</code></a>
+    is used to declare Python <a href=
+    "http://www.python.org/doc/2.2/ext/methodTable.html#SECTION003400000000000000000">
+    module initialization functions</a>. The <code>name</code> argument must
+    exactly match the name of the module to be initialized, and must conform to
+    Python's <a href=
+    "http://www.python.org/doc/2.2/ref/identifiers.html">identifier naming
+    rules</a>. Where you would normally write
+<pre>
+void init<i>name</i>()
+{
+   ...
+</pre>
+    Boost.Python modules should be initialized with 
+<pre>
+BOOST_PYTHON_MODULE_INIT(<i>name</i>)
+{
+   ...
+</pre>
+
+    <h2><a name="classes"></a>Classes</h2>
+
+    <h3><a name="module-spec">Class <code>module</code></a></h3>
+
+    <p>This class represents the Python extension module under construction. It
+    provides functions for adding attributes and for retrieving the underlying
+    Python module object.
+
+    <h4><a name="module-spec-synopsis"></a>Class <code>module</code>
+    synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+  class module : public module_base
+  {
+   public:
+      module(const char* name);
+
+      // modifier functions
+      module&amp; setattr(const char* name, PyObject*);
+      module&amp; setattr(const char* name, PyTypeObject*);
+      module&amp; setattr(const char* name, ref const&amp;);
+
+      module&amp; add(PyTypeObject* x);
+      template &lt;class T, class Bases, class HolderGenerator&gt;
+      module&amp; add(class_&lt;T,Bases,HolderGenerator&gt; const&amp; c);
+
+      template &lt;class Fn&gt;
+      module&amp; def(char const* name, Fn fn);
+      template &lt;class Fn, class ResultHandler&gt;
+      module&amp; def(char const* name, Fn fn, ResultHandler handler);
+
+      // observer function
+      ref object() const;
+  };
+
+}}
+</pre>
+
+    <h4><a name="module-spec-ctors">Class <code>module</code></a>
+    constructor</h4>
+<pre>
+module(const char* name);
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Requires:</b> <code>name</code> is a ntbs whose value matches the
+      argument passed to <a href=
+      "#BOOST_PYTHON_MODULE_INIT-spec">BOOST_PYTHON_MODULE_INIT</a>.
+
+      <dt><b>Effects:</b> Creates a <code>module</code> object representing a
+      Python module named <code>name</code>.
+    </dl>
+
+    <h4><a name="module-spec-modifiers">Class <code>module</code></a> modifier
+    functions</h4>
+<pre>
+module&amp; setattr(const char* name, PyObject* obj);
+module&amp; setattr(const char* name, PyTypeObject* obj);
+module&amp; setattr(const char* name, ref const&amp; r);
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Requires:</b> <code>name</code> is a ntbs which conforms to
+      Python's <a href=
+      "http://www.python.org/doc/2.2/ref/identifiers.html">identifier
+      naming rules</a>. In the first two forms, <code>obj</code> is non-null.
+      In the third form, <code>r.get()</code> is non-null.
+
+      <dt><b>Effects:</b> Adds the given Python object to the module. If the
+      object is a product of <code><a href=
+      "make_function.html#make_function-spec">make_function</a>()</code>, the
+      usual <a href="overloading.html">overloading procedure</a> applies.
+      In the first two forms, ownership of a reference to obj is transferred
+      from caller to callee, even if an exception is thrown.
+
+      <dt><b>Returns:</b> <code>*this</code>
+    </dl>
+<pre>
+module&amp; add(PyTypeObject* x);
+
+template &lt;class T, class Bases, class HolderGenerator&gt;
+module&amp; add(class_&lt;T,Bases,HolderGenerator&gt; const&amp; c);
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Requires:</b> In the first form, <code>x</code> is non-null
+
+      <dt><b>Effects:</b> The first form adds the Python type object named by
+      <code>x</code> to the Python module under construction, with the name
+      given by the type's <code><a href=
+      "http://www.python.org/doc/2.2/ext/dnt-type-methods.html">tp_name</a></code>
+      field. The second form adds the extension class object being constructed
+      by <code>c</code> to the module, with the same name that was passed to
+      <code>c</code>'s constructor.
+
+      <dt><b>Returns:</b> <code>*this</code>
+
+      <dt><b>Rationale:</b> Provides a way to set type attributes in the module
+      without having to explicitly specify the name.
+    </dl>
+<pre>
+template &lt;class Fn&gt;
+module&amp; def(char const* name, Fn f);
+
+template &lt;class Fn, class ResultHandler&gt;
+module&amp; def(char const* name, Fn f, ResultHandler handler);
+</pre>
+
+    <dl class="function-semantics">
+
+      <dt><b>Requires:</b> <code>f</code> is a non-null pointer-to-function or
+      pointer-to-member-function. <code>name</code> is a ntbs which conforms to
+      Python's <a href=
+      "http://www.python.org/doc/2.2/ref/identifiers.html">identifier
+      naming rules</a>. In the first form, the return type of
+      <code>f</code> is not a reference and is not a pointer other
+      than <code>char const*</code> or <code>PyObject*</code>. In the
+      second form <code>policy</code> is a model of <a
+      href="CallPolicy.html">CallPolicy</a>.
+
+      <dt><b>Effects:</b> Adds the result of <code><a href=
+      "make_function.html#make_function-spec">make_function</a>(f)</code> to
+      the extension module being defined, with the given <code>name</code>. If
+      the module already has an attribute named <code><i>name</i></code>, the
+      usual <a href="http:overloading.html">overloading procedure</a> applies.
+
+      <dt><b>Returns:</b> <code>*this</code>
+    </dl>
+
+    <h4><a name="module-spec-observers">Class <code>module</code></a> observer
+    functions</h4>
+<pre>
+ref object() const;
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Returns:</b> A <code>ref</code> object which holds a reference to
+      the Python module object created by the <code>module</code> constructor.
+    </dl>
+
+    <h2><a name="examples"></a>Example(s)</h2>
+
+    <p>C++ module definition:
+<pre>
+#include &lt;boost/python/module.hpp&gt;
+
+char const* greet()
+{
+    return "hello, Boost.Python!";
+}
+
+BOOST_PYTHON_MODULE_INIT(boost_greet)
+{
+    module("boost_greet")
+        .def("greet", greet);
+}
+</pre>
+
+Interactive Python: 
+<pre>
+&gt;&gt;&gt; import boost_greet
+&gt;&gt;&gt; boost_greet.greet()
+'hello, Boost.Python!'
+</pre>
+
+    <p>Revised 
+    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+     14 February, 2002
+    <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+
+
+    <p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
+    Abrahams</a> 2002. All Rights Reserved.</i>
+

doc/v2/operators.html

@@ -0,0 +1,531 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+    <meta name="generator" content="HTML Tidy, see www.w3.org">
+    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+    <link rel="stylesheet" type="text/css" href="../boost.css">
+
+    <title>Boost.Python - &lt;boost/python/operators.hpp&gt;</title>
+
+    <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+      <tr>
+        <td valign="top" width="300">
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+
+        <td valign="top">
+          <h1 align="center">Boost.Python</h1>
+
+          <h2 align="center">Header &lt;boost/python/operators.hpp&gt;</h2>
+    </table>
+    <hr>
+
+    <h2>Contents</h2>
+
+    <dl class="page-index">
+      <dt><a href="#introduction">Introduction</a>
+
+      <dt><a href="#classes">Classes</a>
+      <dd>
+        <dl class="page-index">
+
+          <dt><a href="#self_t-spec">Class <code>self_ns::self_t</code></a>
+          <dd>
+            <dl class="page-index">
+              <dt><a href="#self_t-spec-synopsis">Class <code>self_t</code> synopsis</a>
+
+              <dt><a href="#self_t-spec-inplace">Class <code>self_t</code> inplace operators</a>
+
+              <dt><a href="#self_t-spec-comparisons">Class <code>self_t</code> comparison functions</a>
+
+              <dt><a href="#self_t-spec-ops">Class <code>self_t</code> non-member operations</a>
+
+              <dt><a href="#self_t-spec-value-unary-ops">Class <code>self_t</code> unary operations</a>
+
+              <dt><a href="#self_t-spec-value-value-ops">Class <code>self_t</code> value operations</a>
+            </dl>
+
+          <dt><a href="#other-spec">Class template <code>other</code></a>
+          <dd>
+            <dl class="page-index">
+              <dt><a href="#other-spec-synopsis">Class <code>other</code> synopsis</a>
+            </dl>
+
+          <dt><a href="#operator_-spec">Class template <code>operator_</code></a>
+          <dd>
+            <dl class="page-index">
+              <dt><a href="#operator_-spec-synopsis">Class <code>operator_</code> synopsis</a>
+            </dl>
+ 
+         </dl>
+
+      <dt><a href="#objects">Objects</a>
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#self-spec">self</a>
+        </dl>
+
+      <dt><a href="#examples">Examples</a>
+    </dl>
+    <hr>
+
+    <h2><a name="introduction"></a>Introduction</h2>
+
+    <p><code>&lt;boost/python/operators.hpp&gt;</code> provides types
+    and functions for automatically generating Python <a
+    href="http://www.python.org/doc/ref/specialnames.html">special
+    methods</a> from the corresponding C++ constructs. Most of these
+    constructs are operator expressions, hence the name. To use the
+    facility, substitute the <code><a
+    href="#self-spec">self</a></code> object for an object of the
+    class type being wrapped in the expression to be exposed, and pass
+    the result to <a
+    href="class.html#class_-spec-modifiers">class_&lt;&gt;::def()</a>. Much
+    of what is exposed in this header should be considered part of the
+    implementation, so is not documented in detail here.
+
+    <h2><a name="classes"></a>Classes</h2>
+
+    <h3><a name="self_t-spec"></a>Class <code>self_ns::self_t</code></h3>
+
+    <p><code>self_ns::self_t</code> is the actual type of the <a
+    href="#self-spec"><code>self</code></a> object. The library
+    isolates <code>self_t</code> in its own namespace,
+    <code>self_ns</code>, in order to prevent the generalized operator
+    templates which operate on it from being found by
+    argument-dependent lookup in other contexts. This should be
+    considered an implementation detail, since users should never have
+    to mention <code>self_t</code> directly.
+
+    <h4><a name="self_t-spec-synopsis"></a>Class <code>self_ns::self_t</code> synopsis</h4>
+<pre>
+namespace boost { namespace python { namespace self_ns {
+{
+   class self_t {};
+
+   // inplace operators
+   template &lt;class T&gt; <a
+   href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; operator+=(self_t, T);
+   template &lt;class T&gt; <a
+   href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; operator-=(self_t, T);
+   template &lt;class T&gt; <a
+   href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; operator*=(self_t, T);
+   template &lt;class T&gt; <a
+   href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; operator/=(self_t, T);
+   template &lt;class T&gt; <a
+   href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; operator%=(self_t, T);
+   template &lt;class T&gt; <a
+   href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; operator&gt;&gt;=(self_t, T);
+   template &lt;class T&gt; <a
+   href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; operator&lt;&lt;=(self_t, T);
+   template &lt;class T&gt; <a
+   href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; operator&amp;=(self_t, T);
+   template &lt;class T&gt; <a
+   href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; operator^=(self_t, T);
+   template &lt;class T&gt; <a
+   href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; operator|=(self_t, T);
+
+   // comparisons
+   template &lt;class L, class R&gt; <a
+   href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; operator==(L const&amp;, R const&amp;);
+   template &lt;class L, class R&gt; <a
+   href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; operator!=(L const&amp;, R const&amp;);
+   template &lt;class L, class R&gt; <a
+   href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; operator&lt;(L const&amp;, R const&amp;);
+   template &lt;class L, class R&gt; <a
+   href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; operator&gt;(L const&amp;, R const&amp;);
+   template &lt;class L, class R&gt; <a
+   href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; operator&lt;=(L const&amp;, R const&amp;);
+   template &lt;class L, class R&gt; <a
+   href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; operator&gt;=(L const&amp;, R const&amp;);
+
+   // non-member operations
+   template &lt;class L, class R&gt; <a
+   href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; operator+(L const&amp;, R const&amp);
+   template &lt;class L, class R&gt; <a
+   href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; operator-(L const&amp;, R const&amp);
+   template &lt;class L, class R&gt; <a
+   href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; operator*(L const&amp;, R const&amp);
+   template &lt;class L, class R&gt; <a
+   href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; operator/(L const&amp;, R const&amp);
+   template &lt;class L, class R&gt; <a
+   href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; operator%(L const&amp;, R const&amp);
+   template &lt;class L, class R&gt; <a
+   href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; operator&gt;&gt;(L const&amp;, R const&amp);
+   template &lt;class L, class R&gt; <a
+   href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; operator&lt;&lt;(L const&amp;, R const&amp);
+   template &lt;class L, class R&gt; <a
+   href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; operator&amp;(L const&amp;, R const&amp);
+   template &lt;class L, class R&gt; <a
+   href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; operator^(L const&amp;, R const&amp);
+   template &lt;class L, class R&gt; <a
+   href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; operator|(L const&amp;, R const&amp);
+   template &lt;class L, class R&gt; <a
+   href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; pow(L const&amp;, R const&amp);
+
+   // unary operations
+   <a href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; operator-(self_t);
+   <a href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; operator+(self_t);
+   <a href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; operator~(self_t);
+
+   // value operations
+   <a href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; int_(self_t);
+   <a href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; long_(self_t);
+   <a href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; float_(self_t);
+   <a href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; complex_(self_t);
+   <a href="#operator_-spec">operator_</a>&lt;<i>unspecified</i>&gt; str(self_t);
+
+}}};
+</pre>
+
+The tables below describe the methods generated when the results of
+the expressions described are passed as arguments to <a
+href="class.html#class_-spec-modifiers">class_&lt;&gt;::def()</a>.
+<code><b>x</b></code> is an object of the class type being wrapped.
+
+
+    <h4><a name="self_t-spec-inplace"></a>Class <code>self_t</code> inplace operators</h4>
+
+
+
+In the table below, If <code><b>r</b></code> is an object of type
+<code><a href="#other-spec">other</a>&lt;T&gt;</code>, 
+<code><b>y</b></code> is an object of type <code>T</code>; otherwise,
+<code><b>y</b></code> is an object of the same type as
+<code><b>r</b></code>.
+
+<table border="1">
+<tr>
+  <th>C++ Expression
+  <th>Python Method Name
+  <th>C++ Implementation
+
+<tr><td><code>self&nbsp;+=&nbsp;r</code>
+<td><code>__iadd__</code>
+<td><code>x&nbsp;+=&nbsp;y</code>
+
+<tr><td><code>self&nbsp;-=&nbsp;r</code>
+<td><code>__isub__</code>
+<td><code>x&nbsp;-=&nbsp;y</code>
+
+<tr><td><code>self&nbsp;*=&nbsp;r</code>
+<td><code>__imul__</code>
+<td><code>x&nbsp;*=&nbsp;y</code>
+
+<tr><td><code>self&nbsp;/=&nbsp;r</code>
+<td><code>__idiv__</code>
+<td><code>x&nbsp;/=&nbsp;y</code>
+
+<tr><td><code>self&nbsp;%=&nbsp;r</code>
+<td><code>__imod__</code>
+<td><code>x&nbsp;%=&nbsp;y</code>
+
+<tr><td><code>self&nbsp;&gt;&gt;=&nbsp;r</code>
+<td><code>__irshift__</code>
+<td><code>x&nbsp;&gt;&gt;=&nbsp;y</code>
+
+<tr><td><code>self&nbsp;&lt;&lt;=&nbsp;r</code>
+<td><code>__ilshift__</code>
+<td><code>x&nbsp;&lt;&lt;=&nbsp;y</code>
+
+<tr><td><code>self&nbsp;&amp;=&nbsp;r</code>
+<td><code>__iand__</code>
+<td><code>x&nbsp;&amp;=&nbsp;y</code>
+
+<tr><td><code>self&nbsp;^=&nbsp;r</code>
+<td><code>__ixor__</code>
+<td><code>x&nbsp;^=&nbsp;y</code>
+
+<tr><td><code>self&nbsp;|=&nbsp;r</code>
+<td><code>__ior__</code>
+<td><code>x&nbsp;|=&nbsp;y</code>
+</table>
+
+    <h4><a name="self_t-spec-comparisons"></a>Class <code>self_t</code> comparison
+    functions</h4>
+
+In the tables below, if <code><b>r</b></code> is of type <code><a
+href="#self_t-spec">self_t</a></code>, <code><b>y</b></code> is an object
+of the same type as <code>x</code>;
+<br>
+if <code><b>l</b></code>  or <code><b>r</b></code> is an object of type <code><a
+href="#other-spec">other</a>&lt;T&gt;</code>,
+<code><b>y</b></code> is an object of type <code>T</code>; 
+<br>
+otherwise, <code><b>y</b></code> is an object of the same type as
+<code><b>l</b></code> or <code><b>r</b></code>.<br>
+<code><b>l</b></code>
+is never of type <code><a href="#self_t-spec">self_t</a></code>.
+
+<p>
+The column of <b>Python Expressions</b> illustrates the expressions
+that will be supported in Python for objects convertible to the types
+of <code>x</code> and <code>y</code>. The secondary operation arises
+due to Python's <a
+href="http://www.python.org/doc/ref/customization.html#l2h-89">reflection
+rules</a> for rich comparison operators, and are only used when the
+corresponding operation is not defined as a method of the
+<code>y</code> object.
+
+<table border="1">
+<tr><th>C++ Expression <th>Python Method Name <th>C++ Implementation
+<th>Python Expressions<br>(primary, secondary)
+<code>
+
+<tr><td>self&nbsp;==&nbsp;r <td>__eq__ <td>x&nbsp;==&nbsp;y
+<td>x&nbsp;==&nbsp;y, y&nbsp;==&nbsp;x 
+
+<tr><td>l&nbsp;==&nbsp;self <td>__eq__ <td>y&nbsp;==&nbsp;x
+<td>y&nbsp;==&nbsp;x, x&nbsp;==&nbsp;y
+
+<tr><td>self&nbsp;!=&nbsp;r <td>__ne__ <td>x&nbsp;!=&nbsp;y
+<td>x&nbsp;!=&nbsp;y, y&nbsp;!=&nbsp;x 
+
+<tr><td>l&nbsp;!=&nbsp;self <td>__ne__ <td>y&nbsp;!=&nbsp;x
+<td>y&nbsp;!=&nbsp;x, x&nbsp;!=&nbsp;y
+
+<tr><td>self&nbsp;&lt;&nbsp;r <td>__lt__ <td>x&nbsp;&lt;&nbsp;y
+<td>x&nbsp;&lt;&nbsp;y, y&nbsp;&gt;&nbsp;x 
+
+<tr><td>l&nbsp;&lt;&nbsp;self <td>__gt__ <td>y&nbsp;&lt;&nbsp;x
+<td>y&nbsp;&gt;&nbsp;x, x&nbsp;&lt;&nbsp;y
+
+<tr><td>self&nbsp;&gt;&nbsp;r <td>__gt__ <td>x&nbsp;&gt;&nbsp;y
+<td>x&nbsp;&gt;&nbsp;y, y&nbsp;&lt;&nbsp;x 
+
+<tr><td>l&nbsp;&gt;&nbsp;self <td>__lt__ <td>y&nbsp;&gt;&nbsp;x
+<td>y&nbsp;&lt;&nbsp;x, x&nbsp;&gt;&nbsp;y
+
+<tr><td>self&nbsp;&lt;=&nbsp;r <td>__le__ <td>x&nbsp;&lt;=&nbsp;y
+<td>x&nbsp;&lt;=&nbsp;y, y&nbsp;&gt;=&nbsp;x 
+
+<tr><td>l&nbsp;&lt;=&nbsp;self <td>__ge__ <td>y&nbsp;&lt;=&nbsp;x
+<td>y&nbsp;&gt;=&nbsp;x, x&nbsp;&lt;=&nbsp;y
+
+<tr><td>self&nbsp;&gt;=&nbsp;r <td>__ge__ <td>x&nbsp;&gt;=&nbsp;y
+<td>x&nbsp;&gt;=&nbsp;y, y&nbsp;&lt;=&nbsp;x 
+
+<tr><td>l&nbsp;&gt;=&nbsp;self <td>__le__ <td>y&nbsp;&gt;=&nbsp;x
+<td>y&nbsp;&lt;=&nbsp;x, x&nbsp;&gt;=&nbsp;y
+
+</code>
+</table>
+
+
+    <h4><a name="self_t-spec-ops"></a>Class
+    <code>self_t</code> non-member operations</h4>
+
+The operations whose names begin with &quot;<code>__r</code>&quot;
+below will only be called if the left-hand operand does not already
+support the given operation, as described <a
+href="http://www.python.org/doc/current/ref/numeric-types.html#l2h-152">here</a>.
+
+<table border="1">
+<tr><th>C++ Expression <th>Python Method Name <th>C++ Implementation
+<code>
+
+<tr><td>self&nbsp;+&nbsp;r <td>__add__ <td>x&nbsp;+&nbsp;y
+<tr><td>l&nbsp;+&nbsp;self <td>__radd__ <td>y&nbsp;+&nbsp;x
+
+<tr><td>self&nbsp;-&nbsp;r <td>__sub__ <td>x&nbsp;-&nbsp;y
+<tr><td>l&nbsp;-&nbsp;self <td>__rsub__ <td>y&nbsp;-&nbsp;x
+
+<tr><td>self&nbsp;*&nbsp;r <td>__mul__ <td>x&nbsp;*&nbsp;y
+<tr><td>l&nbsp;*&nbsp;self <td>__rmul__ <td>y&nbsp;*&nbsp;x
+
+<tr><td>self&nbsp;/&nbsp;r <td>__div__ <td>x&nbsp;/&nbsp;y
+<tr><td>l&nbsp;/&nbsp;self <td>__rdiv__ <td>y&nbsp;/&nbsp;x
+
+<tr><td>self&nbsp;%&nbsp;r <td>__mod__ <td>x&nbsp;%&nbsp;y
+<tr><td>l&nbsp;%&nbsp;self <td>__rmod__ <td>y&nbsp;%&nbsp;x
+
+<tr><td>self&nbsp;&gt;&gt;&nbsp;r <td>__rshift__ <td>x&nbsp;&gt;&gt;&nbsp;y
+<tr><td>l&nbsp;&gt;&gt;&nbsp;self <td>__rrshift__ <td>y&nbsp;&gt;&gt;&nbsp;x
+
+<tr><td>self&nbsp;&lt;&lt;&nbsp;r <td>__lshift__ <td>x&nbsp;&lt;&lt;&nbsp;y
+<tr><td>l&nbsp;&lt;&lt;&nbsp;self <td>__rlshift__ <td>y&nbsp;&lt;&lt;&nbsp;x
+
+<tr><td>self&nbsp;&amp;&nbsp;r <td>__and__ <td>x&nbsp;&amp;&nbsp;y
+<tr><td>l&nbsp;&amp;&nbsp;self <td>__rand__ <td>y&nbsp;&amp;&nbsp;x
+
+<tr><td>self&nbsp;^&nbsp;r <td>__xor__ <td>x&nbsp;^&nbsp;y
+<tr><td>l&nbsp;^&nbsp;self <td>__rxor__ <td>y&nbsp;^&nbsp;x
+
+<tr><td>self&nbsp;|&nbsp;r <td>__or__ <td>x&nbsp;|&nbsp;y
+<tr><td>l&nbsp;|&nbsp;self <td>__ror__ <td>y&nbsp;|&nbsp;x
+
+<tr><td>pow(self,&nbsp;r) <td>__pow__ <td>pow(x,&nbsp;y)
+<tr><td>pow(l,&nbsp;self) <td>__rpow__ <td>pow(y,&nbsp;x)
+
+</code>
+</table>
+
+
+    <h4><a name="self_t-spec-unary-ops"></a>Class
+    <code>self_t</code> unary operations</h4>
+
+<table border="1">
+<tr><th>C++ Expression <th>Python Method Name <th>C++ Implementation
+<code>
+
+<tr><td>-self <td>__neg__ <td>-x
+<tr><td>+self<td>__pos__ <td>+x
+<tr><td>~self<td>__invert__ <td>~x
+
+</code>
+</table>
+
+
+    <h4><a name="self_t-spec-value-ops"></a>Class
+    <code>self_t</code> value operations</h4>
+
+<table border="1">
+<tr><th>C++ Expression <th>Python Method Name <th>C++ Implementation
+<code>
+
+<tr><td>int_(self)<td>__int__ <td>long(x)
+<tr><td>long_<td>__long__ <td>PyLong_FromLong(x)
+<tr><td>float_<td>__float__ <td>double(x)
+<tr><td>complex_<td>__complex__ <td>std::complex&lt;double&gt;(x)
+<tr><td>str<td>__str__ <td><a href="../../../conversion/lexical_cast.htm#lexical_cast">lexical_cast</a>&lt;std::string&gt;(x)
+
+</code>
+</table>
+
+
+
+    <h3><a name="other-spec"></a>Class Template <code>other</code></h3>
+
+    <p>Instances of <code>other&lt;T&gt;</code> can be used in
+    operator expressions with <a href="#self-spec">self</a>; the
+    result is equivalent to the same expression with a <code>T</code>
+    object in place of <code>other&lt;T&gt;</code>. Use
+    <code>other&lt;T&gt;</code> to prevent construction of a
+    <code>T</code> object in case it is heavyweight, when no
+    constructor is available, or simply for clarity.
+
+    <h4><a name="other-spec-synopsis"></a>Class Template other synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+  template &lt;class T&gt;
+  struct other
+  {
+  };
+}}
+</pre>
+
+<!-- -->
+
+    <h3><a name="operator_-spec"></a>Class Template <code>detail::operator_</code></h3>
+
+    <p>Instantiations of <code>detail::operator_&lt;&gt;</code> are
+    used as the return type of operator expressions involving <code><a
+    href="#self-spec">self</a></code>. This should be considered an
+    implementation detail and is only documented here as a way of
+    showing how the result of <code>self</code>-expressions match
+    calls to <a
+    href="class.html#class_-spec-modifiers">class_&lt;&gt;::def()</a>.
+    
+    <h4><a name="operator_-spec-synopsis"></a>Class Template
+    <code>detail::operator_</code> synopsis</h4>
+<pre>
+namespace boost { namespace python { namespace detail
+{
+  template &lt;<i>unspecified</i>&gt;
+  struct operator_
+  {
+  };
+}}}
+</pre>
+
+    <h2><a name="objects"></a>Objects</h2>
+
+    <p><a name="self-spec"><code>self</code></a>
+
+<pre>
+namespace boost { namespace python
+{
+  extern self_ns self;
+}}
+</pre>
+
+    <h2><a name="examples"></a>Example</h2>
+
+<pre>
+#include &lt;boost/python/module.hpp&gt;
+#include &lt;boost/python/class.hpp&gt;
+#include &lt;boost/python/operators.hpp&gt;
+#include &lt;boost/operators.hpp&gt;
+
+struct number
+   : boost::<a href="../../../utility/operators.htm#grpd_oprs">integer_arithmetic</a>&lt;number&gt;
+{
+   number(long x_) : x(x_) {}
+   operator long() const { return x; }
+
+   number&amp; operator+=(number const&amp; rhs)
+      { x += rhs }
+   number&amp; operator-=(number const&amp; rhs);
+      { x -= rhs }
+   number&amp; operator*=(number const&amp; rhs)
+      { x *= rhs }
+   number&amp; operator/=(number const&amp; rhs);
+      { x /= rhs }
+   number&amp; operator%=(number const&amp; rhs);
+      { x %= rhs }
+
+   long x;
+};
+
+using namespace boost::python;
+BOOST_PYTHON_MODULE_INIT(demo)
+{
+   module(&quot;demo&quot;)
+      .add(
+         class_&lt;number&gt;(&quot;number&quot;)
+            // interoperate with self
+            .def(self += self)
+            .def(self + self)
+            .def(self -= self)
+            .def(self - self)
+            .def(self *= self)
+            .def(self * self)
+            .def(self /= self)
+            .def(self / self)
+            .def(self %= self)
+            .def(self % self)
+            
+            // Convert to Python int
+            .def(int_(self))
+
+            // interoperate with long
+            .def(self += long())
+            .def(self + long())
+            .def(long() + self)
+            .def(self -= long())
+            .def(self - long())
+            .def(long() - self)
+            .def(self *= long())
+            .def(self * long())
+            .def(long() * self)
+            .def(self /= long())
+            .def(self / long())
+            .def(long() / self)
+            .def(self %= long())
+            .def(self % long())
+            .def(long() % self)
+
+         )
+      ;
+}
+</pre>
+
+    <p>Revised 
+    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+     3 June, 2002
+    <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+
+
+    <p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
+    Abrahams</a> 2002. All Rights Reserved.</i>
+

doc/v2/overview.html

@@ -0,0 +1,48 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+<link rel="stylesheet" type="text/css" href="../boost.css">
+<title>Boost.Python - Overview</title>
+</head>
+<body link="#0000ff" vlink="#800080">
+<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+  <tr> 
+    <td valign="top" width="300"> 
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+    </td>
+    <td valign="top"> 
+      <h1 align="center">Boost.Python</h1>
+      <h2 align="center">Overview</h2>
+    </td>
+  </tr>
+</table>
+<hr>
+<dl class="index">
+  <dt><a href="#introduction">Introduction</a></dt>
+  <dt><a href="#topic1">First topic</a></dt>
+  <dt><a href="#topic2">Second topic</a></dt>
+  <dt><a href="#footnotes">Footnotes</a></dt>
+</dl>
+<h2><a name="introduction"></a>Introduction</h2>
+<p>{{text}}</p>
+<h2><a name="topic1"></a>First Topic</h2>
+<p>{{text}}</p>
+<h2><a name="topic2"></a>Second Topic</h2>
+<p>{{text}}</p>
+<h2><a name="footnotes"></a>Footnotes</h2>
+<dl>
+  <dt><a name="footnote1" class="footnote">(1)</a> {{text}}</dt>
+  <dt><a name="footnote2" class="footnote">(2)</a> {{text}}</dt>
+</dl>
+<hr>
+<p>Revised 
+  <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+  05 November, 2002 
+  <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+</p>
+<p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave Abrahams</a> 
+  2002. All Rights Reserved.</i></p>
+</body>
+</html>

doc/v2/progress_reports.html

@@ -0,0 +1,44 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+<link rel="stylesheet" type="text/css" href="../boost.css">
+<title>Boost.Python - Progress Reports</title>
+</head>
+<body link="#0000ff" vlink="#800080">
+<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+  <tr> 
+    <td valign="top" width="300"> 
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+    </td>
+    <td valign="top"> 
+      <h1 align="center">Boost.Python</h1>
+      <h2 align="center">Progress Reports</h2>
+    </td>
+  </tr>
+</table>
+<hr>
+
+Monthly progress reports are required as part of Boost Consulting's
+contract with LLNL for Boost.Python development. These reports contain
+a useful record of the project history, including the rationale for
+design decisions and links to relevant discussions.
+
+<dl class="page-index">
+  <dt><a href="feb2002.html">February 2002</a></dt>
+  <dt><a href="Mar2002.html">March 2002</a></dt>
+  <dt><a href="Apr2002.html">April 2002</a></dt>
+  <dt><a href="May2002.html">May 2002</a></dt>
+  <dt><a href="Jun2002.html">June 2002</a></dt>
+</dl>
+<hr>
+<p>Revised 
+  <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+  18 July, 2002
+  <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+</p>
+<p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave Abrahams</a> 
+  2002. All Rights Reserved.</i></p>
+</body>
+</html>

doc/v2/ptr.html

@@ -0,0 +1,261 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+    <meta name="generator" content="HTML Tidy, see www.w3.org">
+    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+    <link rel="stylesheet" type="text/css" href="../boost.css">
+
+    <title>Boost.Python - &lt;boost/python/ptr.hpp&gt;</title>
+
+    <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+      <tr>
+        <td valign="top" width="300">
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+
+        <td valign="top">
+          <h1 align="center">Boost.Python</h1>
+
+          <h2 align="center">Header &lt;boost/python/ptr.hpp&gt;</h2>
+    </table>
+    <hr>
+
+    <h2>Contents</h2>
+
+    <dl class="page-index">
+      <dt><a href="#introduction">Introduction</a>
+
+      <dt><a href="#functions">Functions</a>
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#ptr-spec">ptr</a>
+        </dl>
+
+      <dt><a href="#classes">Classes</a>
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#pointer_wrapper-spec">Class template <code>pointer_wrapper</code></a>
+
+          <dd>
+            <dl class="page-index">
+              <dt><a href="#pointer_wrapper-spec-synopsis">Class template <code>pointer_wrapper</code> synopsis</a>
+
+              <dt><a href="#pointer_wrapper-spec-types">Class
+              <code>pointer_wrapper</code> types</a>
+
+              <dt><a href="#pointer_wrapper-spec-ctors">Class
+              <code>pointer_wrapper</code> constructors and destructor</a>
+
+              <dt><a href="#pointer_wrapper-spec-observers">Class
+              <code>pointer_wrapper</code> observer functions</a>
+
+            </dl>
+         </dl>
+
+      <dt><a href="#metafunctions">Metafunctions</a>
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#is_pointer_wrapper-spec">Class template <code>is_pointer_wrapper</code></a>
+
+          <dd>
+            <dl class="page-index">
+              <dt><a href="#is_pointer_wrapper-spec-synopsis">Class template <code>is_pointer_wrapper</code> synopsis</a>
+            </dl>
+
+
+          <dt><a href="#unwrap_pointer-spec">Class template <code>unwrap_pointer</code></a>
+
+          <dd>
+            <dl class="page-index">
+              <dt><a href="#unwrap_pointer-spec-synopsis">Class template <code>unwrap_pointer</code> synopsis</a>
+            </dl>
+
+        </dl>
+
+
+      <dt><a href="#examples">Example(s)</a>
+    </dl>
+    <hr>
+
+    <h2><a name="introduction"></a>Introduction</h2>
+
+    <p><code>&lt;boost/python/ptr.hpp&gt;</code> defines the
+    <code>ptr()</code> function template, which allows users to
+    specify how to convert C++ pointer values to python in the context
+    of implementing overridable virtual functions, invoking Python
+    callable objects, or explicitly converting C++ objects to
+    Python. Normally, when passing pointers to Python callbacks, the
+    pointee is copied to ensure that the Python object
+    never holds a dangling reference. To specify that the new Python
+    object should merely contain a copy of a pointer <code>p</code>,
+    the user can pass <code><a href="#ptr-spec">ptr</a>(p)</code> instead of passing
+    <code>p</code> directly. This interface is meant to mirror the use
+    of <a href="../../../bind/ref.html"><code>boost::ref()</code></a>,
+    which can be similarly used to prevent copying of referents.
+
+    <p><code>ptr(p)</code> returns an instance of <code><a
+    href="#pointer_wrapper-spec">pointer_wrapper&lt;&gt;</a></code>, which
+    can be detected using the <code><a
+    href="#is_pointer_wrapper-spec">is_pointer_wrapper&lt;&gt;</a></code>
+    metafunction; <code><a
+    href="#unwrap_pointer-spec">unwrap_pointer&lt;&gt;</a></code> is a
+    metafunction which extracts the original pointer type from a
+    <code>pointer_wrapper&lt;&gt;</code>. These classes can be thought
+    of as implementation details.
+
+    <h2><a name="functions"></a>Functions</h2>
+<pre>
+
+<a name="ptr-spec">template &lt;class T&gt;</a>
+pointer_wrapper&lt;T&gt; ptr(T x);
+</pre>
+
+    <dl class="ptr-semantics">
+      <dt><b>Requires:</b> <code>T</code> is a pointer type.
+
+      <dt><b>Returns:</b> <code><a href="#pointer_wrapper-spec">pointer_wrapper</a>&lt;T&gt;(x)</code>
+
+      <dt><b>Throws:</b> nothing.
+    </dl>
+
+    <h2><a name="classes"></a>Classes</h2>
+
+    <h3><a name="pointer_wrapper-spec"></a>Class template <code>pointer_wrapper</code></h3>
+
+    <p>A &quot;type envelope&quot; which is returned by <a
+    href="#ptr-spec">ptr()</a>, used to indicate reference semantics
+    for pointers passed to Python callbacks.
+
+    <h4><a name="pointer_wrapper-spec-synopsis"></a>Class
+    <code>pointer_wrapper</code> synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+    template&lt;class Ptr&gt; class pointer_wrapper
+    { 
+     public:
+        typedef Ptr type;
+
+        explicit pointer_wrapper(Ptr x);
+        operator Ptr() const;
+        Ptr get() const;
+    };
+}}
+</pre>
+
+    <h4><a name="pointer_wrapper-spec-types"></a>Class template <code>pointer_wrapper</code> types</h4>
+<pre>
+typedef Ptr type;
+</pre>
+The type of the pointer being wrapped.
+
+    <h4><a name="pointer_wrapper-spec-ctors"></a>Class template <code>pointer_wrapper</code> constructors and
+    destructor</h4>
+<pre>
+explicit pointer_wrapper(Ptr x);
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Requires:</b> <code>Ptr</code> is a pointer type.
+
+      <dt><b>Effects:</b> Stores <code>x</code> in a the <code>pointer_wrapper&lt;&gt;</code>.
+      <dt><b>Throws:</b> nothing.
+    </dl>
+
+    <h4><a name="pointer_wrapper-spec-observers"></a>Class template <code>pointer_wrapper</code> observer
+    functions</h4>
+<pre>
+operator Ptr() const;
+Ptr get() const;
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Returns:</b> a copy of the stored pointer.
+      <dt><b>Rationale:</b> <code>pointer_wrapper</code> is intended
+      to be a stand-in for the actual pointer type, but sometimes it's
+      better to have an explicit way to retrieve the pointer.
+    </dl>
+
+    <h3><a name="is_pointer_wrapper-spec"></a>Class template <code>is_pointer_wrapper</code></h3>
+
+    <p>A unary metafunction whose <code>value</code> is true iff its
+    argument is a <code>pointer_wrapper&lt;&gt;</code>.
+
+    <h4><a name="is_pointer_wrapper-spec-synopsis"></a>Class template <code>is_pointer_wrapper</code> synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+    template&lt;class T&gt; class is_pointer_wrapper
+    { 
+        static <i>unspecified</i> value = ...;
+    };
+}}
+</pre>
+
+
+    <dl class="metafunction-semantics">
+      <dt><b>Returns:</b> <code>true</code> iff <code>T</code> is a
+      specialization of
+<code>pointer_wrapper&lt;&gt;</code>.
+<dt><code>value</code> is an integral constant convertible to bool of
+unspecified type
+
+    </dl>
+
+<h3><a name="unwrap_pointer-spec"></a>Class template <code>unwrap_pointer</code></h3>
+
+A unary metafunction which extracts the wrapped pointer type from a
+specialization of <code>pointer_wrapper&lt;&gt;</code>.
+
+    <h4><a name="unwrap_pointer-spec-synopsis"></a>Class template <code>unwrap_pointer</code> synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+    template&lt;class T&gt; class unwrap_pointer
+    { 
+        typedef <i>unspecified</i> type;
+    };
+}}
+</pre>
+
+    <dl class="metafunction-semantics">
+      <dt><b>Returns:</b> <code>T::type</code> if <code>T</code> is a
+      specialization of
+<code>pointer_wrapper&lt;&gt;</code>, <code>T</code> otherwise
+    </dl>
+
+
+    <h2><a name="examples"></a>Example(s)</h2>
+
+This example illustrates the use of <code>ptr()</code> to prevent an
+object from being copied:
+<pre>
+#include &lt;boost/python/call.hpp&gt;
+#include &lt;boost/python/ptr.hpp&gt;
+
+class expensive_to_copy
+{
+   ...
+};
+
+void pass_as_arg(expensive_to_copy* x, PyObject* f)
+{
+   // call the Python function f, passing a Python object built around
+   // which refers to *x by-pointer.
+   //
+   // *** Note: ensuring that *x outlives the argument to f() is    ***
+   // *** up to the user! Failure to do so could result in a crash! ***
+
+   boost::python::call&lt;void&gt;(f, ptr(x));
+}
+...
+</pre>
+
+    <p>Revised 
+    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+     29 May, 2002 
+    <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+
+
+    <p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
+    Abrahams</a> 2002. All Rights Reserved.</i>
+

doc/v2/rationale.html

@@ -0,0 +1,48 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+<link rel="stylesheet" type="text/css" href="../boost.css">
+<title>Boost.Python - Rationale</title>
+</head>
+<body link="#0000ff" vlink="#800080">
+<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+  <tr> 
+    <td valign="top" width="300"> 
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+    </td>
+    <td valign="top"> 
+      <h1 align="center">Boost.Python</h1>
+      <h2 align="center">Rationale</h2>
+    </td>
+  </tr>
+</table>
+<hr>
+<dl class="index">
+  <dt><a href="#introduction">Introduction</a></dt>
+  <dt><a href="#topic1">First topic</a></dt>
+  <dt><a href="#topic2">Second topic</a></dt>
+  <dt><a href="#footnotes">Footnotes</a></dt>
+</dl>
+<h2><a name="introduction"></a>Introduction</h2>
+<p>{{text}}</p>
+<h2><a name="topic1"></a>First Topic</h2>
+<p>{{text}}</p>
+<h2><a name="topic2"></a>Second Topic</h2>
+<p>{{text}}</p>
+<h2><a name="footnotes"></a>Footnotes</h2>
+<dl>
+  <dt><a name="footnote1" class="footnote">(1)</a> {{text}}</dt>
+  <dt><a name="footnote2" class="footnote">(2)</a> {{text}}</dt>
+</dl>
+<hr>
+<p>Revised 
+  <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+  05 November, 2002 
+  <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+</p>
+<p><i>&copy; Copyright <a href="../../../../../people/dave_abrahams.htm">Dave Abrahams</a> 
+  2002. All Rights Reserved.</i></p>
+</body>
+</html>

doc/v2/reference.html

@@ -0,0 +1,611 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+
+    <meta name="generator" content="HTML Tidy, see www.w3.org">
+    <meta http-equiv="Content-Type" content=
+    "text/html; charset=iso-8859-1">
+    <link rel="stylesheet" type="text/css" href="../boost.css">
+
+    <title>Boost.Python - Reference</title>
+<style type="text/css">
+ p.c3 {font-style: italic}
+ h2.c2 {text-align: center}
+ h1.c1 {text-align: center}
+</style>
+
+    <table border="0" cellpadding="7" cellspacing="0" width="100%"
+    summary="reference">
+      <tr>
+        <td valign="top" width="300">
+          <h3><a href="http://www.boost.org"><img height="86" width=
+          "277" alt="C++ Boost" src="../../../../c++boost.gif" border=
+          "0"></a></h3>
+
+        <td valign="top">
+          <h1 class="c1">Boost.Python</h1>
+
+          <h2 class="c2">Reference</h2>
+    </table>
+    <hr>
+
+    <h2>Contents</h2>
+
+    <dl class="Reference">
+      <dt><a href="#concepts">Concepts</a>
+
+      <dt><a href="#high_level">High Level Components</a>
+
+      <dt><a href="#invocation">Function Invocation and Creation</a>
+
+      <dd>
+        <dl class="index">
+          <dt><a href="#models_of_call_policies">Models of
+          CallPolicies</a>
+
+          <dt><a href="#models_of_result_converter">Models of
+          ResultConverter</a>
+
+          <dt><a href="#result_converter_generators">Models of
+          ResultConverterGenerator</a>
+        </dl>
+
+      <dt><a href="#type_conversion">To/From Python Type Conversion</a>
+
+      <dt><a href="#utility">Utility and Infrastructure</a>
+    </dl>
+    <hr>
+    <!-- xxxxx -->
+
+    <h2><a name="concepts">Concepts</a></h2>
+
+    <dl class="index">
+      <dt><a href=
+      "CallPolicies.html#CallPolicies-concept">CallPolicies</a>
+
+      <dt><a href=
+      "Dereferenceable.html#Dereferenceable-concept">Dereferenceable</a>
+
+      <dt><a href=
+      "Dereferenceable.html#Extractor-concept">Extractor</a>
+
+      <dt><a href=
+      "HolderGenerator.html#HolderGenerator-concept">HolderGenerator</a>
+
+      <dt><a href=
+      "ResultConverter.html#ResultConverter-concept">ResultConverter</a>
+
+      <dt><a href=
+      "ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a>
+    </dl>
+
+    <h2><a name="high_level">High Level Components</a></h2>
+
+    <dl>
+      <dt><a href="class.html">class.hpp/class_fwd.hpp</a>
+
+      <dd>
+        <dl class="index">
+          <dt><a href="class.html#classes">Classes</a>
+
+          <dd>
+            <dl class="index">
+              <dt><a href="class.html#class_-spec">class_</a>
+
+              <dt><a href="class.html#bases-spec">bases</a>
+
+              <dt><a href="class.html#args-spec">args</a>
+            </dl>
+        </dl>
+
+      <dt><a href="errors.html">errors.hpp</a>
+
+      <dd>
+        <dl class="index">
+          <dt><a href="errors.html#classes">Classes</a>
+
+          <dd>
+            <dl class="index">
+              <dt><a href=
+              "errors.html#error_already_set-spec">error_already_set</a>
+            </dl>
+
+          <dt><a href="errors.html#functions">Functions</a>
+
+          <dd>
+            <dl class="index">
+              <dt><a href=
+              "errors.html#handle_exception-spec">handle_exception</a>
+
+              <dt><a href=
+              "errors.html#expect_non_null-spec">expect_non_null</a>
+            </dl>
+        </dl>
+
+      <dt><a href="iterator.html">iterator.hpp</a>
+
+      <dd>
+        <dl class="index">
+
+          <dt><a href="iterator.html#classes">Classes</a>
+          <dd>
+            <dl class="index">
+              <dt><a href="iterator.html#iterator-spec">iterator</a>
+
+              <dt><a href="iterator.html#iterators-spec">iterators</a>
+            </dl>
+
+          <dt><a href="iterator.html#functions">Functions</a>
+
+          <dd>
+            <dl class="index">
+              <dt><a href="iterator.html#range-spec">range</a>
+            </dl>
+        </dl>
+
+      <dt><a href="module.html">module.hpp</a>
+      <dd>
+        <dl class="index">
+          <dt><a href="module.html#classes">Classes</a>
+
+          <dd>
+            <dl class="index">
+              <dt><a href="module.html#module-spec">module</a>
+            </dl>
+        </dl>
+
+      <dt><a href="objects.html">objects.hpp</a>
+      <dd>
+        <dl class="index">
+          <dt><a href="objects.html#classes">Classes</a>
+
+          <dd>
+            <dl class="index">
+              <dt><a href="objects.html#xxx-spec">not yet
+              documented</a>
+            </dl>
+        </dl>
+
+      <dt><a href="operators.html">operators.hpp</a>
+      <dd>
+        <dl class="index">
+          <dt><a href="operators.html#classes">Classes</a>
+          <dd>
+            <dl class="index">
+              <dt><a href="operators.html#self_t-spec">self_t</a>
+              <dt><a href="operators.html#other-spec">other</a>
+              <dt><a href="operators.html#operator_-spec">operator_</a>
+            </dl>
+
+          <dt><a href="operators.html#functions">Objects</a>
+          <dd>
+            <dl class="index">
+              <dt><a href="operators.html#self-spec">self</a>
+            </dl>
+
+        </dl>
+
+    </dl>
+
+    <h2><a name="invocation">Function Invocation and Creation</a></h2>
+
+    <dl class="index">
+      <dt><a href="call.html">call.hpp</a>
+
+      <dd>
+        <dl class="index">
+          <dt><a href="call.html#functions">Functions</a>
+          <dd>
+            <dl class="index">
+              <dt><a href="call.html#call-spec">call</a>
+            </dl>
+        </dl>
+
+      <dt><a href="call_method.html">call_method.hpp</a>
+
+      <dd>
+        <dl class="index">
+          <dt><a href="call_method.html#functions">Functions</a>
+
+          <dd>
+            <dl class="index">
+              <dt><a href=
+              "call_method.html#call_method-spec">call_method</a>
+            </dl>
+        </dl>
+
+      <dt><a href="data_members.html">data_members.hpp</a>
+
+      <dd>
+        <dl class="index">
+          <dt><a href="data_members.html#functions">Functions</a>
+
+          <dd>
+            <dl class="index">
+              <dt><a href=
+              "data_members.html#make_getter-spec">make_getter</a>
+
+              <dt><a href=
+              "data_members.html#make_setter-spec">make_setter</a>
+            </dl>
+        </dl>
+
+      <dt><a href="make_function.html">make_function.hpp</a>
+
+      <dd>
+        <dl class="index">
+          <dt><a href="make_function.html#classes">Functions</a>
+
+          <dd>
+            <dl class="index">
+              <dt><a href=
+              "make_function.html#make_function-spec">make_function</a>
+
+              <dt><a href=
+              "make_function.html#make_constructor-spec">make_constructor</a>
+            </dl>
+        </dl>
+
+      <dt><a href="ptr.html">ptr.hpp</a>
+
+      <dd>
+        <dl class="index">
+          <dt><a href="ptr.html#functions">Functions</a>
+
+          <dd>
+            <dl class="index">
+              <dt><a href="ptr.html#ptr-spec">ptr</a>
+            </dl>
+
+          <dt><a href="ptr.html#classes">Classes</a>
+
+          <dd>
+            <dl class="index">
+              <dt><a href=
+              "ptr.html#pointer_wrapper-spec">pointer_wrapper</a>
+            </dl>
+
+          <dt><a href="ptr.html#metafunctions">MetaFunctions</a>
+
+          <dd>
+            <dl class="index">
+              <dt><a href=
+              "ptr.html#is_pointer_wrapper-spec">is_pointer_wrapper</a>
+
+              <dt><a href=
+              "ptr.html#unwrap_pointer-spec">unwrap_pointer</a>
+            </dl>
+        </dl>
+        <a name="models_of_call_policies"></a> 
+
+        <h3>Models of CallPolicies</h3>
+
+        <dl class="index">
+          <dt><a href=
+          "default_call_policies.html">default_call_policies.hpp</a>
+
+          <dd>
+            <dl class="index">
+              <dt><a href=
+              "default_call_policies.html#classes">Classes</a>
+
+              <dd>
+                <dl class="index">
+                  <dt><a href= 
+                  "default_call_policies.html#default_call_policies-spec">
+                  default_call_policies</a>
+
+                  <dt><a href= 
+                  "default_call_policies.html#default_result_converter-spec">
+                  default_result_converter</a>
+                </dl>
+            </dl>
+
+          <dt><a href=
+          "return_internal_reference.html">return_internal_reference.hpp</a>
+
+          <dd>
+            <dl class="index">
+              <dt><a href=
+              "return_internal_reference.html#classes">Classes</a>
+
+              <dd>
+                <dl class="index">
+                  <dt><a href= 
+                  "return_internal_reference.html#return_internal_reference-spec">
+                  return_internal_reference</a>
+                </dl>
+            </dl>
+
+          <dt><a href=
+          "return_value_policy.html">return_value_policy.hpp</a>
+
+          <dd>
+            <dl class="index">
+              <dt><a href=
+              "return_value_policy.html#classes">Classes</a>
+
+              <dd>
+                <dl class="index">
+                  <dt><a href= 
+                  "return_value_policy.html#return_value_policy-spec">return_value_policy</a>
+                </dl>
+            </dl>
+
+          <dt><a href=
+          "with_custodian_and_ward.html">with_custodian_and_ward.hpp</a>
+
+          <dd>
+            <dl class="index">
+              <dt><a href=
+              "with_custodian_and_ward.html#classes">Classes</a>
+
+              <dd>
+                <dl class="index">
+                  <dt><a href= 
+                  "with_custodian_and_ward.html#with_custodian_and_ward-spec">
+                  with_custodian_and_ward</a>
+
+                  <dt><a href= 
+                  "with_custodian_and_ward.html#with_custodian_and_ward_postcall-spec">
+                  with_custodian_and_ward_postcall</a>
+                </dl>
+            </dl>
+        </dl>
+        <a name="models_of_result_converter"></a> 
+
+        <h3>Models of ResultConverter</h3>
+
+        <dl class="index">
+          <dt><a href=
+          "to_python_indirect.html">to_python_indirect.hpp</a>
+
+          <dd>
+            <dl class="index">
+              <dt><a href="to_python_indirect.html#classes">Classes</a>
+
+              <dd>
+                <dl class="index">
+                  <dt><a href= 
+                  "to_python_indirect.html#to_python_indirect-spec">to_python_indirect</a>
+                </dl>
+            </dl>
+
+          <dt><a href="to_python_value.html">to_python_value.hpp</a>
+
+          <dd>
+            <dl class="index">
+              <dt><a href="to_python_value.html#classes">Classes</a>
+
+              <dd>
+                <dl class="index">
+                  <dt><a href=
+                  "to_python_value.html#to_python_value-spec">to_python_value</a>
+                </dl>
+            </dl>
+        </dl>
+        <a name="result_converter_generators"></a> 
+
+        <h3>Models of ResultConverterGenerator</h3>
+
+        <dl class="index">
+          <dt><a href=
+          "copy_const_reference.html">copy_const_reference.hpp</a>
+
+          <dd>
+            <dl class="index">
+              <dt><a href=
+              "copy_const_reference.html#classes">Classes</a>
+
+              <dd>
+                <dl class="index">
+                  <dt><a href= 
+                  "copy_const_reference.html#copy_const_reference-spec">
+                  copy_const_reference</a>
+                </dl>
+            </dl>
+
+          <dt><a href=
+          "copy_non_const_reference.html">copy_non_const_reference.hpp</a>
+
+          <dd>
+            <dl class="index">
+              <dt><a href=
+              "copy_non_const_reference.html#classes">Classes</a>
+
+              <dd>
+                <dl class="index">
+                  <dt><a href= 
+                  "copy_non_const_reference.html#copy_non_const_reference-spec">
+                  copy_non_const_reference</a>
+                </dl>
+            </dl>
+
+          <dt><a href=
+          "manage_new_object.html">manage_new_object.hpp</a>
+
+          <dd>
+            <dl class="index">
+              <dt><a href="manage_new_object.html#classes">Classes</a>
+
+              <dd>
+                <dl class="index">
+                  <dt><a href= 
+                  "manage_new_object.html#manage_new_object-spec">manage_new_object</a>
+                </dl>
+            </dl>
+
+          <dt><a href=
+          "reference_existing_object.html">reference_existing_object.hpp</a>
+
+          <dd>
+            <dl class="index">
+              <dt><a href=
+              "reference_existing_object.html#classes">Classes</a>
+
+              <dd>
+                <dl class="index">
+                  <dt><a href= 
+                  "reference_existing_object.html#reference_existing_object-spec">
+                  reference_existing_object</a>
+                </dl>
+            </dl>
+        </dl>
+    </dl>
+
+    <h2><a name="type_conversion">To/From Python Type
+    Conversion</a></h2>
+
+    <dl class="index">
+      <dt><a href="from_python.html">from_python.hpp</a>
+
+      <dd>
+        <dl class="index">
+          <dt><a href="from_python.html#classes">Classes</a>
+
+          <dd>
+            <dl class="index">
+              <dt><a href=
+              "from_python.html#from_python-spec">from_python</a>
+            </dl>
+        </dl>
+
+      <dt><a href="implicit.html">implicit.hpp</a>
+
+      <dd>
+        <dl class="index">
+          <dt><a href="implicit.html#functions">Functions</a>
+
+          <dd>
+            <dl class="index">
+              <dt><a href=
+              "implicit.html#implicitly_convertible-spec">implicitly_convertible</a>
+            </dl>
+        </dl>
+
+      <dt><a href="lvalue_from_pytype.html">lvalue_from_pytype.hpp</a>
+
+      <dd>
+        <dl class="index">
+          <dt><a href="lvalue_from_pytype.html#classes">Classes</a>
+
+          <dd>
+            <dl class="index">
+              <dt><a href= 
+              "lvalue_from_pytype.html#lvalue_from_pytype-spec">lvalue_from_pytype</a>
+
+              <dt><a href=
+              "lvalue_from_pytype.html#extract_identity-spec">extract_identity</a>
+
+              <dt><a href=
+              "lvalue_from_pytype.html#extract_member-spec">extract_member</a>
+            </dl>
+        </dl>
+
+      <dt><a href=
+      "to_python_converter.html">to_python_converter.hpp</a>
+
+      <dd>
+        <dl class="index">
+          <dt><a href="to_python_converter.html#classes">Classes</a>
+
+          <dd>
+            <dl class="index">
+              <dt><a href= 
+              "to_python_converter.html#to_python_converter-spec">to_python_converter</a>
+            </dl>
+        </dl>
+
+    </dl>
+
+    <h2><a name="utility">Utility and Infrastructure</a></h2>
+
+    <dl>
+      <dt><a href="has_back_reference.html">has_back_reference.hpp</a>
+
+      <dd>
+        <dl class="index">
+          <dt><a href="has_back_reference.html#classes">Classes</a>
+
+          <dd>
+            <dl class="index">
+              <dt><a href= 
+              "has_back_reference.html#has_back_reference-spec">has_back_reference</a>
+            </dl>
+        </dl>
+
+      <dt><a href="instance_holder.html">instance_holder.hpp</a>
+
+      <dd>
+        <dl class="index">
+          <dt><a href="instance_holder.html#classes">Classes</a>
+
+          <dd>
+            <dl class="index">
+              <dt><a href=
+              "instance_holder.html#instance_holder-spec">instance_holder</a>
+            </dl>
+        </dl>
+
+      <dt><a href="pointee.html">pointee.hpp</a>
+
+      <dd>
+        <dl class="index">
+          <dt><a href="pointee.html#classes">Classes</a>
+
+          <dd>
+            <dl class="index">
+              <dt>class template <a href=
+              "pointee.html#pointee">pointee</a>
+            </dl>
+        </dl>
+
+      <dt><a href="reference_hpp.html">reference.hpp</a>
+
+      <dd>
+        <dl class="index">
+          <dt><a href="reference_hpp.html#classes">Classes</a>
+
+          <dd>
+            <dl class="index">
+              <dt><a href=
+              "reference_hpp.html#reference-spec">reference</a>
+            </dl>
+
+          <dt><a href="reference_hpp.html#types">Types</a>
+
+          <dd>
+            <dl class="index">
+              <dt><a href="reference_hpp.html#ref-spec">ref</a>
+            </dl>
+        </dl>
+
+      <dt><a href="type_id.html">type_id.hpp</a>
+
+      <dd>
+        <dl class="index">
+          <dt><a href="type_id.html#functions">Functions</a>
+
+          <dd>
+            <dl class="index">
+              <dt><a href="type_id.html#type_id-spec">type_id</a>
+            </dl>
+
+          <dt><a href="type_id.html#classes">Classes</a>
+
+          <dd>
+            <dl class="index">
+              <dt><a href="type_id.html#type_info-spec">type_info</a>
+            </dl>
+        </dl>
+    </dl>
+    <hr>
+
+    <p>Revised 
+    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+    3 June, 2002 
+    <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+
+
+    <p class="c3">&copy; Copyright <a href= 
+    "../../../../people/dave_abrahams.htm">Dave Abrahams</a> 2002. All
+    Rights Reserved.
+

doc/v2/reference_existing_object.html

@@ -0,0 +1,161 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+    <meta name="generator" content="HTML Tidy, see www.w3.org">
+    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+    <link rel="stylesheet" type="text/css" href="../boost.css">
+
+    <title>Boost.Python -
+    &lt;boost/python/reference_existing_object.hpp&gt;</title>
+
+    <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+      <tr>
+        <td valign="top" width="300">
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+
+        <td valign="top">
+          <h1 align="center">Boost.Python</h1>
+
+          <h2 align="center">Header
+          &lt;boost/python/reference_existing_object.hpp&gt;</h2>
+    </table>
+    <hr>
+
+    <h2>Contents</h2>
+
+    <dl class="page-index">
+      <dt><a href="#classes">Classes</a>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#reference_existing_object-spec">Class
+          <code>reference_existing_object</code></a>
+
+          <dd>
+            <dl class="page-index">
+              <dt><a href="#reference_existing_object-spec-synopsis">Class
+              <code>reference_existing_object</code> synopsis</a>
+
+              <dt><a href="#reference_existing_object-spec-metafunctions">Class
+              <code>reference_existing_object</code> metafunctions</a>
+            </dl>
+        </dl>
+
+      <dt><a href="#examples">Example</a>
+    </dl>
+    <hr>
+
+    <h2><a name="classes"></a>Classes</h2>
+
+    <h3><a name="reference_existing_object-spec"></a>Class
+    <code>reference_existing_object</code></h3>
+
+    <p><code>reference_existing_object</code> is a model of <a href=
+    "ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a> which can be
+    used to wrap C++ functions which return a reference or pointer to a C++
+    object. When the wrapped function is called, the value referenced by its
+    return value is not copied. A new Python object is created which contains a
+    pointer to the referent, and no attempt is made to ensure that the lifetime
+    of the referent is at least as long as that of the corresponding Python
+    object. Thus, it can be <font color="#ff0000"><b>highly
+    dangerous</b></font> to use <code>reference_existing_object</code> without
+    additional lifetime management from such models of <a href=
+    "CallPolicies.html">CallPolicies</a> as <a href=
+    "with_custodian_and_ward.html#with_custodian_and_ward-spec">with_custodian_and_ward</a>.
+    This class is used in the implementation of <a href=
+    "return_internal_reference.html#return_internal_reference-spec">return_internal_reference</a>.
+
+    <h4><a name="reference_existing_object-spec-synopsis"></a>Class
+    <code>reference_existing_object</code> synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+    struct reference_existing_object
+    {
+        template &lt;class T&gt; struct apply;
+    };
+}}
+</pre>
+
+    <h4><a name="reference_existing_object-spec-metafunctions"></a>Class
+    <code>reference_existing_object</code> metafunctions</h4>
+<pre>
+template &lt;class T&gt; struct apply
+</pre>
+
+    <dl class="metafunction-semantics">
+      <dt><b>Requires:</b> <code>T</code> is <code>U&amp;</code> or
+      <code>U*</code>for some <code>U</code>.
+
+      <dt><b>Returns:</b> <code>typedef <a href=
+      "to_python_indirect.html#to_python_indirect-spec">to_python_indirect</a>&lt;T,V&gt;
+      type</code>, where <code>V</code> is a <a href=
+      "to_python_indirect.html#HolderObjectGenerator">HolderObjectGenerator</a>
+      which constructs an instance holder containing an <i>unowned</i>
+      <code>U*</code> pointing to the referent of the wrapped function's return
+      value.
+    </dl>
+
+    <h2><a name="examples"></a>Example</h2>
+
+    <p>In C++:
+<pre>
+#include &lt;boost/python/module.hpp&gt;
+#include &lt;boost/python/class.hpp&gt;
+#include &lt;boost/python/reference_existing_object.hpp&gt;
+#include &lt;boost/python/return_value_policy.hpp&gt;
+#include &lt;utility&gt;
+
+// classes to wrap
+struct Singleton
+{
+   Singleton() : x(0) {}
+
+   int exchange(int n)  // set x and return the old value
+   {
+        std::swap(n, x);
+        return n;
+   }
+
+   int x;
+};
+
+Singleton&amp; get_it()
+{
+   static Singleton just_one;
+   return just_one;
+}
+
+// Wrapper code
+using namespace boost::python;
+BOOST_PYTHON_MODULE_INIT(singleton)
+{
+   module("singleton")
+      .def("get_it", get_it)
+      .add(
+         class_&lt;Singleton&gt;()
+            .def("exchange", &amp;Singleton::exchange)
+         );
+}
+</pre>
+    In Python: 
+<pre>
+&gt;&gt;&gt; import singleton
+&gt;&gt;&gt; s1 = singleton.get_it()  
+&gt;&gt;&gt; s2 = singleton.get_it()
+&gt;&gt;&gt; id(s1) == id(s2)  # s1 and s2 are not the same object
+0
+&gt;&gt;&gt; s1.exchange(42)   # but they reference the same C++ Singleton
+0
+&gt;&gt;&gt; s2.exchange(99)
+42
+</pre>
+
+    <p>Revised 
+    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+     14 February 2002 <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+
+
+    <p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
+    Abrahams</a> 2002. All Rights Reserved.</i>
+

doc/v2/return_internal_reference.html

@@ -0,0 +1,210 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+    <meta name="generator" content="HTML Tidy, see www.w3.org">
+    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+    <link rel="stylesheet" type="text/css" href="../boost.css">
+
+    <title>Boost.Python - &lt;boost/python/return_internal_reference.hpp&gt;</title>
+
+    <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+      <tr>
+        <td valign="top" width="300">
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+
+        <td valign="top">
+          <h1 align="center">Boost.Python</h1>
+
+          <h2 align="center">Header &lt;boost/python/return_internal_reference.hpp&gt;</h2>
+    </table>
+    <hr>
+
+    <h2>Contents</h2>
+
+    <dl class="page-index">
+      <dt><a href="#introduction">Introduction</a>
+
+
+      <dt><a href="#classes">Classes</a>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#return_internal_reference-spec">Class Template <code>return_internal_reference</code></a>
+
+          <dd>
+            <dl class="page-index">
+
+              <dt><a href="#return_internal_reference-spec-synopsis">Class Template
+              <code>return_internal_reference</code> synopsis</a>
+
+              <dt><a href="#return_internal_reference-spec-statics">Class
+              <code>return_internal_reference</code> static functions</a>
+            </dl>
+        </dl>
+
+
+      <dt><a href="#examples">Example</a>
+    </dl>
+    <hr>
+
+    <h2><a name="introduction"></a>Introduction</h2>
+
+    <code>return_internal_reference</code> instantiations are models of <a href=
+    "CallPolicies.html">CallPolicies</a> which allow pointers and
+    references to objects held internally by a free or member function
+    argument or from the target of a member function to be returned
+    safely without making a copy of the referent. The default for its
+    first template argument handles the common case where the
+    containing object is the target (<code>*this</code>) of a wrapped
+    member function.
+
+    <h2><a name="classes"></a>Classes</h2>
+
+    <h3><a name="return_internal_reference-spec"></a>Class template <code>return_internal_reference</code></h3>
+
+
+    <table border="1" summary="return_internal_reference template parameters">
+      <caption>
+        <b><code>return_internal_reference</code> template parameters</b>
+      </caption>
+      <tr>
+        <th>Parameter
+        
+        <th>Requirements
+
+        <th>Description
+
+        <th>Default
+
+      <tr>
+        <td><code>owner_arg</code> 
+
+        <td>A positive compile-time constant of type
+        <code>std::size_t</code>.
+
+        <td>The index of the parameter which contains the object to
+        which the reference or pointer is being returned. If used to
+        wrap a member function, parameter 1 is the target object
+        (<code>*this</code>). Note that if the target Python object
+        type doesn't support weak references, a Python
+        <code>TypeError</code> exception will be raised when the
+        function being wrapped is called.
+
+        <td>1
+
+      <tr>
+        <td><code>Base</code> 
+
+        <td>A model of <a href="CallPolicies.html">CallPolicies</a>
+
+        <td>Used for policy composition. Any
+        <code>result_converter</code> it supplies will be overridden by
+        <code>return_internal_reference</code>, but its
+        <code>precall</code> and <code>postcall</code> policies are
+        composed as described here <a
+        href="CallPolicies.html#composition">CallPolicies</a>.
+
+        <td><code><a href="default_call_policies.html#default_call_policies-spec">default_call_policies</a></code>
+
+    </table>
+
+    <h4><a name="return_internal_reference-spec-synopsis"></a>Class template <code>return_internal_reference</code> synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+   template &lt;std::size_t owner_arg = 1, class Base = default_call_policies&gt;
+   struct return_internal_reference : Base
+   {
+      static PyObject* postcall(PyObject*, PyObject* result);
+      typedef <a href="reference_existing_object.html#reference_existing_object-spec">reference_existing_object</a> result_converter;
+   };
+}}
+</pre>
+
+    <h4><a name="default_call_policies-spec-statics"></a>Class
+    <code>default_call_policies</code> static functions</h4>
+
+<pre>
+PyObject* postcall(PyObject* args, PyObject* result);
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Requires:</b> <code><a href="http://www.python.org/doc/2.2/api/tupleObjects.html#l2h-476">PyTuple_Check</a>(args) != 0</code>
+
+      <dt><b>Returns:</b> <code><a href="with_custodian_and_ward.html#with_custodian_and_ward_postcall-spec-statics">with_custodian_and_ward_postcall::postcall(args, result)</a></code>
+    </dl>
+
+
+    <h2><a name="examples"></a>Example</h2>
+
+<h3>C++ module definition</h3>
+
+<pre>
+#include &lt;boost/python/module.hpp&gt;
+#include &lt;boost/python/class.hpp&gt;
+#include &lt;boost/python/return_internal_reference.hpp&gt;
+
+class Bar
+{
+   Bar(int x) : x(x) {}
+   int get_x() const { return x; }
+   void set_x(int x) { this-&gt;x = x; }
+ private:
+   int x;
+}
+
+class Foo
+{
+ public:
+   Foo(int x) : b(x) {}
+
+   // Returns an internal reference
+   Bar const&amp; get_bar() const { return b; }
+
+ private:
+   Bar b;
+};
+
+using namespace boost::python;
+BOOST_PYTHON_MODULE_INIT(internal_refs)
+{
+   module m(&quot;internal_refs&quot;)
+      .add(
+         class_&lt;Bar&gt;()
+            .def(&quot;get_x&quot;, &amp;Bar::get_x)
+            .def(&quot;set_x&quot;, &amp;Bar::set_x)
+         )
+      .add(
+         class_&lt;Foo&gt;()
+            .def_init(args&lt;int&gt;())
+            .def(&quot;get_bar&quot;, &amp;Foo::get_bar
+                , return_internal_reference&lt;&gt;())
+         )
+      ;
+}
+</pre>
+
+<h3>Python code</h3>
+
+<pre>
+&gt;&gt;&gt; from internal_refs import *
+&gt;&gt;&gt; f = Foo(3)
+&gt;&gt;&gt; b1 = f.get_bar()
+&gt;&gt;&gt; b2 = f.get_bar()
+&gt;&gt;&gt; b1.get_x()
+3
+&gt;&gt;&gt; b2.get_x()
+3
+&gt;&gt;&gt; b1.set_x(42)
+&gt;&gt;&gt; b2.get_x()
+42
+</pre>
+
+    <p>Revised 
+    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+    15 February, 2002
+    <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+
+    <p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
+    Abrahams</a> 2002. All Rights Reserved.</i>
+

doc/v2/return_value_policy.html

@@ -0,0 +1,148 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+    <meta name="generator" content="HTML Tidy, see www.w3.org">
+    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+    <link rel="stylesheet" type="text/css" href="../boost.css">
+
+    <title>Boost.Python - &lt;boost/python/return_value_policy.hpp&gt;</title>
+
+    <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+      <tr>
+        <td valign="top" width="300">
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+
+        <td valign="top">
+          <h1 align="center">Boost.Python</h1>
+
+          <h2 align="center">Header &lt;boost/python/return_value_policy.hpp&gt;</h2>
+    </table>
+    <hr>
+
+    <h2>Contents</h2>
+
+    <dl class="page-index">
+      <dt><a href="#introduction">Introduction</a>
+
+
+      <dt><a href="#classes">Classes</a>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#return_value_policy-spec">Class Template <code>return_value_policy</code></a>
+
+          <dd>
+            <dl class="page-index">
+
+              <dt><a href="#return_value_policy-spec-synopsis">Class Template
+              <code>return_value_policy</code> synopsis</a>
+            </dl>
+        </dl>
+
+
+      <dt><a href="#examples">Example</a>
+    </dl>
+    <hr>
+
+    <h2><a name="introduction"></a>Introduction</h2>
+
+    <code>return_value_policy</code> instantiations are simply models
+    of <a href=
+    "CallPolicies.html">CallPolicies</a> which are composed of a <a href=
+    "ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a> and optional <code>Base</code> <a href=
+    "CallPolicies.html">CallPolicies</a>.
+
+    <h2><a name="classes"></a>Classes</h2>
+
+    <h3><a name="return_value_policy-spec"></a>Class template <code>return_value_policy</code></h3>
+
+
+    <table border="1" summary="return_value_policy template parameters">
+      <caption>
+        <b><code>return_value_policy</code> template parameters</b>
+      </caption>
+      <tr>
+        <th>Parameter
+        
+        <th>Requirements
+
+        <th>Default
+
+      <tr>
+        <td><a href="ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a>
+
+        <td>A model of <a href=
+    "ResultConverterGenerator.html">ResultConverterGenerator</a>.
+
+      <tr>
+        <td><code>Base</code> 
+
+        <td>A model of <a href="CallPolicies.html">CallPolicies</a>
+
+        <td><code><a href="default_call_policies.html#default_call_policies-spec">default_call_policies</a></code>
+
+    </table>
+
+    <h4><a name="return_value_policy-spec-synopsis"></a>Class template <code>return_value_policy</code> synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+  template &lt;class ResultConverterGenerator, class Base = default_call_policies&gt;
+  struct return_value_policy : Base
+  {
+      typedef ResultConverterGenerator result_converter;
+  };
+}}
+</pre>
+
+    <h2><a name="examples"></a>Example</h2>
+
+<h3>C++ Module Definition</h3>
+<pre>
+#include &lt;boost/python/module.hpp&gt;
+#include &lt;boost/python/class.hpp&gt;
+#include &lt;boost/python/copy_const_reference.hpp&gt;
+#include &lt;boost/python/return_value_policy.hpp&gt;
+
+// classes to wrap
+struct Bar { int x; }
+
+struct Foo {
+   Foo(int x) : { b.x = x; }
+   Bar const&amp; get_bar() const { return b; }
+ private:
+   Bar b;
+};
+
+// Wrapper code
+using namespace boost::python;
+BOOST_PYTHON_MODULE_INIT(my_module)
+{
+   module("my_module")
+      .add(
+         class_&lt;Bar&gt;()
+         )
+      .add(
+         class_&lt;Foo&gt;()
+            .def_init(args&lt;int&gt;())
+            .def("get_bar", &amp;Foo::get_bar
+                , return_value_policy&lt;copy_const_reference&gt;())
+         )
+       ;
+}
+</pre>
+<h3>Python Code</h3>
+<pre>
+&gt;&gt;&gt; from my_module import *
+&gt;&gt;&gt; f = Foo(3)         # create a Foo object
+&gt;&gt;&gt; b = f.get_bar()    # make a copy of the internal Bar object
+</pre>
+
+    <p>Revised 
+    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+    15 February, 2002
+    <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+
+    <p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
+    Abrahams</a> 2002. All Rights Reserved.</i>
+

doc/v2/to_python_converter.html

@@ -0,0 +1,189 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+    <meta name="generator" content="HTML Tidy, see www.w3.org">
+    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+    <link rel="stylesheet" type="text/css" href="../boost.css">
+
+    <title>Boost.Python - &lt;boost/python/to_python_converter.hpp&gt;</title>
+
+    <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+      <tr>
+        <td valign="top" width="300">
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+
+        <td valign="top">
+          <h1 align="center">Boost.Python</h1>
+
+          <h2 align="center">Header &lt;boost/python/to_python_converter.hpp&gt;</h2>
+    </table>
+    <hr>
+
+    <h2>Contents</h2>
+
+    <dl class="page-index">
+      <dt><a href="#introduction">Introduction</a>
+
+
+      <dt><a href="#classes">Classes</a>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#to_python_converter-spec">Class Template <code>to_python_converter</code></a>
+
+          <dd>
+            <dl class="page-index">
+
+              <dt><a href="#to_python_converter-spec-synopsis">Class Template
+              <code>to_python_converter</code> synopsis</a>
+
+              <dt><a href="#to_python_converter-spec-ctors">Class Template
+              <code>to_python_converter</code> constructor</a>
+            </dl>
+        </dl>
+
+      <dt><a href="#examples">Example</a>
+    </dl>
+    <hr>
+
+    <h2><a name="introduction"></a>Introduction</h2>
+
+    <code>to_python_converter</code> registers a conversion from
+    objects of a given C++ type into a Python object.
+
+    <h2><a name="classes"></a>Classes</h2>
+
+    <h3><a name="to_python_converter-spec"></a>Class template <code>to_python_converter</code></h3>
+
+    <code>to_python_converter</code> adds a wrapper around a static
+    member function of its second template parameter, handling
+    low-level details such as insertion into the converter registry.
+
+    <table border="1" summary="to_python_converter template parameters">
+      <caption>
+        <b><code>to_python_converter</code> template parameters</b><br>
+In the table below, <b><code>x</code></b> denotes an object of type <code>T</code>
+      </caption>
+      <tr>
+        <th>Parameter
+        
+        <th>Requirements
+
+        <th>Description
+
+      <tr>
+        <td><code>T</code> 
+
+        <td>
+
+        <td>The C++ type of the source object in the conversion
+
+      <tr>
+        <td><code>Conversion</code> 
+
+        <td><code>PyObject*&nbsp;p&nbsp;=&nbsp;Conversion::convert(x)</code>,<br>
+        if <code>p&nbsp;==&nbsp;0</code>, <code><a href="http://www.python.org/doc/2.2/api/exceptionHandling.html#l2h-71">PyErr_Occurred</a>()&nbsp;!=&nbsp;0</code>.
+
+        <td>A class type whose static member function
+        <code>convert</code> does the real work of the conversion.
+
+      <tr>
+    </table>
+
+    <h4><a name="to_python_converter-spec-synopsis"></a>Class template <code>to_python_converter</code> synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+  template &lt;class T, class Conversion&gt;
+  struct to_python_converter
+  {
+      to_python_converter();
+  };
+}}
+</pre>
+
+    <h4><a name="to_python_converter-spec-ctors"></a>Class template <code>to_python_converter</code> constructor</h4>
+<pre>
+to_python_converter();
+</pre>
+
+    <dl class="function-semantics">
+
+      <dt><b>Effects:</b> Registers a to_python converter which uses
+      <code>Conversion::convert()</code> to do its work.
+
+    </dl>
+
+    <h2><a name="examples"></a>Example</h2>
+
+This example presumes that someone has implemented the standard <a
+href="http://www.python.org/doc/2.2/ext/dnt-basics.html">noddy example
+module</a> from the Python documentation, and placed the corresponding
+declarations in <code>&quot;noddy.h&quot;</code>.  Because
+<code>noddy_NoddyObject</code> is the ultimate trivial extension type,
+the example is a bit contrived: it wraps a function for which all
+information is contained in the <i>type</i> of its return value.
+
+<h3>C++ module definition</h3>
+
+<pre>
+#include &lt;boost/python/reference.hpp&gt;
+#include &lt;boost/python/module.hpp&gt;
+#include &quot;noddy.h&quot;
+
+struct tag {};
+tag make_tag() { return tag(); }
+
+using namespace boost::python;
+
+struct tag_to_noddy
+{
+    static PyObject* convert(tag const&amp; x)
+    {
+        return PyObject_New(noddy_NoddyObject, &amp;noddy_NoddyType);
+    }
+};
+
+BOOST_PYTHON_MODULE_INIT(to_python_converter)
+{
+    module(&quot;to_python_converter&quot;)
+        .def(&quot;make_tag&quot;, make_tag)
+        ;
+    to_python_converter&lt;tag, tag_to_noddy&gt;();
+}
+</pre>
+
+<h3>Python code</h3>
+
+<pre>
+&gt;&gt;&gt; import to_python_converter
+&gt;&gt;&gt; def always_none():
+...     return None
+...
+&gt;&gt;&gt; def choose_function(x):
+...     if (x % 2 != 0):
+...         return to_python_converter.make_tag
+...     else:
+...         return always_none
+...
+&gt;&gt;&gt; a = [ choose_function(x) for x in range(5) ]
+&gt;&gt;&gt; b = [ f() for f in a ]
+&gt;&gt;&gt; type(b[0])
+&lt;type 'NoneType'&gt;
+&gt;&gt;&gt; type(b[1])
+&lt;type 'Noddy'&gt;
+&gt;&gt;&gt; type(b[2])
+&lt;type 'NoneType'&gt;
+&gt;&gt;&gt; type(b[3])
+&lt;type 'Noddy'&gt;
+</pre>
+
+    <p>Revised 
+    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+     05 November, 2001 
+    <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+
+
+    <p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
+    Abrahams</a> 2002. All Rights Reserved.</i>
+

doc/v2/to_python_indirect.html

@@ -0,0 +1,194 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+    <meta name="generator" content="HTML Tidy, see www.w3.org">
+    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+    <link rel="stylesheet" type="text/css" href="../boost.css">
+
+    <title>Boost.Python - &lt;boost/python/to_python_indirect.hpp&gt;</title>
+
+    <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+      <tr>
+        <td valign="top" width="300">
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+
+        <td valign="top">
+          <h1 align="center">Boost.Python</h1>
+
+          <h2 align="center">Header &lt;boost/python/to_python_indirect.hpp&gt;</h2>
+    </table>
+    <hr>
+
+    <h2>Contents</h2>
+
+    <dl class="page-index">
+      <dt><a href="#introduction">Introduction</a>
+
+
+      <dt><a href="#classes">Classes</a>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#to_python_indirect-spec">Class Template <code>to_python_indirect</code></a>
+
+          <dd>
+            <dl class="page-index">
+
+              <dt><a href="#to_python_indirect-spec-synopsis">Class Template
+              <code>to_python_indirect</code> synopsis</a>
+
+              <dt><a href="#to_python_indirect-spec-observers">Class Template
+              <code>to_python_indirect</code> observer functions</a>
+
+              <dt><a href="#to_python_indirect-spec-statics">Class Template
+              <code>to_python_indirect</code> static functions</a>
+            </dl>
+        </dl>
+
+      <dt><a href="#examples">Example</a>
+    </dl>
+    <hr>
+
+    <h2><a name="introduction"></a>Introduction</h2>
+
+    <code>&lt;boost/python/to_python_indirect.hpp&gt;</code> supplies
+    a way to construct new Python objects that hold wrapped C++ class
+    instances via a pointer or smart pointer.
+
+    <h2><a name="classes"></a>Classes</h2>
+
+    <h3><a name="to_python_indirect-spec"></a>Class template <code>to_python_indirect</code></h3>
+    <p>Class template <code>to_python_indirect</code> converts objects
+of its first argument type to python as extension class instances, using the ownership policy provided by its 2nd argument.
+
+    <p>
+
+
+    <table border="1" summary="to_python_indirect template parameters">
+      <caption>
+        <b><code>to_python_indirect</code> Requirements</b><br>
+
+        In the table below, <b><code>x</code></b> denotes an object of
+        type <code>T</code>, <b><code>h</code></b> denotes an
+        object of type
+        <code>boost::python::objects::instance_holder*</code>, and
+        <b><code>p</code></b> denotes an object of type
+        <code>U*</code>.
+
+      </caption>
+      <tr>
+        <th>Parameter
+        
+        <th>Requirements
+
+        <th>Description
+
+      <tr>
+        <td><code>T</code> 
+
+        <td>Either <code>U</code>&nbsp;<i>cv</i><code>&amp;</code>
+        (where <i>cv</i> is any optional cv-qualification) or a <a
+        href="Dereferenceable.html">Dereferenceable</a> type such that
+        <code>*x</code> is convertible to <code>U const&amp;</code>, where
+        <code>U</code> is a class type.
+
+        <td>A type deferencing a C++ class exposed to Python using
+        class template <code><a
+        href="class.html#class_-spec">class_</a></code>.
+
+      <tr>
+        <td><code>MakeHolder</code> 
+
+        <td>h = MakeHolder::execute(p);
+
+        <td>A class whose static <code>execute()</code> creates an
+        <code>instance_holder</code>.
+
+    </table>
+
+    Instantiations of <code>to_python_indirect</code> are models of <a
+    href="ResultConverter.html#ResultConverter-concept">ResultConverter</a>.
+
+
+    <h4><a name="to_python_indirect-spec-synopsis"></a>Class template <code>to_python_indirect</code> synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+  template &lt;class T, class MakeHolder&gt;
+  struct to_python_indirect
+  {
+     static bool convertible();
+     PyObject* operator()(T ptr_or_reference) const;
+   private:
+     static PyTypeObject* type();
+  };
+}}
+</pre>
+
+    <h4><a name="to_python_indirect-spec-observers"></a>Class template <code>to_python_indirect</code> observers</h4>
+<pre>
+PyObject* operator()(T x) const;
+</pre>
+
+    <dl class="function-semantics">
+
+      <dt><b>Requires:</b> <code>x</code> refers to an object (if it
+      is a pointer type, it is non-null). <code>convertible() ==
+      true</code>.
+
+      <dt><b>Effects:</b> Creates an appropriately-typed Boost.Python
+      extension class instance, uses <code>MakeHolder</code> to create
+      an <code>instance_holder</code> from <code>x</code>, installs
+      the <code>instance_holder</code> in the new extension class
+      instance, and returns a pointer to it.
+
+    </dl>
+
+
+    <h4><a name="to_python_indirect-spec-statics"></a>Class template <code>to_python_indirect</code> statics</h4>
+<pre>
+bool convertible();
+</pre>
+
+      <dt><b>Effects:</b> Returns <code>true</code> iff any module has
+      registered a Python type corresponding to <code>U</code>.
+
+    <h2><a name="examples"></a>Example</h2>
+
+This example replicates the functionality of <a
+href="reference_existing_object.html#reference_existing_object-spec">reference_existing_object</a>,
+but without some of the compile-time error checking.
+
+
+<pre>
+
+struct make_reference_holder
+{
+   typedef boost::python::objects::instance_holder* result_type;
+   template &lt;class T&gt;
+   static result_type execute(T* p)
+   {
+      return new boost::python::objects::pointer_holder&lt;T*, T&gt;(p);
+   }
+};
+
+struct reference_existing_object
+{
+   // metafunction returning the <a href="ResultConverter.html#ResultConverter-concept">ResultConverter</a>
+   template &lt;class T&gt;
+   struct apply
+   {
+      typedef boost::python::to_python_indirect&lt;T,make_reference_holder&gt; type;
+   };
+};
+</pre>
+
+    <p>Revised 
+    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+     16 February, 2002
+    <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+
+
+    <p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
+    Abrahams</a> 2002. All Rights Reserved.</i>
+

doc/v2/to_python_value.html

@@ -0,0 +1,101 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+    <meta name="generator" content="HTML Tidy, see www.w3.org">
+    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+    <link rel="stylesheet" type="text/css" href="../boost.css">
+
+    <title>Boost.Python - &lt;boost/python/to_python_value.hpp&gt;</title>
+
+    <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+      <tr>
+        <td valign="top" width="300">
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+
+        <td valign="top">
+          <h1 align="center">Boost.Python</h1>
+
+          <h2 align="center">Header
+          &lt;boost/python/to_python_value.hpp&gt;</h2>
+    </table>
+    <hr>
+
+    <h2>Contents</h2>
+
+    <dl class="page-index">
+      <dt><a href="#classes">Classes</a>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#to_python_value-spec">Class
+          <code>to_python_value</code></a>
+
+          <dd>
+            <dl class="page-index">
+              <dt><a href="#to_python_value-spec-synopsis">Class template
+              <code>to_python_value</code> synopsis</a>
+
+              <dt><a href="#to_python_value-spec-observers">Class template
+              <code>to_python_value</code> observer functions</a>
+            </dl>
+        </dl>
+
+    </dl>
+    <hr>
+
+    <h2><a name="classes"></a>Classes</h2>
+
+    <h3><a name="to_python_value-spec"></a>Class template
+    <code>to_python_value</code></h3>
+
+    <p><code>to_python_value</code> is a model of <a href=
+    "ResultConverter.html#ResultConverter-concept">ResultConverter</a>
+    which copies its argument into a new Python object.
+
+    <h4><a name="to_python_value-spec-synopsis"></a>Class
+    <code>to_python_value</code> synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+   template &lt;class T&gt;
+   struct to_python_value
+   {
+      typedef typename <a href="../../../type_traits/index.htm#transformations">add_reference</a>&lt;
+         typename <a href="../../../type_traits/index.htm#transformations">add_const</a>&lt;T&gt;::type
+      &gt;::type argument_type;
+
+      static bool convertible();
+      PyObject* operator()(argument_type) const;
+   };
+}}
+</pre>
+
+    <h4><a name="to_python_value-spec-observers"></a>Class
+    <code>to_python_value</code> observers</h4>
+<pre>
+static bool convertible();
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Returns:</b> <code>true</code> iff a converter has been registered which can convert <code>T</code> to python by-value.
+    </dl>
+
+<pre>
+PyObject* operator()(argument_type x) const;
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Requires:</b> <code>convertible()&nbsp;==&nbsp;true</code>
+      <dt><b>Effects:</b> converts <code>x</code> to python 
+      <dt><b>Returns:</b> the resulting Python object iff a converter for <code>T</code> has been registered, <code>0</code> otherwise.
+    </dl>
+
+    <p>Revised 
+    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+     15 February, 2002
+    <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+
+
+    <p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
+    Abrahams</a> 2002. All Rights Reserved.</i>
+

doc/v2/type_id.html

@@ -0,0 +1,219 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+
+    <meta name="generator" content="HTML Tidy, see www.w3.org">
+    <meta http-equiv="Content-Type" content=
+    "text/html; charset=iso-8859-1">
+    <link rel="stylesheet" type="text/css" href="../boost.css">
+
+    <title>Boost.Python - &lt;boost/python/type_id.hpp&gt;</title>
+<style type="text/css">
+ p.c4 {font-style: italic}
+ span.c3 {color: #ff0000}
+ h2.c2 {text-align: center}
+ h1.c1 {text-align: center}
+</style>
+
+    <table border="0" cellpadding="7" cellspacing="0" width="100%"
+    summary="header">
+      <tr>
+        <td valign="top" width="300">
+          <h3><a href="../../../../index.htm"><img height="86" width= 
+          "277" alt="C++ Boost" src="../../../../c++boost.gif" border=
+          "0"></a></h3>
+
+        <td valign="top">
+          <h1 class="c1">Boost.Python</h1>
+
+          <h2 class="c2">Header &lt;boost/python/type_id.hpp&gt;</h2>
+    </table>
+    <hr>
+
+    <h2>Contents</h2>
+
+    <dl class="page-index">
+      <dt><a href="#introduction">Introduction</a>
+
+      <dt><a href="#classes">Classes</a>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#type_info-spec">Class
+          <code>type_info</code></a>
+
+          <dd>
+            <dl class="page-index">
+              <dt><a href="#type_info-spec-synopsis">Class
+              <code>type_info</code> synopsis</a>
+
+              <dt><a href="#type_infospec-ctors">Class
+              <code>type_info</code> constructor</a>
+
+              <dt><a href="#type_infospec-comparisons">Class
+              <code>type_info</code> comparison functions</a>
+
+              <dt><a href="#type_infospec-observers">Class
+              <code>type_info</code> observer functions</a>
+            </dl>
+        </dl>
+
+      <dt><a href="#functions">Functions</a>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#type_id-spec">type_id</a>
+        </dl>
+
+      <dt><a href="#examples">Example</a>
+    </dl>
+    <hr>
+
+    <h2><a name="introduction"></a>Introduction</h2>
+
+    <p><code>&lt;boost/python/type_id.hpp&gt;</code> provides types and
+    functions for runtime type identification like those of of
+    <code>&lt;typeinfo&gt;</code>. It exists mostly to work around
+    certain compiler bugs and platform-dependent interactions with
+    shared libraries.
+
+    <h2><a name="classes"></a>Classes</h2>
+
+    <h3><a name="type_info-spec"></a>Class <code>type_info</code></h3>
+
+    <p><code>type_info</code> instances identify a type. As
+    <code>std::type_info</code> is specified to (but unlike its
+    implementation in some compilers),
+    <code>boost::python::type_info</code> never represents top-level
+    references or cv-qualification (see section 5.2.8 in the C++
+    standard). Unlike <code>std::type_info</code>,
+    <code>boost::python::type_info</code> instances are copyable, and
+    comparisons always work reliably across shared library boundaries.
+
+    <h4><a name="type_info-spec-synopsis"></a>Class type_info
+    synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+  class type_info : <a href= 
+"../../../utility/operators.htm#totally_ordered1">totally_ordered</a>&lt;type_info&gt;
+  {
+   public:
+      // constructor
+      type_info(std::type_info const&amp; = typeid(void));
+
+      // comparisons
+      bool operator&lt;(type_info const&amp; rhs) const;
+      bool operator==(type_info const&amp; rhs) const;
+
+      // observers
+      char const* name() const;
+  };
+}}
+</pre>
+
+    <h4><a name="type_infospec-ctors">Class <code>type_info</code>
+    constructor</a></h4>
+<pre>
+type_info(std::type_info const&amp; = typeid(void));
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Effects:</b> constructs a <code>type_info</code> object
+      which identifies the same type as its argument.
+
+      <dt><b>Rationale:</b> Since it is occasionally neccessary to make
+      an array of <code>type_info</code> objects a benign default
+      argument is supplied. <span class="c3"><b>Note:</b></span> this
+      constructor does <i>not</i> correct for non-conformance of
+      compiler <code>typeid()</code> implementations. See <code><a
+      href="#type_id-spec">type_id</a></code>, below.
+    </dl>
+
+    <h4><a name="type_infospec-comparisons">Class
+    <code>type_info</code> comparisons</a></h4>
+<pre>
+bool operator&lt;(type_info const&amp; rhs) const;
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Effects:</b> yields a total order over
+      <code>type_info</code> objects.
+    </dl>
+<pre>
+bool operator==(type_info const&amp; rhs) const;
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Returns:</b> <code>true</code> iff the two values describe
+      the same type.
+    </dl>
+
+    <dl class="function-semantics">
+      <dt><b>Note:</b> The use of <code><a href= 
+      "../../../utility/operators.htm#totally_ordered1">totally_ordered</a>&lt;type_info&gt;</code>
+      as a private base class supplies operators <code>&lt;=</code>,
+      <code>&gt;=</code>, <code>&gt;</code>, and <code>!=</code>
+    </dl>
+
+    <h4><a name="type_infospec-observers">Class <code>type_info</code>
+    observers</a></h4>
+<pre>
+char const* name() const;
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Returns:</b> The result of calling <code>name()</code> on
+      the argument used to construct the object.
+    </dl>
+
+    <h2><a name="functions"></a>Functions</h2>
+<pre>
+std::ostream&amp; operator&lt;&lt;(std::ostream&amp;s, type_info const&amp;x);
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Effects:</b> Writes a description of the type described by
+      to <code>x</code> into <code>s</code>.
+
+      <dt><b>Rationale:</b> Not every C++ implementation provides a
+      truly human-readable <code>type_info::name()</code> string, but
+      for some we may be able to decode the string and produce a
+      reasonable representation.
+    </dl>
+<pre>
+<a name="type_id-spec">template &lt;class T&gt; type_info type_id</a>()
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Returns:</b> <code>type_info(typeid(T))</code>
+
+      <dt><b>Note:</b> On some non-conforming C++ implementations, the
+      code is not actually as simple as described above; the semantics
+      are adjusted to work <i>as-if</i> the C++ implementation were
+      conforming.
+    </dl>
+
+    <h2><a name="examples"></a>Example</h2>
+    The following example, though silly, illustrates how the
+    <code>type_id</code> facility might be used 
+<pre>
+#include &lt;boost/python/type_id.hpp&gt;
+
+// Returns true iff the user passes an int argument
+template &lt;class T&gt;
+bool is_int(T x)
+{
+   using boost::python::type_id;
+   return type_id&lt;T&gt;() == type_id&lt;int&gt;();
+}
+</pre>
+
+    <p>Revised 
+    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+     18 November, 2002 
+    <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+
+
+    <p class="c4">&copy; Copyright <a href= 
+    "../../../../people/dave_abrahams.htm">Dave Abrahams</a> 2002. All
+    Rights Reserved.
+

doc/v2/with_custodian_and_ward.html

@@ -0,0 +1,289 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+    <meta name="generator" content="HTML Tidy, see www.w3.org">
+    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+    <link rel="stylesheet" type="text/css" href="../boost.css">
+
+    <title>Boost.Python - &lt;boost/python/with_custodian_and_ward.hpp&gt;</title>
+
+    <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+      <tr>
+        <td valign="top" width="300">
+          <h3><a href="../../../../index.htm"><img height="86" width="277" alt=
+          "C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+
+        <td valign="top">
+          <h1 align="center">Boost.Python</h1>
+
+          <h2 align="center">Header &lt;boost/python/with_custodian_and_ward.hpp&gt;</h2>
+    </table>
+    <hr>
+
+    <h2>Contents</h2>
+
+    <dl class="page-index">
+      <dt><a href="#introduction">Introduction</a>
+
+
+      <dt><a href="#classes">Classes</a>
+      <dd>
+
+        <dl class="page-index">
+
+          <dt><a href="#with_custodian_and_ward-spec">Class Template <code>with_custodian_and_ward</code></a>
+          <dd>
+            <dl class="page-index">
+
+              <dt><a href="#with_custodian_and_ward-spec-synopsis">Class Template
+              <code>with_custodian_and_ward</code> synopsis</a>
+
+              <dt><a href="#with_custodian_and_ward-spec-statics">Class
+              <code>with_custodian_and_ward</code> static functions</a>
+            </dl>
+
+          <dt><a href="#with_custodian_and_ward_postcall-spec">Class Template <code>with_custodian_and_ward_postcall</code></a>
+          <dd>
+            <dl class="page-index">
+
+              <dt><a href="#with_custodian_and_ward_postcall-spec-synopsis">Class Template
+              <code>with_custodian_and_ward_postcall</code> synopsis</a>
+
+              <dt><a href="#with_custodian_and_ward_postcall-spec-statics">Class
+              <code>with_custodian_and_ward_postcall</code> static functions</a>
+            </dl>
+        </dl>
+
+
+      <dt><a href="#examples">Example</a>
+    </dl>
+    <hr>
+
+    <h2><a name="introduction">Introduction</a></h2>
+
+    This header provides faciliites for establishing a lifetime
+    dependency between two of a function's Python argument or result
+    objects. The <i>ward</i> object will not be destroyed until after
+    the custodian as long as the <i>custodian</i> object supports <a
+    href="http://www.python.org/doc/current/lib/module-weakref.html">weak
+    references</a> (Boost.Python extension classes all support weak
+    references). The two class templates
+    <code>with_custodian_and_ward</code> and
+    <code>with_custodian_and_ward_postcall</code> differ in the point
+    at which they take effect. 
+
+    <p>In order to reduce the chance of inadvertently
+    creating dangling pointers, the default is to do lifetime binding
+    <i>before</i> the underlying C++ object is invoked. However,
+    before invocation the result object is not available, so
+    <code>with_custodian_and_ward_postcall</code> is provided to bind
+    lifetimes after invocation. Also, if a C++ exception is thrown
+    after <code>with_custodian_and_ward&lt;&gt;::precall</code> but 
+    before the underlying C++ object actually stores a pointer, the
+    lifetime of the custodian and ward objects will be artificially
+    bound together, so one might choose
+    <code>with_custodian_and_ward_postcall</code> instead, depending
+    on the semantics of the function being wrapped.
+
+    <h2><a name="classes"></a>Classes</h2>
+
+    <h3><a name="with_custodian_and_ward-spec"></a>Class template <code>with_custodian_and_ward</code></h3>
+
+
+    <table border="1" summary="with_custodian_and_ward template parameters">
+      <caption>
+        <b><code>with_custodian_and_ward</code> template parameters</b>
+      </caption>
+      <tr>
+        <th>Parameter
+        
+        <th>Requirements
+
+        <th>Description
+
+        <th>Default
+
+      <tr>
+        <td><code>custodian</code> 
+
+        <td>A positive compile-time constant of type
+        <code>std::size_t</code>.
+
+        <td>The 1-based index of the parameter which is the dependency in the
+        lifetime relationship to be established. If used to
+        wrap a member function, parameter 1 is the target object
+        (<code>*this</code>). Note that if the target Python object
+        type doesn't support weak references, a Python
+        <code>TypeError</code> exception will be raised when the
+        C++ object being wrapped is called.
+
+
+      <tr>
+        <td><code>ward</code> 
+
+        <td>A positive compile-time constant of type
+        <code>std::size_t</code>.
+
+        <td>The 1-based index of the parameter which is the dependent in the
+        lifetime relationship to be established. If used to
+        wrap a member function, parameter 1 is the target object
+        (<code>*this</code>). 
+
+
+      <tr>
+        <td><code>Base</code> 
+
+        <td>A model of <a href="CallPolicies.html">CallPolicies</a>
+
+        <td>Used for <a href="CallPolicies.html#composition">policy composition</a>. 
+
+        <td><code><a href="default_call_policies.html#default_call_policies-spec">default_call_policies</a></code>
+
+    </table>
+
+    <h4><a name="with_custodian_and_ward-spec-synopsis"></a>Class template <code>with_custodian_and_ward</code> synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+   template &lt;std::size_t custodian, std::size_t ward, class Base = default_call_policies&gt;
+   struct with_custodian_and_ward : Base
+   {
+      static bool precall(PyObject* args);
+   };
+}}
+</pre>
+
+    <h4><a name="with_custodian_and_ward-spec-statics"></a>Class
+    <code>with_custodian_and_ward</code> static functions</h4>
+
+<pre>
+bool precall(PyObject* args);
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Requires:</b> <code><a href="http://www.python.org/doc/2.2/api/tupleObjects.html#l2h-476">PyTuple_Check</a>(args) != 0</code>
+      <dt><b>Effects:</b> Makes the lifetime of the argument indicated
+      by <code>ward</code> dependent on the lifetime of the argument
+      indicated by <code>custodian</code>.
+
+      <dt><b>Returns:</b> <code>false</code> and <code><a
+    href="http://www.python.org/doc/2.2/api/exceptionHandling.html#l2h-71">PyErr_Occurred</a>()&nbsp;!=&nbsp;0</code>
+    upon failure, <code>true</code> otherwise.
+    </dl>
+
+
+<!-- xxxxxx -->
+
+    <h3><a name="with_custodian_and_ward_postcall-spec"></a>Class template <code>with_custodian_and_ward_postcall</code></h3>
+
+
+    <table border="1" summary="with_custodian_and_ward_postcall template parameters">
+      <caption>
+        <b><code>with_custodian_and_ward_postcall</code> template parameters</b>
+      </caption>
+      <tr>
+        <th>Parameter
+        
+        <th>Requirements
+
+        <th>Description
+
+        <th>Default
+
+      <tr>
+        <td><code>custodian</code> 
+
+        <td>A compile-time constant of type
+        <code>std::size_t</code>.
+
+        <td>The index of the parameter which is the dependency in the
+        lifetime relationship to be established. Zero indicates the
+        result object; 1 indicates the first argument. If used to wrap
+        a member function, parameter 1 is the target object
+        (<code>*this</code>). Note that if the target Python object
+        type doesn't support weak references, a Python
+        <code>TypeError</code> exception will be raised when the
+        C++ object being wrapped is called.
+
+
+      <tr>
+        <td><code>ward</code> 
+
+        <td>A compile-time constant of type <code>std::size_t</code>.
+
+        <td>The index of the parameter which is the dependent in the
+        lifetime relationship to be established. Zero indicates the
+        result object; 1 indicates the first argument. If used to wrap
+        a member function, parameter 1 is the target object
+        (<code>*this</code>). 
+
+      <tr>
+        <td><code>Base</code> 
+
+        <td>A model of <a href="CallPolicies.html">CallPolicies</a>
+
+        <td>Used for <a href="CallPolicies.html#composition">policy
+        composition</a>.
+
+        <td><code><a href="default_call_policies.html#default_call_policies-spec">default_call_policies</a></code>
+
+    </table>
+
+    <h4><a name="with_custodian_and_ward_postcall-spec-synopsis"></a>Class template <code>with_custodian_and_ward_postcall</code> synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+   template &lt;std::size_t custodian, std::size_t ward, class Base = default_call_policies&gt;
+   struct with_custodian_and_ward_postcall : Base
+   {
+      static PyObject* postcall(PyObject* args, PyObject* result);
+   };
+}}
+</pre>
+
+    <h4><a name="with_custodian_and_ward_postcall-spec-statics"></a>Class
+    <code>with_custodian_and_ward_postcall</code> static functions</h4>
+
+<pre>
+PyObject* postcall(PyObject* args, PyObject* result);
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Requires:</b> <code><a
+      href="http://www.python.org/doc/2.2/api/tupleObjects.html#l2h-476">PyTuple_Check</a>(args)
+      != 0</code>, <code>result&nbsp;!=&nbsp;0</code>.
+
+      <dt><b>Effects:</b> Makes the lifetime of the object indicated
+      by <code>ward</code> dependent on the lifetime of the object
+      indicated by <code>custodian</code>.
+
+      <dt><b>Returns:</b> <code>0</code> and <code><a
+    href="http://www.python.org/doc/2.2/api/exceptionHandling.html#l2h-71">PyErr_Occurred</a>()&nbsp;!=&nbsp;0</code>
+    upon failure, <code>true</code> otherwise.
+    </dl>
+
+
+
+    <h2><a name="examples"></a>Example</h2>
+
+The following example shows how
+<code>with_custodian_and_ward_postcall</code> is used by the library
+to implement <code><a
+href="return_internal_reference.html#return_internal_reference-spec">return_internal_reference</a></code>
+
+<pre>
+template &lt;std::size_t owner_arg = 1, class Base = default_call_policies&gt;
+struct return_internal_reference
+    : with_custodian_and_ward_postcall&lt;0, owner_arg, Base&gt;
+{
+   typedef <a href="reference_existing_object.html#reference_existing_object-spec">reference_existing_object</a> result_converter;
+};
+</pre>
+
+    <p>Revised 
+    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+    29 May, 2002
+    <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+
+    <p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
+    Abrahams</a> 2002. All Rights Reserved.</i>
+

example/Jamfile

@@ -0,0 +1,39 @@
+# Specify our location in the boost project hierarchy
+subproject libs/python/example ;
+
+# Declares the following targets:
+#    
+#  1. an extension module called "getting_started1", which is
+#     built from "getting_started1.cpp". Built by default
+#
+#  2. A test target called my-test.test which runs
+#     test_getting_started1.py with the extension module above. Built
+#     when out-of date, but only if invoked by name or if the global
+#     "test" target is invoked.
+#
+#  3. A test target called my-test.run wihch runs the above test
+#     unconditionally. Built only when invoked by name.
+#
+# To see verbose test output, add "-sPYTHON_TEST_ARGS=-v" to the bjam
+# command-line before the first target.
+#
+
+# Include definitions needed for Python modules
+SEARCH on python.jam = $(BOOST_BUILD_PATH) ;
+include python.jam ;
+
+# Declare a Python extension called getting_started1
+extension getting_started1
+:  # sources
+   getting_started1.cpp
+  
+   # dependencies
+   <dll>../build/boost_python
+  ;
+
+# Declare a test for the extension module
+boost-python-runtest my-test
+    :  # Python test driver
+    test_getting_started1.py
+    # extension modules to use
+    <pyd>getting_started1 ;

example/README

@@ -0,0 +1,21 @@
+To get started with the Boost Python Library, use the examples
+getting_started1.cpp and getting_started2.cpp.
+
+Examples for providing pickle support can be found in:
+  pickle1.cpp
+  pickle2.cpp
+  pickle3.cpp
+See also: libs/python/doc/pickle.html
+
+Other advanced concepts are introduced by:
+  abstract.cpp
+  simple_vector.cpp
+  do_it_yourself_convts.cpp
+
+Examples for the cross-module support are provided by:
+  noncopyable_export.cpp
+  noncopyable_import.cpp
+  dvect.cpp
+  ivect.cpp
+See also: libs/python/doc/cross_module.html
+

example/abstract.cpp

@@ -0,0 +1,32 @@
+// Example by Ullrich Koethe
+#include "boost/python/class_builder.hpp"
+#include <string>
+
+struct Abstract
+{
+    virtual std::string test() = 0;
+};
+
+struct Abstract_callback: Abstract
+{
+    Abstract_callback(PyObject * self)
+    : m_self(self)
+    {}
+
+    std::string test()
+    {
+      return boost::python::callback<std::string>::call_method(m_self, "test");
+    }
+
+    PyObject * m_self;
+};
+
+BOOST_PYTHON_MODULE_INIT(abstract)
+{
+    boost::python::module_builder a("abstract");
+
+    boost::python::class_builder<Abstract, Abstract_callback>
+        a_class(a, "Abstract");
+    a_class.def(boost::python::constructor<>()); // wrap a constructor
+    a_class.def(&Abstract::test, "test");
+}

example/do_it_yourself_convts.cpp

@@ -0,0 +1,121 @@
+// Example by Ralf W. Grosse-Kunstleve
+/*
+
+   This example shows how to convert a class from and to native
+   Python objects, such as tuples.
+
+   We do not want to expose the helper class MillerIndex as an
+   Extension Class. However, in order to simplify the wrapper code,
+   we want to define from_python() and to_python() functions for
+   class MillerIndex.
+
+   Consider the alternatives:
+
+     - Expose MillerIndex as an Extension Class.
+         We need a constructor MillerIndex(python::tuple).
+         Python function calls become more complex:
+           foo(MillerIndex((1,2,3)) instead of foo((1,2,3))
+         We need a method such as MillerIndex().as_tuple().
+
+     - Define a wrapper function for each function that we
+       want to expose, e.g.:
+          void add(const IndexingSet& ixset, const python::tuple PyMIx)
+
+   The first alternative introduces a new type that the user has to
+   deal with. Other modules using Miller indices might organize them in
+   different ways, for example to increase runtime efficiency for
+   important procedures. This means, the user has to know how to
+   convert between the different kinds of Miller index representations.
+   This can quickly become a nuisance. Relying on native Python data
+   structures minimizes the number of special types the user has to
+   learn and convert. Of course, this argument is only valid for
+   small and relatively simply classes.
+
+   If there are many member functions with MillerIndex arguments, the
+   second alternative is impractical, and concentrating the conversion
+   mechanism in one central place is essential for code
+   maintainability.  An added benefit is that more convenient (smarter)
+   conversion functions can be provided without cluttering the rest of
+   the wrapper code.
+
+ */
+
+#include <string>
+#include <vector>
+#include <boost/python/class_builder.hpp>
+namespace python = boost::python;
+
+namespace { // Avoid cluttering the global namespace.
+
+  // The helper class.
+  //
+  class MillerIndex {
+    public:
+      int v[3];
+  };
+
+  // The main class. Imagine that there are MANY member functions
+  // like add() and get().
+  //
+  class IndexingSet {
+    private:
+      std::vector<MillerIndex> VMIx;
+    public:
+      void add(const MillerIndex& MIx) { VMIx.push_back(MIx); }
+      MillerIndex get(std::size_t i) const { return VMIx[i]; }
+  };
+}
+
+BOOST_PYTHON_BEGIN_CONVERSION_NAMESPACE
+
+  // Convert a Python tuple to a MillerIndex object.
+  //
+  MillerIndex from_python(PyObject* p, python::type<const MillerIndex&>)
+  {
+    python::tuple tup
+      = python::tuple(python::ref(p, python::ref::increment_count));
+    if (tup.size() != 3) {
+      PyErr_SetString(PyExc_ValueError,
+        "expecting exactly 3 values in tuple.");
+      python::throw_error_already_set();
+    }
+    MillerIndex result;
+    for (int i = 0; i < 3; i++)
+      result.v[i] = from_python(tup[i].get(), python::type<int>());
+    return result;
+  }
+
+  // Similar conversion for MillerIndex objects passed by value.
+  // Not actually used, but included to show the principle.
+  //
+  MillerIndex from_python(PyObject* p, python::type<MillerIndex>)
+  {
+    return from_python(p, python::type<const MillerIndex&>());
+  }
+
+  // Convert a MillerIndex object to a Python tuple.
+  //
+  PyObject* to_python(const MillerIndex& hkl)
+  {
+    python::tuple result(3);
+    for (int i = 0; i < 3; i++)
+      result.set_item(i, python::ref(to_python(hkl.v[i])));
+    return result.reference().release();
+  }
+
+BOOST_PYTHON_END_CONVERSION_NAMESPACE
+
+BOOST_PYTHON_MODULE_INIT(do_it_yourself_convts)
+{
+    // Create an object representing this extension module.
+    python::module_builder this_module("do_it_yourself_convts");
+
+    // Create the Python type object for our extension class.
+    python::class_builder<IndexingSet> ixset_class(this_module, "IndexingSet");
+
+    // Add the __init__ function.
+    ixset_class.def(python::constructor<>());
+    // Add the member functions.
+    ixset_class.def(&IndexingSet::add, "add");
+    ixset_class.def(&IndexingSet::get, "get");
+}

example/dvect.cpp

@@ -0,0 +1,48 @@
+// Example by Ralf W. Grosse-Kunstleve
+// See root/libs/python/doc/cross_module.html for an introduction.
+
+#include "dvect.h"
+#include "ivect.h"
+#include <boost/python/cross_module.hpp>
+namespace python = boost::python;
+
+namespace {
+
+# include "dvect_conversions.cpp"
+# include "ivect_conversions.cpp"
+
+  vects::ivect dvect_as_ivect(const vects::dvect& dv)
+  {
+    vects::ivect iv(dv.size());
+    vects::ivect::iterator iviter = iv.begin();
+    for (int i = 0; i < dv.size(); i++) iviter[i] = static_cast<int>(dv[i]);
+    return iv;
+  }
+}
+
+# ifdef BOOST_MSVC // fixes for JIT debugging
+#  include <windows.h>
+extern "C" void structured_exception_translator(unsigned int, EXCEPTION_POINTERS*)
+{
+    throw;
+}
+extern "C" void (*old_translator)(unsigned int, EXCEPTION_POINTERS*)
+    = _set_se_translator(structured_exception_translator);
+# endif
+
+BOOST_PYTHON_MODULE_INIT(dvect)
+{
+    python::module_builder this_module("dvect");
+
+    python::class_builder<vects::dvect> dvect_class(this_module, "dvect");
+    python::export_converters(dvect_class);
+
+    python::import_converters<vects::ivect> ivect_converters("ivect", "ivect");
+
+    dvect_class.def(python::constructor<python::tuple>());
+    dvect_class.def(&vects::dvect::as_tuple, "as_tuple");
+    dvect_class.def(dvect_as_ivect, "as_ivect");
+
+# include "dvect_defs.cpp"
+# include "ivect_defs.cpp"
+}

example/dvect.h

@@ -0,0 +1,32 @@
+#ifndef DVECT_H
+#define DVECT_H
+
+#include <vector>
+#include <boost/python/class_builder.hpp>
+
+namespace vects {
+
+  struct dvect : public std::vector<double>
+  {
+    dvect() : std::vector<double>() {}
+    dvect(std::size_t n) : std::vector<double>(n) {}
+    dvect(boost::python::tuple tuple) : std::vector<double>(tuple.size())
+    {
+      std::vector<double>::iterator v_it = begin();
+      for (int i = 0; i < tuple.size(); i++)
+        v_it[i] = BOOST_PYTHON_CONVERSION::from_python(tuple[i].get(),
+          boost::python::type<double>());
+    }
+
+    boost::python::tuple as_tuple() const
+    {
+      boost::python::tuple t(size());
+      for (int i = 0; i < size(); i++)
+        t.set_item(i,
+          boost::python::ref(BOOST_PYTHON_CONVERSION::to_python((*this)[i])));
+      return t;
+    }
+  };
+}
+
+#endif // DVECT_H

example/dvect_conversions.cpp

@@ -0,0 +1,51 @@
+  // basics first: const reference converters
+  boost::python::tuple const_dvect_reference_as_tuple(const vects::dvect& dv)
+  {
+    return dv.as_tuple();
+  }
+
+  // to_python smart pointer conversions
+  std::auto_ptr<vects::dvect> dvect_as_auto_ptr(const vects::dvect& dv)
+  {
+    return std::auto_ptr<vects::dvect>(new vects::dvect(dv));
+  }
+  boost::shared_ptr<vects::dvect> dvect_as_shared_ptr(const vects::dvect& dv)
+  {
+    return boost::shared_ptr<vects::dvect>(new vects::dvect(dv));
+  }
+
+  // smart pointers passed by value
+  boost::python::ref auto_ptr_value_dvect_as_tuple(std::auto_ptr<vects::dvect> dv)
+  {
+    if (dv.get() == 0) return boost::python::ref(Py_None, boost::python::ref::increment_count);
+    return dv->as_tuple().reference();
+  }
+  boost::python::ref shared_ptr_value_dvect_as_tuple(boost::shared_ptr<vects::dvect> dv)
+  {
+    if (dv.get() == 0) return boost::python::ref(Py_None, boost::python::ref::increment_count);
+    return dv->as_tuple().reference();
+  }
+
+  // smart pointers passed by reference
+  boost::python::ref auto_ptr_reference_dvect_as_tuple(std::auto_ptr<vects::dvect>& dv)
+  {
+    if (dv.get() == 0) return boost::python::ref(Py_None, boost::python::ref::increment_count);
+    return dv->as_tuple().reference();
+  }
+  boost::python::ref shared_ptr_reference_dvect_as_tuple(boost::shared_ptr<vects::dvect>& dv)
+  {
+    if (dv.get() == 0) return boost::python::ref(Py_None, boost::python::ref::increment_count);
+    return dv->as_tuple().reference();
+  }
+
+  // smart pointers passed by const reference
+  boost::python::ref auto_ptr_const_reference_dvect_as_tuple(const std::auto_ptr<vects::dvect>& dv)
+  {
+    if (dv.get() == 0) return boost::python::ref(Py_None, boost::python::ref::increment_count);
+    return dv->as_tuple().reference();
+  }
+  boost::python::ref shared_ptr_const_reference_dvect_as_tuple(const boost::shared_ptr<vects::dvect>& dv)
+  {
+    if (dv.get() == 0) return boost::python::ref(Py_None, boost::python::ref::increment_count);
+    return dv->as_tuple().reference();
+  }

example/dvect_defs.cpp

@@ -0,0 +1,13 @@
+    this_module.def(dvect_as_auto_ptr, "dvect_as_auto_ptr");
+    this_module.def(dvect_as_shared_ptr, "dvect_as_shared_ptr");
+
+    this_module.def(const_dvect_reference_as_tuple, "const_dvect_reference_as_tuple");
+
+    this_module.def(auto_ptr_value_dvect_as_tuple, "auto_ptr_value_dvect_as_tuple");
+    this_module.def(shared_ptr_value_dvect_as_tuple, "shared_ptr_value_dvect_as_tuple");
+
+    this_module.def(auto_ptr_reference_dvect_as_tuple, "auto_ptr_reference_dvect_as_tuple");
+    this_module.def(shared_ptr_reference_dvect_as_tuple, "shared_ptr_reference_dvect_as_tuple");
+
+    this_module.def(auto_ptr_const_reference_dvect_as_tuple, "auto_ptr_const_reference_dvect_as_tuple");
+    this_module.def(shared_ptr_const_reference_dvect_as_tuple, "shared_ptr_const_reference_dvect_as_tuple");