From 8a94c597a050e05940c95822fcc353e3af6c461b Mon Sep 17 00:00:00 2001 From: Joel de Guzman Date: Wed, 9 Oct 2002 14:31:39 +0000 Subject: [PATCH] More tweaks (tutorial) [SVN r15826] --- doc/tutorial/doc/building_hello_world.html | 19 ++++-- doc/tutorial/doc/call_policies.html | 2 +- doc/tutorial/doc/class_data_members.html | 7 +-- doc/tutorial/doc/class_virtual_functions.html | 7 ++- doc/tutorial/doc/constructors.html | 2 +- doc/tutorial/doc/derived_object_types.html | 27 +++++---- doc/tutorial/doc/quickstart.txt | 54 ++++++++++++------ doc/tutorial/doc/theme/jam.png | Bin 0 -> 3884 bytes 8 files changed, 76 insertions(+), 42 deletions(-) create mode 100644 doc/tutorial/doc/theme/jam.png diff --git a/doc/tutorial/doc/building_hello_world.html b/doc/tutorial/doc/building_hello_world.html index 68094b60..8595ea56 100644 --- a/doc/tutorial/doc/building_hello_world.html +++ b/doc/tutorial/doc/building_hello_world.html @@ -36,22 +36,26 @@ building Boost.Python, check out: building.html. After this brief bjam tutorial, we should have built two DLLs:

-This assumes of course that we are running on Windows.

+if you are on Windows, and

+

+if you are on Unix.

The tutorial example can be found in the directory: -/libs/python/example/tutorial. There, you can find:

+libs/python/example/tutorial. There, you can find:

The hello.cpp file is our C++ hello world example. The Jamfile is a minimalist bjam script that builds the DLLs for us.

Before anything else, you should have the bjam executable in your boost -directory. Pre-built Boost.Jam executables are available for some +directory. Pre-built Boost.Jam executables are available for most platforms. For example, a pre-built Microsoft Windows bjam executable can be downloaded here. The complete list of bjam pre-built executables can be found here.

Lets Jam!

+

+

Here is our minimalist Jamfile:

     subproject libs/python/example/tutorial ;
@@ -99,8 +103,9 @@ Python modules. Example:

The above assumes that the Python installation is in c:/dev/tools/python -and that we are using Python version 2.2. Be sure not to include a third -number, e.g. not "2.2.1", even if that's the version you have.

+and that we are using Python version 2.2. You'll have to tweak this path +appropriately. Be sure not to include a third number, e.g. not "2.2.1", +even if that's the version you have.

Now we are ready... Be sure to cd to libs/python/example/tutorial where the tutorial "hello.cpp" and the "Jamfile" is situated.

@@ -139,6 +144,10 @@ And so on... Finally:

If all is well, you should now have:

+if you are on Windows, and

+

+if you are on Unix.

+

boost_python.dll can be found somewhere in libs\python\build\bin while hello.pyd can be found somewhere in libs\python\example\tutorial\bin. After a successful build, you can just diff --git a/doc/tutorial/doc/call_policies.html b/doc/tutorial/doc/call_policies.html index f0decf84..194097df 100644 --- a/doc/tutorial/doc/call_policies.html +++ b/doc/tutorial/doc/call_policies.html @@ -142,7 +142,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 found here.

diff --git a/doc/tutorial/doc/class_data_members.html b/doc/tutorial/doc/class_data_members.html index 4718880c..39847ba8 100644 --- a/doc/tutorial/doc/class_data_members.html +++ b/doc/tutorial/doc/class_data_members.html @@ -56,12 +56,11 @@ Then, in Python:

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

-    >>> x.name = 'e' #can't change name
+    >>> x.name = 'e' # can't change name
     Traceback (most recent call last):
       File "<stdin>", line 1, in ?
-    AttributeError: can't set attribute
-
 -
+ AttributeError: can't set attribute +
diff --git a/doc/tutorial/doc/class_virtual_functions.html b/doc/tutorial/doc/class_virtual_functions.html index dea828c4..72c3fe3d 100644 --- a/doc/tutorial/doc/class_virtual_functions.html +++ b/doc/tutorial/doc/class_virtual_functions.html @@ -92,15 +92,16 @@ polymorphically fromC++.

Wrapping Base and the free function call_f:

