fix: accept universal-pathlib UPath as a StoreLike value

[d-v-b]

🤖 AI text below 🤖

Closes zarr-developers#4244.

What was going on

Passing a remote UPath to the top-level API raised TypeError: Unsupported type for store_like: 'S3Path'. Nothing changed on zarr's side — universal-pathlib 0.3.0 (2025-09-29) rebased UPath onto pathlib_abc, and remote paths like S3Path stopped being pathlib.Path subclasses and stopped implementing __fspath__.

That broke two things that had been working by accident:

1. Via xarray (how the issue was reported). xarray converts any os.PathLike store to a string before handing it to zarr, so zarr used to receive "s3://..." and route it to FsspecStore.from_url. Zarr never actually saw a UPath. With no __fspath__, the raw object now comes through.
2. Direct zarr.open(S3Path). I confirmed against zarr 3.1.3 + upath 0.2.6 that this used to hit the isinstance(store_like, Path) branch and build a LocalStore rooted at an S3Path — which worked only because upath 0.2 overrode every pathlib method to dispatch through fsspec.

So the report is filed as a feature request, and that framing is accurate: remote UPath support was never deliberate. But FsspecStore.from_upath already exists and universal-pathlib is already an optional dependency, so wiring it up is small.

The change

• make_store gains a UPath branch. Remote UPaths go to FsspecStore.from_upath; local ones (protocol "" or "file") go to a LocalStore, so UPath('/data') and Path('/data') agree, mirroring how the equivalent strings are already routed.

• The branch is checked before the Path branch. On universal-pathlib 0.2 every UPath — including S3Path — subclasses pathlib.Path, so otherwise remote paths would keep landing in a LocalStore there. I verified routing is now identical on 0.2.0 and 0.3.10:

  value	0.2.0	0.3.10
  UPath('s3://bucket/foo.zarr')	FsspecStore	FsspecStore
  UPath('memory://bucket/foo.zarr')	FsspecStore	FsspecStore
  UPath('file:///tmp/x.zarr')	LocalStore	LocalStore
  UPath('/tmp/x.zarr')	LocalStore	LocalStore

• Drive-by fix: FsspecStore.from_upath passed upath.fs straight to the constructor without going through _make_async (unlike from_mapper). A UPath hands back a filesystem in whatever mode it was built with, which is synchronous unless the caller passed asynchronous=True. So from_upath raised TypeError: Filesystem needs to support async operations. for genuinely sync filesystems, and emitted the "not created with asynchronous=True" warning for sync-mode instances of async ones. Both reproduce on upath 0.3.10.

• storage_options passed alongside a UPath still raises, since the UPath carries its own — the existing check already covers this, and there's now a test pinning it.

Notes for review

• Passing a UPath with storage_options is an error rather than a merge. Ambiguous either way; erroring seemed better than silently picking one. Happy to change. Note xarray always forwards storage_options to zarr, but as None when unset, so the reported case is unaffected.
• Local UPaths are routed to LocalStore rather than through fsspec's LocalFileSystem. This is a judgement call for consistency with the string handling (and it's faster); the alternative is to send everything to FsspecStore and keep the branch simpler.
• The UPath re-export in _utils.py needed an explicit as UPath alias to satisfy no_implicit_reexport.

Testing

• New parametrized routing test over the four cases in the table, plus an error-case test for storage_options.
• New moto-backed S3 tests: an end-to-end open_group(UPath(...)) round trip reproducing the issue, and one asserting from_upath on a sync-mode UPath yields an async filesystem with storage options preserved and no warning.
• I checked the new tests fail without the source change (5 of 6 do; the other two cases are regression guards that already passed).
• One new test needed a filterwarnings for a DeprecationWarning that universal-pathlib 0.2.0 raises from its own subclass registry when any local UPath is constructed. It fires on a bare UPath('/tmp/x') with zarr uninvolved, and would otherwise break the min_deps CI env, which pins universal_pathlib==0.2.0.
• Full suite: 7069 passed, 380 skipped, 4 xfailed. ruff and mypy clean. Store tests also verified against universal-pathlib 0.2.0.

🤖 Generated with Claude Code