From 9ccde24cffababcd8cc71bd1d1b6ca6742f058b3 Mon Sep 17 00:00:00 2001 From: Joel de Guzman Date: Mon, 15 Nov 2004 06:43:54 +0000 Subject: [PATCH] New Wrapper Facility [SVN r26208] --- doc/tutorial/doc/html/python/embedding.html | 47 ++++++++++---------- doc/tutorial/doc/html/python/functions.html | 10 ++--- doc/tutorial/doc/html/python/hello.html | 10 ++--- doc/tutorial/doc/html/python/object.html | 4 +- doc/tutorial/doc/html/python/techniques.html | 4 +- 5 files changed, 37 insertions(+), 38 deletions(-) diff --git a/doc/tutorial/doc/html/python/embedding.html b/doc/tutorial/doc/html/python/embedding.html index c711ce64..a5d816df 100644 --- a/doc/tutorial/doc/html/python/embedding.html +++ b/doc/tutorial/doc/html/python/embedding.html @@ -39,7 +39,7 @@ the gaps. However, Boost.Python already makes embedding a lot easier and, in a future version, it may become unnecessary to touch the Python/C API at all. So stay tuned...

-Building embedded programs

+Building embedded programs

To be able to use embedding in your programs, they have to be linked to both Boost.Python's and Python's static link library.

@@ -48,7 +48,7 @@ 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 +you probably haven't built Boost.Python yet. See Building and Testing on how to do this.

Python's static link library can be found in the /libs subdirectory of @@ -75,7 +75,7 @@ In a Jamfile, all the above boils down to:

<find-library>$(PYTHON_EMBEDDED_LIBRARY) ;

-Getting started

+Getting started

Being able to build is nice, but there is nothing to build yet. Embedding the Python interpreter into one of your C++ programs requires these 4 @@ -113,7 +113,7 @@ messy and especially hard to get right in the presence of C++ exceptions. Fortunately Boost.Python provides the handle and object class templates to automate the process.

-Reference-counting handles and objects

+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 @@ -146,7 +146,7 @@ discuss in the next section.

-Running Python code

+Running Python code

To run Python code from C++ there is a family of functions in the API starting with the PyRun prefix. You can find the full list of these @@ -161,7 +161,7 @@ The start parameter is the start symbol from the Python for interpreting the code. The possible values are:

-Start symbols +Start symbols

@@ -224,12 +224,12 @@ containing a phrase that is well-known in programming circles.

do this, the the returned object would be kept alive unnecessarily. Unless you want to be a Dr. Frankenstein, always wrap PyObject*s in handles.

-Beyond handles

+Beyond handles

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 -above, and in the previous section: the aptly +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:

@@ -266,12 +266,12 @@ int five_squared =< take into account the different functions that object and handle perform.

-Exception handling

+Exception handling

-If an exception occurs in the execution of some Python code, the PyRun_String -function returns a null pointer. Constructing a handle out of this null -pointer throws error_already_set, -so basically, the Python exception is automatically translated into a +If an exception occurs in the execution of some Python code, the PyRun_String +function returns a null pointer. Constructing a handle out of this null +pointer throws error_already_set, +so basically, the Python exception is automatically translated into a C++ exception when using handle:

try
 {
@@ -290,14 +290,13 @@ catch(error_already
     // handle the exception in some way
 }

-The error_already_set exception class doesn't carry any information in itself. -To find out more about the Python exception that occurred, you need to use the -exception handling functions -of the Python/C API in your catch-statement. This can be as simple as calling -PyErr_Print() to -print the exception's traceback to the console, or comparing the type of the -exception with those of the -standard exceptions:

+The error_already_set exception class doesn't carry any information in itself. +To find out more about the Python exception that occurred, you need to use the +exception handling functions +of the Python/C API in your catch-statement. This can be as simple as calling +PyErr_Print() to +print the exception's traceback to the console, or comparing the type of the +exception with those of the exceptions:

catch(error_already_set)
 {
     if (PyErr_ExceptionMatches(PyExc_ZeroDivisionError))
@@ -311,11 +310,11 @@ standard exceptions:

     }
 }

