diff --git a/doc/tutorial/doc/html/index.html b/doc/tutorial/doc/html/index.html index 5188c77f..53096363 100644 --- a/doc/tutorial/doc/html/index.html +++ b/doc/tutorial/doc/html/index.html @@ -3,21 +3,21 @@ Chapter 1. python 1.0 - + - + - +
-
Boost C++ Libraries Home Libraries People FAQ More
+
-
Next
+
Next

@@ -31,7 +31,7 @@

Copyright © 2002-2005 Joel de Guzman, David Abrahams

-

+

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt ) @@ -93,10 +93,10 @@ code takes on the look of a kind of declarative interface definition language (IDL).

-

- +

+ Hello World -

+

Following C/C++ tradition, let's start with the "hello, world". A C++ Function: @@ -112,10 +112,10 @@ 

 #include <boost/python.hpp>
-using namespace boost::python;
 
-BOOST_PYTHON_MODULE(hello)
+BOOST_PYTHON_MODULE(hello_ext)
 {
+    using namespace boost::python;
     def("greet", greet);
 }
@@ -126,7 +126,7 @@ 

->>> import hello
+>>> import hello_ext
 >>> print hello.greet()
 hello, world
@@ -136,8 +136,8 @@

- Next stop... Building your Hello World - module from start to finish... + Next stop... Building your Hello World + module from start to finish...

@@ -145,10 +145,10 @@
- +

Last revised: May 18, 2007 at 15:46:01 GMT

Last revised: November 04, 2007 at 00:10:08 GMT
-
Next
+
Next
diff --git a/doc/tutorial/doc/html/python/embedding.html b/doc/tutorial/doc/html/python/embedding.html index 7e8250d8..baddd095 100644 --- a/doc/tutorial/doc/html/python/embedding.html +++ b/doc/tutorial/doc/html/python/embedding.html @@ -3,24 +3,24 @@ Embedding - + - + - +
-
Boost C++ Libraries Home Libraries People FAQ More
+
-PrevUpHomeNext +PrevUpHomeNext

@@ -39,28 +39,28 @@ a lot easier and, in a future version, it may become unnecessary to touch the Python/C API at all. So stay tuned... smiley

-

- +

+ Building embedded programs -

+

To be able to embed python into your programs, you have to link to both Boost.Python's as well as Python's own runtime library.

Boost.Python's 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 + /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.

- Python's library can be found in the /libs subdirectory + Python's library can be found in the /libs subdirectory of your Python directory. On Windows it is called pythonXY.lib where X.Y is your major Python version number.

- Additionally, Python's /include subdirectory has to be added + Additionally, Python's /include subdirectory has to be added to your include path.

@@ -81,35 +81,37 @@ exe embedded_program # name of the executable <library-path>$(PYTHON_LIB_PATH) <find-library>$(PYTHON_EMBEDDED_LIBRARY) ; -

- +

+ 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 steps:

  1. - #include <boost/python.hpp>

    + #include <boost/python.hpp>
  2. Call Py_Initialize() - to start the interpreter and create the _main_ - module.

    -
    3. + to start the interpreter and create the _main_ + module. +
  3. - Call other Python C API routines to use the interpreter.

    -
    4. + Call other Python C API routines to use the interpreter. +
-
-

-

- note Note that at this time you must - not call Py_Finalize() - to stop the interpreter. This may be fixed in a future version of boost.python. -

-
+
+ + + + + +
[Note]Note

+ Note that at this time you must not call Py_Finalize() + to stop the interpreter. This may be fixed in a future version of boost.python. +

(Of course, there can be other C++ code between all of these steps.)

@@ -117,8 +119,8 @@ exe embedded_program # name of the executable

- Now that we can embed the interpreter in - our programs, lets see how to put it to use... + Now that we can embed the interpreter in + our programs, lets see how to put it to use...

@@ -128,7 +130,7 @@ exe embedded_program # name of the executable Using the interpreter

As you probably already know, objects in Python are reference-counted. Naturally, - the PyObjects of the Python/C API are also reference-counted. + the PyObjects of the Python/C API are also reference-counted. There is a difference however. While the reference-counting is fully automatic in Python, the PythonC 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 @@ -136,10 +138,10 @@ exe embedded_program # name of the executable and object class templates to automate the process.

-

- +

+ Running Python code -

+

Boost.python provides three related functions to run Python code from C++.

@@ -154,10 +156,10 @@ exe embedded_program # name of the executable and exec_file executes the code contained in the given file.

- The globals and locals parameters are + The globals and locals parameters are Python dictionaries containing the globals and locals of the context in which to run the code. For most intents and purposes you can use the namespace - dictionary of the _main_ + dictionary of the _main_ module for both parameters.

@@ -171,7 +173,7 @@ exe embedded_program # name of the executable first), and returns it.

- Let's import the _main_ + Let's import the _main_ module and run some Python code in its namespace: 

@@ -187,15 +189,15 @@ exe embedded_program # name of the executable
         This should create a file called 'hello.txt' in the current directory containing
         a phrase that is well-known in programming circles.
       

-

-
+

+
         Manipulating Python objects
-      

+      
 

         Often we'd like to have a class to manipulate Python objects. But we have
         already seen such a class above, and in the previous
-        section: the aptly named object class and its
-        derivatives. We've already seen that they can be constructed from a handle.
+        section: the aptly named object class and its
+        derivatives. We've already seen that they can be constructed from a handle.
         The following examples should further illustrate this fact:
       

 
@@ -205,7 +207,7 @@ exe embedded_program # name of the executable
 int five_squared = extract<int>(main_namespace["result"]);
 

 

-        Here we create a dictionary object for the _main_
+        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 use eval instead, which returns the result directly:
@@ -214,10 +216,10 @@ exe embedded_program # name of the executable
 object result = eval("5 ** 2");
 int five_squared = extract<int>(result);
-

- +

+ Exception handling -

+

If an exception occurs in the evaluation of the python expression, error_already_set is thrown: @@ -235,7 +237,7 @@ exe embedded_program # name of the executable }

- The error_already_set exception class doesn't carry any + 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 PythonC API in your catch-statement. @@ -271,7 +273,7 @@ exe embedded_program # name of the executable

-PrevUpHomeNext +PrevUpHomeNext
diff --git a/doc/tutorial/doc/html/python/exception.html b/doc/tutorial/doc/html/python/exception.html index c86133c2..5a0076ef 100644 --- a/doc/tutorial/doc/html/python/exception.html +++ b/doc/tutorial/doc/html/python/exception.html @@ -1,26 +1,26 @@ -Exception Translation + Exception Translation - + - + - +
-
Boost C++ Libraries Home Libraries People FAQ More
+
-PrevUpHomeNext +PrevUpHomeNext

