diff --git a/doc/tutorial/doc/building_hello_world.html b/doc/tutorial/doc/building_hello_world.html index 90ae8056..61c4280c 100644 --- a/doc/tutorial/doc/building_hello_world.html +++ b/doc/tutorial/doc/building_hello_world.html @@ -38,9 +38,9 @@ Besides bjam, there are of course other ways to get your module built. What's written here should not be taken as "the one and only way". There are of course other build tools apart from bjam. -Take note however that the preferred build tool for Boost.Python is bjam. -There are so many ways to set up the build incorrectly. Experience shows -that 90% of the "I can't build Boost.Python" problems come from people +Take note however that the preferred build tool for Boost.Python is bjam. +There are so many ways to set up the build incorrectly. Experience shows +that 90% of the "I can't build Boost.Python" problems come from people who had to use a different tool. @@ -71,9 +71,7 @@ here. The complete list of bjam pre-built executables can be found here.

- -

Let's Jam!

-

+

Let's Jam!

Here is our minimalist Jamfile:

diff --git a/doc/tutorial/doc/class_virtual_functions.html b/doc/tutorial/doc/class_virtual_functions.html index 37ce60ce..ddc73d04 100644 --- a/doc/tutorial/doc/class_virtual_functions.html +++ b/doc/tutorial/doc/class_virtual_functions.html @@ -53,6 +53,18 @@ need to create a class wrapper:

int f() { return call_method<int>(self, "f"); } PyObject* self; }; + + + struct BaseWrap : Base + { + BaseWrap(PyObject* self_) + : self(self_) {} + BaseWrap(PyObject* self_, Base const& copy) + : Base(copy), self(self_) {} + int f() { return call_method<int>(self, "f"); } + int default_f() { return Base::f(); } // <<=== ***ADDED*** + PyObject* self; + }; diff --git a/doc/tutorial/doc/creating_packages.html b/doc/tutorial/doc/creating_packages.html index ad0456bd..fc05287e 100644 --- a/doc/tutorial/doc/creating_packages.html +++ b/doc/tutorial/doc/creating_packages.html @@ -37,7 +37,7 @@ with an example.

We have a C++ library that works with sounds: reading and writing various formats, applying filters to the sound data, etc. It is named (conveniently) -sounds. Our library already has a neat C++ namespace hierarchy, like so:

+sounds. Our library already has a neat C++ namespace hierarchy, like so:

     sounds::core
     sounds::io
@@ -59,21 +59,21 @@ separately with Boost.Python, like this:

     {
         /* export everything in the sounds::core namespace */
         ...
-    } 
-        
+    }
+
     /* file io.cpp */
     BOOST_PYTHON_MODULE(io)
     {
         /* export everything in the sounds::io namespace */
         ...
-    } 
+    }
 
     /* file filters.cpp */
     BOOST_PYTHON_MODULE(filters)
     {
         /* export everything in the sounds::filters namespace */
         ...
-    } 
+    }

Compiling these files will generate the following Python extensions: @@ -97,7 +97,7 @@ Now, we create this directory structure for our Python package:

The file __init__.py is what tells Python that the directory sounds/ is actually a Python package. It can be a empty file, but can also perform some -magic, that will be shown later.

+magic, that will be shown later.

Now our package is ready. All the user has to do is put sounds into his @@ -109,7 +109,7 @@ PYTHONPATH and fire up the interpreter:

>>> new_sound = sounds.filters.echo(sound, 1.0)

-Nice heh?

+Nice heh?

This is the simplest way to create hierarchies of packages, but it is not very flexible. What if we want to add a pure Python function to the filters @@ -126,7 +126,7 @@ little. First, we will have to change the name of the extension modules:

{ ... /* export everything in the sounds::core namespace */ - } + }

Note that we added an underscore to the module name. The filename will have to @@ -147,7 +147,7 @@ Now, we change our package hierarchy like so:

Note that we created a directory for each extension module, and added a __init__.py to each one. But if we leave it that way, the user will have to -access the functions in the core module with this syntax:

