diff --git a/.gitignore b/.gitignore index 7d32026e13..35957f2c99 100644 --- a/.gitignore +++ b/.gitignore @@ -51,7 +51,6 @@ coverage.xml # Sphinx documentation docs/_build/ -docs/_autoapi/ # PyBuilder target/ diff --git a/docs/api.rst b/docs/api.rst deleted file mode 100644 index 2b6e7ea516..0000000000 --- a/docs/api.rst +++ /dev/null @@ -1,22 +0,0 @@ -API reference -============= - -.. toctree:: - :maxdepth: 3 - - api/creation - api/core - api/hierarchy - api/storage - api/n5 - api/convenience - api/codecs - api/attrs - api/sync - -Indices and tables ------------------- - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/api/attrs.rst b/docs/api/attrs.rst deleted file mode 100644 index 067b45fac6..0000000000 --- a/docs/api/attrs.rst +++ /dev/null @@ -1,16 +0,0 @@ -The Attributes class (``zarr.v2.attrs``) -======================================== -.. module:: zarr.v2.attrs - -.. autoclass:: Attributes - - .. automethod:: __getitem__ - .. automethod:: __setitem__ - .. automethod:: __delitem__ - .. automethod:: __iter__ - .. automethod:: __len__ - .. automethod:: keys - .. automethod:: asdict - .. automethod:: put - .. automethod:: update - .. automethod:: refresh diff --git a/docs/api/codecs.rst b/docs/api/codecs.rst deleted file mode 100644 index 454c5ccd20..0000000000 --- a/docs/api/codecs.rst +++ /dev/null @@ -1,23 +0,0 @@ -Compressors and filters (``zarr.v2.codecs``) -============================================ -.. module:: zarr.codecs - -This module contains compressor and filter classes for use with Zarr. Please note that this module -is provided for backwards compatibility with previous versions of Zarr. From Zarr version 2.2 -onwards, all codec classes have been moved to a separate package called Numcodecs_. The two -packages (Zarr and Numcodecs_) are designed to be used together. For example, a Numcodecs_ codec -class can be used as a compressor for a Zarr array:: - - >>> import zarr.v2 - >>> from numcodecs import Blosc - >>> z = zarr.v2.zeros(1000000, compressor=Blosc(cname='zstd', clevel=1, shuffle=Blosc.SHUFFLE)) - -Codec classes can also be used as filters. See the tutorial section on :ref:`tutorial_filters` -for more information. - -Please note that it is also relatively straightforward to define and register custom codec -classes. See the Numcodecs `codec API `_ and -`codec registry `_ documentation for more -information. - -.. _Numcodecs: https://numcodecs.readthedocs.io/ diff --git a/docs/api/convenience.rst b/docs/api/convenience.rst deleted file mode 100644 index 1ff26452fa..0000000000 --- a/docs/api/convenience.rst +++ /dev/null @@ -1,14 +0,0 @@ -Convenience functions (``zarr.v2.convenience``) -=============================================== -.. automodule:: zarr.v2.convenience -.. autofunction:: open -.. autofunction:: save -.. autofunction:: load -.. autofunction:: save_array -.. autofunction:: save_group -.. autofunction:: copy -.. autofunction:: copy_all -.. autofunction:: copy_store -.. autofunction:: tree -.. autofunction:: consolidate_metadata -.. autofunction:: open_consolidated diff --git a/docs/api/core.rst b/docs/api/core.rst deleted file mode 100644 index aacd03e2a5..0000000000 --- a/docs/api/core.rst +++ /dev/null @@ -1,5 +0,0 @@ -The Array class (``zarr.v2.core``) -================================== - -.. automodapi:: zarr.v2.core - :no-heading: diff --git a/docs/api/creation.rst b/docs/api/creation.rst deleted file mode 100644 index ad0a2ead49..0000000000 --- a/docs/api/creation.rst +++ /dev/null @@ -1,15 +0,0 @@ -Array creation (``zarr.v2.creation``) -===================================== -.. module:: zarr.v2.creation -.. autofunction:: create -.. autofunction:: empty -.. autofunction:: zeros -.. autofunction:: ones -.. autofunction:: full -.. autofunction:: array -.. autofunction:: open_array -.. autofunction:: empty_like -.. autofunction:: zeros_like -.. autofunction:: ones_like -.. autofunction:: full_like -.. autofunction:: open_like diff --git a/docs/api/hierarchy.rst b/docs/api/hierarchy.rst deleted file mode 100644 index 5d9280af1e..0000000000 --- a/docs/api/hierarchy.rst +++ /dev/null @@ -1,41 +0,0 @@ -Groups (``zarr.v2.hierarchy``) -============================== -.. module:: zarr.v2.hierarchy - -.. autofunction:: group -.. autofunction:: open_group - -.. autoclass:: Group - - .. automethod:: __len__ - .. automethod:: __iter__ - .. automethod:: __contains__ - .. automethod:: __getitem__ - .. automethod:: __enter__ - .. automethod:: __exit__ - .. automethod:: group_keys - .. automethod:: groups - .. automethod:: array_keys - .. automethod:: arrays - .. automethod:: visit - .. automethod:: visitkeys - .. automethod:: visitvalues - .. automethod:: visititems - .. automethod:: tree - .. automethod:: create_group - .. automethod:: require_group - .. automethod:: create_groups - .. automethod:: require_groups - .. automethod:: create_dataset - .. automethod:: require_dataset - .. automethod:: create - .. automethod:: empty - .. automethod:: zeros - .. automethod:: ones - .. automethod:: full - .. automethod:: array - .. automethod:: empty_like - .. automethod:: zeros_like - .. automethod:: ones_like - .. automethod:: full_like - .. automethod:: move diff --git a/docs/api/index.rst b/docs/api/index.rst new file mode 100644 index 0000000000..58ea531905 --- /dev/null +++ b/docs/api/index.rst @@ -0,0 +1,7 @@ +API Reference +============= + +.. toctree:: + :maxdepth: 1 + + zarr diff --git a/docs/api/n5.rst b/docs/api/n5.rst deleted file mode 100644 index 22e490bad4..0000000000 --- a/docs/api/n5.rst +++ /dev/null @@ -1,5 +0,0 @@ -N5 (``zarr.v2.n5``) -=================== -.. automodule:: zarr.v2.n5 - -.. autoclass:: N5Store diff --git a/docs/api/storage.rst b/docs/api/storage.rst deleted file mode 100644 index d0ebd8a429..0000000000 --- a/docs/api/storage.rst +++ /dev/null @@ -1,50 +0,0 @@ -Storage (``zarr.v2.storage``) -============================= -.. automodule:: zarr.v2.storage - -.. autoclass:: MemoryStore -.. autoclass:: DirectoryStore -.. autoclass:: TempStore -.. autoclass:: NestedDirectoryStore -.. autoclass:: ZipStore - - .. automethod:: close - .. automethod:: flush - -.. autoclass:: DBMStore - - .. automethod:: close - .. automethod:: flush - -.. autoclass:: LMDBStore - - .. automethod:: close - .. automethod:: flush - -.. autoclass:: SQLiteStore - - .. automethod:: close - -.. autoclass:: MongoDBStore -.. autoclass:: RedisStore -.. autoclass:: LRUStoreCache - - .. automethod:: invalidate - .. automethod:: invalidate_values - .. automethod:: invalidate_keys - -.. autoclass:: ABSStore - -.. autoclass:: FSStore - -.. autoclass:: ConsolidatedMetadataStore - -.. autofunction:: init_array -.. autofunction:: init_group -.. autofunction:: contains_array -.. autofunction:: contains_group -.. autofunction:: listdir -.. autofunction:: rmdir -.. autofunction:: getsize -.. autofunction:: rename -.. autofunction:: migrate_1to2 diff --git a/docs/api/sync.rst b/docs/api/sync.rst deleted file mode 100644 index ff961543af..0000000000 --- a/docs/api/sync.rst +++ /dev/null @@ -1,6 +0,0 @@ -Synchronization (``zarr.v2.sync``) -================================== -.. module:: zarr.v2.sync - -.. autoclass:: ThreadSynchronizer -.. autoclass:: ProcessSynchronizer diff --git a/docs/api/zarr.rst b/docs/api/zarr.rst new file mode 100644 index 0000000000..8a9216f19e --- /dev/null +++ b/docs/api/zarr.rst @@ -0,0 +1,5 @@ +zarr +==== + +.. autoapimodule:: zarr + :members: diff --git a/docs/conf.py b/docs/conf.py index 318843a9fb..35afa60577 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -15,6 +15,9 @@ import os import sys +from typing import Any + +import sphinx.application # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -22,6 +25,7 @@ # # The short X.Y version. import zarr +import sphinx # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -42,19 +46,21 @@ "sphinx.ext.autosummary", "sphinx.ext.viewcode", "sphinx.ext.intersphinx", - "sphinx_automodapi.automodapi", + 'autoapi.extension', "numpydoc", "sphinx_issues", "sphinx_copybutton", "sphinx_design", ] -numpydoc_show_class_members = False -numpydoc_class_members_toctree = False issues_github_path = "zarr-developers/zarr-python" -automodapi_inheritance_diagram = False -automodapi_toctreedirnm = "_autoapi" +autoapi_dirs = ['../src/zarr'] +autoapi_add_toctree_entry = False +autoapi_generate_api_docs = False +autoapi_member_order = "groupwise" +autoapi_root = "api" + # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] @@ -166,8 +172,7 @@ html_logo = "_static/logo1.png" -# Add custom css -def setup(app): +def setup(app: sphinx.application.Sphinx) -> None: app.add_css_file("custom.css") diff --git a/docs/index.rst b/docs/index.rst index 06f79b7e7c..92f9a3df18 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,7 +10,7 @@ Zarr-Python getting_started tutorial - api + api/index spec release license @@ -80,7 +80,7 @@ Zarr is a file storage format for chunked, compressed, N-dimensional arrays base +++ - .. button-ref:: api + .. button-ref:: api/index :expand: :color: dark :click-parent: diff --git a/pyproject.toml b/pyproject.toml index 7f8c23f2b6..d61eadea84 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -63,7 +63,7 @@ jupyter = [ docs = [ 'sphinx', 'sphinx-autobuild>=2021.3.14', - 'sphinx-automodapi', + 'sphinx-autoapi', 'sphinx_design', 'sphinx-issues', 'sphinx-copybutton', @@ -146,7 +146,7 @@ features = ['docs'] [tool.hatch.envs.docs.scripts] build = "cd docs && make html" -serve = "sphinx-autobuild docs docs/_build --ignore 'docs/_autoapi/**/*' --host 0.0.0.0" +serve = "sphinx-autobuild docs docs/_build --host 0.0.0.0" [tool.ruff] line-length = 100 diff --git a/src/zarr/buffer.py b/src/zarr/buffer.py index 44691ea352..1298711d4e 100644 --- a/src/zarr/buffer.py +++ b/src/zarr/buffer.py @@ -87,8 +87,8 @@ def all(self) -> bool: ... def __eq__(self, other: Any) -> Self: # type: ignore[explicit-override, override] """Element-wise equal - Notice - ------ + Notes + ----- Type checkers such as mypy complains because the return type isn't a bool like its supertype "object", which violates the Liskov substitution principle. This is true, but since NumPy's ndarray is defined as an element-wise equal, @@ -117,8 +117,8 @@ class Buffer: array-like instance can be copied/converted to a regular Numpy array (host memory). - Note - ---- + Notes + ----- This buffer is untyped, so all indexing and sizes are in bytes. Parameters @@ -188,8 +188,8 @@ def as_array_like(self) -> ArrayLike: def as_numpy_array(self) -> npt.NDArray[Any]: """Returns the buffer as a NumPy array (host memory). - Warning - ------- + Notes + ----- Might have to copy data, consider using `.as_array_like()` instead. Returns @@ -201,8 +201,8 @@ def as_numpy_array(self) -> npt.NDArray[Any]: def to_bytes(self) -> bytes: """Returns the buffer as `bytes` (host memory). - Warning - ------- + Warnings + -------- Will always copy data, only use this method for small buffers such as metadata buffers. If possible, use `.as_numpy_array()` or `.as_array_like()` instead. @@ -244,8 +244,8 @@ class NDBuffer: ndarray-like instance can be copied/converted to a regular Numpy array (host memory). - Note - ---- + Notes + ----- The two buffer classes Buffer and NDBuffer are very similar. In fact, Buffer is a special case of NDBuffer where dim=1, stride=1, and dtype="b". However, in order to use Python's type system to differentiate between the contiguous @@ -290,8 +290,8 @@ def create( ------- New buffer representing a new ndarray_like object - Developer Notes - --------------- + Notes + ----- A subclass can overwrite this method to create a ndarray-like object other then the default Numpy array. """ @@ -344,8 +344,8 @@ def as_ndarray_like(self) -> NDArrayLike: def as_numpy_array(self) -> npt.NDArray[Any]: """Returns the buffer as a NumPy array (host memory). - Warning - ------- + Warnings + -------- Might have to copy data, consider using `.as_ndarray_like()` instead. Returns @@ -433,7 +433,7 @@ def as_numpy_array_wrapper( Returns ------- - The result of `func` converted to a `prototype.buffer` + The result of `func` converted to a `Buffer` """ return prototype.buffer.from_bytes(func(buf.as_numpy_array())) diff --git a/src/zarr/store/local.py b/src/zarr/store/local.py index 9238700445..5915559900 100644 --- a/src/zarr/store/local.py +++ b/src/zarr/store/local.py @@ -109,6 +109,7 @@ async def get_partial_values( ) -> list[Buffer | None]: """ Read byte ranges from multiple keys. + Parameters ---------- key_ranges: List[Tuple[str, Tuple[int, int]]] diff --git a/src/zarr/testing/utils.py b/src/zarr/testing/utils.py index 04b05d1b1c..67c6c72de7 100644 --- a/src/zarr/testing/utils.py +++ b/src/zarr/testing/utils.py @@ -7,8 +7,8 @@ def assert_bytes_equal(b1: Buffer | BytesLike | None, b2: Buffer | BytesLike | None) -> None: """Help function to assert if two bytes-like or Buffers are equal - Warning - ------- + Warnings + -------- Always copies data, only use for testing and debugging """ if isinstance(b1, Buffer): diff --git a/src/zarr/v2/core.py b/src/zarr/v2/core.py index c1223daced..9eeb467d68 100644 --- a/src/zarr/v2/core.py +++ b/src/zarr/v2/core.py @@ -8,11 +8,11 @@ from typing import Any import numpy as np -from numcodecs.compat import ensure_bytes +from numcodecs import AsType, get_codec +from numcodecs.compat import ensure_bytes, ensure_ndarray_like from zarr.v2._storage.store import _prefix_to_attrs_key from zarr.v2.attrs import Attributes -from zarr.v2.codecs import AsType, get_codec from zarr.v2.context import Context from zarr.v2.errors import ArrayNotFoundError, ReadOnlyError, ArrayIndexError from zarr.v2.indexing import ( @@ -56,7 +56,6 @@ normalize_shape, normalize_storage_path, PartialReadBuffer, - ensure_ndarray_like, ) __all__ = ["Array"]