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.
@@ -51,7 +51,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 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 @@ -77,7 +77,7 @@ In a Jamfile, all the above boils down to:
<find-library>$(PYTHON_EMBEDDED_LIBRARY) ;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 @@ -116,9 +116,9 @@ 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 and -object class templates to automate the process.
+object class templates to automate the process.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 @@ -128,7 +128,7 @@ be 'handled' by Boost.Python.
For a function returning a borrowed reference we'll have to tell the handle that the PyObject* is borrowed with the aptly named -borrowed function. Two functions +borrowed function. Two functions returning borrowed references are PyImport_AddModule and PyModule_GetDict. 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 @@ -151,7 +151,7 @@ discuss in the next section.
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 @@ -166,7 +166,7 @@ The start parameter is the start symbol from the Python for interpreting the code. The possible values are:
You can access those values in Python as
diff --git a/doc/tutorial/doc/html/python/techniques.html b/doc/tutorial/doc/html/python/techniques.html index a0fb5eb3..bebc6727 100644 --- a/doc/tutorial/doc/html/python/techniques.html +++ b/doc/tutorial/doc/html/python/techniques.html @@ -108,7 +108,8 @@ 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 and fire up the interpreter:
+PYTHONPATH +and fire up the interpreter:>>> import sounds.io >>> import sounds.filters >>> sound = sounds.io.open('file.mp3') @@ -220,7 +221,8 @@ BOOST_PYTHON_MODULE(
If we are using the technique from the previous session, -Creating Packages, we can code directly into geom/_init_.py:
+Creating Packages, we can code directly +into geom/_init_.py:from _geom import * # a regular function @@ -346,7 +348,7 @@ the compilation of a single cpp, instead of the entire wrapper code.@@ -355,7 +357,7 @@ various files as demonstrated here.
- If you're exporting your classes with Pyste, +
+a large source file, as explained in the FAQ. diff --git a/doc/tutorial/doc/tutorial.qbk b/doc/tutorial/doc/tutorial.qbk index 884557ca..e58ccdc8 100644 --- a/doc/tutorial/doc/tutorial.qbk +++ b/doc/tutorial/doc/tutorial.qbk @@ -86,7 +86,7 @@ with every boost distribution: [*bjam]. We shall skip over the details. Our objective will be to simply create the hello world module and run it in Python. For a complete reference to -building Boost.Python, check out: [@../../building.html building.html]. +building Boost.Python, check out: [@../../../../building.html building.html]. After this brief ['bjam] tutorial, we should have built two DLLs: * boost_python.dll @@ -115,7 +115,7 @@ platforms. The complete list of Bjam executables can be found [@http://sourceforge.net/project/showfiles.php?group_id=7586 here]. [h2 Let's Jam!] -[$images/jam.png] +[$../images/jam.png] Here is our minimalist Jamfile: @@ -468,7 +468,7 @@ instances of class [^Derived]. In such cases, we use [^return_value_policy ] to instruct Python to adopt the pointer to [^Base] and hold the instance in a new Python [^Base] object until the the Python object is destroyed. We shall see more of -Boost.Python [@call_policies.html call policies] later. +Boost.Python [@functions.html#python.call_policies call policies] later. // Tell Python to take ownership of factory's result def("factory", factory, @@ -614,7 +614,7 @@ Here's what's happening: [endsect] [section Virtual Functions with Default Implementations] -Recall that in the [@class_virtual_functions.html previous section], we +Recall that in the [@exposing.html#class_virtual_functions previous section], we wrapped a class with a pure virtual function that we then implemented in C++ or Python classes derived from it. Our base class: @@ -918,7 +918,7 @@ or more policies can be composed by chaining. Here's the general syntax: policy3 > > Here is the list of predefined call policies. A complete reference detailing -these can be found [@../../v2/reference.html#models_of_call_policies here]. +these can be found [@../../../../v2/reference.html#models_of_call_policies here]. * [*with_custodian_and_ward]\n Ties lifetimes of the arguments * [*with_custodian_and_ward_postcall]\n Ties lifetimes of the arguments and results @@ -1000,7 +1000,7 @@ to retrieve the default arguments: def("f", f); // defaults lost! Because of this, when wrapping C++ code, we had to resort to manual -wrapping as outlined in the [@overloading.html previous section], or +wrapping as outlined in the [@functions.html#overloading previous section], or writing thin wrappers: // write "thin wrappers" @@ -1073,7 +1073,7 @@ fourth macro argument). The thin wrappers are all enclosed in a class named .def("wack_em", &george::wack_em, george_overloads()); -See the [@../../v2/overloads.html#BOOST_PYTHON_FUNCTION_OVERLOADS-spec overloads reference] +See the [@../../../../v2/overloads.html#BOOST_PYTHON_FUNCTION_OVERLOADS-spec overloads reference] for details. [h2 init and optional] @@ -1140,12 +1140,12 @@ Notice though that we have a situation now where we have a minimum of zero It is important to emphasize however that [*the overloaded functions must have a common sequence of initial arguments]. Otherwise, our scheme above will not work. If this is not the case, we have to wrap our functions -[@overloading.html manually]. +[@functions.html#overloading manually]. Actually, we can mix and match manual wrapping of overloaded functions and automatic wrapping through [^BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS] and its sister, [^BOOST_PYTHON_FUNCTION_OVERLOADS]. Following up on our example -presented in the section [@overloading.html on overloading], since the +presented in the section [@functions.html#overloading on overloading], since the first 4 overload functins have a common sequence of initial arguments, we can use [^BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS] to automatically wrap the first three of the [^def]s and manually wrap just the last. Here's @@ -1179,7 +1179,7 @@ bidirectional mapping between C++ and Python while maintaining the Python feel. Boost.Python C++ [^object]s are as close as possible to Python. This should minimize the learning curve significantly. -[$images/python.png] +[$../images/python.png] [section Basic Interface] @@ -1361,7 +1361,7 @@ associated with the C++ type passed as its first parameter. [blurb __note__ [*what is a scope?]\n\n The scope is a class that has an associated global Python object which controls the Python namespace in which new extension classes and wrapped functions will be defined as -attributes. Details can be found [@../../v2/scope.html here].] +attributes. Details can be found [@../../../../v2/scope.html here].] You can access those values in Python as @@ -1422,7 +1422,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 [@../../building.html +you probably haven't built Boost.Python yet. See [@../../../../building.html Building and Testing] on how to do this. Python's static link library can be found in the [^/libs] subdirectory of @@ -1478,7 +1478,7 @@ 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] and -[@../../v2/object.html object] class templates to automate the process. +[@../../../../v2/object.html object] class templates to automate the process. [h2 Reference-counting handles and objects] @@ -1490,7 +1490,7 @@ be 'handled' by Boost.Python. For a function returning a ['borrowed reference] we'll have to tell the [^handle] that the [^PyObject*] is borrowed with the aptly named -[@../../v2/handle.html#borrowed-spec borrowed] function. Two functions +[@../../../../v2/handle.html#borrowed-spec borrowed] function. Two functions returning borrowed references are PyImport_AddModule and PyModule_GetDict. 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 @@ -1580,7 +1580,7 @@ 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 -above, and in the [@object_interface.html previous section]: the aptly +above, and in the [@object.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: @@ -1622,7 +1622,11 @@ perform. [h2 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 [@../../v2/errors.html#error_already_set-spec error_already_set], so basically, the Python exception is automatically translated into a C++ exception when using [^handle]: +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 [@../../../../v2/errors.html#error_already_set-spec error_already_set], +so basically, the Python exception is automatically translated into a +C++ exception when using [^handle]: try { @@ -1641,7 +1645,14 @@ If an exception occurs in the execution of some Python code, the PyRun_String fu // 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 [@http://www.python.org/doc/api/exceptionHandling.html exception handling functions] of the Python/C API in your catch-statement. This can be as simple as calling [@http://www.python.org/doc/api/exceptionHandling.html#l2h-70 PyErr_Print()] to print the exception's traceback to the console, or comparing the type of the exception with those of the [@http://www.python.org/doc/api/standardExceptions.html 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 +[@http://www.python.org/doc/api/exceptionHandling.html exception handling functions] +of the Python/C API in your catch-statement. This can be as simple as calling +[@http://www.python.org/doc/api/exceptionHandling.html#l2h-70 PyErr_Print()] to +print the exception's traceback to the console, or comparing the type of the +exception with those of the [@http://www.python.org/doc/api/standardExceptions.html +standard exceptions]: catch(error_already_set) { @@ -1656,9 +1667,12 @@ The [^error_already_set] exception class doesn't carry any information in itself } } -(To retrieve even more information from the exception you can use some of the other exception handling functions listed [@http://www.python.org/doc/api/exceptionHandling.html here].) +(To retrieve even more information from the exception you can use some of the other +exception handling functions listed [@http://www.python.org/doc/api/exceptionHandling.html here].) -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: +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" @@ -1845,7 +1859,8 @@ 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 -[@http://www.python.org/doc/current/tut/node8.html#SECTION008110000000000000000 PYTHONPATH] and fire up the interpreter: +[@http://www.python.org/doc/current/tut/node8.html#SECTION008110000000000000000 PYTHONPATH] +and fire up the interpreter: >>> import sounds.io >>> import sounds.filters @@ -1965,7 +1980,8 @@ we have a class [^point] in C++: } If we are using the technique from the previous session, -[@creating_packages.html Creating Packages], we can code directly into [^geom/__init__.py]: +[@techniques.html#creating_packages Creating Packages], we can code directly +into [^geom/__init__.py]: from _geom import * @@ -2083,13 +2099,13 @@ 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 the compilation of a single cpp, instead of the entire wrapper code. -[blurb __note__ If you're exporting your classes with [@../../../pyste/index.html Pyste], +[blurb __note__ If you're exporting your classes with [@../../../../../pyste/index.html Pyste], take a look at the [^--multiple] option, that generates the wrappers in various files as demonstrated here.] [blurb __note__ This method is useful too if you are getting the error message ['"fatal error C1204:Compiler limit:internal structure overflow"] when compiling -a large source file, as explained in the [@../../v2/faq.html#c1204 FAQ].] +a large source file, as explained in the [@../../../../v2/faq.html#c1204 FAQ].] [endsect] [endsect] [/ General Techniques] diff --git a/doc/tutorial/doc/tutorial.xml b/doc/tutorial/doc/tutorial.xml index ee883900..7b8a5d86 100644 --- a/doc/tutorial/doc/tutorial.xml +++ b/doc/tutorial/doc/tutorial.xml @@ -128,7 +128,7 @@ with every boost distribution: bjam .We shall skip over the details. Our objective will be to simply create the hello world module and run it in Python. For a complete reference to -building Boost.Python, check out: building.html . +building Boost.Python, check out:building.html . After this briefbjam tutorial, we should have built two DLLs:@@ -165,7 +165,7 @@ the command line. Pre-built Boost.Jam executables are available for most platforms. The complete list of Bjam executables can be found here .Let's Jam! - +Here is our minimalist Jamfile: subproject libs/python/example/tutorial ; @@ -582,7 +582,7 @@ instances of class Derived . In such cases, we usereturn_value_policy<manage_new_object> to instruct Python to adopt the pointer toBase and hold the instance in a new PythonBase object until the the Python object is destroyed. We shall see more of -Boost.Pythoncall policies later. +Boost.Pythoncall policies later.// Tell Python to take ownership of factory's result @@ -794,7 +794,7 @@ The overridden virtual function f ofBaseWrap Virtual Functions with Default Implementations -Recall that in the previous section , we +Recall that in theprevious section , we wrapped a class with a pure virtual function that we then implemented in C++ or Python classes derived from it. Our base class:@@ -1178,7 +1178,7 @@ or more policies can be composed by chaining. Here's the general syntax: Here is the list of predefined call policies. A complete reference detailing -these can be found +these can be foundhere .here .with_custodian_and_ward @@ -1308,7 +1308,7 @@ to retrieve the default arguments: Because of this, when wrapping C++ code, we had to resort to manual -wrapping as outlined in the previous section , or +wrapping as outlined in theprevious section , or writing thin wrappers:@@ -1401,7 +1401,7 @@ fourth macro argument). The thin wrappers are all enclosed in a class named -See the overloads reference +See theoverloads reference for details.init and optional A similar facility is provided for class constructors, again, with @@ -1479,12 +1479,12 @@ Notice though that we have a situation now where we have a minimum of zero It is important to emphasize however that +the overloaded functions must have a common sequence of initial arguments . Otherwise, our scheme above will not work. If this is not the case, we have to wrap our functions -manually .manually .Actually, we can mix and match manual wrapping of overloaded functions and automatic wrapping through BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS and its sister,BOOST_PYTHON_FUNCTION_OVERLOADS . Following up on our example -presented in the sectionon overloading , since the +presented in the sectionon overloading , since the first 4 overload functins have a common sequence of initial arguments, we can useBOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS to automatically wrap the first three of thedef s and manually wrap just the last. Here's @@ -1525,7 +1525,7 @@ bidirectional mapping between C++ and Python while maintaining the Python feel. Boost.Python C++object s are as close as possible to Python. This should minimize the learning curve significantly.- +Basic Interface @@ -1770,7 +1770,7 @@ associated with the C++ type passed as its first parameter. The scope is a class that has an associated global Python object which controls the Python namespace in which new extension classes and wrapped functions will be defined as -attributes. Details can be foundhere . +attributes. Details can be foundhere . @@ -1823,7 +1823,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 calledboost_python.lib (for release builds) andboost_python_debug.lib (for debugging). If you can't find the libraries, -you probably haven't built Boost.Python yet. Seeand Testing on how to do this.Python's static link library can be found in the +/libs subdirectory of @@ -1881,7 +1881,7 @@ automatic in Python, the Python/C API requires you to do itby hand . This is messy and especially hard to get right in the presence of C++ exceptions. Fortunately Boost.Python provides thehandle and -object class templates to automate the process.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 aborrowed reference or as anew reference . Which of @@ -1891,7 +1891,7 @@ be 'handled' by Boost.Python.For a function returning a @@ -2047,7 +2047,11 @@ intborrowed reference we'll have to tell thehandle that thePyObject* is borrowed with the aptly named -borrowed function. Two functions +borrowed function. Two functions returning borrowed references arePyImport_AddModule andPyModule_GetDict . 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 @@ -2001,7 +2001,7 @@ you want to be a Dr. Frankenstein, always wrapPyObject* s in It's nice thathandle 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 theprevious section : the aptly +above, and in theprevious section : the aptly namedobject class and it's derivatives. We've already seen that they can be constructed from ahandle . The following examples should further illustrate this fact:five_squared Exception handling -If an exception occurs in the execution of some Python code, the +If an exception occurs in the execution of some Python code, thePyRun_String function returns a null pointer. Constructing ahandle out of this null pointer throwserror_already_set , so basically, the Python exception is automatically translated into a C++ exception when usinghandle :PyRun_String +function returns a null pointer. Constructing ahandle out of this null +pointer throwserror_already_set , +so basically, the Python exception is automatically translated into a +C++ exception when usinghandle :try @@ -2069,7 +2073,14 @@ catch ( error_a -The +Theerror_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 theexception handling functions of the PythonC API in your catch-statement. This can be as simple as calling [@http: /www.python.org/doc/apiexceptionHandling.html#l2h-70 PyErr_Print()] to print the exception's traceback to the console, or comparing the type of the exception with those of the [@http: /www.python.org/doc/api/standardExceptions.html standard exceptions]: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 :catch ( error_already_set ) @@ -2087,9 +2098,12 @@ The error_already_set exception class doesn't carry any infor-(To retrieve even more information from the exception you can use some of the other exception handling functions listed +(To retrieve even more information from the exception you can use some of the other +exception handling functions listedhere .)here .)-If you'd rather not have +If you'd rather not havehandle throw a C++ exception when it is constructed, you can use theallow_null function in the same way you'd use borrowed:handle throw a C++ exception when it is constructed, you +can use theallow_null function in the same +way you'd use borrowed:handle <> result (( allow_null ( PyRun_String ( @@ -2331,7 +2345,8 @@ 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 and fire up the interpreter:PYTHONPATH +and fire up the interpreter:>>> import sounds . io @@ -2478,7 +2493,8 @@ BOOST_PYTHON_MODULE ( Creating Packages, we can code directly into geom/ : +_init _.pyCreating Packages , we can code directly +intogeom/ :_init _.pyfrom _geom import * @@ -2627,7 +2643,7 @@ the compilation of a single cpp, instead of the entire wrapper code.@@ -2642,7 +2658,7 @@ various files as demonstrated here.
- If you're exporting your classes with Pyste , +If you're exporting your classes with Pyste , take a look at the--multiple option, that generates the wrappers in various files as demonstrated here.+a large source file, as explained in the This method is useful too if you are getting the error message "fatal error C1204:Compiler limit:internal structure overflow" when compiling -a large source file, as explained in theFAQ .FAQ .