@@ -54,7 +54,7 @@
-PrevUpHomeNext +PrevUpHomeNext
diff --git a/doc/tutorial/doc/html/python/exposing.html b/doc/tutorial/doc/html/python/exposing.html index 3f3f1888..706207d3 100644 --- a/doc/tutorial/doc/html/python/exposing.html +++ b/doc/tutorial/doc/html/python/exposing.html @@ -1,26 +1,26 @@ -Exposing Classes + Exposing Classes - + - + - +
-
Boost C++ Libraries Home Libraries People FAQ More
+
-PrevUpHomeNext +PrevUpHomeNext

@@ -64,9 +64,9 @@ }

- Here, we wrote a C++ class wrapper that exposes the member functions greet - and set. Now, after building our module as a shared library, - we may use our class World in Python. Here's a sample Python + Here, we wrote a C++ class wrapper that exposes the member functions greet + and set. Now, after building our module as a shared library, + we may use our class World in Python. Here's a sample Python session:

@@ -82,7 +82,7 @@

Constructors

- Our previous example didn't have any explicit constructors. Since World + Our previous example didn't have any explicit constructors. Since World is declared as a plain struct, it has an implicit default constructor. Boost.Python exposes the default constructor by default, which is why we were able to write @@ -106,9 +106,9 @@ };

- This time World has no default constructor; our previous + This time World has no default constructor; our previous wrapping code would fail to compile when the library tried to expose it. - We have to tell class_<World> about the constructor + We have to tell class_<World> about the constructor we want to expose instead. 

@@ -124,13 +124,13 @@
 }

- init<std::string>() exposes the constructor taking - in a std::string (in Python, constructors are spelled - ""_init_""). + init<std::string>() exposes the constructor taking + in a std::string (in Python, constructors are spelled + ""_init_"").

- We can expose additional constructors by passing more init<...>s - to the def() member function. Say for example we have + We can expose additional constructors by passing more init<...>s + to the def() member function. Say for example we have another World constructor taking in two doubles: 

@@ -142,13 +142,13 @@

On the other hand, if we do not wish to expose any constructors at all, we - may use no_init instead: + may use no_init instead: 

 class_<Abstract>("Abstract", no_init)

- This actually adds an _init_ + This actually adds an _init_ method which always raises a Python RuntimeError exception.

@@ -158,8 +158,8 @@

Data members may also be exposed to Python so that they can be accessed as attributes of the corresponding Python class. Each data member that we wish - to be exposed may be regarded as read-only - or read-write. Consider this class Var: + to be exposed may be regarded as read-only + or read-write. Consider this class Var: 

 struct Var
@@ -170,7 +170,7 @@
 };

- Our C++ Var class and its data members can be exposed + Our C++ Var class and its data members can be exposed to Python: 

@@ -191,8 +191,8 @@
 pi is around 3.14

- Note that name is exposed as read-only - while value is exposed as read-write. + Note that name is exposed as read-only + while value is exposed as read-write. 

 >>> x.name = 'e' # can't change name
@@ -224,7 +224,7 @@
 

         However, in Python attribute access is fine; it doesn't neccessarily break
         encapsulation to let users handle attributes directly, because the attributes
-        can just be a different syntax for a method call. Wrapping our Num
+        can just be a different syntax for a method call. Wrapping our Num
         class using Boost.Python:
       

 
@@ -245,8 +245,8 @@
 >>> x.rovalue = 2.17 # error!
 

 

-        Take note that the class property rovalue is exposed as
-        read-only since the rovalue
+        Take note that the class property rovalue is exposed as
+        read-only since the rovalue
         setter member function is not passed in:
       

 

@@ -273,7 +273,7 @@
 struct Derived : Base {};

- And a set of C++ functions operating on Base and Derived + And a set of C++ functions operating on Base and Derived object instances: 

@@ -282,7 +282,7 @@
 Base* factory() { return new Derived; }

- We've seen how we can wrap the base class Base: + We've seen how we can wrap the base class Base: 

 class_<Base>("Base")
@@ -290,8 +290,8 @@
     ;

- Now we can inform Boost.Python of the inheritance relationship between Derived - and its base class Base. Thus: + Now we can inform Boost.Python of the inheritance relationship between Derived + and its base class Base. Thus: 

 class_<Derived, bases<Base> >("Derived")
@@ -307,15 +307,15 @@
           member functions)
         
 
  • 
-If Base is polymorphic, Derived
+If Base is polymorphic, Derived
           objects which have been passed to Python via a pointer or reference to
-          Base can be passed where a pointer or reference to
-          Derived is expected.
+          Base can be passed where a pointer or reference to
+          Derived is expected.
         
    •

    - Now, we shall expose the C++ free functions b and d - and factory: + Now, we will expose the C++ free functions b and d + and factory: 

     def("b", b);
@@ -323,12 +323,12 @@
 def("factory", factory);

    - Note that free function factory is being used to generate - new instances of class Derived. In such cases, we use - return_value_policy<manage_new_object> 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 + Note that free function factory is being used to generate + new instances of class Derived. In such cases, we use + return_value_policy<manage_new_object> 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 will see more of Boost.Python call policies later. 

    @@ -341,9 +341,9 @@
 
    
 Class Virtual Functions
    
 
    
-        In this section, we shall learn how to make functions behave polymorphically
+        In this section, we will learn how to make functions behave polymorphically
         through virtual functions. Continuing our example, let us add a virtual function
-        to our Base class:
+        to our Base class:
       
    
 
     struct Base
@@ -356,11 +356,11 @@
         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. It is not ideal to add anything
-        to our class Base. Yet, when
+        to our class Base. Yet, when
         you have a virtual function that's going to be overridden in Python and called
-        polymorphically from C++, we'll need to
+        polymorphically from C++, we'll need to
         add some scaffoldings to make things work properly. What we'll do is write
-        a class wrapper that derives from Base
+        a class wrapper that derives from Base
         that will unintrusively hook into the virtual functions so that a Python
         override may be called:
       
    
@@ -374,25 +374,28 @@
 };
 
    
 
    
-        Notice too that in addition to inheriting from Base,
-        we also multiply- inherited wrapper<Base> (See Wrapper).
-        The wrapper template makes
+        Notice too that in addition to inheriting from Base,
+        we also multiply- inherited wrapper<Base> (See Wrapper).
+        The wrapper template makes
         the job of wrapping classes that are meant to overridden in Python, easier.
       
    
 
    
-
    
 
    
-        alert MSVC6/7 Workaround
    
-        
     If you are using Microsoft Visual C++ 6 or 7, you have to write f as:
     
     return
-        call<int>(this->get_override("f").ptr());.
+        alert MSVC6/7 Workaround
+      
    
+
    
+        If you are using Microsoft Visual C++ 6 or 7, you have to write f as:
+      
    
+
    
+        return call<int>(this->get_override("f").ptr());.
       
    
 
    
 
    
-        BaseWrap's overridden virtual member function f
-        in effect calls the corresponding method of the Python object through get_override.
+        BaseWrap's overridden virtual member function f
+        in effect calls the corresponding method of the Python object through get_override.
       
    
 
    
-        Finally, exposing Base:
+        Finally, exposing Base:
       
    
 
     class_<BaseWrap, boost::noncopyable>("Base")
