Skip to content

docs: clarify difference between load and open in docstrings#3984

Open
SAY-5 wants to merge 11 commits into
zarr-developers:mainfrom
SAY-5:docs/document-load-vs-open
Open

docs: clarify difference between load and open in docstrings#3984
SAY-5 wants to merge 11 commits into
zarr-developers:mainfrom
SAY-5:docs/document-load-vs-open

Conversation

@SAY-5

@SAY-5 SAY-5 commented May 19, 2026

Copy link
Copy Markdown

Closes #463. Adds Notes and See Also cross-references to the load and open docstrings explaining that load eagerly reads data into in-memory NumPy arrays while open returns a lazy Array/Group backed by the store, addressing the maintainer's note that "the documentation could definitely be improved here, PR welcome."

TODO:

  • Add unit tests and/or doctests in docstrings
  • Add docstrings and API docs for any new/modified user-facing classes and functions
  • New/modified features documented in docs/user-guide/*.md
  • Changes documented as a new file in changes/
  • GitHub Actions have all passed
  • Test coverage is 100% (Codecov passes)

@codecov

codecov Bot commented May 19, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.50%. Comparing base (e29ddd2) to head (e0fa87d).

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #3984   +/-   ##
=======================================
  Coverage   93.50%   93.50%           
=======================================
  Files          90       90           
  Lines       11981    11981           
=======================================
  Hits        11203    11203           
  Misses        778      778           
Files with missing lines Coverage Δ
src/zarr/api/asynchronous.py 94.05% <ø> (ø)
src/zarr/api/synchronous.py 92.95% <ø> (ø)
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@SAY-5 SAY-5 force-pushed the docs/document-load-vs-open branch from 4a16523 to 25998f0 Compare May 21, 2026 07:00

@maxrjones maxrjones left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this PR, and sorry for the slow review!

I left some comments since the loaded array type is not always NumPy.

Comment thread changes/3984.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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
`load` eagerly reads data into an in-memory NumPy array, while `open` returns a
`load` eagerly reads data into an in-memory array, while `open` returns a

-----
`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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
instead when you want the data eagerly read into an in-memory NumPy array.
instead when you want the data eagerly read into an in-memory array
(a NumPy array by default).

-----
`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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
instead when you want the data eagerly read into an in-memory NumPy array.
instead when you want the data eagerly read into an in-memory array (a
NumPy array by default).


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).

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
returns it as an in-memory NumPy array (or a dict of NumPy arrays for a group).
returns it as an in-memory array (or a dict of arrays for a group).
The array type is NumPy by default, but follows the configured
buffer prototype (for example, CuPy for GPU use cases).


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).

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
returns it as an in-memory NumPy array (or a dict of NumPy arrays for a group).
returns it as an in-memory array (or a dict of arrays for a group).
The array type is NumPy by default, but follows the configured
buffer prototype (for example, CuPy for GPU use cases).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Documenting the difference between load and open

2 participants