Add a decorator to make the WIT API raise exceptions more idiomatically. Refs #19.

[erikrose]

See test cases for examples.

For now, I'm satisfied with how it handles, primitive types, unexpected types, and variants. Enums are next. I think that will cover all the common cases, and an escape valve would be trivial.

[posborne]

nit: can do the get here with UnexpectedFastlyError as the default case to avoid the or. E.g.

err_class = nice_classes.get(type(error_value), UnexpectedFastlyError)
raise err_class(error_value) from e

[erikrose]

Good call!

[posborne]

I would probably lean toward naming this something like remap_wit_errs with the argument being named mapping.

[erikrose]

But remap them why? At random? What's the intent?

[erikrose]

I also wouldn't necessarily expect a Python customer to know what "wit" means, and I'd like these to function a bit as documentation if they dig in: at least to the point where they can see what exceptions might come bubbling out. I could live with remap_exceptions, but I think some intent is lost.

[posborne]

I think the customers who are reading the source to understand some problem can reasonable be expected to be exposed to WIT to understand what is going on. Most users won't need to know this just reading the docs won't see the decorator anyway.

I would expect most customers deploying non-trivial apps would also be generally aware of at least basic wasm and component model concepts so seeing WIT in the source is unlikely to be jarring and could, in fact, be anchoring. Also, it's in the imports.

[erikrose]

Okay, remap_wit_exceptions it is. I still don't think most of our customers will have any notion of WITs, but at least it is something they could look up in wide world.

We'll see if the "wit_world" name makes it to production. Do you have a sense of whether we'll façade the whole API surface or just the most common/egregious bits? I don't yet myself. I suppose we'd at least want to wrap exception raisers, which is unsurprisingly most interfaces. So I guess I do have a good sense now. :-) As an aside, I do think "wit_world" is a good descriptor—better than something vague like "low-level", since inevitably such a relative term becomes ambiguous when a super-duper-high-level API atop the high-level one shows up. ;-)

[posborne]

I do think "wit_world" is a good descriptor—better than something vague like "low-level", since inevitably such a relative term becomes ambiguous when a super-duper-high-level API atop the high-level one shows up. ;-)

I have no big issues with that; the one thing I think we should probably do is to move it under the fastly_compute namespace, so fastly_compute.wit_world or however we want to handle that. That follows the pattern used by the spin sdk (they expose more of the bindings directly via spin_sdk.wit as a reference).

[erikrose]

Definitely.

[posborne]

I suspect we might need to make some tweaks later and the test may not be necessary once we have pervasive usage, but this should be good for next steps.

[erikrose]

Yep, I expect to encounter a few more corner cases in reality. It is kind of a branchy thing, so my suspicion is that the (cheap) tests may stay. After all, I doubt we're going to lay in integration tests for each Fastly API. But we shall see if there's sufficient latitude in our façade solution for us to make human mistakes worth testing for!