@@ -400,17 +403,25 @@
     ;
 
    
 
    
-        pure_virtual signals Boost.Python
-        that the function f is a
+        pure_virtual signals Boost.Python
+        that the function f is a
         pure virtual function.
       
    
-
    
-
    
+
    
+
+
+
+
+
+
    [Note]Note
    
 
    
-        note member function and methods
    
-        
     Python, like many object oriented languages uses the term methods. Methods correspond roughly to C++'s member functions
-      
    
-
+          member function and methods
+        
    
+
    
+          Python, like many object oriented languages uses the term methods.
+          Methods correspond roughly to C++'s member functions
+        
    
+
    
 
    
 
    
 
    
@@ -418,7 +429,7 @@
 
    
         We've seen in the previous section how classes with pure virtual functions
         are wrapped using Boost.Python's class
-        wrapper facilities. If we wish to wrap non-pure-virtual
+        wrapper facilities. If we wish to wrap non-pure-virtual
         functions instead, the mechanism is a bit different.
       
    
 
    
@@ -433,8 +444,8 @@
 };

    - had a pure virtual function f. If, however, its member - function f was not declared as pure virtual: + had a pure virtual function f. If, however, its member + function f was not declared as pure virtual: 

     struct Base
@@ -460,17 +471,20 @@
 };

    - Notice how we implemented BaseWrap::f. Now, - we have to check if there is an override for f. - If none, then we call Base::f(). + Notice how we implemented BaseWrap::f. Now, + we have to check if there is an override for f. + If none, then we call Base::f().

    -

    - alert MSVC6/7 Workaround
    -
    If you are using Microsoft Visual C++ 6 or 7, you have to rewrite - the line with the *note* as:

    return - call<char const*>(f.ptr());. + alert MSVC6/7 Workaround +

    +

    + If you are using Microsoft Visual C++ 6 or 7, you have to rewrite the line + with the *note* as: +

    +

    + return call<char const*>(f.ptr());.

    @@ -482,10 +496,10 @@ ;

    - Take note that we expose both &Base::f and &BaseWrap::default_f. Boost.Python needs to keep track - of 1) the dispatch function f and 2) the forwarding function - to its default implementation default_f. There's a special - def function for this purpose. + Take note that we expose both &Base::f and &BaseWrap::default_f. Boost.Python needs to keep track + of 1) the dispatch function f and 2) the forwarding function + to its default implementation default_f. There's a special + def function for this purpose.

    In Python, the results would be as expected: @@ -501,14 +515,14 @@ >>> derived = Derived()

    - Calling base.f(): + Calling base.f(): 

     >>> base.f()
 0

    - Calling derived.f(): + Calling derived.f(): 

     >>> derived.f()
@@ -518,17 +532,17 @@
 
    
 
    
 Class Operators/Special Functions
    
-
    
-
+
    
+
         Python Operators
-      
    
+

    C is well known for the abundance of operators. C++ extends this to the extremes by allowing operator overloading. Boost.Python takes advantage of this and makes it easy to wrap C++ operator-powered classes.

    - Consider a file position class FilePos and a set of operators + Consider a file position class FilePos and a set of operators that take on FilePos instances:

    @@ -561,16 +575,16 @@

    The code snippet above is very clear and needs almost no explanation at all. It is virtually the same as the operators' signatures. Just take note that - self refers to FilePos object. Also, not every class - T that you might need to interact with in an operator - expression is (cheaply) default-constructible. You can use other<T>() - in place of an actual T instance when writing "self + self refers to FilePos object. Also, not every class + T that you might need to interact with in an operator + expression is (cheaply) default-constructible. You can use other<T>() + in place of an actual T instance when writing "self expressions".

    -

    - +

    + Special Methods -

    +

    Python has a few more Special Methods. Boost.Python supports all of the standard special method names supported by real Python @@ -596,15 +610,16 @@

    Need we say more?

    -
    -

    -

    - note What is the business of operator<<? Well, the method str - requires the operator<< - to do its work (i.e. operator<< is used by the method defined by - def(str(self)). -

    -
    +
    + + + + + +
    [Note]Note

    + What is the business of operator<<? Well, the method str requires the operator<< to do its work (i.e. operator<< + is used by the method defined by def(str(self)). +

    @@ -614,7 +629,7 @@
    -PrevUpHomeNext +PrevUpHomeNext
    diff --git a/doc/tutorial/doc/html/python/functions.html b/doc/tutorial/doc/html/python/functions.html index 927863d4..2e39bca7 100644 --- a/doc/tutorial/doc/html/python/functions.html +++ b/doc/tutorial/doc/html/python/functions.html @@ -3,24 +3,24 @@ Functions - + - - + + - +
    -
    Boost C++ Libraries Home Libraries People FAQ More
    +
    -PrevUpHomeNext +PrevUpHomeNext

    @@ -33,10 +33,10 @@

    In this chapter, we'll look at Boost.Python powered functions in closer detail. - We shall see some facilities to make exposing C++ functions to Python safe - from potential pifalls such as dangling pointers and references. We shall also - see facilities that will make it even easier for us to expose C++ functions - that take advantage of C++ features such as overloading and default arguments. + We will see some facilities to make exposing C++ functions to Python safe from + potential pifalls such as dangling pointers and references. We will also see + facilities that will make it even easier for us to expose C++ functions that + take advantage of C++ features such as overloading and default arguments.

    @@ -49,7 +49,7 @@

    But before you do, you might want to fire up Python 2.2 or later and type - >>> import this. + >>> import this. 

    >>> import this
 The Zen of Python, by Tim Peters
@@ -68,7 +68,7 @@ In the face of ambiguity, refuse the temptation to guess.
 There should be one-- and preferably only one --obvious way to do it
 Although that way may not be obvious at first unless you're Dutch.
 Now is better than never.
-Although never is often better than right now.
+Although never is often better than right now.
 If the implementation is hard to explain, it's a bad idea.
 If the implementation is easy to explain, it may be a good idea.
 Namespaces are one honking great idea -- let's do more of those!
@@ -126,19 +126,19 @@ Namespaces are one honking great idea -- let's do more of those!
       
    
 
      
 
    1. 
-f is called passing in a reference to y
-          and a pointer to z
+f is called passing in a reference to y
+          and a pointer to z
 
      2. 
 
    2. 
-          A reference to y.x is returned
+          A reference to y.x is returned
         
      3. 
 
    3. 
-y is deleted. x is a dangling reference
+y is deleted. x is a dangling reference
         
      4. 
 
    4. 
-x.some_method() is called
+x.some_method() is called
         
      5. 
-
    5. BOOM!
      6. 
+
    6. BOOM!
      7. 
 
    
 
    
         We could copy result into a new object:
@@ -168,7 +168,7 @@ Namespaces are one honking great idea -- let's do more of those!
 };

    - Notice that the data member z is held by class Y using + Notice that the data member z is held by class Y using a raw pointer. Now we have a potential dangling pointer problem inside Y: 

    @@ -177,7 +177,7 @@ Namespaces are one honking great idea -- let's do more of those!
 >>> y.z_value() # CRASH!

    - For reference, here's the implementation of f again: + For reference, here's the implementation of f again: 

     X& f(Y& y, Z* z)
@@ -191,33 +191,33 @@ Namespaces are one honking great idea -- let's do more of those!
       
    
 
      
 
    1. 
-f is called passing in a reference to y
-          and a pointer to z
+f is called passing in a reference to y
+          and a pointer to z
 
      2. 
 
    2. 
-          A pointer to z is held by y
+          A pointer to z is held by y
 
      3. 
 
    3. 
-          A reference to y.x is returned
+          A reference to y.x is returned
         
      4. 
 
    4. 
-z is deleted. y.z is a dangling pointer
+z is deleted. y.z is a dangling pointer
         
      5. 
 
    5. 
-y.z_value() is called
+y.z_value() is called
         
      6. 
 
    6. 
-z->value() is called
+z->value() is called
         
      7. 
-
    7. BOOM!
      8. 
+
    8. BOOM!
      9. 
 
    
-
    
-
+
    
+
         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
+        In our example, return_internal_reference and with_custodian_and_ward
         are our friends:
       
    
 
    @@ -226,27 +226,27 @@ Namespaces are one honking great idea -- let's do more of those!
         with_custodian_and_ward<1, 2> >());
 
    
 
    
