fix(zarr-metadata)!: guards narrow only when they say yes

[d-v-b]

🤖 AI text below 🤖

Breaking for type checkers. TypeIs[T] promises True exactly for the values that are T, and type checkers narrow T away when it returns False. Every is_* guard in zarr_metadata.model is stricter than its type: is_json(math.nan) is False for a float, and the document guards are False for well-typed documents that break a structural rule. So this type-checks under pyright strict, and fails at run time:

def payload(v: JSONValue | bytes) -> bytes:
    if is_json(v):
        return b""
    return v  # a float, when v is NaN

The guards are now TypeGuards, which narrow only on True. zarr-python itself does not import zarr_metadata yet, so only outside consumers are affected.

This is one of eight independent PRs from a review of the casts in zarr_metadata.model, each based on main and each passing just check alone, with a test that fails without its fix where there is behaviour to test:

• fix(zarr-metadata): bytes are not a JSON array #4423 bytes are not a JSON array
• fix(zarr-metadata): a v2 array's other members are JSON with string keys #4424 a v2 array's other members are JSON with string keys
• refactor(zarr-metadata): validators type an unread document as what it is #4425 validators type an unread document as what it is
• fix(zarr-metadata): a model shares nothing with the document it read #4426 a model shares nothing with the document it read
• refactor(zarr-metadata): model casts that only restated a type are gone #4427 model casts that only restated a type are gone
• fix(zarr-metadata): the store reader checks that it read bytes #4428 the store reader checks that it read bytes
• fix(zarr-metadata)!: guards narrow only when they say yes #4429 guards narrow only when they say yes
• fix(zarr-metadata): the v2 group document types are closed #4430 the v2 group document types are closed

#4425, #4426, #4428 and #4430 have merged, as have #4420, #4421 and #4422, and each of the four left is rebased onto them, so its tests are type-checked as #4421 requires. Of those four, only #4423 and #4429 touch the same lines, the TypeGuard import, so whichever of them merges second needs a one-line rebase. All eight together, merged with #4421's type-checked tests, pass just check.

🤖 Generated with Claude Code

[read-the-docs-community]

Documentation build overview

📚 zarr-metadata | 🛠️ Build #34777863 | 📁 Comparing e48c105 against latest (d21a5b4)

  🔍 Preview build  

1 file changed

± api/model/index.html

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.37%. Comparing base (5a27243) to head (93b192d).
⚠️ Report is 4 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff             @@
##             main    #4429       +/-   ##
===========================================
+ Coverage   52.54%   94.37%   +41.83%     
===========================================
  Files          93       93               
  Lines       13174    13174               
===========================================
+ Hits         6922    12433     +5511     
+ Misses       6252      741     -5511     

see 73 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.