+access the functions in the core module with this syntax:

     >>> import sounds.core._core
     >>> sounds.core._core.foo(...)
diff --git a/doc/tutorial/doc/embedding.html b/doc/tutorial/doc/embedding.html
index fc1ab8dd..4b0e4069 100644
--- a/doc/tutorial/doc/embedding.html
+++ b/doc/tutorial/doc/embedding.html
@@ -45,8 +45,9 @@ Boost.Python's static link library comes in two variants. Both are located
 in Boost's /libs/python/build/bin-stage subdirectory. On Windows, the
 variants are called boost_python.lib (for release builds) and
 boost_python_debug.lib (for debugging). If you can't find the libraries,
-you probably haven't built Boost.Python yet. See 
-Building and Testing on how to do this.

+you probably haven't built Boost.Python yet. See 
+and Testing on how to do this.

 

 Python's static link library can be found in the /libs subdirectory of
 your Python directory. On Windows it is called pythonXY.lib where X.Y is
diff --git a/doc/tutorial/doc/extending_wrapped_objects_in_python.html b/doc/tutorial/doc/extending_wrapped_objects_in_python.html
index 79020405..df0c7945 100644
--- a/doc/tutorial/doc/extending_wrapped_objects_in_python.html
+++ b/doc/tutorial/doc/extending_wrapped_objects_in_python.html
@@ -34,7 +34,7 @@ even after it was already created:

     >>> def C_str(self): return 'A C instance!'
     >>>
     >>> ##now we turn it in a member function
-    >>> C.__str__ = C_str   
+    >>> C.__str__ = C_str
     >>>
     >>> c = C()
     >>> print c
@@ -56,8 +56,8 @@ we have a class point in C++:

     }

-If we are using the technique from the previous session, - +If we are using the technique from the previous session, + Creating Packages, we can code directly into geom/__init__.py:

     from _geom import *
@@ -65,7 +65,7 @@ Creating Packages, we can code directly into geom/__init__.py:

     ##a regular function
     def point_str(self):
         return str((self.x, self.y))
-        
+
     ##now we turn it into a member function
     point.__str__ = point_str
@@ -76,9 +76,9 @@ This technique has several advantages:

You can even add a little syntactic sugar with the use of metaclasses. Let's create a special metaclass that "injects" methods in other classes.

-    ##The one Boost.Python uses for all wrapped classes. 
+    ##The one Boost.Python uses for all wrapped classes.
     ##You can use here any class exported by Boost instead of "point"
-    BoostPythonMetaclass = point.__class__ 
+    BoostPythonMetaclass = point.__class__
 
     class injector(object):
         class __metaclass__(BoostPythonMetaclass):
