| 1 | <!-- Copyright David Abrahams 2006. Distributed under the Boost --> |
|---|
| 2 | <!-- Software License, Version 1.0. (See accompanying --> |
|---|
| 3 | <!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> |
|---|
| 4 | <html> |
|---|
| 5 | <head> |
|---|
| 6 | <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
|---|
| 7 | <link rel="stylesheet" type="text/css" href="../boost.css"> |
|---|
| 8 | <title>Boost.Python - June 2002 Progress Report</title> |
|---|
| 9 | </head> |
|---|
| 10 | <body link="#0000ff" vlink="#800080"> |
|---|
| 11 | <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= |
|---|
| 12 | "header"> |
|---|
| 13 | <tr> |
|---|
| 14 | <td valign="top" width="300"> |
|---|
| 15 | <h3><a href="../../../../index.htm"><img height="86" width="277" alt= |
|---|
| 16 | "C++ Boost" src="../../../../boost.png" border="0"></a></h3> |
|---|
| 17 | </td> |
|---|
| 18 | <td valign="top"> |
|---|
| 19 | <h1 align="center"><a href="../index.html">Boost.Python</a></h1> |
|---|
| 20 | <h2 align="center">June 2002 Progress Report</h2> |
|---|
| 21 | </td> |
|---|
| 22 | </tr> |
|---|
| 23 | </table> |
|---|
| 24 | <hr> |
|---|
| 25 | <h2>Contents</h2> |
|---|
| 26 | <dl class="index"> |
|---|
| 27 | <dt><a href="#intro">Introduction</a></dt> |
|---|
| 28 | <dt><a href="#handle"><code>handle<T></code></a></dt> |
|---|
| 29 | <dt><a href="#object"><code>object</code></a></dt> |
|---|
| 30 | <dl class="index"> |
|---|
| 31 | <dt><a href="#operators"><code>object</code> operators</a></dt> |
|---|
| 32 | <dt><a href="#conversions"><code>object</code> conversions</a></dt> |
|---|
| 33 | </dl> |
|---|
| 34 | <dt><a href="#list"><code>list</code></a></dt> |
|---|
| 35 | <dt><a href="#numerics"><code>Numerics</code></a></dt> |
|---|
| 36 | <dt><a href="#community">Community</a></dt> |
|---|
| 37 | <dt><a href="#next">What's Next</a></dt> |
|---|
| 38 | </dl> |
|---|
| 39 | |
|---|
| 40 | <h2><a name="intro">Introduction</a></h2> |
|---|
| 41 | |
|---|
| 42 | July was mostly focused on allowing expressive manipulation of |
|---|
| 43 | individual Python objects, or what Ralf Grosse-Kunstleve calls |
|---|
| 44 | "Writing Python in C++". The work began with this <a |
|---|
| 45 | href="http://mail.python.org/pipermail/c++-sig/2002-June/001311.html">posting</a>, |
|---|
| 46 | which outlines the issues and intention. |
|---|
| 47 | |
|---|
| 48 | <h2><a name="handle"><code>handle<T></code></a></h2> |
|---|
| 49 | |
|---|
| 50 | The most basic element needed was a replacement for the |
|---|
| 51 | <code>reference<></code> class template and the |
|---|
| 52 | <code>ref</code> typedef from Boost.Python v1, a simple smart |
|---|
| 53 | pointer to a Python object. The old v1 typedef |
|---|
| 54 | "<code>ref</code>" (for |
|---|
| 55 | <code>reference<PyObject></code>) had to be retired because I |
|---|
| 56 | thought it would be too confusing given the importance of <code><a |
|---|
| 57 | href="../../../bind/ref.html">boost::ref</a>()</code> to this |
|---|
| 58 | library. I began a <a |
|---|
| 59 | href="http://mail.python.org/pipermail/c++-sig/2002-June/001311.html">discussion</a>of |
|---|
| 60 | possible names, and it was eventually <a |
|---|
| 61 | href="http://mail.python.org/pipermail/c++-sig/2002-June/001337.html">decided</a> |
|---|
| 62 | to rename <code>reference</code> to <code>handle</code> and supply a |
|---|
| 63 | default argument so that <code>ref</code> could be spelled |
|---|
| 64 | <code>handle<></code> without an additional typedef. There |
|---|
| 65 | were also some interface changes to make it safer and more-efficient |
|---|
| 66 | to interface with the raw |
|---|
| 67 | <code>PyObject*</code>s forced on us by Python's 'C' API. A |
|---|
| 68 | discussion of those protocols can be found <a |
|---|
| 69 | href="http://mail.python.org/pipermail/c++-sig/2002-June/001401.html">here</a>. |
|---|
| 70 | |
|---|
| 71 | <h2><a name="handle"><code>object</code></a></h2> |
|---|
| 72 | |
|---|
| 73 | It is intended that users will seldom need or want to work with |
|---|
| 74 | <code>handle<></code>; its major distinguishing features are |
|---|
| 75 | that it gives direct access to the underlying object representation |
|---|
| 76 | through <code>operator*</code> and <code>operator-></code>, and |
|---|
| 77 | that can be <code>NULL</code>, both sources of danger. Instead the |
|---|
| 78 | library provides a class called <code>object</code>, which |
|---|
| 79 | encapsulates a valid Python object and provides a similar interface to |
|---|
| 80 | Python's. |
|---|
| 81 | |
|---|
| 82 | <h3><a name="operators"><code>object</code> operators</a></h3> |
|---|
| 83 | |
|---|
| 84 | The first challenge was to provide support for object manipulations |
|---|
| 85 | using a Python-like syntax, mostly in the form of operator overloads: |
|---|
| 86 | |
|---|
| 87 | <table border="1"> |
|---|
| 88 | <tr><th>Python <th>C++ |
|---|
| 89 | |
|---|
| 90 | <tr> |
|---|
| 91 | <td><code>y = x.foo</code> <td><code>y = x.attr("foo"); |
|---|
| 92 | <tr> |
|---|
| 93 | <td><code>x.foo = 1</code> <td><code>x.attr("foo") = 1; |
|---|
| 94 | |
|---|
| 95 | <tr> |
|---|
| 96 | <td><code>y = x[z]</code> <td><code>y = x[z]; |
|---|
| 97 | <tr> |
|---|
| 98 | <td><code>x[z] = 1</code> <td><code>x[z] = 1; |
|---|
| 99 | |
|---|
| 100 | <tr> |
|---|
| 101 | <td><code>y = x[3:-1]</code> <td><code>y = x.slice(3,-1); |
|---|
| 102 | |
|---|
| 103 | <tr> |
|---|
| 104 | <td><code>y = x[3:]</code> <td><code>y = x.slice(3,_); |
|---|
| 105 | |
|---|
| 106 | <tr> |
|---|
| 107 | <td><code>y = x[:-2]</code> <td><code>y = x.slice(_,-2); |
|---|
| 108 | |
|---|
| 109 | <tr> |
|---|
| 110 | <td><code>z = x(1, y)</code> <td><code>z = x(1, y); |
|---|
| 111 | <tr> |
|---|
| 112 | <td><code>z = x.f(1, y)</code> <td><code>z = x.attr("f")(1, y); |
|---|
| 113 | |
|---|
| 114 | <tr> |
|---|
| 115 | <td><code>not x</code> <td><code>!x |
|---|
| 116 | |
|---|
| 117 | <tr> |
|---|
| 118 | <td><code>x and y</code> <td><code>x and y |
|---|
| 119 | </table> |
|---|
| 120 | |
|---|
| 121 | I'm still a unsatisfied with the interface for attribute access. There |
|---|
| 122 | original proposal used a syntax like this one: |
|---|
| 123 | <pre> |
|---|
| 124 | y = x._("foo"); |
|---|
| 125 | x._("foo") = 1; |
|---|
| 126 | </pre> |
|---|
| 127 | |
|---|
| 128 | which was only marginally better than what we've got. Niki Spahiev |
|---|
| 129 | then <a |
|---|
| 130 | href="http://mail.python.org/pipermail/c++-sig/2002-June/001447.html">pointed |
|---|
| 131 | out</a> a potential conflict with the macro which GNU Gettext <a |
|---|
| 132 | href="http://www.gnu.org/manual/gettext/html_mono/gettext.html#SEC6">suggests</a> |
|---|
| 133 | people define. This unfortunate state of affairs forced us into using |
|---|
| 134 | <code>attr</code> instead. I'd still like to find a better interface, |
|---|
| 135 | but the lack of overloadable C++ operators which aren't already used |
|---|
| 136 | in Python is an obstacle. The comma operator is still a possibility, |
|---|
| 137 | but it has the wrong precedence: |
|---|
| 138 | <pre> |
|---|
| 139 | y = x,"foo" // error |
|---|
| 140 | x,"foo" = 1; // error |
|---|
| 141 | |
|---|
| 142 | y = (x,"foo"); // ok |
|---|
| 143 | (x,"foo") = 1; // ok |
|---|
| 144 | </pre> |
|---|
| 145 | |
|---|
| 146 | Well, I guess we could consider adding that to the interface without |
|---|
| 147 | removing <code>attr()</code>, to see how it plays out... |
|---|
| 148 | |
|---|
| 149 | <h3><a name="operators"><code>object</code> conversions</a></h3> |
|---|
| 150 | |
|---|
| 151 | The <code>object</code> class also provided an opportunity to replace |
|---|
| 152 | Boost.Python v1's <code>to_python()</code> as a user-level |
|---|
| 153 | interface. Instead, <code>object</code> has a templated constructor |
|---|
| 154 | which can be used to convert any C++ object to Python using the same |
|---|
| 155 | underlying mechanisms used for the arguments to <code><a |
|---|
| 156 | href="call.html">call</a><></code>. |
|---|
| 157 | |
|---|
| 158 | <p>Incidentally, the implementation of operator and conversion support |
|---|
| 159 | for object uncovered an inordinate number of compiler bugs in our |
|---|
| 160 | targeted platforms. It was a lot more "interesting" than it |
|---|
| 161 | should have been. |
|---|
| 162 | |
|---|
| 163 | <h2><a name="list"><code>list</code></a></h2> |
|---|
| 164 | |
|---|
| 165 | With <code>object</code> implemented, it was time to begin replacing |
|---|
| 166 | the ad-hoc implementations of <code>list</code>, <code>string</code>, |
|---|
| 167 | and <code>dictionary</code> supplied by Boost.Python v1 with something |
|---|
| 168 | more robust. I started with <code>list</code> as an example. Because |
|---|
| 169 | <code>object</code> already provides all of the requisite operators, |
|---|
| 170 | publicly deriving <code>list</code> from object seemed like a good |
|---|
| 171 | choice. The remaining issues were what do do about the one-argument |
|---|
| 172 | list constructor (which in Python attempts to convert its argument to |
|---|
| 173 | a list), and how to deal converting with <code>list</code> arguments |
|---|
| 174 | to wrapped functions. Some of the issues are laid out in <a |
|---|
| 175 | href="http://mail.python.org/pipermail/c++-sig/2002-June/001551.html">this |
|---|
| 176 | thread</a>. Ultimately, it was decided that <code>list(x)</code> |
|---|
| 177 | should do the same thing in C++ as in Python (conversion), while |
|---|
| 178 | <code>list</code> arguments should only match Python |
|---|
| 179 | <code>list</code>s (and <code>list</code> subclasses). The |
|---|
| 180 | implementation worked well, and provided a <a |
|---|
| 181 | href="http://mail.python.org/pipermail/c++-sig/2002-June/001586.html">roadmap</a> |
|---|
| 182 | for the protocol to be used for implementation of the other built-in |
|---|
| 183 | types. |
|---|
| 184 | |
|---|
| 185 | <h2><a name="numerics">Numerics</a></h2> |
|---|
| 186 | |
|---|
| 187 | Support for C++ <code>long long</code> and <code>unsigned long |
|---|
| 188 | long</code> |
|---|
| 189 | (and <code>__int64</code> on MSVC) to/from python conversions was |
|---|
| 190 | added this month. We also improved handling of numeric overflows when |
|---|
| 191 | converting, e.g., a Python int to a type with a more limited range of |
|---|
| 192 | representation. |
|---|
| 193 | |
|---|
| 194 | <h2><a name="community">Community</a></h2> |
|---|
| 195 | |
|---|
| 196 | <ul> |
|---|
| 197 | <li>Ralf W. Grosse-Kunstleve and Nick Sauter have implemented |
|---|
| 198 | <a href="http://cci.lbl.gov/boost/">multiplatform nightly |
|---|
| 199 | build-and-test</a> runs for Boost.Python V2 at LBL. |
|---|
| 200 | |
|---|
| 201 | <li>Dave Hawkes has made significant progress on generating the |
|---|
| 202 | Python <a |
|---|
| 203 | href="http://mail.python.org/pipermail/c++-sig/2002-June/001503.html">built-in |
|---|
| 204 | function and API wrappers</a> |
|---|
| 205 | |
|---|
| 206 | <li>Achim Domma has agreed to take up the job of implementing the |
|---|
| 207 | <code>str</code>, <code>dict</code>, and <code>tuple</code> classes. |
|---|
| 208 | </ul> |
|---|
| 209 | |
|---|
| 210 | Deep thanks to all the Boost.Python contributors! This project |
|---|
| 211 | wouldn't be possible without your participation. |
|---|
| 212 | |
|---|
| 213 | <h2><a name="next">What's Next</a></h2> |
|---|
| 214 | |
|---|
| 215 | As I write this we are already well into the month of July, so I |
|---|
| 216 | suggest you consult the <a |
|---|
| 217 | href="http://mail.python.org/pipermail/c++-sig/2002-July/">Mailing |
|---|
| 218 | List Archive</a> if you want to know what's been happening. Otherwise |
|---|
| 219 | you'll just have to wait till next month (hopefully the beginning). |
|---|
| 220 | |
|---|
| 221 | <p>Revised |
|---|
| 222 | <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> |
|---|
| 223 | 13 November, 2002 |
|---|
| 224 | <!--webbot bot="Timestamp" endspan i-checksum="39359" --> |
|---|
| 225 | </p> |
|---|
| 226 | <p><i>© Copyright <a href="../../../../people/dave_abrahams.htm">Dave Abrahams</a> |
|---|
| 227 | 2002. </i></p> |
|---|
| 228 | </body> |
|---|
| 229 | </html> |
|---|
