Warn on implicit blosc2.open append mode

  Implement the first phase of plans/changing-default-open-mode.md by
  tracking omitted mode= with a sentinel and emitting a FutureWarning when
  blosc2.open() relies on the current implicit "a" behavior.

  Update mmap-related tests, examples, and docstrings to pass explicit
  mode="r" so they keep exercising their intended paths without tripping
  the migration warning.

Author: FrancescAlted

examples/mmap-rw.py

@@ -24,7 +24,7 @@
 blosc2.asarray(a, urlpath=urlpath, mmap_mode="w+", initial_mapping_size=initial_mapping_size)
 
 # Read the ndarray back via the general open function
-a_read = blosc2.open(urlpath, mmap_mode="r")
+a_read = blosc2.open(urlpath, mode="r", mmap_mode="r")
 
 assert np.all(a == a_read)
 blosc2.remove_urlpath(urlpath)

examples/ndarray/blosc2_3_10_demo.py

@@ -33,7 +33,7 @@
 
 # Reopen persistent expression, compute, and write to disk with blosc2
 t0 = time.time()
-lexpr = blosc2.open(urlpath=url_path)
+lexpr = blosc2.open(urlpath=url_path, mode="r")
 dt = time.time() - t0
 print(f"In {round(dt * 1000, 3)} ms opened lazy expression: shape = {lexpr.shape}, dtype = {lexpr.dtype}")
 t1 = time.time()

examples/ndarray/compute_expr.py

@@ -50,7 +50,7 @@
 
 # Get a LazyExpr instance
 (da**2 + db**2 + 2 * da * db + 1).save(urlpath="c.b2nd")
-dc = blosc2.open("c.b2nd")
+dc = blosc2.open("c.b2nd", mode="r")
 
 # Evaluate: output is a NDArray
 dc2 = dc.compute()

examples/ndarray/dsl_save.py

@@ -46,7 +46,7 @@ def heat_step(u, v):
 print("LazyUDF saved to heat_step.b2nd")
 
 # ── reload in a 'fresh' context (no reference to heat_step) ─────────
-reloaded = blosc2.open("heat_step.b2nd")
+reloaded = blosc2.open("heat_step.b2nd", mode="r")
 assert isinstance(reloaded, blosc2.LazyUDF), "Expected a LazyUDF after open()"
 assert isinstance(reloaded.func, DSLKernel), "func must be a DSLKernel after reload"
 assert reloaded.func.dsl_source is not None, "dsl_source must survive the round-trip"
@@ -64,7 +64,7 @@ def heat_step(u, v):
 lazy2 = blosc2.lazyudf(heat_step, (u2, v), dtype=np.float64)
 lazy2.save(urlpath="heat_step2.b2nd")
 
-reloaded2 = blosc2.open("heat_step2.b2nd")
+reloaded2 = blosc2.open("heat_step2.b2nd", mode="r")
 result2 = reloaded2.compute()
 expected2 = u2[()] + 0.1 * (v[()] - u2[()])
 assert np.allclose(result2[()], expected2)

examples/ndarray/meta.py

@@ -27,7 +27,7 @@
 print(a.info)
 
 # Read a b2nd array from disk
-b = blosc2.open(urlpath)
+b = blosc2.open(urlpath, mode="r")
 
 # Deal with meta
 m1 = b.schunk.meta.get("m5", b"0000")

examples/ndarray/persistency.py

@@ -20,6 +20,6 @@
 a = blosc2.asarray(nparray, urlpath=urlpath, mode="w")
 
 # Read the array from disk
-b = blosc2.open(urlpath)
+b = blosc2.open(urlpath, mode="r")
 # And see its contents
 print(b[...])

examples/ndarray/reduce_and_enlarge.py

@@ -49,7 +49,7 @@
 
 url_path = "my_expr.b2nd"
 # Open the saved file
-lazy_expr = blosc2.open(urlpath=url_path)
+lazy_expr = blosc2.open(urlpath=url_path, mode="r")
 print(lazy_expr)
 print(f"expr (after open) shape: {lazy_expr.shape}; dtype: {lazy_expr.dtype}")
 # Evaluate and print the result of the lazy expression (should be a 2x4 arr)

examples/ndarray/reduce_expr_save.py

@@ -24,13 +24,13 @@
 # Get a LazyExpr instance
 c = a**2 + b**2 + 2 * a * b + 1
 c.save(urlpath="c.b2nd")
