Rework exceptions to be native types

[davidhewitt]

This is a rework of pyo3's exception types to be more in line with the rest of the Python native types.

I introduce new exception types PyException, PyRuntimeError etc. These must be accessed through either Py<PyBaseException>, Py<PyRuntimeError> or gil-scoped references &PyBaseException , &PyRuntimeError, just like other native types.

To minimise breakage the old types Exception, RuntimeError continue to exist and behave as they did before, but I mark them deprecated with a suggestion to use the new types.

I think this is an important first step of #295 - we should then be able to make something very similar to #[pyclass] for exceptions. It should also enable #682 to be done relatively cleanly by building off these implementations.

I based this PR on the work of #686, which I think can now be closed. As well as Py<PyBaseException>, I was able to implement std::error::Error for Py<T> and &T for all the error types T.

This PR will introduce a couple of minor breaking changes, but I think it's worth it:

• PyBorrowError and PyBorrowMutError no longer have dedicated Python types and just raise RuntimeError in Python.
  I could undo this change, however the try_borrow() would have to return &PyBorrowError and we'll take a little performance hit.
• The imported exceptions e.g. socket::herror are now only accessible as native types; existing code using these will break slightly.

If you like this, I'll press ahead with documentation.

TODO:

• Documentation EDIT: I'm going to write docs after some follow-up PRs, when it's easier to see what the final result looks like.

[kngwyu]

Thank you, looks good except the approach to the breaking change(i.e., Py prefix) 🤔
Is there any simpler solution? (e.g., type Exception = Py<PyException>)

[davidhewitt]

Is there any simpler solution? (e.g., type Exception = Py)

I think any alternative, including the above, would break more user code than this PR already does.

The simplest alternative would be to embrace the breaking change and just remove the old types.

[davidhewitt]

The simplest alternative would be to embrace the breaking change and just remove the old types.

If you think it's okay, I would be very happy to do this. It keeps the pyo3 codebase smaller and I can document these breaking changes immediately in the migration guide.

[kngwyu]

How about

type BaseException = PyBaseException;

?
This is enough for me.

[programmerjake]

How about

type BaseException = PyBaseException;

?
This is enough for me.

sounds good to me if it's marked deprecated

[davidhewitt]

Agreed marking the old functionality as deprecated. I'll try to finish off this PR at the weekend.

[davidhewitt]

I've updated this PR and rebased.

I was originally intending to write more documentation as part of this PR, but now as I've been thinking about related designs such as impl std::error::Error for PyErr I want to get those into shape before writing new docs.