Make chunk_grid property private

Author: maxrjones

docs/design/chunk-grid.md

@@ -200,7 +200,7 @@ arr = zarr.create_array(shape=(100, 200), chunks=(10, 20))
 arr = zarr.create_array(shape=(60, 100), chunks=[[10, 20, 30], [25, 25, 25, 25]])   # rectilinear
 
 # ChunkGrid as a collection
-grid = arr.chunk_grid             # behavioral ChunkGrid (bound to array shape)
+grid = arr._chunk_grid            # behavioral ChunkGrid (bound to array shape)
 grid.grid_shape                   # (10, 10) — number of chunks per dimension
 grid.ndim                         # 2
 grid.is_regular                   # True if all dimensions are Fixed
@@ -351,7 +351,7 @@ new = zarr.from_array(data=src, store=new_store, chunks="keep")
 # Preserves rectilinear structure: new.write_chunk_sizes == ((10, 20, 30), (50, 50))
 ```
 
-When `chunks="keep"`, the logic checks `data.chunk_grid.is_regular`:
+When `chunks="keep"`, the logic checks `data._chunk_grid.is_regular`:
 - Regular: extracts `data.chunks` (flat tuple) and preserves shards
 - Rectilinear: extracts `data.write_chunk_sizes` (nested tuples) and forces shards to None
 
@@ -372,7 +372,7 @@ Today, `get_chunk_spec()` returns the same `ArraySpec(shape=chunk_grid.chunk_sha
 
 ```python
 def get_chunk_spec(self, chunk_coords, array_config, prototype) -> ArraySpec:
-    spec = self.chunk_grid[chunk_coords]
+    spec = self._chunk_grid[chunk_coords]
     return ArraySpec(shape=spec.codec_shape, ...)
 ```
 

docs/user-guide/examples/rectilinear_chunks.ipynb

@@ -6,11 +6,11 @@
    "id": "da9139cc",
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2026-03-30T01:03:13.606739Z",
-     "iopub.status.busy": "2026-03-30T01:03:13.606597Z",
-     "iopub.status.idle": "2026-03-30T01:03:13.613466Z",
-     "shell.execute_reply": "2026-03-30T01:03:13.612167Z",
-     "shell.execute_reply.started": "2026-03-30T01:03:13.606724Z"
+     "iopub.execute_input": "2026-03-30T13:09:30.606395Z",
+     "iopub.status.busy": "2026-03-30T13:09:30.606270Z",
+     "iopub.status.idle": "2026-03-30T13:09:30.611784Z",
+     "shell.execute_reply": "2026-03-30T13:09:30.608914Z",
+     "shell.execute_reply.started": "2026-03-30T13:09:30.606380Z"
     }
    },
    "outputs": [],
@@ -51,18 +51,18 @@
    "id": "9e9nyjdx06f",
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2026-03-30T01:03:13.614308Z",
-     "iopub.status.busy": "2026-03-30T01:03:13.614115Z",
-     "iopub.status.idle": "2026-03-30T01:03:27.161046Z",
-     "shell.execute_reply": "2026-03-30T01:03:27.160587Z",
-     "shell.execute_reply.started": "2026-03-30T01:03:13.614287Z"
+     "iopub.execute_input": "2026-03-30T13:09:30.613147Z",
+     "iopub.status.busy": "2026-03-30T13:09:30.612776Z",
+     "iopub.status.idle": "2026-03-30T13:09:44.301116Z",
+     "shell.execute_reply": "2026-03-30T13:09:44.300677Z",
+     "shell.execute_reply.started": "2026-03-30T13:09:30.613126Z"
     }
    },
    "outputs": [
     {
      "data": {
       "text/plain": [
-       "<donfig.config_obj.ConfigSet at 0x109d94ec0>"
+       "<donfig.config_obj.ConfigSet at 0x10e48cec0>"
       ]
      },
      "execution_count": 2,
@@ -103,11 +103,11 @@
    "id": "v6cot74r1gq",
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2026-03-30T01:03:27.161531Z",
-     "iopub.status.busy": "2026-03-30T01:03:27.161384Z",
-     "iopub.status.idle": "2026-03-30T01:03:46.210431Z",
-     "shell.execute_reply": "2026-03-30T01:03:46.209459Z",
-     "shell.execute_reply.started": "2026-03-30T01:03:27.161522Z"
+     "iopub.execute_input": "2026-03-30T13:09:44.301615Z",
+     "iopub.status.busy": "2026-03-30T13:09:44.301466Z",
+     "iopub.status.idle": "2026-03-30T13:09:45.297053Z",
+     "shell.execute_reply": "2026-03-30T13:09:45.292702Z",
+     "shell.execute_reply.started": "2026-03-30T13:09:44.301605Z"
     }
    },
    "outputs": [
@@ -117,7 +117,7 @@
      "text": [
       "Members: [('cell_ids', <Array object_store://HTTPStore(\"https://data-taos.ifremer.fr/GRID4EARTH/no_chunk_healpix.zarr\")/cell_ids shape=(222442,) dtype=int64>), ('da', <Array object_store://HTTPStore(\"https://data-taos.ifremer.fr/GRID4EARTH/no_chunk_healpix.zarr\")/da shape=(222442,) dtype=float32>)]\n",
       "Attrs: {}\n",
-      "Chunk grid: ChunkGrid(dimensions=(FixedDimension(size=55611, extent=222442),), _is_regular=True)\n"
+      "Write chunk sizes: ((55611, 55611, 55611, 55609),)\n"
      ]
     }
    ],
