Document the raise_from function for exception chaining (PEP 3134)

Author: edschofield

docs/notebooks/Writing Python 2-3 compatible code.ipynb

@@ -1,7 +1,7 @@
 {
  "metadata": {
   "name": "",
-  "signature": "sha256:a318d976dd8aacb67a39acbcafddb513645c61ae27874c0d32d4a64c1621ca35"
+  "signature": "sha256:f4ac8456d9c7976cb130d88556b7bbe2c3494a960d29e3eeffdca80a91b080e3"
  },
  "nbformat": 3,
  "nbformat_minor": 0,
@@ -294,6 +294,76 @@
      "metadata": {},
      "outputs": []
     },
+    {
+     "cell_type": "markdown",
+     "metadata": {},
+     "source": [
+      "Exception chaining (PEP 3134):"
+     ]
+    },
+    {
+     "cell_type": "code",
+     "collapsed": false,
+     "input": [
+      "# Setup:\n",
+      "class DatabaseError(Exception):\n",
+      "    pass"
+     ],
+     "language": "python",
+     "metadata": {},
+     "outputs": [],
+     "prompt_number": 3
+    },
+    {
+     "cell_type": "code",
+     "collapsed": false,
+     "input": [
+      "# Python 3 only\n",
+      "class FileDatabase:\n",
+      "    def __init__(self, filename):\n",
+      "        try:\n",
+      "            self.file = open(filename)\n",
+      "        except IOError as exc:\n",
+      "            raise DatabaseError('failed to open') from exc"
+     ],
+     "language": "python",
+     "metadata": {},
+     "outputs": []
+    },
+    {
+     "cell_type": "code",
+     "collapsed": false,
+     "input": [
+      "# Python 2 and 3:\n",
+      "from future.utils import raise_from\n",
+      "\n",
+      "class FileDatabase:\n",
+      "    def __init__(self, filename):\n",
+      "        try:\n",
+      "            self.file = open(filename)\n",
+      "        except IOError as exc:\n",
+      "            raise_from(DatabaseError('failed to open'), exc)"
+     ],
+     "language": "python",
+     "metadata": {},
+     "outputs": [],
+     "prompt_number": 16
+    },
+    {
+     "cell_type": "code",
+     "collapsed": false,
+     "input": [
+      "# Testing the above:\n",
+      "try:\n",
+      "    fd = FileDatabase('non_existent_file.txt')\n",
+      "except Exception as e:\n",
+      "    assert isinstance(e.__cause__, IOError)    # FileNotFoundError on Py3.3+ inherits from IOError"
+     ],
+     "language": "python",
+     "metadata": {},
+     "outputs": [],
+     "prompt_number": 17
+    },
     {
      "cell_type": "heading",
      "level": 3,