From be46f34213b00ba9bd995a8aef8132b8a790a78a Mon Sep 17 00:00:00 2001 From: Sai Asish Y Date: Tue, 19 May 2026 00:20:48 -0700 Subject: [PATCH 1/3] docs: clarify difference between load and open in docstrings --- src/zarr/api/asynchronous.py | 18 +++++++++++++++++- src/zarr/api/synchronous.py | 18 +++++++++++++++++- 2 files changed, 34 insertions(+), 2 deletions(-) diff --git a/src/zarr/api/asynchronous.py b/src/zarr/api/asynchronous.py index 7f185535df..12553b6227 100644 --- a/src/zarr/api/asynchronous.py +++ b/src/zarr/api/asynchronous.py @@ -294,12 +294,18 @@ async def load( See Also -------- - save + save, open Notes ----- If loading data from a group of arrays, data will not be immediately loaded into memory. Rather, arrays will be loaded into memory as they are requested. + + Unlike [`open`][zarr.open], which returns a lazy [`Array`][zarr.Array] or + [`Group`][zarr.Group] backed by the store, `load` eagerly reads the data and + returns it as an in-memory NumPy array (or a dict of NumPy arrays for a group). + Use `open` when you want to read or write data incrementally without loading it + all into memory. """ obj = await open(store=store, path=path, zarr_format=zarr_format) @@ -347,6 +353,16 @@ async def open( ------- z : array or group Return type depends on what exists in the given store. + + See Also + -------- + load + + Notes + ----- + `open` returns a lazy [`Array`][zarr.Array] or [`Group`][zarr.Group] backed by + the store, so data is read and written incrementally. Use [`load`][zarr.load] + instead when you want the data eagerly read into an in-memory NumPy array. """ if mode is None: diff --git a/src/zarr/api/synchronous.py b/src/zarr/api/synchronous.py index 97d460a183..aa1fc9d563 100644 --- a/src/zarr/api/synchronous.py +++ b/src/zarr/api/synchronous.py @@ -161,12 +161,18 @@ def load( See Also -------- - save, savez + save, savez, open Notes ----- If loading data from a group of arrays, data will not be immediately loaded into memory. Rather, arrays will be loaded into memory as they are requested. + + Unlike [`open`][zarr.open], which returns a lazy [`Array`][zarr.Array] or + [`Group`][zarr.Group] backed by the store, `load` eagerly reads the data and + returns it as an in-memory NumPy array (or a dict of NumPy arrays for a group). + Use `open` when you want to read or write data incrementally without loading it + all into memory. """ return sync(async_api.load(store=store, zarr_format=zarr_format, path=path)) @@ -209,6 +215,16 @@ def open( ------- z : array or group Return type depends on what exists in the given store. + + See Also + -------- + load + + Notes + ----- + `open` returns a lazy [`Array`][zarr.Array] or [`Group`][zarr.Group] backed by + the store, so data is read and written incrementally. Use [`load`][zarr.load] + instead when you want the data eagerly read into an in-memory NumPy array. """ obj = sync( async_api.open( From 8a0b4dbf2538f221fded84be6ba7cac0599ac6e0 Mon Sep 17 00:00:00 2001 From: Sai Asish Y Date: Tue, 19 May 2026 00:21:28 -0700 Subject: [PATCH 2/3] docs: add changelog entry for load/open clarification --- changes/3983.doc.md | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 changes/3983.doc.md diff --git a/changes/3983.doc.md b/changes/3983.doc.md new file mode 100644 index 0000000000..cbf3e3b22d --- /dev/null +++ b/changes/3983.doc.md @@ -0,0 +1,4 @@ +Clarify the difference between `zarr.load` and `zarr.open` in their docstrings. +`load` eagerly reads data into an in-memory NumPy array, while `open` returns a +lazy `Array` or `Group` backed by the store, with `See Also` cross-references +linking the two. From 25998f0a7080900b49fcb891f52f9a1b102ab738 Mon Sep 17 00:00:00 2001 From: Sai Asish Y Date: Tue, 19 May 2026 00:21:45 -0700 Subject: [PATCH 3/3] docs: rename changelog entry to match PR number --- changes/{3983.doc.md => 3984.doc.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename changes/{3983.doc.md => 3984.doc.md} (100%) diff --git a/changes/3983.doc.md b/changes/3984.doc.md similarity index 100% rename from changes/3983.doc.md rename to changes/3984.doc.md