Improve exception-fluency of SDK API

[erikrose]

Currently, errors are raised (exclusively?) as Err exceptions (parallel to Rust's Err variant of its Result type), and the caller must pick them apart manually using isinstance() or similar:

try:
    result = await_request(pending_request)
except Err as exc:
    if isinstance(exc.value, Error_OptionalNone):
        # There were no more requests within the timeout.
        break
    else:
        # Something truly went wrong.
        raise
else:
    # Do the no-error case.

This should be shortenable to:

try:
    result = await_request(pending_request)
except NoRequestError as exc:
    break
else:
    # Do the no-error case.

(This may not be the most motivating example, since await_request() should perhaps return None when there is no request. However, it serves to illustrate the form.)

Result is currently defined as Union[Ok[T], Err[E]]. It seems to me that we can achieve an idiomatic and lossless mapping onto Python's result/exception duality by having Result-returning functions raise E xor return T.

Note that currently we raise the entire Err(E), not merely E, necessitating further unpacking. I don't think it brings any benefit, since E is the only thing in the Err:

@dataclass(frozen=True)
class Err(Generic[E], Exception):
    value: E

A notable speed bump is that the current error classes are root classes, not subclasses of BaseException, as is required for catching them.

@dataclass
class Error_OptionalNone:
    pass

However, it appears the binding generator is aware those are errors…

Error = Union[Error_GenericError, Error_InvalidArgument, Error_BadHandle, Error_BufferLen, Error_Unsupported, Error_HttpInvalid, Error_HttpUser, Error_HttpIncomplete, Error_OptionalNone, Error_HttpHeadTooLarge, Error_HttpInvalidStatus, Error_LimitExceeded]

…so perhaps the fix is straightforward.

For completeness and in case fixing it closer to the source proves intractable: decorating Result-returning functions with one that catches any Err, unpacks it, and re-raises its E would domesticate them sufficiently. (The BaseException speed bump would still need to be solved first.)

[erikrose]

Here's where the templating happens in the binding generator: https://github.com/bytecodealliance/componentize-py/blob/b39f84b60ead942bfcd7caab701a8c73381d299c/src/summary.rs#L1443

[erikrose]

Ah, the Error = Union… type is just the WIT variant error we happen to define in compute.wit. The binding generator isn't aware of the errorness of any of it.

[posborne]

Ah, the Error = Union… type is just the WIT variant error we happen to define in compute.wit. The binding generator isn't aware of the errorness of any of it.

Yeah, unfortunately, I have been considering ways to wrap this in python but I'm not sure if there's going to be a good way to do so at the bindings layer that isn't an abomination.

[erikrose]

And the thoughts I've been having in parallel:

What if we could tag certain result<_, error> error values as should-be-exceptions (and thus improve ergonomics directly in the bindgen)? But shouldn't all result errors be exceptions?

If they're primitives like u8s, they'll have to be wrapped in something raisable like Err, and that could be done by the bindgen, because it knows their types. This…

crash-with-int: func() -> result<_, u8>

…gets used like…

try:
    crash_with_int()
except Err as e:
    assert isinstance(e.value, int)

…just as today.

But what if all error types of a result are non-primitives?

If all the error types of a result are enums, we could do this to make them raisable…

class OpenError(Exception, Enum):
     """
     An error returned by `open`-like functions.
     """
     INVALID_SYNTAX = 0
     NAME_TOO_LONG = 1
     RESERVED = 2
    ...

…but then OpenError.INVALID_SYNTAX ends up being Exception(2), which is odd for non-result uses of the type, if any.

If, as is often the case with Fastly's WIT, all the error types of a result are variants, we could make the presently generated dataclasses also subclass Exception:

@dataclass
class Error_CannotRead(Exception):
    pass

This shares the same reservation as above, where non-result uses of the variant will be surprised to find that the cases are all exceptions. It's not as severe, however, as there's no subverted expectation that, say, OpenError.NAME_TOO_LONG's value is 6. The only surprises would lie in isinstance checks (acceptable, I deem) and the presence of the add_note, args, and with_traceback methods from Exception. I could live with these if they made everything else very ergonomic.

I'll cut this off here to share it. I'm reasonably certain I'm converging on the conclusion that the best we can do is a runtime intervention, at which time we can see that an Err is in flight and munge it into something more descriptive. It's a shame to blow the extra cycles to do that, but it may be unavoidable. And many of those cycles would otherwise have to be blown by customer code anyway.