-        What are the 1 and 2 parameters, you
+        What are the 1 and 2 parameters, you
         ask?
       
    
 
     return_internal_reference<1
 
    
 
    
-        Informs Boost.Python that the first argument, in our case Y&
-        y, is the owner of the returned reference: X&.
-        The "1" simply specifies the first argument.
-        In short: "return an internal reference X& owned
-        by the 1st argument Y& y".
+        Informs Boost.Python that the first argument, in our case Y&
+        y, is the owner of the returned reference: X&.
+        The "1" simply specifies the first argument.
+        In short: "return an internal reference X& owned
+        by the 1st argument Y& y".
       
    
 
     with_custodian_and_ward<1, 2>
 
    
 
    
         Informs Boost.Python that the lifetime of the argument indicated by ward
-        (i.e. the 2nd argument: Z* z) is dependent on the lifetime
-        of the argument indicated by custodian (i.e. the 1st argument: Y&
-        y).
+        (i.e. the 2nd argument: Z* z) is dependent on the lifetime
+        of the argument indicated by custodian (i.e. the 1st argument: Y&
+        y).
       
    
 
    
         It is also important to note that we have defined two policies above. Two
@@ -263,42 +263,46 @@ Namespaces are one honking great idea -- let's do more of those!
       
    
 
      
 
    • 
-with_custodian_and_ward
       Ties lifetimes
+with_custodian_and_ward: Ties lifetimes
           of the arguments
         
      • 
 
    • 
-with_custodian_and_ward_postcall
      
-          Ties lifetimes of the arguments and results
+with_custodian_and_ward_postcall: Ties
+          lifetimes of the arguments and results
         
      • 
 
    • 
-return_internal_reference
       Ties lifetime
+return_internal_reference: Ties lifetime
           of one argument to that of result
         
      • 
 
    • 
-return_value_policy<T> with T one of:
      
+return_value_policy<T> with T one of:
        
+
      • 
+reference_existing_object: naive (dangerous)
+              approach
+            
        • 
+
      • 
+copy_const_reference: Boost.Python
+              v1 approach
+            
        • 
+
      • 
+copy_non_const_reference:
+            
        • 
+
      • 
+manage_new_object: Adopt a pointer
+              and hold the instance
+            
        • 
+
      
 
      • 
-
    • 
-reference_existing_object
       naive
-          (dangerous) approach
-        
      • 
-
    • 
-copy_const_reference
       Boost.Python
-          v1 approach
-        
      • 
-
    • 
-copy_non_const_reference
      
-
      • 
-
    • 
-manage_new_object
       Adopt a pointer
-          and hold the instance
-        
      • 
 
    
 
    
-
    
 
    
-        smiley Remember the Zen, Luke:
    
-        
     "Explicit is better than implicit"
     "In the face
-        of ambiguity, refuse the temptation to guess"
    
+        smiley Remember the Zen, Luke:
+      
    
+
    
+        "Explicit is better than implicit"
+      
    
+
    