-(To retrieve even more information from the exception you can use some of the other +(To retrieve even more information from the exception you can use some of the other exception handling functions listed 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 +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"
diff --git a/doc/tutorial/doc/html/python/functions.html b/doc/tutorial/doc/html/python/functions.html
index 6dbf93bd..b8fa2735 100644
--- a/doc/tutorial/doc/html/python/functions.html
+++ b/doc/tutorial/doc/html/python/functions.html
@@ -172,7 +172,7 @@ A reference to y.x is returned
 
  • BOOM!
    • 
 
 
    
-Call Policies
    
+Call Policies
 
    
 Call Policies may be used in situations such as the example detailed above.
 In our example, return_internal_reference and with_custodian_and_ward
@@ -335,7 +335,7 @@ are overloaded with a common sequence of initial arguments
 
 
 
    
-BOOST_PYTHON_FUNCTION_OVERLOADS
    
+BOOST_PYTHON_FUNCTION_OVERLOADS
 
    
 Boost.Python now has a way to make it easier. For instance, given a function:
    
 
    int foo(int a, char b = 1, unsigned c = 2, double d = 3)
@@ -354,7 +354,7 @@ and the maximum number of arguments is 4. The def(...)
 automatically add all the foo variants for us:
    
 
    def("foo", foo, foo_overloads());
    
 
    
-BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS
    
+BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS
 
    
 Objects here, objects there, objects here there everywhere. More frequently
 than anything else, we need to expose member functions of our classes to
@@ -386,7 +386,7 @@ fourth macro argument). The thin wrappers are all enclosed in a class named
 See the overloads reference
 for details.
    
 
    
-init and optional
    
+init and optional
 
    
 A similar facility is provided for class constructors, again, with
 default arguments or a sequence of overloads. Remember init<...>? For example,
@@ -441,7 +441,7 @@ Then...
    
 Notice though that we have a situation now where we have a minimum of zero
 (0) arguments and a maximum of 3 arguments.
    
 
    
-Manual Wrapping
    
+Manual Wrapping
 
    
 It is important to emphasize however that the overloaded functions must
 have a common sequence of initial arguments. Otherwise, our scheme above
diff --git a/doc/tutorial/doc/html/python/hello.html b/doc/tutorial/doc/html/python/hello.html
index 0af79eb3..c8ae53bc 100644
--- a/doc/tutorial/doc/html/python/hello.html
+++ b/doc/tutorial/doc/html/python/hello.html
@@ -26,7 +26,7 @@
 
    
  Building Hello World
    
 
    
-From Start To Finish
    
+From Start To Finish
 
    
 Now the first thing you'd want to do is to build the Hello World module and
 try it for yourself in Python. In this section, we shall outline the steps
@@ -92,11 +92,11 @@ minimalist bjam script that builds the DL
 Before anything else, you should have the bjam executable in your boost
 directory or somewhere in your path such that bjam can be executed in
 the command line. Pre-built Boost.Jam executables are available for most
-platforms. The complete list of Bjam executables can be found 
+platforms. The complete list of Bjam executables can be found
 here.
    
 
    
-Let's Jam!
    
-
    
+Let's Jam!
+
    
 
    
 Here is our minimalist Jamfile:
    
 
        subproject libs/python/example/tutorial ;
@@ -128,7 +128,7 @@ Finally we declare our hello extension:
    
         ;
 
    
 
    
-Running bjam
    
+Running bjam
 
    bjam is run using your operating system's command line interpreter.
    
 
    Start it up.
    
 
    
diff --git a/doc/tutorial/doc/html/python/object.html b/doc/tutorial/doc/html/python/object.html
index 1764e057..c842c3f1 100644
--- a/doc/tutorial/doc/html/python/object.html
+++ b/doc/tutorial/doc/html/python/object.html
@@ -42,7 +42,7 @@ As mentioned, one of the goals of Boost.Python is to provide a
 bidirectional mapping between C++ and Python while maintaining the Python
 feel. Boost.Python C++ objects are as close as possible to Python. This
 should minimize the learning curve significantly.
    
-
    
+
    
 
    
 
    
 Basic Interface
    
@@ -146,7 +146,7 @@ C++:
    
 
    dict d(x.attr("__dict__"));  # copies x.__dict__
 d['whatever'] = 3;           # modifies the copy
    
 
    
-class_<T> as objects
    
+class_<T> as objects
 
    
 Due to the dynamic nature of Boost.Python objects, any class_<T> may
 also be one of these types! The following code snippet wraps the class
diff --git a/doc/tutorial/doc/html/python/techniques.html b/doc/tutorial/doc/html/python/techniques.html
index 3be6d38b..db9c6e11 100644
--- a/doc/tutorial/doc/html/python/techniques.html
+++ b/doc/tutorial/doc/html/python/techniques.html
@@ -102,7 +102,7 @@ actually a Python package. It can be a empty file, but can also perform some
 magic, that will be shown later.
    
 
    
 Now our package is ready. All the user has to do is put sounds into his
-PYTHONPATH 
+PYTHONPATH
 and fire up the interpreter:
    
 
    >>> import sounds.io
 >>> import sounds.filters
@@ -212,7 +212,7 @@ BOOST_PYTHON_MODULE(
    
 
    
 If we are using the technique from the previous session,
-Creating Packages, we can code directly 
+Creating Packages, we can code directly
 into geom/_init_.py:
    
 
    from _geom import *