Add DictStore.to_b2d method for consistency

Author: FrancescAlted

doc/reference/dict_store.rst

@@ -86,5 +86,11 @@ Quick example
     .. automethod:: __enter__
     .. automethod:: __exit__
 
+    Persistence
+    -----------
+    Use :meth:`DictStore.to_b2z` to pack a directory-backed store into a
+    ``.b2z`` archive, and :meth:`DictStore.to_b2d` to materialize a store as a
+    ``.b2d`` directory.
+
     Public Members
     --------------

src/blosc2/ctable.py

@@ -19,7 +19,6 @@
 import pprint
 import re
 import shutil
-import zipfile
 from collections import namedtuple
 from collections.abc import Iterable, Mapping
 from dataclasses import MISSING, dataclass
@@ -2324,20 +2323,11 @@ def to_b2d(self, urlpath: str, *, overwrite: bool = False, compact: bool = False
             and storage.open_mode() == "r"
         )
         if can_physical_unpack:
-            target_path = os.fspath(urlpath)
-            if os.path.exists(target_path):
-                if not overwrite:
-                    raise FileExistsError(
-                        f"'{target_path}' already exists. Use overwrite=True to overwrite."
-                    )
-                if os.path.isdir(target_path):
-                    shutil.rmtree(target_path)
-                else:
-                    os.remove(target_path)
-            os.makedirs(target_path, exist_ok=True)
-            with zipfile.ZipFile(storage._root, "r") as zf:
-                zf.extractall(target_path)
-            return os.path.abspath(target_path)
+            store = blosc2.TreeStore(storage._root, mode="r")
+            try:
+                return store.to_b2d(urlpath, overwrite=overwrite)
+            finally:
+                store.close()
 
         if self.base is not None:
             materialized = self.copy(compact=True)

src/blosc2/dict_store.py

@@ -632,6 +632,21 @@ def to_b2z(self, overwrite=False, filename=None) -> os.PathLike[Any] | str:
         -------
         filename : str
             The absolute path to the created b2z file.