+        "In the face of ambiguity, refuse the temptation to guess"
    @@ -338,7 +342,7 @@ Namespaces are one honking great idea -- let's do more of those! };

    - Class X has 4 overloaded functions. We shall start by introducing some member + Class X has 4 overloaded functions. We will start by introducing some member function pointer variables: 

    @@ -362,21 +366,21 @@ Namespaces are one honking great idea -- let's do more of those!
 Default Arguments

    Boost.Python wraps (member) function pointers. Unfortunately, C++ function - pointers carry no default argument info. Take a function f + pointers carry no default argument info. Take a function f with default arguments: 

     int f(int, double = 3.14, char const* = "hello");

    - But the type of a pointer to the function f has no information + But the type of a pointer to the function f has no information about its default arguments: 

     int(*g)(int,double,char const*) = f;    // defaults lost!

    - When we pass this function pointer to the def function, + When we pass this function pointer to the def function, there is no way to retrieve the default arguments: 

    @@ -410,10 +414,10 @@ Namespaces are one honking great idea -- let's do more of those!
           are overloaded with a common sequence of initial arguments
    -

    - +

    + BOOST_PYTHON_FUNCTION_OVERLOADS -

    +

    Boost.Python now has a way to make it easier. For instance, given a function:

    @@ -431,19 +435,19 @@ Namespaces are one honking great idea -- let's do more of those!

    will automatically create the thin wrappers for us. This macro will create - a class foo_overloads that can be passed on to def(...). + a class foo_overloads that can be passed on to def(...). The third and fourth macro argument are the minimum arguments and maximum - arguments, respectively. In our foo function the minimum - number of arguments is 1 and the maximum number of arguments is 4. The def(...) + arguments, respectively. In our foo function the minimum + number of arguments is 1 and the maximum number of arguments is 4. The def(...) function will automatically add all the foo variants for us: 

     def("foo", foo, foo_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 @@ -452,7 +456,7 @@ Namespaces are one honking great idea -- let's do more of those! play. Another macro is provided to make this a breeze.

    - Like BOOST_PYTHON_FUNCTION_OVERLOADS, BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS + Like BOOST_PYTHON_FUNCTION_OVERLOADS, BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS may be used to automatically create the thin wrappers for wrapping member functions. Let's have an example:

    @@ -473,11 +477,11 @@ Namespaces are one honking great idea -- let's do more of those! BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS(george_overloads, wack_em, 1, 3)

    - will generate a set of thin wrappers for george's wack_em + will generate a set of thin wrappers for george's wack_em member function accepting a minimum of 1 and a maximum of 3 arguments (i.e. the third and fourth macro argument). The thin wrappers are all enclosed - in a class named george_overloads that can then be used - as an argument to def(...): + in a class named george_overloads that can then be used + as an argument to def(...): 

     .def("wack_em", &george::wack_em, george_overloads());
@@ -486,13 +490,13 @@ Namespaces are one honking great idea -- let's do more of those!
         See the overloads
         reference for details.
       
    
-
    
-
+
    
+
         init and optional
-      
    
+      
 
    
         A similar facility is provided for class constructors, again, with default
-        arguments or a sequence of overloads. Remember init<...>?
+        arguments or a sequence of overloads. Remember init<...>?
         For example, given a class X with a constructor:
       
    
 
    @@ -509,7 +513,7 @@ Namespaces are one honking great idea -- let's do more of those!
 .def(init<int, optional<char, std::string, double> >())
 
    
 
    
-        Notice the use of init<...> and optional<...>
+        Notice the use of init<...> and optional<...>
         to signify the default (optional arguments).
    @@ -517,8 +521,8 @@ Namespaces are one honking great idea -- let's do more of those!

    Auto-Overloading

    - It was mentioned in passing in the previous section that BOOST_PYTHON_FUNCTION_OVERLOADS - and BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS can also be + It was mentioned in passing in the previous section that BOOST_PYTHON_FUNCTION_OVERLOADS + and BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS can also be used for overloaded functions and member functions with a common sequence of initial arguments. Here is an example:

    @@ -560,24 +564,24 @@ Namespaces are one honking great idea -- let's do more of those! 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 -

    +

    - It is important to emphasize however that the overloaded - functions must have a common sequence of initial arguments. Otherwise, + 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.

    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 + automatic wrapping through BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS + and its sister, BOOST_PYTHON_FUNCTION_OVERLOADS. Following up on our example presented in the section 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 defs and + of initial arguments, we can use BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS + to automatically wrap the first three of the defs and manually wrap just the last. Here's how we'll do this: 

    @@ -606,7 +610,7 @@ Namespaces are one honking great idea -- let's do more of those!
 
 
    
 
    
-PrevUpHomeNext
+PrevUpHomeNext
 
    
 
 
diff --git a/doc/tutorial/doc/html/python/hello.html b/doc/tutorial/doc/html/python/hello.html
index 062e5c29..54c5f63e 100644
--- a/doc/tutorial/doc/html/python/hello.html
+++ b/doc/tutorial/doc/html/python/hello.html
@@ -1,84 +1,71 @@
 
 
 
-Building Hello World
+ Building Hello World
 
-
+
 
 
 
-
+
 
 
-
+
    
-
    
 Boost C++ Libraries
 Home
 Libraries
 People
 FAQ
 More
    
+
 
    
 
    
-PrevUpHomeNext
+PrevUpHomeNext
 
    
 
    
 
    
  Building Hello World
    
-
    
-
+
    
+
       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
-      necessary to achieve that. We shall use the build tool that comes bundled with
-      every boost distribution: bjam.
+      try it for yourself in Python. In this section, we will outline the steps necessary
+      to achieve that. We will use the build tool that comes bundled with every boost
+      distribution: bjam.
     
    
-
    
-
    
+
    
+
+
+
+
+
+
    [Note]Note
    
 
    
-      note Building without bjam
    
-      
     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
-      who had to use a different tool.
-    
    
-
+        Building without 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.
-      After this brief bjam tutorial, we should have built two
-      DLLs:
-    
    
-
      
-
    • 
-        boost_python.dll
-      
      • 
-
    • 
-        hello.pyd
-      
      • 
-
    
+        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.
+      
    
 
    
-      if you are on Windows, and
-    
    
-
      
-
    • 
-        libboost_python.so
-      
      • 
-
    • 
-        hello.so
-      
      • 
-
    
+        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.
+      
    
+
    
 
    
-      if you are on Unix.
+      We will 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. After
+      this brief bjam tutorial, we should have built the DLLs
+      and run a python program using the extension.
     
    
 
    
-      The tutorial example can be found in the directory: libs/python/example/tutorial.
+      The tutorial example can be found in the directory: libs/python/example/tutorial.
       There, you can find:
     
    
 
      
@@ -86,75 +73,44 @@
         hello.cpp
       
 
    • 
-        Jamfile
+        hello.py
+      
      • 
+
    • 
+        Jamroot
       
      • 
 
    
 
    
-      The hello.cpp file is our C++ hello world example. The
-      Jamfile is a minimalist bjam script
-      that builds the DLLs for us.
+      The hello.cpp file is our C++ hello world example. The
+      Jamroot is a minimalist bjam script
+      that builds the DLLs for us. Finally, hello.py is our Python
+      program that uses the extension in hello.cpp.
     
    
 
    
       Before anything else, you should have the bjam executable in your boost directory
-      or somewhere in your path such that bjam can be executed
+      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 here.
     
    
-
    
-
+
    
+
       Let's Jam!
-    
    
+    
 
    
       jam
     
    
 
    
-      Here is our minimalist Jamfile:
-    
    
-
    # This is the top of our own project tree
-project-root ;
-
-import python ;
-
-extension hello                     # Declare a Python extension called hello
-:   hello.cpp                       # source
-    # requirements and dependencies for Boost.Python extensions
-    <template>@boost/libs/python/build/extension
-    ;
-
    
-
    
-      First, we need to specify our location. You may place your project anywhere.
-      project-root allows you to do that.
-    
    
-
    project-root ;
-
    
-
    
-      By doing so, you'll need a Jamrules file. Simply copy the one in the example/tutorial directory
-      and tweak the path-global BOOST_ROOT to where your boost
-      root directory is. The file has detailed
-      instructions you can follow.
+      Here is our minimalist
+      Jamroot file. Simply copy the file and tweak use-project boost
+      to where your boost root directory is and your OK.
     
    
 
    
-      Then we will import the definitions needed by Python modules:
+      The comments contained in the Jamrules file above should be sufficient to get
+      you going.
     
    
-
    import python ;
-
    
-
    
-      Finally we declare our hello extension:
-    
    
-
    extension hello                     # Declare a Python extension called hello
-:   hello.cpp                       # source
-
-    # requirements and dependencies for Boost.Python extensions
-    <template>@boost/libs/python/build/extension
-    ;
-
    
-
    
-      The last part tells BJam that we are depending on the Boost Python Library.
-    
    
-
    
-
+
    
+
       Running bjam
-    
    
+    
 
    
       bjam is run using your operating system's command line
       interpreter.
@@ -169,124 +125,66 @@ extension hello                     # Declare a Python extension called hello
       
    
 
    
 
    
-      Make sure that the environment is set so that we can invoke the C++ compiler.
-      With MSVC, that would mean running the Vcvars32.bat batch
-      file. For instance:
+      A file called user-config.jam in your home directory is used to configure your
+      tools. In Windows, your home directory can be found by typing:
     
    
-
    C:\Program Files\Microsoft Visual Studio .NET 2003\Common7\Tools\vsvars32.bat
+
    ECHO %HOMEDRIVE%%HOMEPATH%
 
    
 
    
-      Some environment variables will have to be setup for proper building of our
-      Python modules. Example:
+      into a command prompt window. Your file should at least have the rules for
+      your compiler and your python installation. A specific example of this on Windows
+      would be:
     
    
-
    set PYTHON_ROOT=c:/dev/tools/python
-set PYTHON_VERSION=2.2
+
    #  MSVC configuration
+using msvc : 8.0 ;
+
+#  Python configuration
+using python : 2.4 : C:/dev/toolsPython ;
 
    
 
    
-      The above assumes that the Python installation is in c:/dev/tools/python
-      and that we are using Python version 2.2. You'll have to tweak these appropriately.
-    
    
-
    
-
    
-
    
-      tip Be sure not to include a third number, e.g. not "2.2.1", even if that's the version you
-      have.
-    
    
-
    
-
    
-      Take note that you may also do that through the Jamrules file we put in our
-      project as detailed above. The file has detailed
-      instructions you can follow.
+      The first rule tells Bjam to use the MSVC 8.0 compiler and associated tools.
+      The second rule provides information on Python, its version and where it is
+      located. The above assumes that the Python installation is in C:/dev/tools/Python/.
+      If you have one fairly "standard" python installation for your platform,
+      you might not need to do this.
     
    
 
    
-      Now we are ready... Be sure to cd to libs/python/example/tutorial
-      where the tutorial "hello.cpp" and the "Jamfile"
+      Now we are ready... Be sure to cd to libs/python/example/tutorial
+      where the tutorial "hello.cpp" and the "Jamroot"
       is situated.
     
    
 
    
       Finally:
     
    
 
    -bjam -sTOOLS=vc-7_1
+bjam
 
    
-
    
-      We are again assuming that we are using Microsoft Visual C++ version 7.1. If
-      not, then you will have to specify the appropriate tool. See Building
-      Boost Libraries for further details.
-    
    
 
    
       It should be building now:
     
    
 
    cd C:\dev\boost\libs\python\example\tutorial
-bjam -sTOOLS=msvc
+bjam
 ...patience...
-...found 1703 targets...
-...updating 40 targets...
+...found 1101 targets...
+...updating 35 targets...
 
    
 
    
       And so on... Finally:
     
    
-
    Creating library bin\boost\libs\python\build\boost_python.dll\vc-7_1\debug\th
-reading-multi\boost_python.lib and object bin\boost\libs\python\build\boost_pyth
-on.dll\vc-7_1\debug\threading-multi\boost_python.exp
-vc-C++ bin\tutorial\hello.pyd\vc-7_1\debug\threading-multi\hello.obj
-hello.cpp
-vc-Link bin\tutorial\hello.pyd\vc-7_1\debug\threading-multi\hello.pyd bin\tutori
-al\hello.pyd\vc-7_1\debug\threading-multi\hello.lib
-   Creating library bin\tutorial\hello.pyd\vc-7_1\debug\threading-multi\hello.li
-b and object bin\tutorial\hello.pyd\vc-7_1\debug\threading-multi\hello.exp
-...updated 31 targets...
-
    
-
    
-      If all is well, you should now have:
-    
    
-
      
-
    • 
-        boost_python.dll
-      
      • 
-
    • 
-        hello.pyd
-      
      • 
-
    
-
    
-      if you are on Windows, and
-    
    
-
      
-
    • 
-        libboost_python.so
-      
      • 
-
    • 
-        hello.so
-      
      • 
-
    
-
    
-      if you are on Unix.
-    
    
-
    
-      boost_python.dll and hello.pyd can be
-      found somewhere in your project's bin directory. After a
-      successful build, you make it possible for the system to find boost_python.dll
-      or libboost_python.so (usually done with LD_LIBRARY_PATH, DYLD_LIBRARY_PATH,
-      or some other variable on *nix and with PATH on Windows) and for Python to
-      find the hello module (Done with PYTHONPATH on all systems.)
-    
    
-
    
-      You may now fire up Python and run our hello module:
-    
    
-
    
-    
    
-
    ->>> import hello
->>> print hello.greet()
-hello, world
+
    Creating library path-to-boost_python.dll
+   Creating library path-to-'''hello_ext'''.exp
+**passed** ... hello.test
+...updated 35 targets...
 
    
 
    
+      Or something similar. If all is well, you should now have built the DLLs and
+      run the Python program.
     
    
 
    
 
    
         
    
 
    
-          There you go... Have fun!
+          There you go... Have fun!
         
    
 
    
       
    
@@ -299,7 +197,7 @@ b and object bin\tutorial\hello.pyd\vc-7_1\debug\threading-multi\hello.exp
 
 
    
 
    
-PrevUpHomeNext
+PrevUpHomeNext
 
    
 
 
diff --git a/doc/tutorial/doc/html/python/iterators.html b/doc/tutorial/doc/html/python/iterators.html
index a937c377..621a683e 100644
--- a/doc/tutorial/doc/html/python/iterators.html
+++ b/doc/tutorial/doc/html/python/iterators.html
@@ -3,24 +3,24 @@
 
 Iterators
 
-
+
 
 
 
-
+
 
 
-
+
    
-
    
 Boost C++ Libraries
 Home
 Libraries
 People
 FAQ
 More
    
+
 
    
 
    
-PrevUpHomeNext
+PrevUpHomeNext
 
    
 
    
 
    
@@ -30,7 +30,7 @@
       iterators, but these are two very different beasts.
     
    
 
    
-      C++ iterators:
+      C++ iterators:
     
    
 
      
 
    • 
@@ -45,7 +45,7 @@
       
      • 
 
    
 
    
-      Python Iterators:
+      Python Iterators:
     
    
 
      
 
    • 
@@ -59,8 +59,8 @@
       
      • 
 
    
 
    
-      The typical Python iteration protocol: for y
-      in x... is as follows:
+      The typical Python iteration protocol: for y
+      in x... is as follows:
     
    
 
    
     
    
@@ -74,7 +74,7 @@
 
    
 
    
       Boost.Python provides some mechanisms to make C++ iterators play along nicely
-      as Python iterators. What we need to do is to produce appropriate __iter__ function from C++ iterators that
+      as Python iterators. What we need to do is to produce appropriate __iter__ function from C++ iterators that
       is compatible with the Python iteration protocol. For example:
     
    
 
    
@@ -91,7 +91,7 @@
 .def("__iter__", iterator<vector<int> >())
 
    
 
    
-      range
+      range
     
    
 
    
       We can create a Python savvy iterator using the range function:
@@ -119,14 +119,14 @@
       
 
    
 
    
-      iterator
+      iterator
     
    
 
    • 
         iterator<T, Policies>()
       
    
 
    
-      Given a container T, iterator is a shortcut that simply
-      calls range with &T::begin, &T::end.
+      Given a container T, iterator is a shortcut that simply
+      calls range with &T::begin, &T::end.
     
    
 
    
       Let's put this into action... Here's an example from some hypothetical bogon
@@ -152,14 +152,14 @@
     .property("bogons", range(&F::b_begin, &F::b_end));

    - stl_input_iterator + stl_input_iterator

    So far, we have seen how to expose C++ iterators and ranges to Python. Sometimes we wish to go the other way, though: we'd like to pass a Python sequence to an STL algorithm or use it to initialize an STL container. We need to make - a Python iterator look like an STL iterator. For that, we use stl_input_iterator<>. - Consider how we might implement a function that exposes std::list<int>::assign() to Python: + a Python iterator look like an STL iterator. For that, we use stl_input_iterator<>. + Consider how we might implement a function that exposes std::list<int>::assign() to Python:

    @@ -178,7 +178,7 @@ ;

    - Now in Python, we can assign any integer sequence to list_int + Now in Python, we can assign any integer sequence to list_int objects:

    @@ -195,7 +195,7 @@

    -PrevUpHomeNext +PrevUpHomeNext
    diff --git a/doc/tutorial/doc/html/python/object.html b/doc/tutorial/doc/html/python/object.html index e198cca7..36e94d62 100644 --- a/doc/tutorial/doc/html/python/object.html +++ b/doc/tutorial/doc/html/python/object.html @@ -1,26 +1,26 @@ -Object Interface + Object Interface - + - +
    -
    Boost C++ Libraries Home Libraries People FAQ More
    +
    -PrevUpHomeNext +PrevUpHomeNext

    @@ -35,13 +35,13 @@ Python is dynamically typed, unlike C++ which is statically typed. Python variables may hold an integer, a float, list, dict, tuple, str, long etc., among other things. In the viewpoint of Boost.Python and C++, these Pythonic variables - are just instances of class object. We shall see in this + are just instances of class object. We will see in this chapter how to deal with Python objects.

    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 + C++ objects are as close as possible to Python. This should minimize the learning curve significantly.

    @@ -51,10 +51,10 @@

    Basic Interface

    - Class object wraps PyObject*. All the - intricacies of dealing with PyObjects such as managing - reference counting are handled by the object class. C++ - object interoperability is seamless. Boost.Python C++ objects + Class object wraps PyObject*. All the + intricacies of dealing with PyObjects such as managing + reference counting are handled by the object class. C++ + object interoperability is seamless. Boost.Python C++ objects can in fact be explicitly constructed from any C++ object.

    @@ -99,7 +99,7 @@

    Derived Object types

    - Boost.Python comes with a set of derived object types + Boost.Python comes with a set of derived object types corresponding to that of Python's:

      @@ -123,32 +123,32 @@

    - These derived object types act like real Python types. + These derived object types act like real Python types. For instance: 

     str(1) ==> "1"

    - Wherever appropriate, a particular derived object has - corresponding Python type's methods. For instance, dict - has a keys() method: + Wherever appropriate, a particular derived object has + corresponding Python type's methods. For instance, dict + has a keys() method: 

     d.keys()

    - make_tuple is provided for declaring tuple literals. + make_tuple is provided for declaring tuple literals. Example: 

     make_tuple(123, 'D', "Hello, World", 0.0);

    - In C++, when Boost.Python objects are used as arguments + In C++, when Boost.Python objects are used as arguments to functions, subtype matching is required. For example, when a function - f, as declared below, is wrapped, it will only accept - instances of Python's str type and subtypes. + f, as declared below, is wrapped, it will only accept + instances of Python's str type and subtypes. 

     void f(str name)
@@ -172,18 +172,15 @@
 object msg = "%s is bigger than %s" % make_tuple(NAME,name);

    - Demonstrates that you can write the C++ equivalent of "format" - % x,y,z in Python, which is useful since there's no easy way to + Demonstrates that you can write the C++ equivalent of "format" + % x,y,z in Python, which is useful since there's no easy way to do that in std C++.

    -
    -

    -

    - alert Beware the common pitfall +

    + alert Beware the common pitfall of forgetting that the constructors of most of Python's mutable types make copies, just as in Python. -

    -
    +

    Python:

    @@ -198,12 +195,12 @@ dict d(x.attr("__dict__")); // copies x.__dict__ d['whatever'] = 3; // modifies the copy -

    - +

    + class_<T> as objects -

    +

    - Due to the dynamic nature of Boost.Python objects, any class_<T> + 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 (type) object.

    @@ -225,15 +222,15 @@ Extracting C++ objects

    At some point, we will need to get C++ values out of object instances. This - can be achieved with the extract<T> function. Consider + can be achieved with the extract<T> function. Consider the following: 

     double x = o.attr("length"); // compile error

    - In the code above, we got a compiler error because Boost.Python object - can't be implicitly converted to doubles. Instead, what + In the code above, we got a compiler error because Boost.Python object + can't be implicitly converted to doubles. Instead, what we wanted to do above can be achieved by writing: 

    @@ -243,14 +240,14 @@

    The first line attempts to extract the "length" attribute of the - Boost.Python object. The second line attempts to extract - the Vec2 object from held by the Boost.Python object. + Boost.Python object. The second line attempts to extract + the Vec2 object from held by the Boost.Python object.

    Take note that we said "attempt to" above. What if the Boost.Python - object does not really hold a Vec2 + object does not really hold a Vec2 type? This is certainly a possibility considering the dynamic nature of Python - objects. To be on the safe side, if the C++ type can't + objects. To be on the safe side, if the C++ type can't be extracted, an appropriate exception is thrown. To avoid an exception, we need to test for extractibility:

    @@ -260,7 +257,7 @@ Vec2& v = x(); ...

    - tip The astute reader might have noticed that the extract<T> + tip The astute reader might have noticed that the extract<T> facility in fact solves the mutable copying problem: 

    @@ -273,8 +270,8 @@
 Enums

    Boost.Python has a nifty facility to capture and wrap C++ enums. While Python - has no enum type, we'll often want to expose our C++ enums - to Python as an int. Boost.Python's enum facility makes + has no enum type, we'll often want to expose our C++ enums + to Python as an int. Boost.Python's enum facility makes this easy while taking care of the proper conversions from Python's dynamic typing to C++'s strong static typing (in C++, ints cannot be implicitly converted to enums). To illustrate, given a C++ enum: @@ -293,19 +290,26 @@

    can be used to expose to Python. The new enum type is created in the current - scope(), which is usually the current module. The snippet - above creates a Python class derived from Python's int + scope(), which is usually the current module. The snippet + above creates a Python class derived from Python's int type which is associated with the C++ type passed as its first parameter.

    -
    -

    +
    + + + + + +
    [Note]Note

    - note what is a scope?
    -
    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 here. -

    - + what is a scope? +

    +

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

    +

    You can access those values in Python as

    @@ -342,7 +346,7 @@
    -PrevUpHomeNext +PrevUpHomeNext
    diff --git a/doc/tutorial/doc/html/python/techniques.html b/doc/tutorial/doc/html/python/techniques.html index 4b8971ec..d4c60f54 100644 --- a/doc/tutorial/doc/html/python/techniques.html +++ b/doc/tutorial/doc/html/python/techniques.html @@ -1,25 +1,25 @@ -General Techniques + General Techniques - + - + - +
    -
    Boost C++ Libraries Home Libraries People FAQ More
    +
    -PrevUpHome +PrevUpHome

    @@ -50,7 +50,7 @@

    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, + sounds. Our library already has a neat C++ namespace hierarchy, like so: 

    @@ -93,18 +93,21 @@
 }

    - Compiling these files will generate the following Python extensions: core.pyd, - io.pyd and filters.pyd. + Compiling these files will generate the following Python extensions: core.pyd, + io.pyd and filters.pyd.

    -
    -

    -

    - note The extension .pyd is used for python - extension modules, which are just shared libraries. Using the default for - your system, like .so for Unix and .dll - for Windows, works just as well. -

    -
    +
    + + + + + +
    [Note]Note

    + The extension .pyd is used for python extension modules, + which are just shared libraries. Using the default for your system, like + .so for Unix and .dll for Windows, + works just as well. +

    Now, we create this directory structure for our Python package:

    @@ -115,12 +118,12 @@ io.pyd

    - The file __init__.py is what tells Python that the directory - sounds/ is actually a Python package. It can be a empty + 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.

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

    @@ -159,7 +162,7 @@

    Note that we added an underscore to the module name. The filename will have - to be changed to _core.pyd as well, and we do the same + to be changed to _core.pyd as well, and we do the same to the other extension modules. Now, we change our package hierarchy like so:

    @@ -187,11 +190,11 @@ >>> sounds.core._core.foo(...)

    - which is not what we want. But here enters the __init__.py - magic: everything that is brought to the __init__.py namespace + which is not what we want. But here enters the __init__.py + magic: everything that is brought to the __init__.py namespace can be accessed directly by the user. So, all we have to do is bring the - entire namespace from _core.pyd to core/__init__.py. - So add this line of code to soundscore__init__.py: + entire namespace from _core.pyd to core/__init__.py. + So add this line of code to soundscore__init__.py: 

     from _core import *
