Harden parsing to answer with a reason instead of raising

[jwrosewell]

Hardening, and the Python half of the same change as owid-dotnet#9.

Reading an OWID means reading whatever a caller was handed, which on a public endpoint is anything at all, so malformed data is an ordinary outcome rather than an exceptional one. Raising for it costs the construction and unwinding of an exception per bad input, and whoever sends the data chooses how often that happens.

What changes

# before
owid = Owid.from_base64(value)          # raises on anything malformed

# after
result = Owid.parse(value)
if result:                              # truthy on success
    use(result.owid)                    # the value only when it worked
else:
    log(result.status)                  # a named reason either way

Owid.parse reads the base 64 form, Owid.parse_bytes reads a buffer holding exactly one OWID, and Owid.parse_prefix reads one from the front of a buffer that may carry more after it.

A caller can no longer build an OWID. Python cannot make a constructor package private, so the boundary is kept by refusing a caller who has not come through one of the two allowed paths, being a successful parse, or Creator.create, which owns the version, domain, date and signature.

# before
owid = Owid(payload=b"...")
creator.sign(owid)

# after
owid = creator.create(b"...")           # creation names itself

The fields are read-only properties, because a parsed OWID's signature covers its fields as they arrived.

Two reading contracts

Owid.parse and Owid.parse_bytes read a buffer holding one OWID and nothing else, so the declared payload must leave exactly the signature and a byte after it is BYTE_COUNT_MISMATCH.

Owid.parse_prefix reads a frame, so it needs only the declared payload and the signature to be present and says nothing about what follows, which may be the next envelope. A frame whose declaration runs past the bytes supplied is UNEXPECTED_END instead, because there the bytes may still be arriving and a caller has to be able to tell waiting for more from giving up.

The one byte marker for a node that is absent is reported as ABSENT_NODE by both reads, and neither hands back an OWID because the marker carries no signature and so can never verify. A framed read counts its one byte as consumed, so a caller walking a run of frames steps over the absent node and reaches the next envelope.

Cross-language vocabulary

ParseStatus and SignatureStatus match the other ports, so a failure means the same thing whichever language read the bytes. The signature vocabulary keeps "could not check" apart from "does not match", as a key that cannot be fetched or decoded leaves the signature unjudged and calling that invalid would report an outage as an attack.

ParseResult, ParseStatus and SignatureStatus are exported from the package root, the way owid-rust exports its own, because a caller cannot act on a result without naming the reason the result carries.

Documentation

The README described the API this change replaced, naming Owid.from_base64, Owid.from_byte_array, direct construction and creator.sign_with_others, none of which exist. Every example and every interface entry now names the real surface, the reading contracts and the status vocabulary are written down, and the docstrings that said a malformed buffer raises are corrected. The private base 64 raising route and the decode helper it called had no callers at all, so both are removed.

tests/test_readme.py runs the Python examples in the README in the order they appear, so documentation naming a method that does not exist fails the build.

Two things caught while writing it

A first draft of the reader used b64decode(validate=True) and refused unpadded base 64, which is a normal way to carry an OWID. The round trip test caught it and padding is added again before decoding.

A test tampered with a signed OWID by rebinding owid.payload, which is exactly what the change prevents, so it now tampers with the serialised bytes and reads them back, which is how tampering actually reaches a verifier.

Verification

python -m unittest discover passes 111 tests, 0 failures, on Python 3.9 and on Python 3.14. The four Python examples in the README were also extracted and run on their own against the installed package, and they produce the results the surrounding text claims.

Produced with AI assistance under James Rosewell's direction and needs human review.