From: troy_at_[hidden]
Date: 2008-06-30 10:36:35
Author: troy
Date: 2008-06-30 10:36:33 EDT (Mon, 30 Jun 2008)
New Revision: 46913
URL: http://svn.boost.org/trac/boost/changeset/46913
Log:
merge from release branch
Text files modified:
branches/CMake/release/libs/assign/doc/index.html | 20
branches/CMake/release/libs/assign/test/list_of.cpp | 40 +++
branches/CMake/release/libs/fusion/test/functional/invoke.cpp | 2
branches/CMake/release/libs/fusion/test/functional/invoke_function_object.cpp | 2
branches/CMake/release/libs/fusion/test/functional/invoke_procedure.cpp | 2
branches/CMake/release/libs/maintainers.txt | 3
branches/CMake/release/libs/python/doc/tutorial/doc/html/index.html | 24 +-
branches/CMake/release/libs/python/doc/tutorial/doc/html/python/embedding.html | 10
branches/CMake/release/libs/python/doc/tutorial/doc/html/python/exposing.html | 4
branches/CMake/release/libs/python/doc/tutorial/doc/html/python/functions.html | 6
branches/CMake/release/libs/python/doc/tutorial/doc/html/python/hello.html | 3
branches/CMake/release/libs/python/doc/tutorial/doc/html/python/object.html | 2
branches/CMake/release/libs/python/doc/tutorial/doc/tutorial.qbk | 4
branches/CMake/release/libs/python/doc/v2/pickle.html | 457 +++++++++++++++++----------------------
14 files changed, 287 insertions(+), 292 deletions(-)
Modified: branches/CMake/release/libs/assign/doc/index.html
==============================================================================
--- branches/CMake/release/libs/assign/doc/index.html (original)
+++ branches/CMake/release/libs/assign/doc/index.html 2008-06-30 10:36:33 EDT (Mon, 30 Jun 2008)
@@ -23,7 +23,7 @@
</p>
<p>
Use, modification and distribution is subject to the Boost Software License, Version 1.0
- (see <a href=http://www.boost.org/LICENSE_1_0.txt>
+ (see <a href="http://www.boost.org/LICENSE_1_0.txt">
http://www.boost.org/LICENSE_1_0.txt>).
</p>
<h3>Table of Contents</h3>
@@ -706,7 +706,7 @@
All forwarding is done by passing objects by <code>const</code> reference.
Originally arguments were passed by value (and still is in
<code>tuple_list_of()</code>). One thing to remember is that references
- can be passed by using <code>boost::<a href=http://www.boost.org/doc/html/ref.html>ref</a></code>.
+ can be passed by using <code>boost::ref</code>.
</p>
<p>
@@ -871,7 +871,7 @@
<p>
These two functions are used to construct anonymous
list which can be converted to any standard container
- and <code>boost::<a href=../../array/index.html>array</a><T,sz>.</code>
+ and <code>boost::array<T,sz>.</code>
The object returned by the two
functions is guaranteed to have the interface described below.
</p>
@@ -1292,9 +1292,9 @@
Here is a list libraries has been tested with Boost.Assign:
<ol>
- <li> <code>boost::<a href=../../array/index.html>array</a></code>
- <li> <code>boost::<a href=../../multi_index/index.html>multi_index_container</a></code>
- <li> <code>Boost.<a href=../../ptr_container/index.html>Pointer Container</code> </ol> <p>
+ <li> <code>boost::array</code>
+ <li> <code>boost::multi_index_container</code>
+ <li> <code>Boost.<a href="../../ptr_container/index.html">Pointer Container</code> </ol> <p>
</p>
@@ -1357,9 +1357,9 @@
library is non-intrusive and puts only a minimum of requirements
on its supported classes.
Overloading operator comma is sometimes viewed as a bad practice <a
-href=#meyers>[1]</A>. However, it has been done
+href="#meyers">[1]</A>. However, it has been done
with success in eg. the Generative Matrix Computation Library and Blitz to initialize matrices
- (see <a href=#gmcl>[2]</A>) and <a href=#blitz>[3]</A>). The
+ (see [2]) and [3]). The
Initialization Library overloads
the comma operator in a safe manner by letting free standing functions
return an object that is responsible for the initialization. Therefore it takes
@@ -1388,10 +1388,10 @@
<ol>
<li> <a name="meyers"> Scott. Meyers, "More Effective C++", Item 7, Addison Wesley, 1996
<li> <a name="gmcl"> K. Czarnecki and U.W. Eisenecker, "Generative programming", Addison-Wesley, 2000
- <li> <a name="blitz"> <a href=http://www.oonumerics.org/blitz/> http://www.oonumerics.org/blitz/ </A>
+ <li> <a name="blitz"> http://www.oonumerics.org/blitz/
<li> <a name="initializer">
Gabriel Dos Reis and Bjarne Stroustrup,
- <a href=http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1509.pdf> "Generalized Initializer
+ <a href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1509.pdf"> "Generalized Initializer
Lists"</a>, 2003 </a>
</OL>
</p>
Modified: branches/CMake/release/libs/assign/test/list_of.cpp
==============================================================================
--- branches/CMake/release/libs/assign/test/list_of.cpp (original)
+++ branches/CMake/release/libs/assign/test/list_of.cpp 2008-06-30 10:36:33 EDT (Mon, 30 Jun 2008)
@@ -224,7 +224,44 @@
*/
}
+//
+// @remark: ADL is required here, but it is a bit wierd to
+// open up namespace std. Perhaps Boost.Test needs a
+// better configuration option.
+//
+namespace std
+{
+ template< class T, class Elem, class Traits >
+ inline std::basic_ostream<Elem,Traits>&
+ operator<<( std::basic_ostream<Elem, Traits>& Os,
+ const std::vector<T>& r )
+ {
+ return Os << ::boost::make_iterator_range( r.begin(), r.end() );
+ }
+}
+template <class Seq>
+inline std::vector<int> as_seq( const Seq& s )
+{
+ std::vector<int> c;
+ return s.to_container( c );
+}
+
+void test_comparison_operations()
+{
+ BOOST_CHECK_EQUAL( ba::list_of(0)(1)(2), as_seq(ba::list_of(0)(1)(2)) );
+ BOOST_CHECK_NE( ba::list_of(0)(1)(2), as_seq(ba::list_of(-1)(1)(2)) );
+ BOOST_CHECK_LT( ba::list_of(0)(1)(2), as_seq(ba::list_of(0)(1)(3)) );
+ BOOST_CHECK_LE( ba::list_of(0)(1)(2), as_seq(ba::list_of(0)(1)(2)) );
+ BOOST_CHECK_GT( ba::list_of(0)(1)(3), as_seq(ba::list_of(0)(1)(2)) );
+ BOOST_CHECK_GE( ba::list_of(0)(1)(2), as_seq(ba::list_of(0)(1)(2)) );
+ BOOST_CHECK_EQUAL( as_seq(ba::list_of(0)(1)(2)), ba::list_of(0)(1)(2) );
+ BOOST_CHECK_NE( as_seq(ba::list_of(0)(1)(2)), ba::list_of(-1)(1)(2) );
+ BOOST_CHECK_LT( as_seq(ba::list_of(0)(1)(2)), ba::list_of(0)(1)(3) );
+ BOOST_CHECK_LE( as_seq(ba::list_of(0)(1)(2)), ba::list_of(0)(1)(2) );
+ BOOST_CHECK_GT( as_seq(ba::list_of(0)(1)(3)), ba::list_of(0)(1)(2) );
+ BOOST_CHECK_GE( as_seq(ba::list_of(0)(1)(2)), ba::list_of(0)(1)(2) );
+}
void check_list_of()
{
@@ -242,9 +279,8 @@
std::stack<std::string> s = ba::list_of( "Foo" )( "Bar" )( "FooBar" ).to_adapter( s );
test_list_of();
-
test_vector_matrix();
-
+ test_comparison_operations();
}
Modified: branches/CMake/release/libs/fusion/test/functional/invoke.cpp
==============================================================================
--- branches/CMake/release/libs/fusion/test/functional/invoke.cpp (original)
+++ branches/CMake/release/libs/fusion/test/functional/invoke.cpp 2008-06-30 10:36:33 EDT (Mon, 30 Jun 2008)
@@ -1,5 +1,5 @@
/*=============================================================================
- Copyright (c) 2005-2006 João Abecasis
+ Copyright (c) 2005-2006 Joao Abecasis
Copyright (c) 2006-2007 Tobias Schwinger
Use modification and distribution are subject to the Boost Software
Modified: branches/CMake/release/libs/fusion/test/functional/invoke_function_object.cpp
==============================================================================
--- branches/CMake/release/libs/fusion/test/functional/invoke_function_object.cpp (original)
+++ branches/CMake/release/libs/fusion/test/functional/invoke_function_object.cpp 2008-06-30 10:36:33 EDT (Mon, 30 Jun 2008)
@@ -1,5 +1,5 @@
/*=============================================================================
- Copyright (c) 2005-2006 João Abecasis
+ Copyright (c) 2005-2006 Joao Abecasis
Copyright (c) 2006-2007 Tobias Schwinger
Use modification and distribution are subject to the Boost Software
Modified: branches/CMake/release/libs/fusion/test/functional/invoke_procedure.cpp
==============================================================================
--- branches/CMake/release/libs/fusion/test/functional/invoke_procedure.cpp (original)
+++ branches/CMake/release/libs/fusion/test/functional/invoke_procedure.cpp 2008-06-30 10:36:33 EDT (Mon, 30 Jun 2008)
@@ -1,5 +1,5 @@
/*=============================================================================
- Copyright (c) 2005-2006 João Abecasis
+ Copyright (c) 2005-2006 Joao Abecasis
Copyright (c) 2006-2007 Tobias Schwinger
Use modification and distribution are subject to the Boost Software
Modified: branches/CMake/release/libs/maintainers.txt
==============================================================================
--- branches/CMake/release/libs/maintainers.txt (original)
+++ branches/CMake/release/libs/maintainers.txt 2008-06-30 10:36:33 EDT (Mon, 30 Jun 2008)
@@ -1,3 +1,4 @@
+accumulators Eric Niebler <eric -at- boost-consulting.com>
algorithm/minmax Herve Bronnimann <hbr -at- poly.edu>
algorithm/string Pavol Droba <droba -at- topmail.sk>
any Alexander Nasonov <alexander.nasonov -at- gmail.com>
@@ -65,6 +66,8 @@
tuple Jaakko Jarvi <jarvi -at- cs.tamu.edu>
type_traits John Maddock <john -at- johnmaddock.co.uk>
typeof Arkadiy Vertleyb <vertleyb -at- hotmail.com>, Peder Holt <peder.holt -at- gmail.com>
+units Matthias Schabel <boost -at- schabel-family.org>, Steven Watanabe <steven -at- providere-consulting.com>
+unordered Daniel James <daniel_james -at- fmail.co.uk>
utility
utility/enable_if Jaakko Jarvi <jarvi -at- cs.tamu.edu>, Jeremiah Willcock <jewillco -at- osl.iu.edu>
variant Eric Friedman <ericbrandon -at- gmail.com>
Modified: branches/CMake/release/libs/python/doc/tutorial/doc/html/index.html
==============================================================================
--- branches/CMake/release/libs/python/doc/tutorial/doc/html/index.html (original)
+++ branches/CMake/release/libs/python/doc/tutorial/doc/html/index.html 2008-06-30 10:36:33 EDT (Mon, 30 Jun 2008)
@@ -3,17 +3,17 @@
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Chapter 1. python 1.0</title>
<link rel="stylesheet" href="../../../../../../doc/html/boostbook.css" type="text/css">
-<meta name="generator" content="DocBook XSL Stylesheets V1.73.2">
+<meta name="generator" content="DocBook XSL Stylesheets V1.66.1">
<link rel="start" href="index.html" title="Chapter 1. python 1.0">
-<link rel="next" href="python/hello.html" title="Building Hello World">
+<link rel="next" href="python/hello.html" title=" Building Hello World">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
-<td align="center">Home</td>
+<td align="center">Home</td>
<td align="center">Libraries</td>
-<td align="center">People</td>
-<td align="center">FAQ</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
<td align="center">More</td>
</tr></table>
<hr>
@@ -31,7 +31,7 @@
<div><p class="copyright">Copyright © 2002-2005 Joel
de Guzman, David Abrahams</p></div>
<div><div class="legalnotice">
-<a name="id2625929"></a><p>
+<a name="id455921"></a><p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">
http://www.boost.org/LICENSE_1_0.txt </a>)
@@ -93,10 +93,10 @@
code takes on the look of a kind of declarative interface definition language
(IDL).
</p>
-<a name="quickstart.hello_world"></a><h3>
-<a name="id2625972"></a>
+<a name="quickstart.hello_world"></a><h2>
+<a name="id385276"></a>
Hello World
- </h3>
+ </h2>
<p>
Following C/C++ tradition, let's start with the "hello, world". A
C++ Function:
@@ -136,8 +136,8 @@
<p>
</p>
<p>
- <span class="emphasis"><em><span class="bold"><strong>Next stop... Building your Hello World
- module from start to finish...</strong></span></em></span>
+ <span class="emphasis"><em><span class="bold"><b>Next stop... Building your Hello World
+ module from start to finish...</b></span></em></span>
</p>
<p>
</p>
@@ -145,7 +145,7 @@
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
-<td align="left"><p><small>Last revised: March 15, 2008 at 13:46:47 GMT</small></p></td>
+<td align="left"><p><small>Last revised: March 24, 2008 at 23:09:39 GMT</small></p></td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>
Modified: branches/CMake/release/libs/python/doc/tutorial/doc/html/python/embedding.html
==============================================================================
--- branches/CMake/release/libs/python/doc/tutorial/doc/html/python/embedding.html (original)
+++ branches/CMake/release/libs/python/doc/tutorial/doc/html/python/embedding.html 2008-06-30 10:36:33 EDT (Mon, 30 Jun 2008)
@@ -40,7 +40,7 @@
Python/C API at all. So stay tuned... <span class="inlinemediaobject"><img src="../images/smiley.png" alt="smiley"></span>
</p>
<a name="embedding.building_embedded_programs"></a><h2>
-<a name="id471329"></a>
+<a name="id471330"></a>
Building embedded programs
</h2>
<p>
@@ -82,7 +82,7 @@
<find-library>$(PYTHON_EMBEDDED_LIBRARY) ;
</pre>
<a name="embedding.getting_started"></a><h2>
-<a name="id471434"></a>
+<a name="id471435"></a>
Getting started
</h2>
<p>
@@ -139,7 +139,7 @@
automate the process.
</p>
<a name="using_the_interpreter.running_python_code"></a><h2>
-<a name="id471597"></a>
+<a name="id471598"></a>
Running Python code
</h2>
<p>
@@ -190,7 +190,7 @@
a phrase that is well-known in programming circles.
</p>
<a name="using_the_interpreter.manipulating_python_objects"></a><h2>
-<a name="id472185"></a>
+<a name="id472186"></a>
Manipulating Python objects
</h2>
<p>
@@ -217,7 +217,7 @@
<span class="keyword">int</span> <span class="identifier">five_squared</span> <span class="special">=</span> <span class="identifier">extract</span><span class="special"><</span><span class="keyword">int</span><span class="special">>(</span><span class="identifier">result</span><span class="special">);</span>
</pre>
<a name="using_the_interpreter.exception_handling"></a><h2>
-<a name="id472557"></a>
+<a name="id472558"></a>
Exception handling
</h2>
<p>
Modified: branches/CMake/release/libs/python/doc/tutorial/doc/html/python/exposing.html
==============================================================================
--- branches/CMake/release/libs/python/doc/tutorial/doc/html/python/exposing.html (original)
+++ branches/CMake/release/libs/python/doc/tutorial/doc/html/python/exposing.html 2008-06-30 10:36:33 EDT (Mon, 30 Jun 2008)
@@ -533,7 +533,7 @@
<div class="titlepage"><div><div><h3 class="title">
<a name="python.class_operators_special_functions"></a>Class Operators/Special Functions</h3></div></div></div>
<a name="class_operators_special_functions.python_operators"></a><h2>
-<a name="id461481"></a>
+<a name="id461482"></a>
Python Operators
</h2>
<p>
@@ -582,7 +582,7 @@
expressions".
</p>
<a name="class_operators_special_functions.special_methods"></a><h2>
-<a name="id462238"></a>
+<a name="id462239"></a>
Special Methods
</h2>
<p>
Modified: branches/CMake/release/libs/python/doc/tutorial/doc/html/python/functions.html
==============================================================================
--- branches/CMake/release/libs/python/doc/tutorial/doc/html/python/functions.html (original)
+++ branches/CMake/release/libs/python/doc/tutorial/doc/html/python/functions.html 2008-06-30 10:36:33 EDT (Mon, 30 Jun 2008)
@@ -212,7 +212,7 @@
<li><span class="bold"><b>BOOM!</b></span></li>
</ol></div>
<a name="call_policies.call_policies"></a><h2>
-<a name="id464235"></a>
+<a name="id464236"></a>
Call Policies
</h2>
<p>
@@ -445,7 +445,7 @@
<span class="identifier">def</span><span class="special">(</span><span class="string">"foo"</span><span class="special">,</span> <span class="identifier">foo</span><span class="special">,</span> <span class="identifier">foo_overloads</span><span class="special">());</span>
</pre>
<a name="default_arguments.boost_python_member_function_overloads"></a><h2>
-<a name="id466594"></a>
+<a name="id466595"></a>
BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS
</h2>
<p>
@@ -565,7 +565,7 @@
(0) arguments and a maximum of 3 arguments.
</p>
<a name="auto_overloading.manual_wrapping"></a><h2>
-<a name="id467739"></a>
+<a name="id467740"></a>
Manual Wrapping
</h2>
<p>
Modified: branches/CMake/release/libs/python/doc/tutorial/doc/html/python/hello.html
==============================================================================
--- branches/CMake/release/libs/python/doc/tutorial/doc/html/python/hello.html (original)
+++ branches/CMake/release/libs/python/doc/tutorial/doc/html/python/hello.html 2008-06-30 10:36:33 EDT (Mon, 30 Jun 2008)
@@ -187,7 +187,8 @@
</tr>
<tr><td colspan="2" align="left" valign="top"><p>
Starting from Boost 1.35, bjam erases the generated executables (e.g. pyd
- file). To keep bjam from doing that, pass --preserve-test-targets to bjam.
+ file) after the test has concluded to conserve disk space. To keep bjam from
+ doing that, pass --preserve-test-targets to bjam.
</p></td></tr>
</table></div>
<div class="blockquote"><blockquote class="blockquote">
Modified: branches/CMake/release/libs/python/doc/tutorial/doc/html/python/object.html
==============================================================================
--- branches/CMake/release/libs/python/doc/tutorial/doc/html/python/object.html (original)
+++ branches/CMake/release/libs/python/doc/tutorial/doc/html/python/object.html 2008-06-30 10:36:33 EDT (Mon, 30 Jun 2008)
@@ -196,7 +196,7 @@
</span><span class="identifier">d</span><span class="special">[</span><span class="char">'whatever'</span><span class="special">]</span> <span class="special">=</span> <span class="number">3</span><span class="special">;</span> <span class="comment">// modifies the copy
</span></pre>
<a name="derived_object_types.class__lt_t_gt__as_objects"></a><h2>
-<a name="id469744"></a>
+<a name="id469745"></a>
class_<T> as objects
</h2>
<p>
Modified: branches/CMake/release/libs/python/doc/tutorial/doc/tutorial.qbk
==============================================================================
--- branches/CMake/release/libs/python/doc/tutorial/doc/tutorial.qbk (original)
+++ branches/CMake/release/libs/python/doc/tutorial/doc/tutorial.qbk 2008-06-30 10:36:33 EDT (Mon, 30 Jun 2008)
@@ -186,6 +186,10 @@
Or something similar. If all is well, you should now have built the DLLs and
run the Python program.
+[note Starting from Boost 1.35, bjam erases the generated executables
+(e.g. pyd file) after the test has concluded to conserve disk space.
+To keep bjam from doing that, pass --preserve-test-targets to bjam.]
+
[:[*There you go... Have fun!]]
[endsect]
Modified: branches/CMake/release/libs/python/doc/v2/pickle.html
==============================================================================
--- branches/CMake/release/libs/python/doc/v2/pickle.html (original)
+++ branches/CMake/release/libs/python/doc/v2/pickle.html 2008-06-30 10:36:33 EDT (Mon, 30 Jun 2008)
@@ -1,112 +1,93 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN"
-"http://www.w3.org/TR/REC-html40/strict.dtd">
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<title>Boost.Python Pickle Support</title>
-
-<div>
-
-<img src="../../../../boost.png"
- alt="boost.png (6897 bytes)"
- align="center"
- width="277" height="86">
-
-<hr>
-<h1>Boost.Python Pickle Support</h1>
-
-Pickle is a Python module for object serialization, also known
-as persistence, marshalling, or flattening.
-
-<p>
-It is often necessary to save and restore the contents of an object to
-a file. One approach to this problem is to write a pair of functions
-that read and write data from a file in a special format. A powerful
-alternative approach is to use Python's pickle module. Exploiting
-Python's ability for introspection, the pickle module recursively
-converts nearly arbitrary Python objects into a stream of bytes that
-can be written to a file.
-
-<p>
-The Boost Python Library supports the pickle module
-through the interface as described in detail in the
-<a href="http://www.python.org/doc/current/lib/module-pickle.html"
->Python Library Reference for pickle.</a> This interface
-involves the special methods <tt>__getinitargs__</tt>,
-<tt>__getstate__</tt> and <tt>__setstate__</tt> as described
-in the following. Note that Boost.Python is also fully compatible
-with Python's cPickle module.
-
-<hr>
-<h2>The Boost.Python Pickle Interface</h2>
-
-At the user level, the Boost.Python pickle interface involves three special
-methods:
-
-<dl>
-<dt>
-<strong><tt>__getinitargs__</tt></strong>
-<dd>
- When an instance of a Boost.Python extension class is pickled, the
- pickler tests if the instance has a <tt>__getinitargs__</tt> method.
- This method must return a Python tuple (it is most convenient to use
- a boost::python::tuple). When the instance is restored by the
- unpickler, the contents of this tuple are used as the arguments for
- the class constructor.
-
- <p>
- If <tt>__getinitargs__</tt> is not defined, <tt>pickle.load</tt>
- will call the constructor (<tt>__init__</tt>) without arguments;
- i.e., the object must be default-constructible.
-
-<p>
-<dt>
-<strong><tt>__getstate__</tt></strong>
-
-<dd>
- When an instance of a Boost.Python extension class is pickled, the
- pickler tests if the instance has a <tt>__getstate__</tt> method.
- This method should return a Python object representing the state of
- the instance.
-
-<p>
-<dt>
-<strong><tt>__setstate__</tt></strong>
-
-<dd>
- When an instance of a Boost.Python extension class is restored by the
- unpickler (<tt>pickle.load</tt>), it is first constructed using the
- result of <tt>__getinitargs__</tt> as arguments (see above). Subsequently
- the unpickler tests if the new instance has a <tt>__setstate__</tt>
- method. If so, this method is called with the result of
- <tt>__getstate__</tt> (a Python object) as the argument.
-
-</dl>
-
-The three special methods described above may be <tt>.def()</tt>'ed
-individually by the user. However, Boost.Python provides an easy to use
-high-level interface via the
-<strong><tt>boost::python::pickle_suite</tt></strong> class that also
-enforces consistency: <tt>__getstate__</tt> and <tt>__setstate__</tt>
-must be defined as pairs. Use of this interface is demonstrated by the
-following examples.
-
-<hr>
-<h2>Examples</h2>
-
-There are three files in
-<tt>boost/libs/python/test</tt> that show how to
-provide pickle support.
-
-<hr>
-<h3>pickle1.cpp</h3>
-
- The C++ class in this example can be fully restored by passing the
- appropriate argument to the constructor. Therefore it is sufficient
- to define the pickle interface method <tt>__getinitargs__</tt>.
- This is done in the following way:
-
-<ul>
-<li>1. Definition of the C++ pickle function:
-<pre>
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+ <title>Boost.Python Pickle Support</title>
+</head>
+
+<body>
+ <div>
+ <img src="../../../../boost.png" alt="boost.png (6897 bytes)" align=
+ "center" width="277" height="86" />
+ <hr />
+
+ <h1>Boost.Python Pickle Support</h1>Pickle is a Python module for object
+ serialization, also known as persistence, marshalling, or flattening.
+
+ <p>It is often necessary to save and restore the contents of an object to
+ a file. One approach to this problem is to write a pair of functions that
+ read and write data from a file in a special format. A powerful
+ alternative approach is to use Python's pickle module. Exploiting
+ Python's ability for introspection, the pickle module recursively
+ converts nearly arbitrary Python objects into a stream of bytes that can
+ be written to a file.</p>
+
+ <p>The Boost Python Library supports the pickle module through the
+ interface as described in detail in the <a href=
+ "http://www.python.org/doc/current/lib/module-pickle.html">Python Library
+ Reference for pickle.</a> This interface involves the special methods
+ <tt>__getinitargs__</tt>, <tt>__getstate__</tt> and <tt>__setstate__</tt>
+ as described in the following. Note that Boost.Python is also fully
+ compatible with Python's cPickle module.</p>
+ <hr />
+
+ <h2>The Boost.Python Pickle Interface</h2>At the user level, the
+ Boost.Python pickle interface involves three special methods:
+
+ <dl>
+ <dt><strong><tt>__getinitargs__</tt></strong></dt>
+
+ <dd>
+ When an instance of a Boost.Python extension class is pickled, the
+ pickler tests if the instance has a <tt>__getinitargs__</tt> method.
+ This method must return a Python tuple (it is most convenient to use
+ a boost::python::tuple). When the instance is restored by the
+ unpickler, the contents of this tuple are used as the arguments for
+ the class constructor.
+
+ <p>If <tt>__getinitargs__</tt> is not defined, <tt>pickle.load</tt>
+ will call the constructor (<tt>__init__</tt>) without arguments;
+ i.e., the object must be default-constructible.</p>
+ </dd>
+
+ <dt><strong><tt>__getstate__</tt></strong></dt>
+
+ <dd>When an instance of a Boost.Python extension class is pickled, the
+ pickler tests if the instance has a <tt>__getstate__</tt> method. This
+ method should return a Python object representing the state of the
+ instance.</dd>
+
+ <dt><strong><tt>__setstate__</tt></strong></dt>
+
+ <dd>When an instance of a Boost.Python extension class is restored by
+ the unpickler (<tt>pickle.load</tt>), it is first constructed using the
+ result of <tt>__getinitargs__</tt> as arguments (see above).
+ Subsequently the unpickler tests if the new instance has a
+ <tt>__setstate__</tt> method. If so, this method is called with the
+ result of <tt>__getstate__</tt> (a Python object) as the argument.</dd>
+ </dl>The three special methods described above may be <tt>.def()</tt>'ed
+ individually by the user. However, Boost.Python provides an easy to use
+ high-level interface via the
+ <strong><tt>boost::python::pickle_suite</tt></strong> class that also
+ enforces consistency: <tt>__getstate__</tt> and <tt>__setstate__</tt>
+ must be defined as pairs. Use of this interface is demonstrated by the
+ following examples.
+ <hr />
+
+ <h2>Examples</h2>There are three files in <tt>boost/libs/python/test</tt>
+ that show how to provide pickle support.
+ <hr />
+
+ <h3>pickle1.cpp</h3>The C++
+ class in this example can be fully restored by passing the appropriate
+ argument to the constructor. Therefore it is sufficient to define the
+ pickle interface method <tt>__getinitargs__</tt>. This is done in the
+ following way:
+
+ <ul>
+ <li>1. Definition of the C++ pickle function:
+ <pre>
struct world_pickle_suite : boost::python::pickle_suite
{
static
@@ -117,26 +98,28 @@
}
};
</pre>
-<li>2. Establishing the Python binding:
-<pre>
+ </li>
+
+ <li>2. Establishing the Python binding:
+ <pre>
class_<world>("world", args<const std::string&>())
// ...
.def_pickle(world_pickle_suite())
// ...
</pre>
-</ul>
-
-<hr>
-<h3>pickle2.cpp</h3>
-
- The C++ class in this example contains member data that cannot be
- restored by any of the constructors. Therefore it is necessary to
- provide the <tt>__getstate__</tt>/<tt>__setstate__</tt> pair of
- pickle interface methods:
-
-<ul>
-<li>1. Definition of the C++ pickle functions:
-<pre>
+ </li>
+ </ul>
+ <hr />
+
+ <h3>pickle2.cpp</h3>The C++
+ class in this example contains member data that cannot be restored by any
+ of the constructors. Therefore it is necessary to provide the
+ <tt>__getstate__</tt>/<tt>__setstate__</tt> pair of pickle interface
+ methods:
+
+ <ul>
+ <li>1. Definition of the C++ pickle functions:
+ <pre>
struct world_pickle_suite : boost::python::pickle_suite
{
static
@@ -161,92 +144,76 @@
}
};
</pre>
-<li>2. Establishing the Python bindings for the entire suite:
-<pre>
+ </li>
+
+ <li>2. Establishing the Python bindings for the entire suite:
+ <pre>
class_<world>("world", args<const std::string&>())
// ...
.def_pickle(world_pickle_suite())
// ...
</pre>
-</ul>
-
- <p>
- For simplicity, the <tt>__dict__</tt> is not included in the result
- of <tt>__getstate__</tt>. This is not generally recommended, but a
- valid approach if it is anticipated that the object's
- <tt>__dict__</tt> will always be empty. Note that the safety guard
- described below will catch the cases where this assumption is violated.
-
-<hr>
-<h3>pickle3.cpp</h3>
-
- This example is similar to <a
- href="../../test/pickle2.cpp"><tt>pickle2.cpp</tt></a>. However, the
- object's <tt>__dict__</tt> is included in the result of
- <tt>__getstate__</tt>. This requires a little more code but is
- unavoidable if the object's <tt>__dict__</tt> is not always empty.
-
-<hr>
-<h2>Pitfall and Safety Guard</h2>
-
-The pickle protocol described above has an important pitfall that the
-end user of a Boost.Python extension module might not be aware of:
-<p>
-<strong>
-<tt>__getstate__</tt> is defined and the instance's <tt>__dict__</tt>
-is not empty.
-</strong>
-<p>
-
- The author of a Boost.Python extension class might provide a
- <tt>__getstate__</tt> method without considering the possibilities
- that:
-
- <p>
- <ul>
- <li>
- his class is used in Python as a base class. Most likely the
- <tt>__dict__</tt> of instances of the derived class needs to be
- pickled in order to restore the instances correctly.
-
- <p>
- <li>
- the user adds items to the instance's <tt>__dict__</tt> directly.
- Again, the <tt>__dict__</tt> of the instance then needs to be
- pickled.
-
- </ul>
- <p>
-
- To alert the user to this highly unobvious problem, a safety guard is
- provided. If <tt>__getstate__</tt> is defined and the instance's
- <tt>__dict__</tt> is not empty, Boost.Python tests if the class has
- an attribute <tt>__getstate_manages_dict__</tt>. An exception is
- raised if this attribute is not defined:
+ </li>
+ </ul>
-<pre>
+ <p>For simplicity, the <tt>__dict__</tt> is not included in the result of
+ <tt>__getstate__</tt>. This is not generally recommended, but a valid
+ approach if it is anticipated that the object's <tt>__dict__</tt> will
+ always be empty. Note that the safety guard described below will catch
+ the cases where this assumption is violated.</p>
+ <hr />
+
+ <h3>pickle3.cpp</h3>This
+ example is similar to <a href=
+ "../../test/pickle2.cpp"><tt>pickle2.cpp</tt></a>. However, the object's
+ <tt>__dict__</tt> is included in the result of <tt>__getstate__</tt>.
+ This requires a little more code but is unavoidable if the object's
+ <tt>__dict__</tt> is not always empty.
+ <hr />
+
+ <h2>Pitfall and Safety Guard</h2>The pickle protocol described above has
+ an important pitfall that the end user of a Boost.Python extension module
+ might not be aware of:
+
+ <p><strong><tt>__getstate__</tt> is defined and the instance's
+ <tt>__dict__</tt> is not empty.</strong></p>
+
+ <p>The author of a Boost.Python extension class might provide a
+ <tt>__getstate__</tt> method without considering the possibilities
+ that:</p>
+
+ <ul>
+ <li>his class is used in Python as a base class. Most likely the
+ <tt>__dict__</tt> of instances of the derived class needs to be pickled
+ in order to restore the instances correctly.</li>
+
+ <li>the user adds items to the instance's <tt>__dict__</tt> directly.
+ Again, the <tt>__dict__</tt> of the instance then needs to be
+ pickled.</li>
+ </ul>
+
+ <p>To alert the user to this highly unobvious problem, a safety guard is
+ provided. If <tt>__getstate__</tt> is defined and the instance's
+ <tt>__dict__</tt> is not empty, Boost.Python tests if the class has an
+ attribute <tt>__getstate_manages_dict__</tt>. An exception is raised if
+ this attribute is not defined:</p>
+ <pre>
RuntimeError: Incomplete pickle support (__getstate_manages_dict__ not set)
-</pre>
-
- To resolve this problem, it should first be established that the
- <tt>__getstate__</tt> and <tt>__setstate__</tt> methods manage the
- instances's <tt>__dict__</tt> correctly. Note that this can be done
- either at the C++ or the Python level. Finally, the safety guard
- should intentionally be overridden. E.g. in C++ (from
- pickle3.cpp):
-
-<pre>
+</pre>To resolve this problem, it should first be established that the <tt>
+ __getstate__</tt> and <tt>__setstate__</tt> methods manage the
+ instances's <tt>__dict__</tt> correctly. Note that this can be done
+ either at the C++ or the Python level. Finally, the safety guard should
+ intentionally be overridden. E.g. in C++ (from <a href=
+ "../../test/pickle3.cpp"><tt>pickle3.cpp</tt></a>):
+ <pre>
struct world_pickle_suite : boost::python::pickle_suite
{
// ...
static bool getstate_manages_dict() { return true; }
};
-</pre>
-
- Alternatively in Python:
-
-<pre>
+</pre>Alternatively in Python:
+ <pre>
import your_bpl_module
class your_class(your_bpl_module.your_class):
__getstate_manages_dict__ = 1
@@ -255,54 +222,41 @@
def __setstate__(self, state):
# your code here
</pre>
+ <hr />
-<hr>
-<h2>Practical Advice</h2>
+ <h2>Practical Advice</h2>
-<ul>
-<li>
- In Boost.Python extension modules with many extension classes,
- providing complete pickle support for all classes would be a
- significant overhead. In general complete pickle support should
- only be implemented for extension classes that will eventually
- be pickled.
-
-<p>
-<li>
- Avoid using <tt>__getstate__</tt> if the instance can also be
- reconstructed by way of <tt>__getinitargs__</tt>. This automatically
- avoids the pitfall described above.
-
-<p>
-<li>
- If <tt>__getstate__</tt> is required, include the instance's
- <tt>__dict__</tt> in the Python object that is returned.
-
-</ul>
-
-<hr>
-<h2>Light-weight alternative: pickle support implemented in Python</h2>
-
-<h3>pickle4.cpp</h3>
-
-The <tt>pickle4.cpp</tt> example demonstrates an alternative technique
-for implementing pickle support. First we direct Boost.Python via
-the <tt>class_::enable_pickling()</tt> member function to define only
-the basic attributes required for pickling:
-
-<pre>
+ <ul>
+ <li>In Boost.Python extension modules with many extension classes,
+ providing complete pickle support for all classes would be a
+ significant overhead. In general complete pickle support should only be
+ implemented for extension classes that will eventually be pickled.</li>
+
+ <li>Avoid using <tt>__getstate__</tt> if the instance can also be
+ reconstructed by way of <tt>__getinitargs__</tt>. This automatically
+ avoids the pitfall described above.</li>
+
+ <li>If <tt>__getstate__</tt> is required, include the instance's
+ <tt>__dict__</tt> in the Python object that is returned.</li>
+ </ul>
+ <hr />
+
+ <h2>Light-weight alternative: pickle support implemented in Python</h2>
+
+ <h3>pickle4.cpp</h3>The
+ <tt>pickle4.cpp</tt> example demonstrates an alternative technique for
+ implementing pickle support. First we direct Boost.Python via the
+ <tt>class_::enable_pickling()</tt> member function to define only the
+ basic attributes required for pickling:
+ <pre>
class_<world>("world", args<const std::string&>())
// ...
.enable_pickling()
// ...
-</pre>
-
-This enables the standard Python pickle interface as described
-in the Python documentation. By "injecting" a
-<tt>__getinitargs__</tt> method into the definition of the wrapped
-class we make all instances pickleable:
-
-<pre>
+</pre>This enables the standard Python pickle interface as described in the
+Python documentation. By "injecting" a <tt>__getinitargs__</tt> method into
+the definition of the wrapped class we make all instances pickleable:
+ <pre>
# import the wrapped world class
from pickle4_ext import world
@@ -312,18 +266,15 @@
# now inject __getinitargs__ (Python is a dynamic language!)
world.__getinitargs__ = world_getinitargs
-</pre>
-
-See also the
-<a href="../tutorial/doc/html/python/techniques.html#python.extending_wrapped_objects_in_python"
->tutorial section</a> on injecting additional methods from Python.
-
-<hr>
-
-© Copyright Ralf W. Grosse-Kunstleve 2001-2004. 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)
-
-<p>
-Updated: Feb 2004.
-</div>
+</pre>See also the <a href=
+"../tutorial/doc/html/python/techniques.html#python.extending_wrapped_objects_in_python">
+ tutorial section</a> on injecting additional methods from Python.
+ <hr />
+ © Copyright Ralf W. Grosse-Kunstleve 2001-2004. 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)
+
+ <p>Updated: Feb 2004.</p>
+ </div>
+</body>
+</html>