diff --git a/doc/tutorial/doc/quickstart.txt b/doc/tutorial/doc/quickstart.txt
index 9650f43a..d750cf74 100644
--- a/doc/tutorial/doc/quickstart.txt
+++ b/doc/tutorial/doc/quickstart.txt
@@ -1439,10 +1439,10 @@ There is a difference however. While the reference-counting is fully
 automatic in Python, the Python/C API requires you to do it
 [@http://www.python.org/doc/current/api/refcounts.html by hand]. This is
 messy and especially hard to get right in the presence of C++ exceptions.
-Fortunately Boost.Python provides the [@../../v2/handle.html handle] class
-template to automate the process.
+Fortunately Boost.Python provides the [@../../v2/handle.html handle] and
+[@../../v2/object.html object] class templates to automate the process.
 
-[h2 Reference-counting handles]
+[h2 Reference-counting handles and objects]
 
 There are two ways in which a function in the Python/C API can return a
 [^PyObject*]: as a ['borrowed reference] or as a ['new reference]. Which of
@@ -1458,12 +1458,10 @@ The former returns a reference to an already imported module, the latter
 retrieves a module's namespace dictionary. Let's use them to retrieve the
 namespace of the [^__main__] module:
 
-    handle<> main_module(borrowed( PyImport_AddModule("__main__") ));
-    handle<> main_namespace(borrowed( PyModule_GetDict(main_module.get()) ));
+    object main_module(
+        handle<>(borrowed(PyImport_AddModule("__main__"))));
+    object main_namespace = main_module.attr("__dict__");
 
-Because the Python/C API doesn't know anything about [^handle]s, we used
-the [@../../v2/handle.html#handle-spec-observers get] member function to
-retrieve the [^PyObject*] from which the [^handle] was constructed.
 
 For a function returning a ['new reference] we can just create a [^handle]
 out of the raw [^PyObject*] without wrapping it in a call to borrowed. One
@@ -1512,12 +1510,24 @@ For most intents and purposes you can use the namespace dictionary of the
 We have already seen how to get the [^__main__] module's namespace so let's
 run some Python code in it:
 
-    handle<> main_module(borrowed( PyImport_AddModule("__main__") ));
-    handle<> main_namespace(borrowed( PyModule_GetDict(main_module.get()) ));
-    handle<>( PyRun_String("hello = file('hello.txt', 'w')\n"
-                           "hello.write('Hello world!')\n"
-                           "hello.close()", Py_file_input,
-                           main_namespace.get(), main_namespace.get()) );
+    object main_module(
+        handle<>(borrowed(PyImport_AddModule("__main__"))));
+
+    object main_namespace = main_module.attr("__dict__");
+
+    handle<>(PyRun_String(
+
+        "hello = file('hello.txt', 'w')\n"
+        "hello.write('Hello world!')\n"
+        "hello.close()"
+
+      , Py_file_input
+      , main_namespace.ptr()
+      , main_namespace.ptr())
+    );
+
+Because the Python/C API doesn't know anything about [^object]s, we used
+the object's [^ptr] member function to retrieve the [^PyObject*].
 
 This should create a file called 'hello.txt' in the current directory
 containing a phrase that is well-known in programming circles.
@@ -1532,24 +1542,39 @@ you want to be a Dr. Frankenstein, always wrap [^PyObject*]s in [^handle]s.
 It's nice that [^handle] manages the reference counting details for us, but
 other than that it doesn't do much. Often we'd like to have a more useful
 class to manipulate Python objects. But we have already seen such a class
-in the [@object_interface.html previous section]: the aptly named [^object]
-class and it's derivatives. What we haven't seen, is that they can be
-constructed from a [^handle]. The following examples should illustrate this
-fact:
+above, and in the [@object_interface.html previous section]: the aptly
+named [^object] class and it's derivatives. We've already seen that they
+can be constructed from a [^handle]. The following examples should further
+illustrate this fact:
 
-    handle<> main_module(borrowed( PyImport_AddModule("__main__") ));
-    dict main_namespace(handle<>(borrowed( PyModule_GetDict(main_module.get()) )));
-    handle<>( PyRun_String("result = 5 ** 2", Py_file_input,
-                           main_namespace.ptr(), main_namespace.ptr()) );
-    int five_squared = extract( main_namespace["result"] );
+    object main_module(
+        handle<>(borrowed(PyImport_AddModule("__main__"))));
+
+    dict main_namespace(
+        handle<>(borrowed(PyModule_GetDict(main_module.ptr()))));
+
+    handle<>(PyRun_String(
+
+        "result = 5 ** 2"
+
+        , Py_file_input
+        , main_namespace.ptr()
+        , main_namespace.ptr())
+    );
+
+    int five_squared = extract(main_namespace["result"] );
 
 Here we create a dictionary object for the [^__main__] module's namespace.
 Then we assign 5 squared to the result variable and read this variable from
 the dictionary. Another way to achieve the same result is to let
 PyRun_String return the result directly with Py_eval_input:
 
-    object result(handle<>( PyRun_String("5 ** 2", Py_eval_input,
-                                         main_namespace.ptr(), main_namespace.ptr()) ));
+    object result(handle<>(PyRun_String(
+        "5 ** 2"
+      , Py_eval_input
+      , main_namespace.ptr()
+      , main_namespace.ptr()))
+    );
     int five_squared = extract(result);
 
 __note__ [*Note] that [^object]'s member function to return the wrapped
@@ -1563,8 +1588,13 @@ If an exception occurs in the execution of some Python code, the PyRun_String fu
 
     try
     {
-        object result(handle<>( PyRun_String("5/0", Py_eval_input,
-                                             main_namespace.ptr(), main_namespace.ptr()) ));
+        object result(handle<>(PyRun_String(
+            "5/0"
+          , Py_eval_input
+          , main_namespace.ptr()
+          , main_namespace.ptr()))
+        );
+
         // execution will never get here:
         int five_divided_by_zero = extract(result);
     }
@@ -1592,8 +1622,12 @@ The [^error_already_set] exception class doesn't carry any information in itself
 
 If you'd rather not have [^handle] throw a C++ exception when it is constructed, you can use the [@../../v2/handle.html#allow_null-spec allow_null] function in the same way you'd use borrowed:
 
-    handle<> result(allow_null( PyRun_String("5/0", Py_eval_input,
-                                             main_namespace.ptr(), main_namespace.ptr()) ));
+    handle<> result(allow_null(PyRun_String(
+        "5/0"
+       , Py_eval_input
+       , main_namespace.ptr()
+       , main_namespace.ptr())));
+
     if (!result)
         // Python exception occurred
     else
@@ -1886,8 +1920,8 @@ we have a class [^point] in C++:
         class_("point")...;
     }
 
-If we are using the technique from the previous session, [@creating_packages.html
-Creating Packages], we can code directly into [^geom/__init__.py]:
+If we are using the technique from the previous session,
+[@creating_packages.html Creating Packages], we can code directly into [^geom/__init__.py]:
 
     from _geom import *
 
diff --git a/doc/tutorial/doc/reducing_compiling_time.html b/doc/tutorial/doc/reducing_compiling_time.html
index bb265167..3839fcef 100644
--- a/doc/tutorial/doc/reducing_compiling_time.html
+++ b/doc/tutorial/doc/reducing_compiling_time.html
@@ -32,10 +32,10 @@ class_ definitions in multiple files:

     /* file point.cpp */
     #include <point.h>
     #include <boost/python.hpp>
-    
+
     void export_point()
     {
-        class_<point>("point")...;    
+        class_<point>("point")...;
     }
 
     /* file triangle.cpp */
@@ -49,11 +49,11 @@ class_ definitions in multiple files:

Now you create a file main.cpp, which contains the BOOST_PYTHON_MODULE -macro, and call the various export functions inside it.

+macro, and call the various export functions inside it.

     void export_point();
     void export_triangle();
-    
+
     BOOST_PYTHON_MODULE(_geom)
     {
         export_point();
@@ -72,10 +72,10 @@ usual approach:

     {
         class_<point>("point")...;
         class_<triangle>("triangle")...;
-    } 
+    }

-but the memory is kept under control.

+but the memory is kept under control.

This method is recommended too if you are developing the C++ library and exporting it to Python at the same time: changes in a class will only demand @@ -84,7 +84,7 @@ the compilation of a single cpp, instead of the entire wrapper code.

diff --git a/doc/tutorial/doc/using_the_interpreter.html b/doc/tutorial/doc/using_the_interpreter.html index 3bff8d71..8a4a70a7 100644 --- a/doc/tutorial/doc/using_the_interpreter.html +++ b/doc/tutorial/doc/using_the_interpreter.html @@ -33,9 +33,10 @@ automatic in Python, the Python/C API requires you to do it by hand. This is messy and especially hard to get right in the presence of C++ exceptions. Fortunately Boost.Python provides the -handle class -template to automate the process.

-

Reference-counting handles

+handle and + +object class templates to automate the process.

+

Reference-counting handles and objects

There are two ways in which a function in the Python/C API can return a PyObject*: as a borrowed reference or as a new reference. Which of these a function uses, is listed in that function's documentation. The two @@ -53,15 +54,11 @@ The former returns a reference to an already imported module, the latter retrieves a module's namespace dictionary. Let's use them to retrieve the namespace of the __main__ module:

-    handle<> main_module(borrowed( PyImport_AddModule("__main__") ));
-    handle<> main_namespace(borrowed( PyModule_GetDict(main_module.get()) ));
+    object main_module(
+        handle<>(borrowed(PyImport_AddModule("__main__"))));
+    object main_namespace = main_module.attr("__dict__");

-Because the Python/C API doesn't know anything about handles, we used -the -get member function to -retrieve the PyObject* from which the handle was constructed.

-

For a function returning a new reference we can just create a handle out of the raw PyObject* without wrapping it in a call to borrowed. One such function that returns a new reference is @@ -120,14 +117,26 @@ For most intents and purposes you can use the namespace dictionary of the We have already seen how to get the __main__ module's namespace so let's run some Python code in it:

-    handle<> main_module(borrowed( PyImport_AddModule("__main__") ));
-    handle<> main_namespace(borrowed( PyModule_GetDict(main_module.get()) ));
-    handle<>( PyRun_String("hello = file('hello.txt', 'w')\n"
-                           "hello.write('Hello world!')\n"
-                           "hello.close()", Py_file_input,
-                           main_namespace.get(), main_namespace.get()) );
+    object main_module(
+        handle<>(borrowed(PyImport_AddModule("__main__"))));
+
+    object main_namespace = main_module.attr("__dict__");
+
+    handle<>(PyRun_String(
+
+        "hello = file('hello.txt', 'w')\n"
+        "hello.write('Hello world!')\n"
+        "hello.close()"
+
+      , Py_file_input
+      , main_namespace.ptr()
+      , main_namespace.ptr())
+    );

+Because the Python/C API doesn't know anything about objects, we used +the object's ptr member function to retrieve the PyObject*.

+

This should create a file called 'hello.txt' in the current directory containing a phrase that is well-known in programming circles.

@@ -140,17 +149,28 @@ you want to be a Dr. Frankenstein, always wrap PyObject*s in handle It's nice that handle manages the reference counting details for us, but other than that it doesn't do much. Often we'd like to have a more useful class to manipulate Python objects. But we have already seen such a class -in the -previous section: the aptly named object -class and it's derivatives. What we haven't seen, is that they can be -constructed from a handle. The following examples should illustrate this -fact:

+above, and in the +previous section: the aptly +named object class and it's derivatives. We've already seen that they +can be constructed from a handle. The following examples should further +illustrate this fact:

-    handle<> main_module(borrowed( PyImport_AddModule("__main__") ));
-    dict main_namespace(handle<>(borrowed( PyModule_GetDict(main_module.get()) )));
-    handle<>( PyRun_String("result = 5 ** 2", Py_file_input,
-                           main_namespace.ptr(), main_namespace.ptr()) );
-    int five_squared = extract<int>( main_namespace["result"] );
+    object main_module(
+        handle<>(borrowed(PyImport_AddModule("__main__"))));
+
+    dict main_namespace(
+        handle<>(borrowed(PyModule_GetDict(main_module.ptr()))));
+
+    handle<>(PyRun_String(
+
+        "result = 5 ** 2"
+
+        , Py_file_input
+        , main_namespace.ptr()
+        , main_namespace.ptr())
+    );
+
+    int five_squared = extract<int>(main_namespace["result"] );

Here we create a dictionary object for the __main__ module's namespace. @@ -160,8 +180,12 @@ the dictionary. Another way to achieve the same result is to let PyRun_String return the result directly with Py_eval_input:

-    object result(handle<>( PyRun_String("5 ** 2", Py_eval_input,
-                                         main_namespace.ptr(), main_namespace.ptr()) ));
+    object result(handle<>(PyRun_String(
+        "5 ** 2"
+      , Py_eval_input
+      , main_namespace.ptr()
+      , main_namespace.ptr()))
+    );
     int five_squared = extract<int>(result);

@@ -176,8 +200,13 @@ error_already_set, so basically, the Python exception is automatically trans 

     try
     {
-        object result(handle<>( PyRun_String("5/0", Py_eval_input,
-                                             main_namespace.ptr(), main_namespace.ptr()) ));
+        object result(handle<>(PyRun_String(
+            "5/0"
+          , Py_eval_input
+          , main_namespace.ptr()
+          , main_namespace.ptr()))
+        );
+
         // execution will never get here:
         int five_divided_by_zero = extract<int>(result);
     }
@@ -212,8 +241,12 @@ here.)

 If you'd rather not have handle throw a C++ exception when it is constructed, you can use the 
 allow_null function in the same way you'd use borrowed:

 
-    handle<> result(allow_null( PyRun_String("5/0", Py_eval_input,
-                                             main_namespace.ptr(), main_namespace.ptr()) ));
+    handle<> result(allow_null(PyRun_String(
+        "5/0"
+       , Py_eval_input
+       , main_namespace.ptr()
+       , main_namespace.ptr())));
+
     if (!result)
         // Python exception occurred
     else
diff --git a/doc/tutorial/doc/virtual_functions_with_default_implementations.html b/doc/tutorial/doc/virtual_functions_with_default_implementations.html
index 6140ce59..f7b15115 100644
--- a/doc/tutorial/doc/virtual_functions_with_default_implementations.html
+++ b/doc/tutorial/doc/virtual_functions_with_default_implementations.html
@@ -22,7 +22,7 @@
- +
If you're exporting your classes with -Pyste, +Pyste, take a look at the --multiple option, that generates the wrappers in various files as demonstrated here.

Recall that in the @@ -48,18 +48,16 @@ not declared as pure virtual:

and instead had a default implementation that returns 0, as shown above, we need to add a forwarding function that calls the Base default virtual function f implementation:

-
-    struct BaseWrap : Base
+
+    struct BaseWrap : Base
     {
         BaseWrap(PyObject* self_)
             : self(self_) {}
-        BaseWrap(PyObject* self_, Base const& copy)
-            : Base(copy), self(self_) {}
-        int f() { return call_method<int>(self, "f"); }
+        int f() { return call_method<int>(self, "f"); }
         int default_f() { return Base::f(); } // <<=== ***ADDED***
         PyObject* self;
     };
-

+

Then, Boost.Python needs to keep track of 1) the dispatch function f and 2) the forwarding function to its default implementation default_f. @@ -112,7 +110,7 @@ Calling call_f, passing in a derived object:

 - +

