Merge branch 'main' into refactor/metadata-package

Author: d-v-b

changes/3924.bugfix.md

@@ -0,0 +1 @@
+Apply path normalization to the `path` attribute of `FsspecStore`, ensuring that leading and trailing "/" symbols are removed.

docs/contributing.md

@@ -311,6 +311,29 @@ The Zarr library is an implementation of a file format standard defined external
 
 If an existing Zarr format version changes, or a new version of the Zarr format is released, then the Zarr library will generally require changes. It is very likely that a new Zarr format will require extensive breaking changes to the Zarr library, and so support for a new Zarr format in the Zarr library will almost certainly come in new `major` release. When the Zarr library adds support for a new Zarr format, there may be a period of accelerated changes as developers refine newly added APIs and deprecate old APIs. In such a transitional phase breaking changes may be more frequent than usual.
 
+
+## Experimental API policy
+
+The `zarr.experimental` namespace contains features that are under active development and may change without notice. When contributing to or depending on experimental features, please keep the following in mind:
+
+### For contributors
+
+When adding a new feature to `zarr.experimental`:
+
+1. Place the feature under `src/zarr/experimental/` and export it from `src/zarr/experimental/__init__.py`.
+2. Document the feature in `docs/user-guide/experimental.md` and note clearly that it is experimental.
+3. Add a changelog entry categorized as `feature`.
+
+We aim to either **promote** or **remove** experimental features within **6 months** of their addition. To promote a feature to stable:
+
+1. Move it from `zarr.experimental` to the appropriate stable module.
+2. Keep a deprecated re-export in `zarr.experimental` for one minor release.
+3. Update the documentation to reflect the stable location.
+
+### For users
+
+Features in `zarr.experimental` carry no stability guarantees. They may be changed or removed in any release, including patch releases. If you depend on an experimental feature, pin your `zarr-python` version accordingly.
+
 ## Release procedure
 
 Open an issue on GitHub announcing the release using the release checklist template:

src/zarr/storage/_fsspec.py

@@ -16,7 +16,7 @@
 )
 from zarr.core.buffer import Buffer
 from zarr.errors import ZarrUserWarning
-from zarr.storage._utils import _join_paths
+from zarr.storage._utils import _join_paths, normalize_path
 
 if TYPE_CHECKING:
     from collections.abc import AsyncIterator, Iterable
@@ -127,7 +127,7 @@ def __init__(
     ) -> None:
         super().__init__(read_only=read_only)
         self.fs = fs
-        self.path = path
+        self.path = normalize_path(path)
         self.allowed_exceptions = allowed_exceptions
 
         if not self.fs.async_impl:

tests/test_store/test_fsspec.py

@@ -17,6 +17,7 @@
 from zarr.errors import ZarrUserWarning
 from zarr.storage import FsspecStore
 from zarr.storage._fsspec import _make_async
+from zarr.storage._utils import normalize_path
 from zarr.testing.store import StoreTests
 
 if TYPE_CHECKING:
@@ -286,6 +287,27 @@ def array_roundtrip(store: FsspecStore) -> None:
     np.testing.assert_array_equal(arr[:], data)
 
 
+@pytest.mark.skipif(
+    parse_version(fsspec.__version__) < parse_version("2024.12.0"),
+    reason="No AsyncFileSystemWrapper",
+)
+@pytest.mark.parametrize("path", ["", "/", "//", "foo", "foo/", "/foo", "/foo/", "//foo//"])
+def test_fsspec_store_path_normalization(path: str) -> None:
+    """`FsspecStore.path` is normalized to the canonical form, matching
+    `normalize_path`, regardless of the surface representation the caller
+    supplies.
+
+    Regression test for https://github.com/zarr-developers/zarr-python/issues/3922
+    -- when a caller passed `path="/"` the leading slash flowed through
+    unmodified to subsequent `_join_paths([self.path, key])` calls, producing
+    `"//key"` and missing the underlying object.
+    """
+    sync_fs = fsspec.filesystem("memory")
+    fs = _make_async(sync_fs)
+    store = FsspecStore(fs=fs, path=path)
+    assert store.path == normalize_path(path)
+
+
 @pytest.mark.skipif(
     parse_version(fsspec.__version__) < parse_version("2024.12.0"),
     reason="No AsyncFileSystemWrapper",