make docstring code examples executible, and fix errors

Author: d-v-b

src/zarr/api/synchronous.py

@@ -946,15 +946,17 @@ def create_array(
 
     Examples
     --------
-    >>> import zarr
-    >>> store = zarr.storage.MemoryStore()
-    >>> arr = await zarr.create_array(
-    >>>     store=store,
-    >>>     shape=(100,100),
-    >>>     chunks=(10,10),
-    >>>     dtype='i4',
-    >>>     fill_value=0)
-    <Array memory://140349042942400 shape=(100, 100) dtype=int32>
+    ```python
+    import zarr
+    store = zarr.storage.MemoryStore()
+    arr = zarr.create_array(
+        store=store,
+        shape=(100,100),
+        chunks=(10,10),
+        dtype='i4',
+        fill_value=0)
+    # <Array memory://... shape=(100, 100) dtype=int32>
+    ```
     """
     return Array(
         sync(
@@ -1132,49 +1134,64 @@ def from_array(
 
     Examples
     --------
-    Create an array from an existing Array::
-
-        >>> import zarr
-        >>> store = zarr.storage.MemoryStore()
-        >>> store2 = zarr.storage.LocalStore('example.zarr')
-        >>> arr = zarr.create_array(
-        >>>     store=store,
-        >>>     shape=(100,100),
-        >>>     chunks=(10,10),
-        >>>     dtype='int32',
-        >>>     fill_value=0)
-        >>> arr2 = zarr.from_array(store2, data=arr)
-        <Array file://example.zarr shape=(100, 100) dtype=int32>
-
-    Create an array from an existing NumPy array::
-
-        >>> import numpy as np
-        >>> arr3 = zarr.from_array(
-                zarr.storage.MemoryStore(),
-        >>>     data=np.arange(10000, dtype='i4').reshape(100, 100),
-        >>> )
-        <Array memory://125477403529984 shape=(100, 100) dtype=int32>
-
-    Create an array from any array-like object::
-
-        >>> arr4 = zarr.from_array(
-        >>>     zarr.storage.MemoryStore(),
-        >>>     data=[[1, 2], [3, 4]],
-        >>> )
-        <Array memory://125477392154368 shape=(2, 2) dtype=int64>
-        >>> arr4[...]
-        array([[1, 2],[3, 4]])
-
-    Create an array from an existing Array without copying the data::
-
-        >>> arr5 = zarr.from_array(
-        >>>     zarr.storage.MemoryStore(),
-        >>>     data=arr4,
-        >>>     write_data=False,
-        >>> )
-        <Array memory://140678602965568 shape=(2, 2) dtype=int64>
-        >>> arr5[...]
-        array([[0, 0],[0, 0]])
+    Create an array from an existing Array:
+
+    ```python
+    import zarr
+    store = zarr.storage.MemoryStore()
+    store2 = zarr.storage.LocalStore('example_from_array.zarr')
+    arr = zarr.create_array(
+        store=store,
+        shape=(100,100),
+        chunks=(10,10),
+        dtype='int32',
+        fill_value=0)
+    arr2 = zarr.from_array(store2, data=arr, overwrite=True)
+    # <Array file://example_from_array.zarr shape=(100, 100) dtype=int32>
+    ```
+
+    Create an array from an existing NumPy array:
+
+    ```python
+    import zarr
+    import numpy as np
+    arr3 = zarr.from_array(
+            zarr.storage.MemoryStore(),
+        data=np.arange(10000, dtype='i4').reshape(100, 100),
+    )
+    # <Array memory://... shape=(100, 100) dtype=int32>
+    ```
+
+    Create an array from any array-like object:
+
+    ```python
+    import zarr
+    arr4 = zarr.from_array(
+        zarr.storage.MemoryStore(),
+        data=[[1, 2], [3, 4]],
+    )
+    # <Array memory://... shape=(2, 2) dtype=int64>
+    arr4[...]
+    # array([[1, 2],[3, 4]])
+    ```
+
+    Create an array from an existing Array without copying the data:
+
+    ```python
+    import zarr
+    arr4 = zarr.from_array(
+        zarr.storage.MemoryStore(),
+        data=[[1, 2], [3, 4]],
+    )
+    arr5 = zarr.from_array(
+        zarr.storage.MemoryStore(),
+        data=arr4,
+        write_data=False,
+    )
+    # <Array memory://... shape=(2, 2) dtype=int64>
+    arr5[...]
+    # array([[0, 0],[0, 0]])
+    ```
     """
     return Array(
         sync(

src/zarr/codecs/numcodecs/_codecs.py

@@ -3,18 +3,21 @@
 
 These codecs were previously defined in [numcodecs][], and have now been moved to `zarr`.
 
->>> import numpy as np
->>> import zarr
->>> import zarr.codecs.numcodecs as numcodecs
->>>
->>> array = zarr.create_array(
-...   store="data.zarr",
-...   shape=(1024, 1024),
-...   chunks=(64, 64),
-...   dtype="uint32",
-...   filters=[numcodecs.Delta(dtype="uint32")],
-...   compressors=[numcodecs.BZ2(level=5)])
->>> array[:] = np.arange(np.prod(array.shape), dtype=array.dtype).reshape(*array.shape)
+```python
+import numpy as np
+import zarr
+import zarr.codecs.numcodecs as numcodecs
+
+array = zarr.create_array(
+  store="data_numcodecs.zarr",
+  shape=(1024, 1024),
+  chunks=(64, 64),
+  dtype="uint32",
+  filters=[numcodecs.Delta(dtype="uint32")],
+  compressors=[numcodecs.BZ2(level=5)],
+  overwrite=True)
+array[:] = np.arange(np.prod(array.shape), dtype=array.dtype).reshape(*array.shape)
+```
 
 !!! note
     Please note that the codecs in [zarr.codecs.numcodecs][] are not part of the Zarr version

src/zarr/core/array.py

@@ -982,10 +982,22 @@ async def open(
 
         Examples
         --------
-        >>> import zarr
-        >>>  store = zarr.storage.MemoryStore()
-        >>>  async_arr = await AsyncArray.open(store) # doctest: +ELLIPSIS
-        <AsyncArray memory://... shape=(100, 100) dtype=int32>
+        ```python
+        import zarr
+
+        async def example():
+            store = zarr.storage.MemoryStore()
+            # First create an array to open
+            await zarr.api.asynchronous.create_array(
+                store=store, shape=(100, 100), dtype="int32"
+            )
+            # Now open it
+            async_arr = await AsyncArray.open(store)
+            return async_arr
+
+        # async_arr = await example()
+        # AsyncArray(...)
+        ```
         """
         store_path = await make_store_path(store)
         metadata_dict = await get_array_metadata(store_path, zarr_format=zarr_format)
@@ -1300,12 +1312,20 @@ async def nchunks_initialized(self) -> int:
 
         Examples
         --------
-        >>> arr = await zarr.api.asynchronous.create(shape=(10,), chunks=(1,), shards=(2,))
-        >>> await arr.nchunks_initialized()
-        0
-        >>> await arr.setitem(slice(5), 1)
-        >>> await arr.nchunks_initialized()
-        6
+        ```python
+        import zarr.api.asynchronous
+
+        async def example():
+            arr = await zarr.api.asynchronous.create(shape=(10,), chunks=(1,), shards=(2,))
+            count = await arr.nchunks_initialized()
+            # 0
+            await arr.setitem(slice(5), 1)
+            count = await arr.nchunks_initialized()
+            # 6
+            return count
+
+        # result = await example()
+        ```
         """
         if self.shards is None:
             chunks_per_shard = 1
@@ -1333,12 +1353,20 @@ async def _nshards_initialized(self) -> int:
 
         Examples
         --------
-        >>> arr = await zarr.api.asynchronous.create(shape=(10,), chunks=(2,))
-        >>> await arr._nshards_initialized()
-        0
-        >>> await arr.setitem(slice(5), 1)
-        >>> await arr._nshards_initialized()
-        3
+        ```python
+        import zarr.api.asynchronous
+
+        async def example():
+            arr = await zarr.api.asynchronous.create(shape=(10,), chunks=(2,))
+            count = await arr._nshards_initialized()
+            # 0
+            await arr.setitem(slice(5), 1)
+            count = await arr._nshards_initialized()
+            # 3
+            return count
+
+        # result = await example()
+        ```
         """
         return len(await _shards_initialized(self))
 
@@ -1566,18 +1594,23 @@ async def getitem(
 
         Examples
         --------
-        >>> import zarr
-        >>>  store = zarr.storage.MemoryStore()
-        >>>  async_arr = await zarr.api.asynchronous.create_array(
-        ...      store=store,
-        ...      shape=(100,100),
-        ...      chunks=(10,10),
-        ...      dtype='i4',
-        ...      fill_value=0)
-        <AsyncArray memory://... shape=(100, 100) dtype=int32>
-        >>> await async_arr.getitem((0,1)) # doctest: +ELLIPSIS
-        array(0, dtype=int32)
-
+        ```python
+        import zarr.api.asynchronous
+
+        async def example():
+            store = zarr.storage.MemoryStore()
+            async_arr = await zarr.api.asynchronous.create_array(
+                 store=store,
+                 shape=(100,100),
+                 chunks=(10,10),
+                 dtype='i4',
+                 fill_value=0)
+            result = await async_arr.getitem((0,1))
+            # array(0, dtype=int32)
+            return result
+
+        # value = await example()
+        ```
         """
         if prototype is None:
             prototype = default_buffer_prototype()

src/zarr/core/dtype/__init__.py

@@ -213,14 +213,16 @@ def parse_data_type(
 
     Examples
     --------
-    >>> from zarr.dtype import parse_data_type
-    >>> import numpy as np
-    >>> parse_data_type("int32", zarr_format=2)
-    Int32(endianness='little')
-    >>> parse_data_type(np.dtype('S10'), zarr_format=2)
-    NullTerminatedBytes(length=10)
-    >>> parse_data_type({"name": "numpy.datetime64", "configuration": {"unit": "s", "scale_factor": 10}}, zarr_format=3)
-    DateTime64(endianness='little', scale_factor=10, unit='s')
+    ```python
+    from zarr.dtype import parse_data_type
+    import numpy as np
+    parse_data_type("int32", zarr_format=2)
+    # Int32(endianness='little')
+    parse_data_type(np.dtype('S10'), zarr_format=2)
+    # NullTerminatedBytes(length=10)
+    parse_data_type({"name": "numpy.datetime64", "configuration": {"unit": "s", "scale_factor": 10}}, zarr_format=3)
+    # DateTime64(endianness='little', scale_factor=10, unit='s')
+    ```
     """
     return parse_dtype(dtype_spec, zarr_format=zarr_format)
 
@@ -251,14 +253,16 @@ def parse_dtype(
 
     Examples
     --------
-    >>> from zarr.dtype import parse_dtype
-    >>> import numpy as np
-    >>> parse_dtype("int32", zarr_format=2)
-    Int32(endianness='little')
-    >>> parse_dtype(np.dtype('S10'), zarr_format=2)
-    NullTerminatedBytes(length=10)
-    >>> parse_dtype({"name": "numpy.datetime64", "configuration": {"unit": "s", "scale_factor": 10}}, zarr_format=3)
-    DateTime64(endianness='little', scale_factor=10, unit='s')
+    ```python
+    from zarr.dtype import parse_dtype
+    import numpy as np
+    parse_dtype("int32", zarr_format=2)
+    # Int32(endianness='little')
+    parse_dtype(np.dtype('S10'), zarr_format=2)
+    # NullTerminatedBytes(length=10)
+    parse_dtype({"name": "numpy.datetime64", "configuration": {"unit": "s", "scale_factor": 10}}, zarr_format=3)
+    # DateTime64(endianness='little', scale_factor=10, unit='s')
+    ```
     """
     if isinstance(dtype_spec, ZDType):
         return dtype_spec