doc: tutorial updates for 3.0 #2401

jhamman · 2024-10-18T19:22:01Z

This is a work in progress. Running through the tutorial helped identify a number of issues that we likely want to address before we release 3.0.

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/tutorial.rst
Changes documented in docs/release.rst
GitHub Actions have all passed
Test coverage is 100% (Codecov passes)

jhamman

self review 👇

jhamman · 2024-10-18T19:24:47Z

docs/tutorial.rst

@@ -155,7 +155,7 @@ argument accepted by all array creation functions. For example::
    >>> from numcodecs import Blosc
    >>> compressor = Blosc(cname='zstd', clevel=3, shuffle=Blosc.BITSHUFFLE)
    >>> data = np.arange(100000000, dtype='i4').reshape(10000, 10000)
-    >>> z = zarr.array(data, chunks=(1000, 1000), compressor=compressor)
+    >>> z = zarr.array(data, chunks=(1000, 1000), compressor=compressor, zarr_format=2)


This example works for zarr_format=2 but requires #2398 to work for zarr_format=3

jhamman · 2024-10-18T19:35:20Z

docs/tutorial.rst

@@ -300,32 +300,30 @@ Groups have a similar API to the Group class from `h5py

 Groups can also contain arrays, e.g.::

-    >>> z1 = bar.zeros('baz', shape=(10000, 10000), chunks=(1000, 1000), dtype='i4')
+    >>> z1 = bar.zeros(name='baz', shape=(10000, 10000), chunks=(1000, 1000), dtype='i4')


Suggested change

>>> z1 = bar.zeros(name='baz', shape=(10000, 10000), chunks=(1000, 1000), dtype='i4')

>>> z1 = bar.zeros('baz', shape=(10000, 10000), chunks=(1000, 1000), dtype='i4')

see #2402

jhamman · 2024-10-18T19:35:38Z

docs/tutorial.rst


-    >>> z = bar.create_dataset('quux', shape=(10000, 10000), chunks=(1000, 1000), dtype='i4')
+    >>> z = bar.create_array(name='quux', shape=(10000, 10000), chunks=(1000, 1000), dtype='i4')


Suggested change

>>> z = bar.create_array(name='quux', shape=(10000, 10000), chunks=(1000, 1000), dtype='i4')

>>> z = bar.create_array('quux', shape=(10000, 10000), chunks=(1000, 1000), dtype='i4')

see #2402

jhamman · 2024-10-18T19:36:14Z

docs/tutorial.rst

-    <zarr.hierarchy.Group '/'>
-    >>> z = root.zeros('foo/bar/baz', shape=(10000, 10000), chunks=(1000, 1000), dtype='i4')
+    <Group file://data/group.zarr>
+    >>> z = root.zeros(name='foo/bar/baz', shape=(10000, 10000), chunks=(1000, 1000), dtype='i4')


Suggested change

>>> z = root.zeros(name='foo/bar/baz', shape=(10000, 10000), chunks=(1000, 1000), dtype='i4')

>>> z = root.zeros('foo/bar/baz', shape=(10000, 10000), chunks=(1000, 1000), dtype='i4')

#2402

jhamman · 2024-10-18T19:36:24Z

docs/tutorial.rst

@@ -362,9 +360,9 @@ property. E.g.::

    >>> root = zarr.group()
    >>> foo = root.create_group('foo')
-    >>> bar = foo.zeros('bar', shape=1000000, chunks=100000, dtype='i8')
+    >>> bar = foo.zeros(name='bar', shape=1000000, chunks=100000, dtype='i8')


Suggested change

>>> bar = foo.zeros(name='bar', shape=1000000, chunks=100000, dtype='i8')

>>> bar = foo.zeros('bar', shape=1000000, chunks=100000, dtype='i8')

#2402

jhamman · 2024-10-18T19:36:33Z

docs/tutorial.rst

    >>> bar[:] = 42
-    >>> baz = foo.zeros('baz', shape=(1000, 1000), chunks=(100, 100), dtype='f4')
+    >>> baz = foo.zeros(name='baz', shape=(1000, 1000), chunks=(100, 100), dtype='f4')


Suggested change

>>> baz = foo.zeros(name='baz', shape=(1000, 1000), chunks=(100, 100), dtype='f4')

>>> baz = foo.zeros('baz', shape=(1000, 1000), chunks=(100, 100), dtype='f4')

#2402

jhamman · 2024-10-18T19:36:44Z

docs/tutorial.rst

@@ -440,7 +438,7 @@ storing application-specific metadata. For example::

    >>> root = zarr.group()
    >>> root.attrs['foo'] = 'bar'
-    >>> z = root.zeros('zzz', shape=(10000, 10000))
+    >>> z = root.zeros(name='zzz', shape=(10000, 10000))


Suggested change

>>> z = root.zeros(name='zzz', shape=(10000, 10000))

>>> z = root.zeros('zzz', shape=(10000, 10000))

#2402

jhamman · 2024-10-18T19:37:44Z

docs/tutorial.rst

@@ -1655,9 +1642,9 @@ Datetimes and timedeltas
 NumPy's ``datetime64`` ('M8') and ``timedelta64`` ('m8') dtypes are supported for Zarr
 arrays, as long as the units are specified. E.g.::

-    >>> z = zarr.array(['2007-07-13', '2006-01-13', '2010-08-13'], dtype='M8[D]')
+    >>> z = zarr.array(['2007-07-13', '2006-01-13', '2010-08-13'], dtype='M8[D]', zarr_format=2)


Add note above explaining that datetimes/timedeltas are only supported by v2 data format for now.

dstansby · 2024-10-18T21:06:58Z

Woop woop! In case you don't know about it already, https://github.com/scientific-python/pytest-doctestplus?tab=readme-ov-file#fixing-existing-docstrings might be helpful

…c/tutorial

jhamman · 2024-12-30T02:44:50Z

closing in favor of #2589

doc: tutorial updates for v3

f1ab32a

jhamman commented Oct 18, 2024

View reviewed changes

Merge branch 'main' into doc/tutorial

313ab48

jhamman added 2 commits October 18, 2024 15:28

tidy

edb5bf4

Merge branch 'doc/tutorial' of github.com:jhamman/zarr-python into do…

10f3e67

…c/tutorial

jhamman added the V3 label Nov 29, 2024

dstansby added this to the 3.0.0 milestone Dec 9, 2024

dstansby added documentation Improvements to the documentation and removed V3 labels Dec 12, 2024

jhamman closed this Dec 30, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: tutorial updates for 3.0 #2401

doc: tutorial updates for 3.0 #2401

jhamman commented Oct 18, 2024

jhamman left a comment

jhamman Oct 18, 2024

jhamman Oct 18, 2024

jhamman Oct 18, 2024

jhamman Oct 18, 2024

jhamman Oct 18, 2024

jhamman Oct 18, 2024

jhamman Oct 18, 2024

jhamman Oct 18, 2024

dstansby commented Oct 18, 2024

jhamman commented Dec 30, 2024

	>>> z1 = bar.zeros(name='baz', shape=(10000, 10000), chunks=(1000, 1000), dtype='i4')
	>>> z1 = bar.zeros('baz', shape=(10000, 10000), chunks=(1000, 1000), dtype='i4')


		>>> z = bar.create_dataset('quux', shape=(10000, 10000), chunks=(1000, 1000), dtype='i4')
		>>> z = bar.create_array(name='quux', shape=(10000, 10000), chunks=(1000, 1000), dtype='i4')

	>>> z = bar.create_array(name='quux', shape=(10000, 10000), chunks=(1000, 1000), dtype='i4')
	>>> z = bar.create_array('quux', shape=(10000, 10000), chunks=(1000, 1000), dtype='i4')

	>>> z = root.zeros(name='foo/bar/baz', shape=(10000, 10000), chunks=(1000, 1000), dtype='i4')
	>>> z = root.zeros('foo/bar/baz', shape=(10000, 10000), chunks=(1000, 1000), dtype='i4')

	>>> bar = foo.zeros(name='bar', shape=1000000, chunks=100000, dtype='i8')
	>>> bar = foo.zeros('bar', shape=1000000, chunks=100000, dtype='i8')

	>>> baz = foo.zeros(name='baz', shape=(1000, 1000), chunks=(100, 100), dtype='f4')
	>>> baz = foo.zeros('baz', shape=(1000, 1000), chunks=(100, 100), dtype='f4')

	>>> z = root.zeros(name='zzz', shape=(10000, 10000))
	>>> z = root.zeros('zzz', shape=(10000, 10000))

doc: tutorial updates for 3.0 #2401

doc: tutorial updates for 3.0 #2401

Conversation

jhamman commented Oct 18, 2024

jhamman left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dstansby commented Oct 18, 2024

jhamman commented Dec 30, 2024