Name the match key constants after the match key

[jwrosewell]

The problem

Pull request #69 renamed the stable, comparable part of a 51Did from the hash to the match key, giving FodId a match_key attribute and leaving hash behind as a deprecated property that warns. The two constants naming that same field in the payload were not renamed, so fod_id.py still declared this.

HASH_OFFSET = 5
HASH_LENGTH = 32
HEADER_LENGTH = HASH_OFFSET
PAYLOAD_LENGTH = HASH_OFFSET + HASH_LENGTH

Their own comments already read "Byte offset of the match key field" and "Byte length of the match key field", so anyone reading the class met one vocabulary in the comments and the older one in the names.

What changed

• MATCH_KEY_OFFSET and MATCH_KEY_LENGTH are now the real constants in fod_id.py, holding the same values of 5 and 32 and keeping the comments they already had.
• HEADER_LENGTH and PAYLOAD_LENGTH are worked out from the new names. Their own names do not change, because they name the header and the payload rather than the match key.
• Every use inside the repository now reads the new names, being the reader fod_id.py, the client did_client.py, the tests test_fodid.py and test_did_client.py, the test helper envelope.py and the example fodid_example.py. That is 30 uses, plus the two declarations themselves.
• A new test, test_deprecated_constant_aliases_hold_the_new_values, checks that each old name still holds the value of the constant it points at.
• The package readme now names the new constants beside the existing note about the deprecated hash property.
• Nothing to do with SHA-256 hashing itself was renamed, so HASHED_EMAIL, IdType.HASHED_EMAIL and the descriptions of the SHA-256 match key all stand as they were.

Why the alias is kept

HASH_OFFSET and HASH_LENGTH remain as deprecated aliases pointing at the new constants, so code outside this repository that reads them keeps working through this release, exactly as the deprecated hash property keeps working beside match_key. The property warns with DeprecationWarning when it is read, which a plain class constant cannot do, so the aliases carry the same wording as that property in a comment saying they are deprecated, that the field is now called the match key after the Model Terms for Marketing vocabulary, and that they will be removed in a future release.

How it was verified

The package tests were run in a clean virtual environment on Python 3.14.5, with the OWID source taken from the owid-python submodule the way ci/copy-owid-source.ps1 and tox.ini do it.

$ python -m pytest tests -q -rs
........................................................................ [ 48%]
...........ss........................................................... [ 97%]
...                                                                      [100%]
=========================== short test summary info ===========================
SKIPPED [1] tests\test_did_client_live.py:80: set resource_key (or _51DEGREES_RESOURCE_KEY) to run the live tests
SKIPPED [1] tests\test_did_client_live.py:89: set resource_key (or _51DEGREES_RESOURCE_KEY) to run the live tests
145 passed, 2 skipped in 1.52s

The two skips are the live cloud tests, which need a resource key that was not set, and they were skipped on this branch as they are on main.

The example was run as well, so the change is exercised outside the tests.

$ python examples/fodid_example.py
51Did parsed from base64:
  Domain    : 51degrees.com
  Type      : PROBABILISTIC
  Flags     : 0x00
  LicenseId : 305419896
  Match key : 202122232425262728292a2b2c2d2e2f303132333435363738393a3b3c3d3e3f
  Verifies  : True

Same payload, re-issued:
  Same envelope (base64) : False
  Same match key         : True

A search of the whole working copy for the old names now returns only the two alias declarations.

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