Replace donfig with a statically-typed configuration object

[d-v-b]

Summary

Replaces the donfig-based configuration with a statically-typed, dataclass-backed config in src/zarr/core/config.py. zarr.config now provides precise static types for both attribute access (zarr.config.array.order) and the dotted-string API (zarr.config.get("array.order")), while preserving donfig's runtime behavior.

Motivation: donfig stores config as an untyped nested dict, so every value is typed Any and typos in keys go undetected. This models the config as frozen dataclasses (the single source of truth) and surfaces the familiar string API through hand-written @overloads that relate each dotted key to its value type.

Design

• Schema: frozen, slotted dataclasses (ZarrConfig + ArraySettings / AsyncSettings / ThreadingSettings / CodecPipelineSettings). codecs is an open Mapping[str, str] subtree so arbitrary codec names still register at runtime.
• Typed string API: hand-written @overloads map each dotted key ("array.order") to its value type (Literal["C", "F"]), plus a str fallback for codecs.*/unknown keys. A drift-protection test asserts every structured key has a matching overload, so the two can't fall out of sync.
• async namespace: async is a Python keyword, so the dataclass field is async_ while the serialized key stays "async"; the string API (config.get("async.concurrency")) is unaffected.
• State model: a process-global _base snapshot plus a ContextVar scope overlay. config.set(...) updates both; with config.set(...) restores both on exit. The global base is what makes a permanent set visible inside ThreadPoolExecutor workers (which don't copy contextvars).

Backwards compatibility

The public zarr.config surface is preserved. Verified against donfig 0.8.1 and across all in-repo consumers (registry, sync, abc/codec, codec_pipeline, group, abc/store, array_spec, metadata v2/v3):

• config.get("a.b.c"[, default]), subtree config.get("codecs", {}).get(key)
• config.set({...}) (permanent) and with config.set({...}) (scoped), plus the config.set(key=value) kwargs form
• config.reset(), config.refresh(), config.enable_gpu(), config.defaults
• ZARR_FOO__BAR env-var ingestion and YAML config files (ZARR_CONFIG, ~/.config/zarr)
• the deprecations mechanism (set raises BadConfigError on a removed key; get honors the default — both donfig-faithful)

Intentional, ratified behavior changes

• Unknown keys — "validate at the API, parse external input": programmatic config.set/config.get now raise on an unknown structured key (typo detection — the point of the typed config), while env-var / YAML ingest tolerates unknown keys (skips with a warning) so a stray ZARR_* var or version-skewed config file can't crash import zarr. The open codecs.* namespace still accepts arbitrary keys.
• config.defaults now returns a nested dict (donfig returned a one-element list[dict]).

Dependency change

• donfig removed (deps, lockfile, version-report).
• pyyaml>=6 added (YAML support was previously transitive via donfig; the config module now reads YAML directly).

Testing

• Full suite green: 6238 passed, 277 skipped, 7 xfailed; mypy src clean (strict).
• New tests/test_config_typed.py: schema/path-helpers, env + YAML ingest (including the codecs-block deep-merge regression), the base+contextvar state model incl. cross-thread visibility, deprecations, the overload drift-protection test, and assert_type static-typing assertions.

Notes for reviewers

• The implementation followed an approved design spec and implementation plan, available here as a gist: https://gist.github.com/d-v-b/2a95ff0104824ef52545ed9baf1b66c3

---

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 94.21769% with 17 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.51%. Comparing base (e29ddd2) to head (55485bf).

Files with missing lines	Patch %	Lines
src/zarr/core/config.py	94.21%	17 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4101      +/-   ##
==========================================
+ Coverage   93.50%   93.51%   +0.01%     
==========================================
  Files          90       90              
  Lines       11981    12262     +281     
==========================================
+ Hits        11203    11467     +264     
- Misses        778      795      +17     

Files with missing lines	Coverage Δ
src/zarr/__init__.py	100.00% <ø> (ø)
src/zarr/core/config.py	94.31% <94.21%> (-5.69%)	⬇️

🚀 New features to boost your workflow:

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

[d-v-b]

I'm adding some useful error messages:

  5 Traceback (most recent call last):
  4   File "<stdin>", line 1, in <module>
  3   File "/home/d-v-b/wt/statically-typed-config/src/zarr/core/config.py", line 483, in get
  2     raise _unknown_key_error(key, current) from None
  1 KeyError: "'arraya' is not a valid configuration key. Did you mean 'array'?"

[d-v-b]

flagging this as nice, but delicate (polite term for brittle). These overloads have to be kept synced up with the actual structure of the configuration, which is defined elsewhere. This PR adds tests that confirm that these overloaded signatures match the field name + type of the config object. I'm not sure how we can do do any better than that, if we want a string-based API like this to be statically typed.

an alternative that we can add later would be a non-string-based API, where we define an object that acts like a cursor / lens over our config.

[d-v-b]

donfig returned defaults as a list, we just return a dict

[d-v-b]

I was motivated to open this PR because I think we need a more explicit data structure for our config. Donfig worked well but a morass of untyped dicts is not the UX we want if we plan to be agile with deprecations and feature additions.

[maxrjones]

I really like this direction @d-v-b! Thanks for working on it.

I'll give it a spin, likely on Monday.