=================
Custom exceptions
=================

------------
Introduction
------------

.. include:: ./definition.irest

-------------------
What's the problem?
-------------------

It is all about module interface and user expectations. If you can translate all
your exceptions to built-in ones, than you are fine. You don't have to read this
guide, but Boost.Python `exception translator`_ documentation.

.. _`exception translator` : http://boost.org/libs/python/doc/v2/exception_translator.html

My use case was different. I was supposed to export the exception classes and make
them play nice with the ``try ... except`` mechanism. I mean, users should be able
to:

  1. "except" all exceptions using ``except Exception, err:`` statement

  2. "except" the exposed library defined exception classes

I thought about few possible solutions to the problem. My first attempt was to
add a missing functionality to Boost.Python library. Well, I quickly found out
that the task is not a trivial one.

The following solution, I thought about, was to expose the exception class as-is and
to define new class in Python, which derives from it and the built-in ``Exception``.
I implemented it and when I run the code I've got ``TypeError``:
"Error when calling the metaclass bases multiple bases have instance lay-out conflict".

The only solution left was to use "aggregation with automatic delegation". I mean
instead of deriving from the exception class, I will keep it as a member variable
in a class defined in Python, which derives from the built-in ``Exception`` one.
Every time user access an attribute, the class defined in Python will automatically
redirect the request to the variable. This technique is explained much better here:
http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/52295 .

Files
-----

All files contain comments, which describe what and why was done.

.. toctree::

   `exceptions.cpp` - C++ source code <exceptions.cpp.rest>
   Build script (SCons) <sconstruct.rest>
   Usage example/tester <test.py.rest>

--------
Download
--------

:download:`exceptions.zip`