@@ -129,7 +129,7 @@
     "\n",
     "print(\"Members:\", list(g.members()))\n",
     "print(\"Attrs:\", dict(g.attrs))\n",
-    "print(\"Chunk grid:\", arr.chunk_grid)"
+    "print(\"Write chunk sizes:\", arr.write_chunk_sizes)"
    ]
   },
   {
@@ -148,11 +148,11 @@
    "id": "90bc91b9",
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2026-03-30T01:03:46.211439Z",
-     "iopub.status.busy": "2026-03-30T01:03:46.211138Z",
-     "iopub.status.idle": "2026-03-30T01:03:47.632389Z",
-     "shell.execute_reply": "2026-03-30T01:03:47.631887Z",
-     "shell.execute_reply.started": "2026-03-30T01:03:46.211416Z"
+     "iopub.execute_input": "2026-03-30T13:09:45.301060Z",
+     "iopub.status.busy": "2026-03-30T13:09:45.299959Z",
+     "iopub.status.idle": "2026-03-30T13:09:46.662995Z",
+     "shell.execute_reply": "2026-03-30T13:09:46.662527Z",
+     "shell.execute_reply.started": "2026-03-30T13:09:45.301022Z"
     }
    },
    "outputs": [],
@@ -170,11 +170,11 @@
    "id": "0d7785b0-d72f-4ef8-8a57-91d61f07be96",
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2026-03-30T01:03:47.633034Z",
-     "iopub.status.busy": "2026-03-30T01:03:47.632792Z",
-     "iopub.status.idle": "2026-03-30T01:03:47.635838Z",
-     "shell.execute_reply": "2026-03-30T01:03:47.635478Z",
-     "shell.execute_reply.started": "2026-03-30T01:03:47.633024Z"
+     "iopub.execute_input": "2026-03-30T13:09:46.663527Z",
+     "iopub.status.busy": "2026-03-30T13:09:46.663301Z",
+     "iopub.status.idle": "2026-03-30T13:09:46.666266Z",
+     "shell.execute_reply": "2026-03-30T13:09:46.665875Z",
+     "shell.execute_reply.started": "2026-03-30T13:09:46.663516Z"
     }
    },
    "outputs": [
@@ -200,11 +200,11 @@
    "id": "72c80224-dcac-4724-8caf-5717b29a25d5",
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2026-03-30T01:03:47.636213Z",
-     "iopub.status.busy": "2026-03-30T01:03:47.636138Z",
-     "iopub.status.idle": "2026-03-30T01:03:47.643387Z",
-     "shell.execute_reply": "2026-03-30T01:03:47.642743Z",
-     "shell.execute_reply.started": "2026-03-30T01:03:47.636205Z"
+     "iopub.execute_input": "2026-03-30T13:09:46.666584Z",
+     "iopub.status.busy": "2026-03-30T13:09:46.666509Z",
+     "iopub.status.idle": "2026-03-30T13:09:46.673617Z",
+     "shell.execute_reply": "2026-03-30T13:09:46.672827Z",
+     "shell.execute_reply.started": "2026-03-30T13:09:46.666576Z"
     }
    },
    "outputs": [
@@ -238,11 +238,11 @@
    "id": "a79a281b-ca74-49c3-a467-60490a4ad63e",
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2026-03-30T01:03:47.643801Z",
-     "iopub.status.busy": "2026-03-30T01:03:47.643715Z",
-     "iopub.status.idle": "2026-03-30T01:03:47.648805Z",
-     "shell.execute_reply": "2026-03-30T01:03:47.648326Z",
-     "shell.execute_reply.started": "2026-03-30T01:03:47.643792Z"
+     "iopub.execute_input": "2026-03-30T13:09:46.674098Z",
+     "iopub.status.busy": "2026-03-30T13:09:46.673995Z",
+     "iopub.status.idle": "2026-03-30T13:09:46.690488Z",
+     "shell.execute_reply": "2026-03-30T13:09:46.686144Z",
+     "shell.execute_reply.started": "2026-03-30T13:09:46.674089Z"
     }
    },
    "outputs": [
@@ -278,19 +278,19 @@
    "id": "ribguojdr0s",
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2026-03-30T01:03:47.649560Z",
-     "iopub.status.busy": "2026-03-30T01:03:47.649480Z",
-     "iopub.status.idle": "2026-03-30T01:03:47.943997Z",
-     "shell.execute_reply": "2026-03-30T01:03:47.943488Z",
-     "shell.execute_reply.started": "2026-03-30T01:03:47.649552Z"
+     "iopub.execute_input": "2026-03-30T13:09:46.691041Z",
+     "iopub.status.busy": "2026-03-30T13:09:46.690923Z",
+     "iopub.status.idle": "2026-03-30T13:09:47.241836Z",
+     "shell.execute_reply": "2026-03-30T13:09:47.241361Z",
+     "shell.execute_reply.started": "2026-03-30T13:09:46.691030Z"
     }
    },
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Written to: /var/folders/70/hc_nynms54d8lp67z4rsfctc0000gp/T/tmpgjlmnfff/healpix_rectilinear.zarr\n"
+      "Written to: /var/folders/70/hc_nynms54d8lp67z4rsfctc0000gp/T/tmp30rjewd0/healpix_rectilinear.zarr\n"
      ]
     }
    ],
