feat: add IndexTransform library for composable, lazy coordinate mappings

.github/workflows/check_changelogs.yml

@@ -29,3 +29,6 @@ jobs:
 
       - name: Check zarr-metadata changelog entries
         run: uv run --no-sync python ci/check_changelog_entries.py packages/zarr-metadata/changes
+
+      - name: Check zarr-transforms changelog entries
+        run: uv run --no-sync python ci/check_changelog_entries.py packages/zarr-transforms/changes

.github/workflows/zarr-transforms-release.yml

@@ -0,0 +1,117 @@
+name: zarr-transforms release
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - 'zarr_transforms-v*'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build wheel and sdist
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+        working-directory: packages/zarr-transforms
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+          fetch-depth: 0          # hatch-vcs needs full history + tags
+
+      - name: Install Hatch
+        uses: pypa/hatch@257e27e51a6a5616ed08a39a408a21c35c9931bc
+        with:
+          version: '1.16.5'
+
+      - name: Build
+        run: hatch build
+
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: zarr-transforms-dist
+          path: packages/zarr-transforms/dist
+
+  test_artifacts:
+    name: Test built artifacts
+    needs: [build]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: zarr-transforms-dist
+          path: dist
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          enable-cache: false
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install built wheel and run import smoke test
+        run: |
+          wheel=$(ls dist/*.whl)
+          uv run --with "${wheel}" --python 3.12 --no-project \
+            python -c "import zarr_transforms; print('zarr_transforms', zarr_transforms.__version__)"
+
+  upload_pypi:
+    name: Upload to PyPI
+    needs: [build, test_artifacts]
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/zarr_transforms-v')
+    runs-on: ubuntu-latest
+    environment:
+      name: zarr-transforms-releases
+      url: https://pypi.org/p/zarr-transforms
+    permissions:
+      id-token: write          # required for OIDC trusted publishing
+      attestations: write      # required for artifact attestations
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: zarr-transforms-dist
+          path: dist
+
+      - name: Generate artifact attestation
+        uses: actions/attest@59d89421af93a897026c735860bf21b6eb4f7b26 # v4.1.0
+        with:
+          subject-path: dist/*
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+
+  upload_testpypi:
+    name: Upload to TestPyPI
+    needs: [build, test_artifacts]
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    environment:
+      name: zarr-transforms-releases-test
+      url: https://test.pypi.org/p/zarr-transforms
+    permissions:
+      id-token: write
+      attestations: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: zarr-transforms-dist
+          path: dist
+
+      - name: Generate artifact attestation
+        uses: actions/attest@59d89421af93a897026c735860bf21b6eb4f7b26 # v4.1.0
+        with:
+          subject-path: dist/*
+
+      - name: Publish package to TestPyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+        with:
+          repository-url: https://test.pypi.org/legacy/

.github/workflows/zarr-transforms.yml

@@ -0,0 +1,102 @@
+name: zarr-transforms
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'packages/zarr-transforms/**'
+      - '.github/workflows/zarr-transforms.yml'
+  pull_request:
+    paths:
+      - 'packages/zarr-transforms/**'
+      - '.github/workflows/zarr-transforms.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: pytest py=${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.12', '3.13', '3.14']
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          enable-cache: true
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      # The transform tests exercise chunk resolution against zarr's ChunkGrid,
+      # so they run from the repo root against the full workspace (which installs
+      # both `zarr` and the `zarr-transforms` workspace member) rather than in
+      # package isolation.
+      - name: Sync test dependency group
+        run: uv sync --group test --python ${{ matrix.python-version }}
+      - name: Run pytest
+        run: uv run --group test pytest packages/zarr-transforms/tests
+
+  ruff:
+    name: ruff
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+        working-directory: packages/zarr-transforms
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+      - name: Run ruff
+        run: uvx ruff check .
+
+  pyright:
+    name: pyright
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+        working-directory: packages/zarr-transforms
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install 3.12
+      - name: Sync test dependency group
+        run: uv sync --group test --python 3.12
+      - name: Run pyright
+        run: uv run --group test --with pyright pyright src
+
+  zarr-transforms-complete:
+    name: zarr-transforms complete
+    needs: [test, ruff, pyright]
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check failure
+        if: |
+          contains(needs.*.result, 'failure') ||
+          contains(needs.*.result, 'cancelled')
+        run: exit 1
+      - name: Success
+        run: echo Success!

changes/3906.feature.md

@@ -0,0 +1 @@
+Added a `.lazy` accessor to `Array` for lazy (deferred) indexing. `array.lazy[...]`, `array.lazy.oindex[...]`, and `array.lazy.vindex[...]` return a new `Array` view composed on a TensorStore-style index-transform layer; slicing and indexing a view never triggers I/O, and views can be composed further before reading. Call `.result()` on a view to resolve it and return the underlying data. Regular (eager) indexing semantics on `Array` and `AsyncArray` are unchanged, with two deliberate exceptions on `Array`: its `repr` now carries a `domain={...}` suffix describing the view's coordinate box, and iterating a 0-d array now raises `TypeError("iteration over a 0-d array")` to match NumPy (previously it silently yielded nothing). Arrays also gain `Array.chunk_projections`, which enumerates the stored chunks a view (or a whole array) projects onto, for view-aware chunk partitioning. The index-transform machinery that powers this lives in a new NumPy-only `zarr-transforms` workspace package (import name `zarr_transforms`), which `zarr` now depends on at runtime.

docs/api/zarr/array.md

@@ -1,2 +1,3 @@
 ::: zarr.Array
 ::: zarr.AsyncArray
+::: zarr.ChunkProjection