Rename FodId hash to match_key to match the Model Terms vocabulary

[jwrosewell]

The stable, comparable part of a 51Did (the payload bytes after the flags and licence id) is now called the match key. The Model Terms for Marketing, which will be published later, and the patent both use that word, so the code uses the same one. Previously the Python reader exposed those bytes as FodId.hash. This mirrors the .NET rename in 51Degrees/pipeline-dotnet#348 and the Rust one in 51Degrees/rust#19.

Change

• Rename the public FodId.hash property to FodId.match_key.
• Keep FodId.hash as a deprecated alias that returns the same bytes and warns with DeprecationWarning (warnings.warn(..., DeprecationWarning, stacklevel=2)), so existing callers keep working and see where to move. The alias will be removed in a future release.
• Move the internal names that carry the same bytes to match key naming, being the _match_key field, the match_key parameters of _assign and _build, the locals in _read_payload and _unpack_or_raise, the _match_key_length helper (was _value_length) and the local in DidClient's _payload_length_valid.
• HASH_OFFSET and HASH_LENGTH keep their names because the SHA-256 wording behind them stays true. Their docstrings, and the GUID_LENGTH one, now describe the match key field. SHA-256 and HASHED_EMAIL wording is unchanged.
• Update the FodId and FodIdParseStatus docstrings, the package docstring, the PyPI description in setup.py, the readme (terminology, payload layout tables, usage and comparison snippets, lower bounds section, guarantees) and the offline example examples/fodid_example.py to the match key vocabulary. The readme usage section notes the deprecated alias.
• Update the tests to match_key and add one test, test_deprecated_hash_alias_returns_match_key_and_warns, which reads the alias, asserts the same bytes come back and asserts the DeprecationWarning.

Before and after for a caller

# before
value = fod_id.hash

# after
match_key = fod_id.match_key

fod_id.hash still works and returns the same bytes, with a DeprecationWarning.

Tests

tox -e py in fiftyone_pipeline_did on this branch: 142 passed, 2 skipped. That is main's 141 passed, 2 skipped (measured on the same checkout before the change) plus the new alias test. The two skipped tests are the live cloud ones, as on main.

The same suite under Python 3.9, the package floor, run with python -m unittest discover and -W error::DeprecationWarning: 144 tests, OK, 2 skipped. Running with deprecation warnings as errors shows nothing outside the alias test touches the deprecated name.

The offline example examples/fodid_example.py runs clean with -W error::DeprecationWarning, prints the match key and reports a different envelope with the same match key across two issues of the same payload.

Part of the cross-repository match key vocabulary rename (documentation, website, .NET reader, Rust reader and cloud internals in separate PRs).

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