Added proper exception handling to dot example

3 files changed, 33 insertions, 4 deletions

diff --git a/numpy/doc/swig/numpy_swig.html b/numpy/doc/swig/numpy_swig.html
index e19f5c3ac..1b5cc4568 100644
--- a/numpy/doc/swig/numpy_swig.html
+++ b/numpy/doc/swig/numpy_swig.html
@@ -925,6 +925,10 @@ arguments).  The recommended solution is the following:</p>
 %apply (int DIM1, double* IN_ARRAY1) {(int len1, double* vec1),
                                       (int len2, double* vec2)}
 %rename (dot) my_dot;
+%exception my_dot {
+    $action
+    if (PyErr_Occurred()) SWIG_fail;
+}
 %inline %{
 double my_dot(int len1, double* vec1, int len2, double* vec2) {
     if (len1 != len2) {
@@ -944,6 +948,16 @@ to <tt class="docutils literal"><span class="pre">%include</span></tt> this head
 <tt class="docutils literal"><span class="pre">%include</span></tt> directives.  Or, if the function in question is a class
 method, you will want to use <tt class="docutils literal"><span class="pre">%extend</span></tt> rather than <tt class="docutils literal"><span class="pre">%inline</span></tt> in
 addition to <tt class="docutils literal"><span class="pre">%ignore</span></tt>.</p>
+<p><strong>A note on error handling:</strong> Note that <tt class="docutils literal"><span class="pre">my_dot</span></tt> returns a
+<tt class="docutils literal"><span class="pre">double</span></tt> but that it can also raise a <a class="reference" href="http://www.python.org">python</a> error.  The
+resulting wrapper function will return a <a class="reference" href="http://www.python.org">python</a> float
+representation of 0.0 when the vector lengths do not match.  Since
+this is not <tt class="docutils literal"><span class="pre">NULL</span></tt>, the <a class="reference" href="http://www.python.org">python</a> interpreter will not know to check
+for an error.  For this reason, we add the <tt class="docutils literal"><span class="pre">%exception</span></tt> directive
+above for <tt class="docutils literal"><span class="pre">my_dot</span></tt> to get the behavior we want (note that
+<tt class="docutils literal"><span class="pre">$action</span></tt> is a macro that gets expanded to a valid call to
+<tt class="docutils literal"><span class="pre">my_dot</span></tt>).  In general, you will probably want to write a <a class="reference" href="http://www.swig.org">SWIG</a>
+macro to perform this task.</p>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id15" id="other-situations" name="other-situations">Other Situations</a></h2>
@@ -1049,7 +1063,7 @@ possible.</p>
 </div>
 <div class="footer">
 <hr class="footer" />
-Generated on: 2007-08-15 21:36 UTC.
+Generated on: 2007-09-13 17:04 UTC.
 Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
 
 </div>
diff --git a/numpy/doc/swig/numpy_swig.pdf b/numpy/doc/swig/numpy_swig.pdf
index a2801f095..f1f1b4584 100644
--- a/numpy/doc/swig/numpy_swig.pdf
+++ b/numpy/doc/swig/numpy_swig.pdf
diff --git a/numpy/doc/swig/numpy_swig.txt b/numpy/doc/swig/numpy_swig.txt
index cc57b6fc3..23d3ecbdb 100644
--- a/numpy/doc/swig/numpy_swig.txt
+++ b/numpy/doc/swig/numpy_swig.txt
@@ -1,6 +1,6 @@
-========================================
-numpy.i: a SWIG Interface File for NumPy
-========================================
+==========================================
+ numpy.i: a SWIG Interface File for NumPy
+==========================================
 
 :Author:      Bill Spotz
 :Institution: Sandia National Laboratories
@@ -652,6 +652,10 @@ arguments).  The recommended solution is the following::
     %apply (int DIM1, double* IN_ARRAY1) {(int len1, double* vec1),
                                           (int len2, double* vec2)}
     %rename (dot) my_dot;
+    %exception my_dot {
+        $action
+	if (PyErr_Occurred()) SWIG_fail;
+    }
     %inline %{
     double my_dot(int len1, double* vec1, int len2, double* vec2) {
         if (len1 != len2) {
@@ -672,6 +676,17 @@ dot;`` directive, placed after the ``%rename`` and before the
 method, you will want to use ``%extend`` rather than ``%inline`` in
 addition to ``%ignore``.
 
+**A note on error handling:** Note that ``my_dot`` returns a
+``double`` but that it can also raise a `python`_ error.  The
+resulting wrapper function will return a `python`_ float
+representation of 0.0 when the vector lengths do not match.  Since
+this is not ``NULL``, the `python`_ interpreter will not know to check
+for an error.  For this reason, we add the ``%exception`` directive
+above for ``my_dot`` to get the behavior we want (note that
+``$action`` is a macro that gets expanded to a valid call to
+``my_dot``).  In general, you will probably want to write a `SWIG`_
+macro to perform this task.
+
 Other Situations
 ----------------