+
+        Examples
+        --------
+        Pack a directory-backed store into a zip store::
+
+            with blosc2.DictStore("data.b2d", mode="w") as dstore:
+                dstore["/values"] = np.arange(10)
+
+            with blosc2.DictStore("data.b2d", mode="r") as dstore:
+                dstore.to_b2z(filename="data.b2z", overwrite=True)
+
+        ``filename`` can also be passed positionally::
+
+            with blosc2.DictStore("data.b2d", mode="r") as dstore:
+                dstore.to_b2z("copy.b2z", overwrite=True)
         """
         if isinstance(overwrite, str | os.PathLike) and filename is None:
             filename = overwrite
@@ -641,6 +656,7 @@ def to_b2z(self, overwrite=False, filename=None) -> os.PathLike[Any] | str:
             raise ValueError("Cannot call to_b2z() on a .b2z DictStore opened in read mode.")
 
         b2z_path = self.b2z_path if filename is None else filename
+        b2z_path = os.fspath(b2z_path)
         if not b2z_path.endswith(".b2z"):
             raise ValueError("b2z_path must have a .b2z extension")
 
@@ -669,6 +685,68 @@ def to_b2z(self, overwrite=False, filename=None) -> os.PathLike[Any] | str:
                 zf.write(self.estore_path, arcname)
         return os.path.abspath(b2z_path)
 
+    def to_b2d(self, dirname=None, *, overwrite: bool = False) -> os.PathLike[Any] | str:
+        """
+        Serialize store contents to a b2d directory.
+
+        Parameters
+        ----------
+        dirname : str, optional
+            If provided, use this directory instead of the default b2d path.
+        overwrite : bool, optional
+            If True, overwrite the existing b2d directory if it exists.
+            Default is False.
+
+        Returns
+        -------
+        dirname : str
+            The absolute path to the created b2d directory.
+
+        Examples
+        --------
+        Unpack a zip-backed store into a directory-backed store::
+
+            with blosc2.DictStore("data.b2z", mode="r") as dstore:
+                dstore.to_b2d("data.b2d", overwrite=True)
+
+            with blosc2.DictStore("data.b2d", mode="r") as dstore:
+                values = dstore["/values"][:]
+
+        Copy an existing directory-backed store to another ``.b2d`` directory::
+
+            with blosc2.DictStore("data.b2d", mode="r") as dstore:
+                dstore.to_b2d("backup.b2d", overwrite=True)
+        """
+        b2d_path = self.localpath if dirname is None and not self.is_zip_store else dirname
+        if b2d_path is None:
+            b2d_path = (
+                self.b2z_path[:-4] + ".b2d" if self.b2z_path.endswith(".b2z") else self.b2z_path + ".b2d"
+            )
+        b2d_path = os.fspath(b2d_path)
+        if not b2d_path.endswith(".b2d"):
+            raise ValueError("b2d_path must have a .b2d extension")
+
+        target_path = os.path.abspath(b2d_path)
+        source_path = os.path.abspath(self.working_dir)
+        if not self.is_zip_store and target_path == source_path:
+            return target_path
+
+        if os.path.exists(target_path):
+            if not overwrite:
+                raise FileExistsError(f"'{target_path}' already exists. Use overwrite=True to overwrite.")
+            if os.path.isdir(target_path):
+                shutil.rmtree(target_path)
+            else:
+                os.remove(target_path)
+
+        if self.is_zip_store and self.mode == "r":
+            os.makedirs(target_path, exist_ok=True)
+            with zipfile.ZipFile(self.b2z_path, "r") as zf:
+                zf.extractall(target_path)
+        else:
+            shutil.copytree(self.working_dir, target_path)
+        return target_path
+
     def _get_zip_offsets(self) -> dict[str, dict[str, int]]:
         """Get offset and length of all files in the zip archive."""
         self.offsets = {}  # Reset offsets

tests/test_dict_store.py

@@ -179,6 +179,41 @@ def test_to_b2z_accepts_positional_filename():
     os.remove(b2z_path)
 
 
+def test_to_b2d_from_readonly_b2z(tmp_path):
+    b2z_path = tmp_path / "test_to_b2d_src.b2z"
+    b2d_path = tmp_path / "test_to_b2d_dst.b2d"
+
+    with DictStore(str(b2z_path), mode="w") as dstore:
+        dstore["/nodeA"] = np.arange(5)
+        dstore["/nodeB"] = np.arange(6)
+
+    with DictStore(str(b2z_path), mode="r") as dstore:
+        unpacked = dstore.to_b2d(str(b2d_path))
+        assert unpacked == os.path.abspath(b2d_path)
+
+    with DictStore(str(b2d_path), mode="r") as dstore:
+        assert np.all(dstore["/nodeA"][:] == np.arange(5))
+        assert np.all(dstore["/nodeB"][:] == np.arange(6))
+
+
+def test_to_b2d_overwrite_existing_raises(tmp_path):
+    b2z_path = tmp_path / "test_to_b2d_existing.b2z"
+    b2d_path = tmp_path / "test_to_b2d_existing.b2d"
+
+    with DictStore(str(b2z_path), mode="w") as dstore:
+        dstore["/nodeA"] = np.arange(5)
+    b2d_path.mkdir()
+
+    with DictStore(str(b2z_path), mode="r") as dstore, pytest.raises(FileExistsError):
+        dstore.to_b2d(str(b2d_path))
+
+    with DictStore(str(b2z_path), mode="r") as dstore:
+        dstore.to_b2d(str(b2d_path), overwrite=True)
+
+    with DictStore(str(b2d_path), mode="r") as dstore:
+        assert np.all(dstore["/nodeA"][:] == np.arange(5))
+
+
 def test_to_b2z_from_readonly_b2z_raises():
     b2z_path = "test_to_b2z_readonly_zip.b2z"
     out_path = "test_to_b2z_readonly_zip_out.b2z"

tests/test_tree_store.py

@@ -1057,6 +1057,23 @@ def test_open_context_manager(populated_tree_store):
         assert np.array_equal(tstore["/child0/data"][:], np.array([1, 2, 3]))
 
 
+def test_to_b2d_from_readonly_b2z(tmp_path):
+    b2z_path = tmp_path / "test_tstore_to_b2d.b2z"
+    b2d_path = tmp_path / "test_tstore_to_b2d.b2d"
+
+    with TreeStore(str(b2z_path), mode="w") as tstore:
+        tstore["/group/node"] = np.arange(6)
+        tstore.vlmeta["description"] = "tree metadata"
+
+    with TreeStore(str(b2z_path), mode="r") as tstore:
+        unpacked = tstore.to_b2d(str(b2d_path))
+        assert unpacked == os.path.abspath(b2d_path)
+
+    with TreeStore(str(b2d_path), mode="r") as tstore:
+        assert np.array_equal(tstore["/group/node"][:], np.arange(6))
+        assert tstore.vlmeta["description"] == "tree metadata"
+
+
 def test_extensionless_tree_store_defaults_to_directory(tmp_path):
     path = tmp_path / "test_tstore_extless"