@@ -331,11 +331,11 @@
    "id": "mpdn5hxp7lp",
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2026-03-30T01:03:47.944360Z",
-     "iopub.status.busy": "2026-03-30T01:03:47.944287Z",
-     "iopub.status.idle": "2026-03-30T01:03:47.946825Z",
-     "shell.execute_reply": "2026-03-30T01:03:47.946372Z",
-     "shell.execute_reply.started": "2026-03-30T01:03:47.944352Z"
+     "iopub.execute_input": "2026-03-30T13:09:47.242174Z",
+     "iopub.status.busy": "2026-03-30T13:09:47.242097Z",
+     "iopub.status.idle": "2026-03-30T13:09:47.244629Z",
+     "shell.execute_reply": "2026-03-30T13:09:47.244126Z",
+     "shell.execute_reply.started": "2026-03-30T13:09:47.242166Z"
     }
    },
    "outputs": [
@@ -367,38 +367,36 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 10,
+   "execution_count": 13,
    "id": "308gxly6r3j",
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2026-03-30T01:03:47.947072Z",
-     "iopub.status.busy": "2026-03-30T01:03:47.946996Z",
-     "iopub.status.idle": "2026-03-30T01:03:47.967534Z",
-     "shell.execute_reply": "2026-03-30T01:03:47.967022Z",
-     "shell.execute_reply.started": "2026-03-30T01:03:47.947061Z"
+     "iopub.execute_input": "2026-03-30T13:11:17.611493Z",
+     "iopub.status.busy": "2026-03-30T13:11:17.610692Z",
+     "iopub.status.idle": "2026-03-30T13:11:17.655199Z",
+     "shell.execute_reply": "2026-03-30T13:11:17.654529Z",
+     "shell.execute_reply.started": "2026-03-30T13:11:17.611441Z"
     }
    },
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Round-trip chunk sizes: Frozen({'cell_ids': (25, 645, 1510, 2363, 3203, 74, 769, 3963, 4096, 233, 1603, 2450, 4096, 4096, 3327, 4047, 4096, 4096, 1278, 2113, 4096, 3879, 4096, 3842, 2173, 983, 4046, 2187, 4095, 1369, 4096, 4096, 4096, 4096, 3515, 1395, 4096, 3622, 4096, 4096, 3875, 4096, 4096, 4096, 4096, 4096, 2034, 4096, 358, 3991, 4096, 4096, 4096, 4096, 2714, 1210, 4096, 4096, 4096, 4096, 92, 3826, 4096, 2629, 4096, 1438, 4096, 353, 4078, 3410, 2407, 226, 132, 2738, 1223, 23)})\n",
-      "Regular grid: False\n"
+      "Round-trip chunk sizes: Frozen({'cell_ids': (25, 645, 1510, 2363, 3203, 74, 769, 3963, 4096, 233, 1603, 2450, 4096, 4096, 3327, 4047, 4096, 4096, 1278, 2113, 4096, 3879, 4096, 3842, 2173, 983, 4046, 2187, 4095, 1369, 4096, 4096, 4096, 4096, 3515, 1395, 4096, 3622, 4096, 4096, 3875, 4096, 4096, 4096, 4096, 4096, 2034, 4096, 358, 3991, 4096, 4096, 4096, 4096, 2714, 1210, 4096, 4096, 4096, 4096, 92, 3826, 4096, 2629, 4096, 1438, 4096, 353, 4078, 3410, 2407, 226, 132, 2738, 1223, 23)})\n"
      ]
     }
    ],
    "source": [
     "roundtrip = xr.open_zarr(output_path, zarr_format=3, consolidated=False)\n",
     "\n",
-    "print(\"Round-trip chunk sizes:\", roundtrip.chunks)\n",
-    "print(\"Regular grid:\", roundtrip[\"da\"].variable.encoding.get(\"chunks\") == tuple(chunk_sizes.tolist()))"
+    "print(\"Round-trip chunk sizes:\", roundtrip.chunks)"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "d3c32f1c-2c4f-403f-a4e8-98c6582eef96",
+   "id": "e8d42341-c242-44f5-ad6a-491370e3ffab",
    "metadata": {},
    "outputs": [],
    "source": []