-    class_<Base, BaseWrap, noncopyable>("Base", no_init)
+    class_<Base, BaseWrap, boost::noncopyable>("Base", no_init)
         ;
     def("call_f", call_f);

Notice that we parameterized the class_ template with BaseWrap as the second parameter. What is noncopyable? Without it, the library will try -to instantiate a copy constructor for returning Base objects from -functions.

+to create code for converting Base return values of wrapped functions to +Python. To do that, it needs Base's copy constructor... which isn't +available, since Base is an abstract class.

In Python, let us try to instantiate our Base class:

diff --git a/doc/tutorial/doc/constructors.html b/doc/tutorial/doc/constructors.html
index 621387f5..79237526 100644
--- a/doc/tutorial/doc/constructors.html
+++ b/doc/tutorial/doc/constructors.html
@@ -64,7 +64,7 @@ expose instead.

 

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

+""__init__"").

 

 We can expose additional constructors by passing more init<...>s to
 the def() member function. Say for example we have another World
diff --git a/doc/tutorial/doc/derived_object_types.html b/doc/tutorial/doc/derived_object_types.html
index 4d08db05..303774f7 100644
--- a/doc/tutorial/doc/derived_object_types.html
+++ b/doc/tutorial/doc/derived_object_types.html
@@ -70,18 +70,21 @@ member functions.

 

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

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

- - dict d(x.attr("__dict__")); # makes a copy of x's dict
- d['whatever'] = 3; # modifies a copy of x.__dict__ (not the original)
 -
+

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

+

+Python:

+
+    >>> d = dict(x.__dict__)     #copies x.__dict__
+    >>> d['whatever']            #modifies the copy
+
 +

+C++:

+
+    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> may also be one of these types! The following code snippet wraps the class diff --git a/doc/tutorial/doc/quickstart.txt b/doc/tutorial/doc/quickstart.txt index ecf3b87d..a8176ec1 100644 --- a/doc/tutorial/doc/quickstart.txt +++ b/doc/tutorial/doc/quickstart.txt @@ -65,10 +65,15 @@ After this brief ['bjam] tutorial, we should have built two DLLs: * boost_python.dll * hello.pyd -This assumes of course that we are running on Windows. +if you are on Windows, and + +* libboost_python.so +* hello.so + +if you are on Unix. The tutorial example can be found in the directory: -[^/libs/python/example/tutorial]. There, you can find: +[^libs/python/example/tutorial]. There, you can find: * hello.cpp * Jamfile @@ -77,12 +82,13 @@ The [^hello.cpp] file is our C++ hello world example. The [^Jamfile] is a minimalist ['bjam] script that builds the DLLs for us. Before anything else, you should have the bjam executable in your boost -directory. Pre-built Boost.Jam executables are available for some +directory. Pre-built Boost.Jam executables are available for most platforms. For example, a pre-built Microsoft Windows bjam executable can be downloaded [@http://boost.sourceforge.net/jam-executables/bin.ntx86/bjam.zip here]. The complete list of bjam pre-built executables can be found [@../../../../../tools/build/index.html#Jam here]. [h2 Lets Jam!] +[$theme/jam.png] Here is our minimalist Jamfile: @@ -141,8 +147,9 @@ Python modules. Example: set PYTHON_VERSION=2.2 The above assumes that the Python installation is in [^c:/dev/tools/python] -and that we are using Python version 2.2. Be sure not to include a third -number, e.g. [*not] "2.2.1", even if that's the version you have. +and that we are using Python version 2.2. You'll have to tweak this path +appropriately. __note__ Be sure not to include a third number, e.g. [*not] "2.2.1", +even if that's the version you have. Now we are ready... Be sure to [^cd] to [^libs/python/example/tutorial] where the tutorial [^"hello.cpp"] and the [^"Jamfile"] is situated. @@ -186,6 +193,13 @@ 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] can be found somewhere in [^libs\python\build\bin] while [^hello.pyd] can be found somewhere in [^libs\python\example\tutorial\bin]. After a successful build, you can just @@ -276,7 +290,7 @@ expose instead. [^init()] exposes the constructor taking in a [^std::string] (in Python, constructors are spelled -"[^__init__(...)]"). +"[^"__init__"]"). We can expose additional constructors by passing more [^init<...>]s to the [^def()] member function. Say for example we have another World @@ -326,10 +340,12 @@ Then, in Python: Note that [^name] is exposed as [*read-only] while [^value] is exposed as [*read-write]. +[pre >>> x.name = 'e' # can't change name Traceback (most recent call last): File "", line 1, in ? AttributeError: can't set attribute +] [page:1 Class Properties] @@ -482,14 +498,15 @@ polymorphically ['from] [*C++].] Wrapping [^Base] and the free function [^call_f]: - class_("Base", no_init) + class_("Base", no_init) ; def("call_f", call_f); Notice that we parameterized the [^class_] template with [^BaseWrap] as the second parameter. What is [^noncopyable]? Without it, the library will try -to instantiate a copy constructor for returning Base objects from -functions. +to create code for converting Base return values of wrapped functions to +Python. To do that, it needs Base's copy constructor... which isn't +available, since Base is an abstract class. In Python, let us try to instantiate our [^Base] class: @@ -820,7 +837,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/CallPolicies.html here]. +these can be found [@../../v2/reference.html#models_of_call_policies here]. * [*with_custodian_and_ward][br] Ties lifetimes of the arguments * [*with_custodian_and_ward_postcall][br] Ties lifetimes of the arguments and results @@ -1007,13 +1024,18 @@ member functions. 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++. -[blurb __alert__ Beware the common pitfall of -forgetting that the constructors of most of Python's mutable types -make copies, just as in Python.[br][br] +__alert__ [*Beware] the common pitfall of forgetting that the constructors +of most of Python's mutable types make copies, just as in Python. - [^dict d(x.attr("__dict__")); # makes a copy of x's dict[br] - '''d['whatever']''' = 3; # modifies a copy of x.__dict__ (not the original)[br]] -] +Python: + + >>> d = dict(x.__dict__) # copies x.__dict__ + >>> d['whatever'] # modifies the copy + +C++: + + dict d(x.attr("__dict__")); # copies x.__dict__ + d['whatever'] = 3; # modifies the copy [h2 class_ as objects] diff --git a/doc/tutorial/doc/theme/jam.png b/doc/tutorial/doc/theme/jam.png new file mode 100644 index 0000000000000000000000000000000000000000..224ed7914bb5a31a407511093500aa1fe9d9e571 GIT binary patch literal 3884 zcmeAS@N?(olHy`uVBq!ia0y~yV5nzcU~uJNV_;xNjW#hE=bLrwBlWk7u9BNWG%WIzG^?ia{Jx0?d2cu65lo_tIq4R{ZpB|^Gj6) zSQHbUotHf@zxm;v$tNPW%s1Luc2<|6?FW0^VrZqF7Q%Y`1Ew|lr=xYj$EHQEz3mDMmMpd z>ejiX)97pynn`5kW z|CRi$_`uF-U0Tl!|N5S1TOOPDXU~o+TYOinI`YoqQ_`=^1)VOOpVS2UPMZHtf92(U zF(~lpmyJ~=b>FwfdM6w>w@64vPjkD9T!BlS8{-PeFW+C~FR$XwJ;(0LL4_y0b2(bBrxt6b;~fkM&QareVtIlX>mx{c)k=f}URyJiaR zcRjOF;pM%D1^TaQcvl$+gnzii-F1xrciDrp+t{xBlnQwM`lzw)`c>DOBDhY4PWZnt zR)FQek=PkocKsFVcH$fQ_AtJdIN(>n{=t*q-~sQq@h3+fzfG`F{L=O>KV|n{Gpl%-%i!=JgyXArJMZ($hYaT!{XP6Jj;Fo) z|Aw2nSEX5*73

m`0On#VPL z(`-H6pYI}XPFPiH`tH!Kb;Un6?Qy%i{QJk7Kgwo3X;m_c?qD_-v=DX5Fi847WiQi| zOos3Fb}>PHhgF}RNnUp>c14!$A=P;at9~2T{H^G|>zKLjeb$}USKF@hI=QIlzxh#q zizPj~PF#1{BZ2k33I*Hv7cN|p85}u{mC-BY{M`GWeC#f|xhKE=$1~Zz-}%+flv{nO zAzQA!X10lXExuOF|7hbTuh(TazbR^dS1j1ZFPr|mLf1Mal5fVO{Aq#4#$Tr;zxmgr z&2Tk$z4W)2TkUrJW!Jd9Nsd9l=ZJXQ6U|dc&v-c$NiiNfE7rbfl~~=cck4f87pnbB zzwxyGdGa*T8``Hg?O^Jf@%J*Hy^^P9l@*`w@6|HD8oc=bku@x5{FpZj9XZHxpIvcqk*@0k_3 z7MK1VF?R@(?6(kU{eOJx%j9*Zwn)#MDx&C_m2UMYK&1Nq&xrca(yxGtLj* zi!1zlDEirLvrxhF=&#zjyKc|F+jn5|ZP9FnkLl(zk4zPwv?pwS(C~EfS^?=^WwTih zf6ZKrI?Ik96MC`Bpy}Chxu)gIf^6kLa?>1gOd6-k?|Hw&UM*v--^@Jgz`}KcQe94a z?r{G<%>Pk3aLKFMvg0@HTm$acHC6AD{P^V&pJIGVU(K}r@xMJM*eCEMEiNpH-LtSx zZC2d=tzz?Lae;WhDw+I!Rg;oAkJm~%aGY=cnbxqg>e#7;Ea$#CF7dTseiSf8d(Ogz z8ZFQ5J)#-!R;o$KFWPUR_27)kiPyU-n7>A6hvvSM?^t!DI!o(eWcb22x0h{E6l;iJ zZ|b}p9$34e@v=7;&s(wfML!j8f19;a=XBj(hL)fspAyVF-Wbe3XQ=O6pE&9Kr7G?C z`D zi(M-Gyp~5WO*p^fP>KxWuispoj6?0-O0<+P?6|*~^KWzD)Ee82Vn2^%Tj#6IW2s}A zoUUst`zD_CY*Jowe`4WXJKw6zNY-mt z^1}Kv&wO`?lCUuqJ)jWeviz*=#k$&R2TlXert~F`m3?v}xmBjB-fvu|f2C|TLynVR z-Q&swMQ zmE`s2YdL?P|60rSk!1_Rgni+BHLMTMJePR!%gK39@DH!pjFl@6+1v0hDE%sR_+yP- zq|WJ0@zYWpZ!xX(J@cU|=~azlXu~Z=H(jOExfh?TR)3>o6t?G8^IqP#);TXV%R>B= zDuhl5R$L2}SX90BZiLfTj*{7{t|_l#n6PTW{ChK7!;Ru!Z)c8QdHO@g^}Re^GkjVZ zA7uQSYME@fOzxh@&yOD^K3C+J9Q@<+yEf@rzla1-r5WNE&Q7<~eUV9&lNMK#@Zb{Ft-JUJ0w%n5U z@tM_ExU$J}pX_}8C8qPGzx1lkc(%7LTle}F;TfWJ0*VR=nL8t2&XAj<8E-u$s$G@a z_NVLv7VABaxF3CA`u=gjT9a4yCvQ#cbr5A~6Zmjy-?47ip7kE~e(qd0a|PDAKQE6@ zuX(qZFYmzjduL>OUp}As{_C|zVJdAeSGIWV`%)XTmCg2U;FbK#>l{jBB`)gRxxkd* zw&&kMo?TN`SC#qAWt_3Feri!)uX@F|S#cSh2LiX)U#vVMkSn}jUcO&)S#7T`zx29~ z58Z2b`0k9TwVL5-^LioAy!m-6jp~DLxW(3UoSJ>u2X~T z8cU7pOQ!PWN4Xy``YH3N_@~g)rl#E8RjGMw(^slHNzImXdmXL+_@(+(OWT>NtM_iT zsK}6KaQ*!Fv7w3muE@1FSl4v2-#948&Hb0_aVQ!;6cq48-?D-TTb)VXPq*y z{9$h|F zb@iUP|J8e=&WBaG5t?_MYW?fhO$d~{K6R($Ri+z)47J4lAo1cLc!v{A+|dhx);1Ub%$r(>|MDWEOQUM z;hj4trY@s0Z@%rDeHE4r(ofH%>E}OkeE<05Ws@hy>eJ_czP?yoDQADt-IM)08y9^mUe%y%zQN~