feat: expore public type aliases from zarr.types

Author: maxrjones

changes/3886.feature.md

@@ -0,0 +1 @@
+Export public type aliases from ``zarr.types``, including ``JSON``, ``ZarrFormat``, ``ShapeLike``, ``CompressorLike``, ``FiltersLike``, ``Selection``, and other types used in the public API.

docs/api/zarr/types.md

@@ -0,0 +1,5 @@
+---
+title: types
+---
+
+::: zarr.types

docs/contributing.md

@@ -183,6 +183,19 @@ prek list
 
 If you would like to skip the failing checks and push the code for further discussion, use the `--no-verify` option with `git commit`.
 
+### Public and private API
+
+Zarr follows standard Python conventions for distinguishing public from private API:
+
+- **Public modules** are top-level or one level deep: `zarr`, `zarr.dtype`, `zarr.types`, `zarr.codecs`, `zarr.storage`, etc. Users should only need to import from these modules.
+- **Private modules** use a leading underscore or are within `zarr.core` (e.g. `zarr.core.dtype.npy.common`, `zarr.core._info`). These are implementation details and may change without notice.
+- **`__all__`** declares the public API of a module. Every public module should define `__all__`. If a name is not in `__all__`, it is not part of the public API.
+- **Type aliases** used across the codebase (e.g. `JSON`, `ZarrFormat`, `ShapeLike`) are re-exported from [`zarr.types`][zarr.types]. External users and tests should import from `zarr.types`. Internal code may import from the defining module (e.g. `zarr.core.common`).
+- **Extension points** (custom codecs, data types) should be fully usable by importing only from public modules. If a user needs to reach into `zarr.core.*` to implement an extension, that is a gap in the public API.
+- **Entry points** (e.g. `zarr.codecs`, `zarr.data_type`) are part of the public plugin interface and should be documented in the [extending guide](user-guide/extending.md).
+
+When adding new functionality, consider whether it belongs in the public API. If so, export it from the appropriate top-level module and add it to `__all__`. If it is an internal helper, place it in a private module or use a leading underscore.
+
 ### Test coverage
 
 > **Note:** Test coverage for Zarr-Python 3 is currently not at 100%. This is a known issue and help is welcome to bring test coverage back to 100%. See issue #2613 for more details.

mkdocs.yml

@@ -49,6 +49,7 @@ nav:
       - api/zarr/registry.md
       - api/zarr/storage.md
       - api/zarr/experimental.md
+      - api/zarr/types.md
       - ABC:
         - api/zarr/abc/index.md
         - api/zarr/abc/buffer.md

src/zarr/types.py

@@ -1,9 +1,73 @@
 from typing import Any
 
-from zarr.core.array import Array, AsyncArray
+from zarr.core.array import (
+    Array,
+    AsyncArray,
+    CompressorLike,
+    CompressorsLike,
+    FiltersLike,
+    SerializerLike,
+    ShardsLike,
+)
+from zarr.core.array_spec import ArrayConfigLike
+from zarr.core.buffer import NDArrayLikeOrScalar
+from zarr.core.chunk_key_encodings import ChunkKeyEncodingLike
+from zarr.core.common import (
+    JSON,
+    AccessModeLiteral,
+    BytesLike,
+    ChunksLike,
+    DimensionNamesLike,
+    MemoryOrder,
+    NodeType,
+    ShapeLike,
+    ZarrFormat,
+)
+from zarr.core.dtype import ZDTypeLike
+from zarr.core.indexing import (
+    BasicSelection,
+    CoordinateSelection,
+    Fields,
+    MaskSelection,
+    OrthogonalSelection,
+    Selection,
+)
 from zarr.core.metadata.v2 import ArrayV2Metadata
 from zarr.core.metadata.v3 import ArrayV3Metadata
 
+__all__ = [
+    "JSON",
+    "AccessModeLiteral",
+    "AnyArray",
+    "AnyAsyncArray",
+    "ArrayConfigLike",
+    "ArrayV2",
+    "ArrayV3",
+    "AsyncArrayV2",
+    "AsyncArrayV3",
+    "BasicSelection",
+    "BytesLike",
+    "ChunkKeyEncodingLike",
+    "ChunksLike",
+    "CompressorLike",
+    "CompressorsLike",
+    "CoordinateSelection",
+    "DimensionNamesLike",
+    "Fields",
+    "FiltersLike",
+    "MaskSelection",
+    "MemoryOrder",
+    "NDArrayLikeOrScalar",
+    "NodeType",
+    "OrthogonalSelection",
+    "Selection",
+    "SerializerLike",
+    "ShapeLike",
+    "ShardsLike",
+    "ZDTypeLike",
+    "ZarrFormat",
+]
+
 type AnyAsyncArray = AsyncArray[Any]
 """A Zarr format 2 or 3 `AsyncArray`"""
 

tests/package_with_entrypoint/__init__.py

@@ -17,7 +17,7 @@
     from typing import Any, ClassVar, Literal, Self
 
     from zarr.core.array_spec import ArraySpec
-    from zarr.core.common import ZarrFormat
+    from zarr.types import ZarrFormat
 
 
 class TestEntrypointCodec(ArrayBytesCodec):

tests/test_api.py

@@ -15,8 +15,7 @@
     from pathlib import Path
 
     from zarr.abc.store import Store
-    from zarr.core.common import JSON, MemoryOrder, ZarrFormat
-    from zarr.types import AnyArray
+    from zarr.types import JSON, AnyArray, MemoryOrder, ZarrFormat
 
 import contextlib
 from typing import Literal

tests/test_array.py

@@ -48,7 +48,7 @@
 from zarr.core.buffer import NDArrayLike, NDArrayLikeOrScalar, default_buffer_prototype
 from zarr.core.chunk_grids import _auto_partition
 from zarr.core.chunk_key_encodings import ChunkKeyEncodingParams
-from zarr.core.common import JSON, ZarrFormat, ceildiv
+from zarr.core.common import ceildiv
 from zarr.core.dtype import (
     DateTime64,
     Float32,
@@ -76,7 +76,7 @@
 )
 from zarr.storage import LocalStore, MemoryStore, StorePath
 from zarr.storage._logging import LoggingStore
-from zarr.types import AnyArray, AnyAsyncArray
+from zarr.types import JSON, AnyArray, AnyAsyncArray, ZarrFormat
 
 from .test_dtype.conftest import zdtype_examples
 

tests/test_attributes.py

@@ -8,7 +8,7 @@
 import zarr.core.attributes
 import zarr.storage
 from tests.conftest import deep_nan_equal
-from zarr.core.common import ZarrFormat
+from zarr.types import ZarrFormat
 
 if TYPE_CHECKING:
     from zarr.types import AnyArray

tests/test_cli/conftest.py

@@ -5,7 +5,7 @@
 
 import zarr
 from zarr.abc.store import Store
-from zarr.core.common import ZarrFormat
+from zarr.types import ZarrFormat
 
 
 def create_nested_zarr(