@@ -208,10 +211,10 @@
         with the additional benefit that we can easily add pure Python functions
         to any module, in a way that the user can't tell the difference between a
         C++ function and a Python function. Let's add a pure
-        Python function, echo_noise, to the filters
-        package. This function applies both the echo and noise
-        filters in sequence in the given sound object. We create
-        a file named sounds/filters/echo_noise.py and code our
+        Python function, echo_noise, to the filters
+        package. This function applies both the echo and noise
+        filters in sequence in the given sound object. We create
+        a file named sounds/filters/echo_noise.py and code our
         function:
       
    
 
    @@ -222,14 +225,14 @@
     return s
 
    
 
    
-        Next, we add this line to soundsfilters__init__.py:
+        Next, we add this line to soundsfilters__init__.py:
       
    
 
     from echo_noise import echo_noise
 
    
 
    
         And that's it. The user now accesses this function like any other function
-        from the filters package:
+        from the filters package:
       
    
 
     >>> import sounds.filters
@@ -263,7 +266,7 @@
       
    
 
    
         We can do the same with classes that were wrapped with Boost.Python. Suppose
-        we have a class point in C++:
+        we have a class point in C++:
       
    
 
    
       
    
@@ -277,7 +280,7 @@
 
    
 
    
         If we are using the technique from the previous session, Creating
