From 146958ad785cf07cc7e9c8b32bbb6d735d2e3eec Mon Sep 17 00:00:00 2001
From: Marcelo Matus <mmatus@acms.arizona.edu>
Date: Fri, 27 Jan 2006 18:47:15 +0000
Subject: [PATCH] add and extend missing/deleted docs for the
 pythonappend/pythonpreppend features and the new directive forms
 %pythonappend/%pythonpreppend

git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@8573 626c5289-ae23-0410-ae9c-e8d60b6d4f22
---
 Doc/Manual/Python.html   | 95 ++++++++++++++++++++++++++++++++++++++++
 Lib/python/pyuserdir.swg | 17 +++++++
 2 files changed, 112 insertions(+)

diff --git a/Doc/Manual/Python.html b/Doc/Manual/Python.html
index b73ab1ea3..4c1aa318f 100644
--- a/Doc/Manual/Python.html
+++ b/Doc/Manual/Python.html
@@ -2986,6 +2986,101 @@ what can be done without having to rely on any of the more advanced
 customization features.
 </p>
 
+<p>Sometimes you may want to replace or modify the wrapper function
+that SWIG creates in the proxy <tt>.py</tt> file.  The Python module
+in SWIG provides some features that enable you do do this.  First, to
+entirely replace a proxy function you can use
+<tt>%feature("shadow")</tt>.  For example:</p>
+
+<div class="code">
+<pre>
+%module example
+
+// Rewrite bar() python code
+
+%feature("shadow") Foo::bar(int) %{
+def bar(*args):
+    #do something before
+    $action
+    #do something after
+%}
+    
+class Foo {
+public:
+    int bar(int x);
+}
+</pre>
+</div>
+
+<p> where <tt>$action</tt> will be replaced by the call to
+the C/C++ proper method. 
+</p>
+
+<p>
+Often the proxy function created by SWIG is fine, but you simply want
+to add code to it without touching the rest of the generated function
+body.  For these cases SWIG provides the <tt>pythonprepend</tt> and
+<tt>pythonappend</tt> features which do exactly as their names suggest.  The
+<tt>pythonprepend</tt> feature will insert its value at the begining of the
+proxy function, and <tt>pythonappend</tt> will insert code at the end of the
+proxy, just before the return statement.
+</p>
+
+
+<div class="code">
+<pre>
+%module example
+
+// Add python code to bar() 
+
+%feature("pythonpreppend") Foo::bar(int) %{
+   #do something before C++ call
+%}
+
+%feature("pythonappend") Foo::bar(int) %{
+   #do something after C++ call
+%}
+
+    
+class Foo {
+public:
+    int bar(int x);
+}
+</pre>
+</div>
+
+<p>
+Notes: Usually the <tt>pythonappend</tt> and <tt>pythonpreppend</tt>
+features are safer to use than the <tt>shadow</tt> feature. Also, from
+SWIG version 1.3.28 you can use the directive forms
+<tt>%pythonappend</tt>  and <tt>%pythonpreppend</tt> as follows:</p>
+
+
+<div class="code">
+<pre>
+%module example
+
+// Add python code to bar() 
+
+%pythonpreppend Foo::bar(int) %{
+   #do something before C++ call
+%}
+
+%pythonappend Foo::bar(int) %{
+   #do something after C++ call
+%}
+
+    
+class Foo {
+public:
+    int bar(int x);
+}
+</pre>
+</div>
+
+
+
+
 <H3><a name="Python_nn43"></a>29.6.3 Class extension with %extend</H3>
 
 
diff --git a/Lib/python/pyuserdir.swg b/Lib/python/pyuserdir.swg
index 0e983fb7b..53962acd2 100644
--- a/Lib/python/pyuserdir.swg
+++ b/Lib/python/pyuserdir.swg
@@ -169,3 +169,20 @@ These methods "may be called" if needed.
 #define %nokwargs    %feature("kwargs", "0")
 #define %clearkwargs %feature("kwargs", "")
 
+/* ------------------------------------------------------------------------- */
+/*
+  Add python code to the proxy/shadow code 
+  
+   %pythonpreppend  - Add code before the C++ function is called
+   %pythonappend    - Add code after the C++ function is called
+*/
+
+#define %pythonpreppend       %feature("pythonpreppend") 
+#define %clearpythonpreppend  %feature("pythonpreppend","")
+
+#define %pythonappend         %feature("pythonappend") 
+#define %clearpythonappend    %feature("pythonappend","")
+
+
+
+