Add some numpydoc validation checks

Author: dstansby

.pre-commit-config.yaml

@@ -9,9 +9,9 @@ repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.6.9
     hooks:
-    - id: ruff
-      args: ["--fix", "--show-fixes"]
-    - id: ruff-format
+      - id: ruff
+        args: ["--fix", "--show-fixes"]
+      - id: ruff-format
   - repo: https://github.com/codespell-project/codespell
     rev: v2.3.0
     hooks:
@@ -20,7 +20,7 @@ repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v5.0.0
     hooks:
-    - id: check-yaml
+      - id: check-yaml
   - repo: https://github.com/pre-commit/mirrors-mypy
     rev: v1.11.2
     hooks:
@@ -49,3 +49,7 @@ repos:
     hooks:
       - id: rst-directive-colons
       - id: rst-inline-touching-normal
+  - repo: https://github.com/numpy/numpydoc
+    rev: v1.8.0
+    hooks:
+      - id: numpydoc-validation

pyproject.toml

@@ -7,9 +7,7 @@ build-backend = "hatchling.build"
 name = "zarr"
 description = "An implementation of chunked, compressed, N-dimensional arrays for Python"
 readme = { file = "README.md", content-type = "text/markdown" }
-authors = [
-    { name = "Alistair Miles", email = "[email protected]" },
-]
+authors = [{ name = "Alistair Miles", email = "[email protected]" }]
 maintainers = [
     { name = "Davis Bennett", email = "[email protected]" },
     { name = "jakirkham" },
@@ -18,7 +16,7 @@ maintainers = [
     { name = "Juan Nunez-Iglesias", email = "[email protected]" },
     { name = "Martin Durant", email = "[email protected]" },
     { name = "Norman Rzepka" },
-    { name = "Ryan Abernathey" }
+    { name = "Ryan Abernathey" },
 ]
 requires-python = ">=3.11"
 # If you add a new dependency here, please also add it to .pre-commit-config.yml
@@ -32,9 +30,7 @@ dependencies = [
     'typing_extensions',
     'donfig',
 ]
-dynamic = [
-  "version",
-]
+dynamic = ["version"]
 classifiers = [
     'Development Status :: 6 - Mature',
     'Intended Audience :: Developers',
@@ -48,7 +44,7 @@ classifiers = [
     'Programming Language :: Python :: 3.11',
     'Programming Language :: Python :: 3.12',
 ]
-license = {text = "MIT License"}
+license = { text = "MIT License" }
 keywords = ["Python", "compressed", "ndimensional-arrays", "zarr"]
 
 [project.optional-dependencies]
@@ -69,14 +65,8 @@ test = [
     "universal-pathlib",
 ]
 
-jupyter = [
-    'notebook',
-    'ipytree>=0.2.2',
-    'ipywidgets>=8.0.0',
-]
-gpu = [
-    "cupy-cuda12x",
-]
+jupyter = ['notebook', 'ipytree>=0.2.2', 'ipywidgets>=8.0.0']
+gpu = ["cupy-cuda12x"]
 docs = [
     'sphinx==8.0.2',
     'sphinx-autobuild>=2021.3.14',
@@ -90,13 +80,8 @@ docs = [
     'msgpack',
     'lmdb',
 ]
-extra = [
-    'msgpack',
-]
-optional = [
-    'lmdb',
-    'universal-pathlib',
-]
+extra = ['msgpack']
+optional = ['lmdb', 'universal-pathlib']
 
 [project.urls]
 "Bug Tracker" = "https://github.com/zarr-developers/zarr-python/issues"
@@ -106,26 +91,17 @@ Documentation = "https://zarr.readthedocs.io/"
 Homepage = "https://github.com/zarr-developers/zarr-python"
 
 [tool.coverage.report]
-exclude_lines = [
-    "pragma: no cover",
-    "pragma: ${PY_MAJOR_VERSION} no cover",
-]
+exclude_lines = ["pragma: no cover", "pragma: ${PY_MAJOR_VERSION} no cover"]
 
 [tool.coverage.run]
-omit = [
-    "src/zarr/meta_v1.py",
-    "bench/compress_normal.py",
-]
+omit = ["src/zarr/meta_v1.py", "bench/compress_normal.py"]
 
 [tool.hatch]
 version.source = "vcs"
 build.hooks.vcs.version-file = "src/zarr/_version.py"
 
 [tool.hatch.envs.test]
-dependencies = [
-    "numpy~={matrix:numpy}",
-    "universal_pathlib",
-]
+dependencies = ["numpy~={matrix:numpy}", "universal_pathlib"]
 features = ["test", "extra"]
 
 [[tool.hatch.envs.test.matrix]]
@@ -153,10 +129,7 @@ run-hypothesis = "pytest --hypothesis-profile ci tests/v3/test_properties.py tes
 list-env = "pip list"
 
 [tool.hatch.envs.gputest]
-dependencies = [
-    "numpy~={matrix:numpy}",
-    "universal_pathlib",
-]
+dependencies = ["numpy~={matrix:numpy}", "universal_pathlib"]
 features = ["test", "extra", "gpu"]
 
 [[tool.hatch.envs.gputest.matrix]]
@@ -197,7 +170,7 @@ extend-exclude = [
     "buck-out",
     "build",
     "dist",
-    "notebooks", # temporary, until we achieve compatibility with ruff ≥ 0.6
+    "notebooks",      # temporary, until we achieve compatibility with ruff ≥ 0.6
     "venv",
     "docs",
     "src/zarr/v2/",
@@ -267,9 +240,7 @@ warn_unreachable = true
 enable_error_code = ["ignore-without-code", "redundant-expr", "truthy-bool"]
 
 [[tool.mypy.overrides]]
-module = [
-    "zarr.v2.*",
-]
+module = ["zarr.v2.*"]
 ignore_errors = true
 
 [[tool.mypy.overrides]]
@@ -300,22 +271,22 @@ doctest_optionflags = [
     "ELLIPSIS",
     "IGNORE_EXCEPTION_DETAIL",
 ]
-addopts = [
-    "--durations=10", "-ra", "--strict-config", "--strict-markers",
-]
+addopts = ["--durations=10", "-ra", "--strict-config", "--strict-markers"]
 filterwarnings = [
     "error:::zarr.*",
     "ignore:PY_SSIZE_T_CLEAN will be required.*:DeprecationWarning",
     "ignore:The loop argument is deprecated since Python 3.8.*:DeprecationWarning",
     "ignore:Creating a zarr.buffer.gpu.*:UserWarning",
-    "ignore:Duplicate name:UserWarning",  # from ZipFile
-]
-markers = [
-    "gpu: mark a test as requiring CuPy and GPU"
+    "ignore:Duplicate name:UserWarning",                                            # from ZipFile
 ]
+markers = ["gpu: mark a test as requiring CuPy and GPU"]
 
 [tool.repo-review]
 ignore = [
-	"PC111",  # fix Python code in documentation - enable later
-	"PC180",  # for JavaScript - not interested
+    "PC111", # fix Python code in documentation - enable later
+    "PC180", # for JavaScript - not interested
 ]
+
+[tool.numpydoc_validation]
+# See https://numpydoc.readthedocs.io/en/latest/validation.html#built-in-validation-checks for list of checks
+checks = ["GL06", "GL07", "GL10", "PR03", "PR05", "PR06"]

src/zarr/api/asynchronous.py

@@ -159,7 +159,7 @@ async def load(
 
     Parameters
     ----------
-    store : Store or string
+    store : Store or str
         Store or path to directory in file system or name of zip file.
     path : str or None, optional
         The path within the store from which to load.
@@ -203,7 +203,7 @@ async def open(
 
     Parameters
     ----------
-    store : Store or string, optional
+    store : Store or str, optional
         Store or path to directory in file system or name of zip file.
     mode : {'r', 'r+', 'a', 'w', 'w-'}, optional
         Persistence mode: 'r' means read only (must exist); 'r+' means
@@ -267,7 +267,7 @@ async def save(
 
     Parameters
     ----------
-    store : Store or string
+    store : Store or str
         Store or path to directory in file system or name of zip file.
     args : ndarray
         NumPy arrays with data to save.
@@ -303,7 +303,7 @@ async def save_array(
 
     Parameters
     ----------
-    store : Store or string
+    store : Store or str
         Store or path to directory in file system or name of zip file.
     arr : ndarray
         NumPy array with data to save.
@@ -351,7 +351,7 @@ async def save_group(
 
     Parameters
     ----------
-    store : Store or string
+    store : Store or str
         Store or path to directory in file system or name of zip file.
     args : ndarray
         NumPy arrays with data to save.
@@ -467,7 +467,7 @@ async def group(
 
     Parameters
     ----------
-    store : Store or string, optional
+    store : Store or str, optional
         Store or path to directory in file system.
     overwrite : bool, optional
         If True, delete any pre-existing data in `store` at `path` before
@@ -481,7 +481,7 @@ async def group(
         to all attribute read operations.
     synchronizer : object, optional
         Array synchronizer.
-    path : string, optional
+    path : str, optional
         Group path within store.
     meta_array : array-like, optional
         An array instance to use for determining arrays to create and return
@@ -547,7 +547,7 @@ async def open_group(
 
     Parameters
     ----------
-    store : Store, string, or mapping, optional
+    store : Store, str, or mapping, optional
         Store or path to directory in file system or name of zip file.
 
         Strings are interpreted as paths on the local file system
@@ -570,9 +570,9 @@ async def open_group(
         to all attribute read operations.
     synchronizer : object, optional
         Array synchronizer.
-    path : string, optional
+    path : str, optional
         Group path within store.
-    chunk_store : Store or string, optional
+    chunk_store : Store or str, optional
         Store or path to directory in file system or name of zip file.
     storage_options : dict
         If using an fsspec URL to create the store, these will be passed to
@@ -664,22 +664,22 @@ async def create(
         False, will be set to `shape`, i.e., single chunk for the whole array.
         If an int, the chunk size in each dimension will be given by the value
         of `chunks`. Default is True.
-    dtype : string or dtype, optional
+    dtype : str or dtype, optional
         NumPy dtype.
     compressor : Codec, optional
         Primary compressor.
     fill_value : object
         Default value to use for uninitialized portions of the array.
     order : {'C', 'F'}, optional
         Memory layout to be used within each chunk.
-    store : Store or string
+    store : Store or str
         Store or path to directory in file system or name of zip file.
     synchronizer : object, optional
         Array synchronizer.
     overwrite : bool, optional
         If True, delete all pre-existing data in `store` at `path` before
         creating the array.
-    path : string, optional
+    path : str, optional
         Path under which array is stored.
     chunk_store : MutableMapping, optional
         Separate storage for chunks. If not provided, `store` will be used
@@ -937,11 +937,11 @@ async def open_array(
 
     Parameters
     ----------
-    store : Store or string
+    store : Store or str
         Store or path to directory in file system or name of zip file.
     zarr_format : {2, 3, None}, optional
         The zarr format to use when saving.
-    path : string, optional
+    path : str, optional
         Path in store to array.
     storage_options : dict
         If using an fsspec URL to create the store, these will be passed to

src/zarr/core/array.py

@@ -1288,11 +1288,11 @@ def get_basic_selection(
             array. May be any combination of int and/or slice or ellipsis for multidimensional arrays.
         out : NDBuffer, optional
             If given, load the selected data directly into this buffer.
+        prototype : BufferPrototype, optional
+            The prototype of the buffer to use for the output data. If not provided, the default buffer prototype is used.
         fields : str or sequence of str, optional
             For arrays with a structured dtype, one or more fields can be specified to
             extract data for.
-        prototype : BufferPrototype, optional
-            The prototype of the buffer to use for the output data. If not provided, the default buffer prototype is used.
 
         Returns
         -------
@@ -2284,6 +2284,17 @@ def resize(self, new_shape: ChunkCoords) -> Array:
         This method does not modify the original Array object. Instead, it returns a new Array
         with the specified shape.
 
+        Notes
+        -----
+        When resizing an array, the data are not rearranged in any way.
+
+        If one or more dimensions are shrunk, any chunks falling outside the
+        new array shape will be deleted from the underlying store.
+        However, it is noteworthy that the chunks partially falling inside the new array
+        (i.e. boundary chunks) will remain intact, and therefore,
+        the data falling outside the new array but inside the boundary chunks
+        would be restored by a subsequent resize operation that grows the array size.
+
         Examples
         --------
         >>> import zarr
@@ -2301,17 +2312,6 @@ def resize(self, new_shape: ChunkCoords) -> Array:
         (20000, 1000)
         >>> z2.shape
         (50, 50)
-
-        Notes
-        -----
-        When resizing an array, the data are not rearranged in any way.
-
-        If one or more dimensions are shrunk, any chunks falling outside the
-        new array shape will be deleted from the underlying store.
-        However, it is noteworthy that the chunks partially falling inside the new array
-        (i.e. boundary chunks) will remain intact, and therefore,
-        the data falling outside the new array but inside the boundary chunks
-        would be restored by a subsequent resize operation that grows the array size.
         """
         return type(self)(
             sync(