Exceptions?

[tpgillam]

The current early prototype uses error value types rather than exceptions.

The ergonomics of this, unfortunately, are not great, because Python has no equivalent to rust's ? operator which would allow immediately returning from the current value with any error value encountered.

This adds boilerplate in encode and decode, including in the coders that users will write (since they may have to encode attributes of a type).

Exceptions are "easier", at the expense of harder-to-follow control flow in error cases.

[Rupt]

if isinstance(payload, EncodeError):
    return payload

is simple, explicit, and unambiguous.

[Rupt]

More boilerplate, but one could consider a rust-like unwrap setup, where all possible return types have an unwrap method that users can call if they want to raise on error.

Half-baked sketch:

@dataclasses.dataclass(frozen=True, slots=True)
class Error:
    msg: str

    def unwrap() -> Never:
        raise ValueError(self.msg)


@dataclasses.dataclass(frozen=True, slots=True)
class Success[T]:
    value: T

    def unwrap() -> T:
        return self.value


def encode_to_document(obj: object, fmt: SerialisationFormat) -> Error | Success[Document]:
    ...

[tpgillam]

Unfortunately you get the explosion:

# hypothetical
return [encode(x, fmt) for x in some_list]

# current
res: list[JsonType] = []
for x in some_list:
    tmp = encode(x, fmt)
    if isinstance(tmp, EncodeError):
        return tmp
    res.append(tmp)
return res

but it's also true that the comprehension case won't be encountered by downstream users, since if they have an attribute they want to encode that is a list, then they can can rely on encode(self.some_list_attribute, fmt) doing the iteration.

edit: I don't really care about boilerplate at all within this library. So on those grounds error types are actually not so bad.

[tpgillam]

I think unwrap is a nice feature we could provide to let downstream users use exceptions if they want to. Neat!

[tpgillam]

So it seems like someone made a library roughly along these lines.
But it's recently become unmaintained, and there are some grumbles from maintainers about it not being a style that suits python well: rustedpy/result#201 .