Description
Zarr version
3.0.6
Numcodecs version
0.15.0
Python Version
3.11
Operating System
Linux
Installation
pip
Description
The Group.create_hierarchy function returns a generator that lazily creates nodes in the Zarr hierarchy, but the docstring incorrectly implies immediate creation.
The generator must be consumed (at least partially, e.g., via next()) to trigger node creation.
Expected Fix:
Update the docstring, or adjust behaviour of method.
** Expected Docstring Content**:
Explicitly state that the function returns a generator requiring consumption.
Clarify that nodes are only created when the generator is iterated over (fully or partially).
Include examples of both full (dict()) and partial (next()) consumption.
Current Behavior:
Misleading documentation suggests immediate creation, which could lead to incorrect assumptions about side effects.
Steps to reproduce
import zarr
from zarr.core.group import GroupMetadata
root = zarr.create_group(store={})
unconsumed_generator = root.create_hierarchy({'a/b/c': GroupMetadata(), 'd': GroupMetadata()})
# This will throw a "FileNotFoundError: a/b", as it is not yet generated. See also root.tree()
root["a"]
root["a/b"]
# consume just the first item
next(root)
# These now work and are all generated. See also root.tree()
root["a"]
root["a/b"]
root["d"]
Additional output
No response