[PyQt] sip: extend exception support

[Matt Newell]

> 
> In current hg...
> 
> %VirtualErrorCode is a new sub-directive of the %Module directive.
> 
> all_throw_cpp_exception replaced by all_use_VirtualErrorCode.
> 
> /ThrowsCppException/ replaced by /UsesVirtualErrorCode/.
> 
> /NoThrowsCppException/ replaced by /NoUsesVirtualErrorCode/.
> 
> Removed SIPPyException.
> 
> Phil
> _______________________________________________
> PyQt mailing list    PyQt at riverbankcomputing.com
> http://www.riverbankcomputing.com/mailman/listinfo/pyqt

I'm coming in a bit late to this discussion, but I have been maintaining a 
similar patch for a few years in order to solve the same problem.  

Below is the documentation that I wrote for my patch.

I don't know enough about the code you just added to compare the approaches, 
but hopefully you can read through these docs(i can try to prepare an actual 
patch too if you want) and verify that your changes will allow the same level 
of functionality.  Specifically my code gives access to the c++ and python 
objects which allows the error to be handled without throwing a c++ exception, 
since in my case the calling c++ code does not expect an exception.

Under Sip Directives:

%VirtualErrorHandler
--------------------

.. parsed-literal::

%VirtualErrorHandler *name*


Used to define the name of an error handler function that is called when the 
python reimplementation of
a virtual function throws an exception. The call to the virtual error handler 
is inserted in the
 `generated derived classes`_ to handle the exception before returning.

%VirtualErrorHandler defines a module-wide default virtual error handler 
function. One can specify virtual
error handler functions per class or per virtual function by using an 
annotation.

The named function must take two arguments. This first is the class instance. 
Generic virtual error handler
functions can simply use 'const void *' to accept all class types. The second 
argument is the const sipWrapper *
which can be cast to a PyObject *. These can be used to gather relevant 
debugging information, or to handle the
exception more intelligently by calling an error handler function on the c++ 
instance or the python instance.

The virtual error handler is responsible for clearing the exception before 
returning.

For example::

%ModuleHeaderCode
void MyVirtualErrorHandler( const void *, const sipWrapper * );
%End

%ModuleCode
void MyVirtualErrorHandler( const void * /*klass*/, const sipWrapper * 
/*pyObject*/ )
{
  PyErr_Print();
}
%End

%VirtualErrorHandler MyVirtualErrorHandler


Under Class Annotations:

VirtualErrorHandler
*******************

This annotation specifies the name of the default virtual error handler for the
class.

And under function annotations:

VirtualErrorHandler
*******************

This annotation specifies a virtual error handler for this function.