Make error_already_set fetch and hold the Python error

This clears the Python error at the error_already_set throw site, thus
allowing Python calls to be made in destructors which are triggered by
the exception. This is preferable to the alternative, which would be
guarding every Python API call with an error_scope.

This effectively flips the behavior of error_already_set. Previously,
it was assumed that the error stays in Python, so handling the exception
in C++ would require explicitly calling PyErr_Clear(), but nothing was
needed to propagate the error to Python. With this change, handling the
error in C++ does not require a PyErr_Clear() call, but propagating the
error to Python requires an explicit error_already_set::restore().

The change does not break old code which explicitly calls PyErr_Clear()
for cleanup, which should be the majority of user code. The need for an
explicit restore() call does break old code, but this should be mostly
confined to the library and not user code.

tests/test_exceptions.py

@@ -13,6 +13,14 @@ def test_error_already_set(msg):
     assert msg(excinfo.value) == "foo"
 
 
+def test_python_call_in_catch():
+    from pybind11_tests import python_call_in_destructor
+
+    d = {}
+    assert python_call_in_destructor(d) is True
+    assert d["good"] is True
+
+
 def test_custom(msg):
     from pybind11_tests import (MyException, throws1, throws2, throws3, throws4,
                                 throws_logic_error)