Copyright © 2002-2003 David Abrahams
Copyright © 2002-2003 Joel de Guzman

diff --git a/test/embedding.cpp b/test/embedding.cpp index 652e2060..f0a7d15c 100644 --- a/test/embedding.cpp +++ b/test/embedding.cpp @@ -132,6 +132,40 @@ test_tutorial() ); } +void +test_tutorial2() +{ + using namespace boost::python; + + object main_module( + handle<>(borrowed(PyImport_AddModule("__main__")))); + + dict main_namespace( + handle<>(borrowed(PyModule_GetDict(main_module.ptr())))); + + handle<>(PyRun_String( + + "result = 5 ** 2" + + , Py_file_input + , main_namespace.ptr() + , main_namespace.ptr()) + ); + + int five_squared = extract(main_namespace["result"]); + assert(five_squared == 25); + + object result(handle<>( + PyRun_String("5 ** 2" + , Py_eval_input + , main_namespace.ptr() + , main_namespace.ptr())) + ); + + int five_squared2 = extract(result); + assert(five_squared2 == 25); +} + int main() { if (python::handle_exception(test)) @@ -148,6 +182,13 @@ int main() return 1; } + if (python::handle_exception(test_tutorial2)) + { + if (PyErr_Occurred()) + PyErr_Print(); + return 1; + } + return 0; } #include "module_tail.cpp"