Group.create_hierarchy should clarify or avoid lazy evaluation behavior

[FabricioArendTorres]

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

[d-v-b]

thank you for using this feature! and sorry I messed up the docstring. it is designed to be a generator, so I need to update the docstring to say so.

[FabricioArendTorres]

Thanks - When reading the docstring exactly it makes sense, but it is very easy to miss and a bit confusing to catch what happens.
Might be worth it to "over-explain" in the docstring.