-        Packages, we can code directly into geom/__init__.py:
+        Packages, we can code directly into geom/__init__.py:
       
    
 
    
       
    
@@ -292,7 +295,7 @@
 point.__str__ = point_str

    - All point instances created from C++ will + All point instances created from C++ will also have this member function! This technique has several advantages:

      @@ -391,7 +394,7 @@ }

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

      @@ -427,23 +430,28 @@
         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.
       
      
-
      
-
      
-
      
-        note 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.
-      
      
-
      
-
      
-
      
-
      
-        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 FAQ.
-      
      
-
      
+
      
+
+
+
+
+
+
      [Note]Note
      
+          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.
+        
      
+
      
+
+
+
+
+
+
      [Note]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 FAQ.
+

    @@ -453,7 +461,7 @@
    -PrevUpHome +PrevUpHome
    diff --git a/doc/tutorial/doc/tutorial.qbk b/doc/tutorial/doc/tutorial.qbk index 13a2222a..bd02cd04 100644 --- a/doc/tutorial/doc/tutorial.qbk +++ b/doc/tutorial/doc/tutorial.qbk @@ -49,10 +49,10 @@ Function: can be exposed to Python by writing a Boost.Python wrapper: #include - using namespace boost::python; - BOOST_PYTHON_MODULE(hello) + BOOST_PYTHON_MODULE(hello_ext) { + using namespace boost::python; def("greet", greet); } @@ -61,7 +61,7 @@ resulting DLL is now visible to Python. Here's a sample Python session: [python] - >>> import hello + >>> import hello_ext >>> print hello.greet() hello, world @@ -75,43 +75,39 @@ resulting DLL is now visible to Python. Here's a sample Python session: [h2 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 -necessary to achieve that. We shall use the build tool that comes bundled +try it for yourself in Python. In this section, we will outline the steps +necessary to achieve that. We will use the build tool that comes bundled with every boost distribution: [*bjam]. -[blurb __note__ [*Building without bjam]\n\n - 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].\n\n - 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. +[note [*Building without bjam] + +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 +who had to use a different tool. ] -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]. -After this brief ['bjam] tutorial, we should have built two DLLs: - -* boost_python.dll -* hello.pyd - -if you are on Windows, and - -* libboost_python.so -* hello.so - -if you are on Unix. +We will 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]. After this brief ['bjam] tutorial, we should have built +the DLLs and run a python program using the extension. The tutorial example can be found in the directory: [^libs/python/example/tutorial]. There, you can find: * hello.cpp -* Jamfile +* hello.py +* Jamroot -The [^hello.cpp] file is our C++ hello world example. The [^Jamfile] is a -minimalist ['bjam] script that builds the DLLs for us. +The [^hello.cpp] file is our C++ hello world example. The [^Jamroot] is +a minimalist ['bjam] script that builds the DLLs for us. Finally, +[^hello.py] is our Python program that uses the extension in +[^hello.cpp]. 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 @@ -122,51 +118,12 @@ platforms. The complete list of Bjam executables can be found [h2 Let's Jam!] __jam__ -Here is our minimalist Jamfile: +[@../../../../example/tutorial/Jamroot Here] is our minimalist Jamroot +file. Simply copy the file and tweak [^use-project boost] to where your +boost root directory is and your OK. -[pre -# This is the top of our own project tree -project-root ; - -import python ; - -extension hello # Declare a Python extension called hello -: hello.cpp # source - # requirements and dependencies for Boost.Python extensions -