-c = blosc2.open("c.b2nd")
+c = blosc2.open("c.b2nd", mode="r")
 # Evaluate: output is a NDArray
 d = blosc2.lazyexpr("a + c.sum() + a.std()", operands={"a": a, "c": c})
 d.save(urlpath="lazy-d.b2nd")
 
 # Load the expression from disk
-d = blosc2.open("lazy-d.b2nd")
+d = blosc2.open("lazy-d.b2nd", mode="r")
 print(f"Expression: {d}")
 assert isinstance(d, blosc2.LazyExpr)
 e = d.compute()

src/blosc2/core.py

@@ -834,7 +834,7 @@ def load_tensor(urlpath: str, dparams: dict | None = None) -> tensorflow.Tensor
     :func:`~blosc2.save_tensor`
     :func:`~blosc2.pack_tensor`
     """
-    schunk = blosc2.open(urlpath, dparams=dparams)
+    schunk = blosc2.open(urlpath, mode="r", dparams=dparams)
     return _unpack_tensor(schunk)
 
 

src/blosc2/indexing.py

@@ -935,7 +935,7 @@ def _open_sidecar_handle(array: blosc2.NDArray, token: str, category: str, name:
             raise RuntimeError("sidecar handle path is not available")
         handle = legacy if isinstance(legacy, blosc2.NDArray) else blosc2.asarray(np.asarray(legacy))
     else:
-        handle = blosc2.open(path, mmap_mode=_INDEX_MMAP_MODE)
+        handle = blosc2.open(path, mode="r", mmap_mode=_INDEX_MMAP_MODE)
     _SIDECAR_HANDLE_CACHE[cache_key] = handle
     return handle
 
@@ -1054,7 +1054,7 @@ def _compute_sorted_boundaries_from_sidecar(
 ) -> np.ndarray:
     nsegments = math.ceil(length / segment_len)
     boundaries = np.empty(nsegments, dtype=_boundary_dtype(dtype))
-    sidecar = blosc2.open(path, mmap_mode=_INDEX_MMAP_MODE)
+    sidecar = blosc2.open(path, mode="r", mmap_mode=_INDEX_MMAP_MODE)
     start_value = np.empty(1, dtype=dtype)
     end_value = np.empty(1, dtype=dtype)
     for idx in range(nsegments):
@@ -1301,7 +1301,7 @@ def _sidecar_storage_geometry(
 ) -> tuple[int, int]:
     if path is None:
         return fallback_chunk_len, fallback_block_len
-    sidecar = blosc2.open(path, mmap_mode=_INDEX_MMAP_MODE)
+    sidecar = blosc2.open(path, mode="r", mmap_mode=_INDEX_MMAP_MODE)
     return int(sidecar.chunks[0]), int(sidecar.blocks[0])
 
 
@@ -1385,7 +1385,7 @@ def _stream_copy_sidecar_array(
     blocks: tuple[int, ...],
     cparams: dict | None = None,
 ) -> None:
-    source = blosc2.open(str(source_path), mmap_mode=_INDEX_MMAP_MODE)
+    source = blosc2.open(str(source_path), mode="r", mmap_mode=_INDEX_MMAP_MODE)
     blosc2.remove_urlpath(str(dest_path))
     kwargs = {"chunks": chunks, "blocks": blocks, "urlpath": str(dest_path), "mode": "w"}
     if cparams is not None:
@@ -2754,7 +2754,7 @@ def _copy_sidecar_to_temp_run(
     cparams: dict | None = None,
 ) -> Path:
     out_path = workdir / f"{prefix}.b2nd"
-    sidecar = blosc2.open(path, mmap_mode=_INDEX_MMAP_MODE)
+    sidecar = blosc2.open(path, mode="r", mmap_mode=_INDEX_MMAP_MODE)
     output = _create_blosc2_temp_array(out_path, length, dtype, FULL_OOC_MERGE_BUFFER_ITEMS, cparams)
     chunk_len = int(sidecar.chunks[0])
     for chunk_id, start in enumerate(range(0, length, chunk_len)):
@@ -2814,10 +2814,10 @@ def _merge_run_pair(
     tracker: TempRunTracker | None = None,
     cparams: dict | None = None,
 ) -> SortedRun:
-    left_values_mm = blosc2.open(str(left.values_path), mmap_mode=_INDEX_MMAP_MODE)
-    left_positions_mm = blosc2.open(str(left.positions_path), mmap_mode=_INDEX_MMAP_MODE)
-    right_values_mm = blosc2.open(str(right.values_path), mmap_mode=_INDEX_MMAP_MODE)
-    right_positions_mm = blosc2.open(str(right.positions_path), mmap_mode=_INDEX_MMAP_MODE)
+    left_values_mm = blosc2.open(str(left.values_path), mode="r", mmap_mode=_INDEX_MMAP_MODE)
+    left_positions_mm = blosc2.open(str(left.positions_path), mode="r", mmap_mode=_INDEX_MMAP_MODE)
+    right_values_mm = blosc2.open(str(right.values_path), mode="r", mmap_mode=_INDEX_MMAP_MODE)
+    right_positions_mm = blosc2.open(str(right.positions_path), mode="r", mmap_mode=_INDEX_MMAP_MODE)
 
     out_values_path = workdir / f"full_merge_values_{merge_id}.b2nd"
     out_positions_path = workdir / f"full_merge_positions_{merge_id}.b2nd"
@@ -3024,8 +3024,8 @@ def _build_full_descriptor_ooc(
             array, token, kind, full, final_run, dtype, persistent, tracker, cparams
         )
     else:
-        sorted_values = blosc2.open(str(final_run.values_path), mmap_mode=_INDEX_MMAP_MODE)[:]
-        positions = blosc2.open(str(final_run.positions_path), mmap_mode=_INDEX_MMAP_MODE)[:]
+        sorted_values = blosc2.open(str(final_run.values_path), mode="r", mmap_mode=_INDEX_MMAP_MODE)[:]
+        positions = blosc2.open(str(final_run.positions_path), mode="r", mmap_mode=_INDEX_MMAP_MODE)[:]
         values_sidecar = _store_array_sidecar(
             array, token, kind, "full", "values", sorted_values, persistent, cparams=cparams
         )
@@ -3257,14 +3257,14 @@ def iter_index_components(array: blosc2.NDArray, descriptor: dict):
 
 def _component_nbytes(array: blosc2.NDArray, descriptor: dict, component: IndexComponent) -> int:
     if component.path is not None:
-        return int(blosc2.open(component.path, mmap_mode=_INDEX_MMAP_MODE).nbytes)
+        return int(blosc2.open(component.path, mode="r", mmap_mode=_INDEX_MMAP_MODE).nbytes)
     token = descriptor["token"]
     return int(_load_array_sidecar(array, token, component.category, component.name).nbytes)
 
 
 def _component_cbytes(array: blosc2.NDArray, descriptor: dict, component: IndexComponent) -> int:
     if component.path is not None:
-        return int(blosc2.open(component.path, mmap_mode=_INDEX_MMAP_MODE).cbytes)
+        return int(blosc2.open(component.path, mode="r", mmap_mode=_INDEX_MMAP_MODE).cbytes)
     token = descriptor["token"]
     sidecar = _load_array_sidecar(array, token, component.category, component.name)
     kwargs = {}
@@ -3804,8 +3804,8 @@ def compact_index(array: blosc2.NDArray, field: str | None = None, name: str | N
                 array, descriptor, final_run.values_path, final_run.positions_path, final_run.length
             )
         else:
-            sorted_values = blosc2.open(str(final_run.values_path), mmap_mode=_INDEX_MMAP_MODE)[:]
-            positions = blosc2.open(str(final_run.positions_path), mmap_mode=_INDEX_MMAP_MODE)[:]
+            sorted_values = blosc2.open(str(final_run.values_path), mode="r", mmap_mode=_INDEX_MMAP_MODE)[:]
+            positions = blosc2.open(str(final_run.positions_path), mode="r", mmap_mode=_INDEX_MMAP_MODE)[:]
             _replace_full_descriptor(array, descriptor, sorted_values, positions, descriptor["persistent"])
             del sorted_values, positions
             final_run.values_path.unlink(missing_ok=True)
@@ -4859,7 +4859,7 @@ def _bucket_batch_result_dtype(where_x) -> np.dtype:
 
 def _bucket_worker_source(where_x):
     if _supports_block_reads(where_x) and getattr(where_x, "urlpath", None) is not None:
-        return blosc2.open(str(where_x.urlpath), mmap_mode=_INDEX_MMAP_MODE)
+        return blosc2.open(str(where_x.urlpath), mode="r", mmap_mode=_INDEX_MMAP_MODE)
     return where_x
 
 
@@ -4877,7 +4877,7 @@ def _gather_mmap_source(where_x):
     urlpath = str(urlpath)
     handle = _GATHER_MMAP_HANDLES.get(urlpath)
     if handle is None:
-        handle = blosc2.open(urlpath, mmap_mode=_INDEX_MMAP_MODE)
+        handle = blosc2.open(urlpath, mode="r", mmap_mode=_INDEX_MMAP_MODE)
         _GATHER_MMAP_HANDLES[urlpath] = handle
     return handle
 
@@ -5104,17 +5104,17 @@ def process_batch(chunk_ids: np.ndarray) -> tuple[list[tuple[int, np.ndarray]],
         batch_values = (
             values_sidecar
             if bucket.get("values_path") is None
-            else blosc2.open(bucket["values_path"], mmap_mode=_INDEX_MMAP_MODE)
+            else blosc2.open(bucket["values_path"], mode="r", mmap_mode=_INDEX_MMAP_MODE)
         )
         batch_buckets = (
             bucket_sidecar
             if bucket.get("bucket_positions_path") is None
-            else blosc2.open(bucket["bucket_positions_path"], mmap_mode=_INDEX_MMAP_MODE)
+            else blosc2.open(bucket["bucket_positions_path"], mode="r", mmap_mode=_INDEX_MMAP_MODE)
         )
         batch_l2 = (
             l2_sidecar
             if bucket.get("l2_path") is None
-            else blosc2.open(bucket["l2_path"], mmap_mode=_INDEX_MMAP_MODE)
+            else blosc2.open(bucket["l2_path"], mode="r", mmap_mode=_INDEX_MMAP_MODE)
         )
         batch_results = []
         batch_candidate_segments = 0
@@ -5251,9 +5251,9 @@ def _partial_chunk_nav_positions_cython(
     def process_cython_batch(chunk_ids: np.ndarray) -> tuple[np.ndarray, int]:
         if len(chunk_ids) == 0:
             return np.empty(0, dtype=np.int64), 0
-        batch_values = blosc2.open(partial["values_path"], mmap_mode=_INDEX_MMAP_MODE)
-        batch_positions = blosc2.open(partial["positions_path"], mmap_mode=_INDEX_MMAP_MODE)
-        batch_l2 = blosc2.open(partial["l2_path"], mmap_mode=_INDEX_MMAP_MODE)
+        batch_values = blosc2.open(partial["values_path"], mode="r", mmap_mode=_INDEX_MMAP_MODE)
+        batch_positions = blosc2.open(partial["positions_path"], mode="r", mmap_mode=_INDEX_MMAP_MODE)
+        batch_l2 = blosc2.open(partial["l2_path"], mode="r", mmap_mode=_INDEX_MMAP_MODE)
         batch_l2_row = np.empty(nsegments_per_chunk, dtype=l2_boundary_dtype)
         batch_span_values = np.empty(chunk_len, dtype=dtype)
         batch_local_positions = np.empty(chunk_len, dtype=local_position_dtype)
@@ -5300,17 +5300,17 @@ def process_batch(chunk_ids: np.ndarray) -> tuple[list[np.ndarray], int]:
         batch_values = (
             values_sidecar
             if partial.get("values_path") is None
-            else blosc2.open(partial["values_path"], mmap_mode=_INDEX_MMAP_MODE)
+            else blosc2.open(partial["values_path"], mode="r", mmap_mode=_INDEX_MMAP_MODE)
         )
         batch_positions = (
             positions_sidecar
             if partial.get("positions_path") is None
-            else blosc2.open(partial["positions_path"], mmap_mode=_INDEX_MMAP_MODE)
+            else blosc2.open(partial["positions_path"], mode="r", mmap_mode=_INDEX_MMAP_MODE)
         )
         batch_l2 = (
             l2_sidecar
             if partial.get("l2_path") is None
-            else blosc2.open(partial["l2_path"], mmap_mode=_INDEX_MMAP_MODE)
+            else blosc2.open(partial["l2_path"], mode="r", mmap_mode=_INDEX_MMAP_MODE)
         )
         batch_parts = []
         batch_candidate_segments = 0