pydantic-tensorstore 0.1.0__tar.gz

pydantic_tensorstore-0.1.0/.github/DRIFT_TEMPLATE.md

@@ -0,0 +1,14 @@
+---
+title: "[drift-bot] models out of sync with latest tensorstore"
+labels: [drift]
+---
+The weekly drift check failed: the models no longer match the newest tensorstore
+release (its JSON schema files and/or runtime behaviour).
+
+See the failed run for details: https://github.com/{{ env.GITHUB_REPOSITORY }}/actions/runs/{{ env.RUN_ID }}
+
+To update:
+
+1. `uv run scripts/update_ts_schema.py --latest`
+2. Bump `TENSORSTORE_VERSION` in `src/pydantic_tensorstore/__init__.py`
+3. `uv run pytest tests/test_schema_conformance.py` and fix the reported gaps

pydantic_tensorstore-0.1.0/.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,15 @@
+* pydantic-tensorstore version:
+* Python version:
+* Operating System:
+
+### Description
+
+Describe what you were trying to get done.
+Tell us what happened, what went wrong, and what you expected to happen.
+
+### What I Did
+
+```
+Paste the command(s) you ran and the output.
+If there was a crash, please include the traceback here.
+```

pydantic_tensorstore-0.1.0/.github/TEST_FAIL_TEMPLATE.md

@@ -0,0 +1,12 @@
+---
+title: "{{ env.TITLE }}"
+labels: [bug]
+---
+The {{ workflow }} workflow failed on {{ date | date("YYYY-MM-DD HH:mm") }} UTC
+
+The most recent failing test was on {{ env.PLATFORM }} py{{ env.PYTHON }}
+with commit: {{ sha }}
+
+Full run: https://github.com/{{ repo }}/actions/runs/{{ env.RUN_ID }}
+
+(This post will be updated if another test fails, as long as this issue remains open.)

pydantic_tensorstore-0.1.0/.github/dependabot.yml

@@ -0,0 +1,14 @@
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "quarterly"
+    commit-message:
+      prefix: "ci(dependabot):"
+    groups:
+      actions:
+        patterns:
+          - "*"

pydantic_tensorstore-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,183 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: [v*]
+  pull_request:
+  workflow_dispatch:
+  schedule:
+    # run every week (for --pre release tests)
+    - cron: "0 0 * * 0"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check-manifest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - run: pipx run check-manifest
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.13"
+          enable-cache: true
+      - run: uv run prek run --all-files
+
+  test:
+    name: ${{ matrix.platform }} (${{ matrix.python-version }}) [${{ matrix.resolution }}]
+    runs-on: ${{ matrix.platform }}
+    env:
+      UV_PRERELEASE: ${{ github.event_name == 'schedule' && 'allow' || 'if-necessary-or-explicit' }}
+      UV_RESOLUTION: ${{ matrix.resolution }}
+      PYTEST_ADDOPTS: ${{ matrix.resolution == 'lowest-direct' && '-W ignore' || '' }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+        platform: [ubuntu-latest, macos-latest, windows-latest]
+        resolution: ["highest", "lowest-direct"]
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: 🐍 Set up Python ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install Dependencies
+        run: uv sync --no-dev --group test
+
+      - name: 🧪 Run Tests
+        run: uv run --no-sync coverage run -p -m pytest -v
+
+      # If something goes wrong with --pre tests, we can open an issue in the repo
+      - name: 📝 Report --pre Failures
+        if: failure() && github.event_name == 'schedule'
+        uses: JasonEtco/create-an-issue@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PLATFORM: ${{ matrix.platform }}
+          PYTHON: ${{ matrix.python-version }}
+          RUN_ID: ${{ github.run_id }}
+          TITLE: "[test-bot] pip install --pre is failing"
+        with:
+          filename: .github/TEST_FAIL_TEMPLATE.md
+          update_existing: true
+
+      - name: Upload coverage
+        uses: actions/upload-artifact@v7
+        with:
+          name: covreport-${{ matrix.platform }}-py${{ matrix.python-version }}-${{ matrix.resolution }}
+          path: ./.coverage*
+          include-hidden-files: true
+
+  upload_coverage:
+    if: always()
+    needs: [test]
+    uses: pyapp-kit/workflows/.github/workflows/upload-coverage.yml@v2
+    secrets:
+      codecov_token: ${{ secrets.CODECOV_TOKEN }}
+
+  # Explicit tensorstore version ladder: oldest supported, a midpoint, the pinned
+  # (schema-verified) release, and whatever is newest on PyPI.
+  tensorstore-compat:
+    name: tensorstore ${{ matrix.tensorstore }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        tensorstore: ["min", "0.1.77", "pinned", "latest"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+          enable-cache: true
+      - run: uv sync --no-dev --group test
+      - name: Install tensorstore ${{ matrix.tensorstore }}
+        run: |
+          case "${{ matrix.tensorstore }}" in
+            min)    v=$(uv run --no-sync python -c "import pydantic_tensorstore as p; print(p.MIN_TENSORSTORE_VERSION)") ;;
+            pinned) v=$(uv run --no-sync python -c "import pydantic_tensorstore as p; print(p.TENSORSTORE_VERSION)") ;;
+            latest) uv pip install --upgrade tensorstore; exit 0 ;;
+            *)      v="${{ matrix.tensorstore }}" ;;
+          esac
+          uv pip install "tensorstore==$v"
+      - run: uv run --no-sync python -c "from importlib.metadata import version; print('tensorstore', version('tensorstore'))"
+      - run: uv run --no-sync pytest -v
+
+  # Weekly: does the newest tensorstore release still match our models?
+  drift:
+    name: drift check (latest tensorstore)
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.13"
+          enable-cache: true
+      - name: Fetch latest tensorstore schema
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: uv run --no-project scripts/update_ts_schema.py --latest --dest "$RUNNER_TEMP/ts_schema"
+      - name: Install latest tensorstore
+        run: uv sync --no-dev --group test --upgrade-package tensorstore
+      - name: Compare models against latest schema and runtime
+        env:
+          PTS_SCHEMA_DIR: ${{ runner.temp }}/ts_schema
+        run: |
+          uv run --no-sync python -c "from importlib.metadata import version; print('tensorstore', version('tensorstore'))"
+          uv run --no-sync pytest -v tests/test_schema_conformance.py tests/test_dtypes.py tests/test_since.py tests/test_tensorstore.py --deselect tests/test_schema_conformance.py::test_vendored_version_matches_package
+      - name: Report drift
+        if: failure()
+        uses: JasonEtco/create-an-issue@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RUN_ID: ${{ github.run_id }}
+        with:
+          filename: .github/DRIFT_TEMPLATE.md
+          update_existing: true
+
+  build-and-inspect-package:
+    name: Build & inspect package.
+    needs: [test, tensorstore-compat, lint]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      # no moving major tag as of v3; pin the full version
+      - uses: hynek/build-and-inspect-python-package@v3.0.1
+
+  upload-to-pypi:
+    name: Upload package to PyPI
+    needs: build-and-inspect-package
+    if: success() && startsWith(github.ref, 'refs/tags/') && github.event_name != 'schedule'
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: write
+
+    steps:
+      - name: Download built artifact to dist/
+        uses: actions/download-artifact@v8
+        with:
+          name: Packages
+          path: dist
+      - name: 🚢 Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+      - uses: softprops/action-gh-release@v3
+        with:
+          generate_release_notes: true
+          files: "./dist/*"

pydantic_tensorstore-0.1.0/.gitignore

@@ -0,0 +1,115 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+.DS_Store
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# dotenv
+.env
+
+# virtualenv
+.venv
+venv/
+ENV/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# ruff
+.ruff_cache/
+
+# IDE settings
+.vscode/
+.idea/
+uv.lock
+
+# local agent settings
+.claude/

pydantic_tensorstore-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,42 @@
+# enable pre-commit.ci at https://pre-commit.ci/
+# it adds:
+# 1. auto fixing pull requests
+# 2. auto updating the pre-commit configuration
+ci:
+  autoupdate_schedule: monthly
+  autofix_commit_msg: "style(pre-commit.ci): auto fixes [...]"
+  autoupdate_commit_msg: "ci(pre-commit.ci): autoupdate"
+  skip:
+    - mypy
+
+repos:
+  - repo: https://github.com/abravalheri/validate-pyproject
+    rev: "0.26"
+    hooks:
+      - id: validate-pyproject
+
+  - repo: https://github.com/rhysd/actionlint
+    rev: v1.7.12
+    hooks:
+      - id: actionlint
+        files: "^\\.github/workflows/.*\\.ya?ml$"
+
+  - repo: https://github.com/adhtruong/mirrors-typos
+    rev: v1.50.1
+    hooks:
+      - id: typos
+        args: [--force-exclude] # omitting --write-changes
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.6
+    hooks:
+      - id: ruff-check
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        entry: uv run --active mypy
+        language: system
+        pass_filenames: false

pydantic_tensorstore-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2023, Talley Lambert
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pydantic_tensorstore-0.1.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.5
+Name: pydantic-tensorstore
+Version: 0.1.0
+Summary: Pydantic models for TensorStore specifications
+Project-URL: homepage, https://github.com/tlambert03/pydantic-tensorstore
+Project-URL: repository, https://github.com/tlambert03/pydantic-tensorstore
+Project-URL: changelog, https://github.com/tlambert03/pydantic-tensorstore/releases
+Author-email: Talley Lambert <talley.lambert@gmail.com>
+License: BSD-3-Clause
+License-File: LICENSE
+Keywords: pydantic,scientific-computing,tensorstore,validation
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.23.2
+Requires-Dist: numpy>=2.1; python_version >= '3.13'
+Requires-Dist: numpy>=2.3.2; python_version >= '3.14'
+Requires-Dist: pydantic-core>=2.35.0; python_version >= '3.14'
+Requires-Dist: pydantic>=2.11.0
+Provides-Extra: tensorstore
+Requires-Dist: tensorstore>=0.1.68; extra == 'tensorstore'
+Requires-Dist: tensorstore>=0.1.70; (python_version >= '3.13') and extra == 'tensorstore'
+Requires-Dist: tensorstore>=0.1.79; (python_version >= '3.14') and extra == 'tensorstore'
+Description-Content-Type: text/markdown
+
+# pydantic-tensorstore
+
+[![License](https://img.shields.io/pypi/l/pydantic-tensorstore.svg?color=green)](https://github.com/tlambert03/pydantic-tensorstore/raw/main/LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/pydantic-tensorstore.svg?color=green)](https://pypi.org/project/pydantic-tensorstore)
+[![Python Version](https://img.shields.io/pypi/pyversions/pydantic-tensorstore.svg?color=green)](https://python.org)
+[![CI](https://github.com/tlambert03/pydantic-tensorstore/actions/workflows/ci.yml/badge.svg)](https://github.com/tlambert03/pydantic-tensorstore/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/tlambert03/pydantic-tensorstore/branch/main/graph/badge.svg)](https://codecov.io/gh/tlambert03/pydantic-tensorstore)
+
+*Type-safe, validated TensorStore specifications with Pydantic*
+
+## Motivation
+
+[TensorStore](https://github.com/google/tensorstore) is an exceptional C++ and
+Python library for reading and writing large multi-dimensional arrays. It
+supports numerous storage formats (Zarr, N5, Neuroglancer Precomputed) and
+backends (local files, cloud storage, memory), making it incredibly powerful for
+scientific computing and data analysis.
+
+However, TensorStore has some pain points that this library attempts to address:
+
+- **Poor type hinting**: TensorStore specifications are typically created as
+  dictionaries with minimal type information, making it difficult to know what
+  fields are available or required
+- **Complex documentation**: Creating proper TensorStore JSON spec objects often
+  requires constantly referencing web documentation to understand the various
+  options and their relationships
+- **No IDE support**: Without proper types, IDEs can't provide autocomplete,
+  validation, or refactoring support
+
+**pydantic-tensorstore** solves these issues by providing:
+
+- [x] **Full type safety** with Pydantic v2 models
+- [x] **Excellent IDE support** with autocomplete and validation
+- [x] **Clear, actionable error messages** when specifications are invalid
+- [x] **Runtime validation** with detailed error reporting
+- [x] **Seamless conversion** to native TensorStore specs
+- [x] **Documentation** embedded in the type system (field descriptions state
+  TensorStore's defaults)
+
+## Quick Example
+
+Instead of wrestling with raw dictionaries:
+
+```python
+# Raw TensorStore (no types, no validation, no IDE support)
+import tensorstore as ts
+
+spec = {
+    "driver": "zarr",
+    "kvstore": {"driver": "file", "path": "/data/"},
+    "metadata": {
+        "chunks": [64, 64],
+        "compressor": {"id": "blosc", "cname": "lz4", "clevel": 5},
+        "dtype": "<f4",  # Is this right? 🤔
+    },
+}
+# Hope it works! 🤞
+```
+
+Use type-safe, validated specifications with IDE autocompletion:
+
+```python
+#  pydantic-tensorstore (full types, validation, IDE support)
+import pydantic_tensorstore as pts
+
+spec = pts.Zarr2Spec(
+    kvstore=pts.MemoryKvStore(),
+    metadata=pts.Zarr2Metadata(
+        chunks=[64, 64],
+        compressor=pts.Zarr2CompressorBlosc(cname="lz4", clevel=5),
+        dtype="<f4",
+    ),
+)
+
+# Convert to native TensorStore when needed
+ts_spec = spec.to_tensorstore()  # requires tensorstore to be installed
+```
+
+To cast any dict (or JSON string, or `tensorstore.Spec`) to a validated spec:
+
+```python
+from pydantic_tensorstore import validate_spec
+
+validated_spec = validate_spec(raw_dict)
+```
+
+## Installation
+
+```bash
+pip install pydantic-tensorstore
+
+# with a compatible version of tensorstore installed for .to_tensorstore() support
+pip install 'pydantic-tensorstore[tensorstore]'
+```
+
+## TensorStore compatibility
+
+TensorStore's JSON spec is defined by the
+[schema files in its repository](https://github.com/google/tensorstore/search?q=filename%3Aschema.yml).
+The models here are checked field-by-field against those files for a single
+pinned release, exposed as `pydantic_tensorstore.TENSORSTORE_VERSION`.
+
+- **Verified against**: tensorstore `0.1.85` (`TENSORSTORE_VERSION`)
+- **Tested with**: tensorstore `>= 0.1.68` (`MIN_TENSORSTORE_VERSION`). CI runs
+  the full suite against the oldest, a midpoint, the pinned, and the newest
+  release. Nearly everything the models can express already works on 0.1.68;
+  the dozen fields and data types TensorStore added later carry a `since`
+  marker.
+- **Version check**: `spec.required_tensorstore_version()` reports the oldest
+  release a spec needs, and `to_tensorstore()` raises
+  `UnsupportedTensorStoreVersionError` naming the offending fields when the
+  installed tensorstore is older (pass `check_version=False` to skip).
+- **Drift**: a weekly CI job re-checks the models against the newest
+  tensorstore release and opens an issue when something changes.
+
+```python
+>>> spec = pts.Zarr3Spec(kvstore="memory://", open_as_void=True)
+>>> spec.required_tensorstore_version()
+'0.1.85'
+>>> spec.to_tensorstore()  # with tensorstore 0.1.68 installed
+UnsupportedTensorStoreVersionError: installed tensorstore 0.1.68 does not support:
+  open_as_void: requires tensorstore >= 0.1.85
+```
+
+Two design rules keep the models forward-compatible:
+
+- **Optional fields default to `None`**, meaning "let TensorStore decide".
+  TensorStore's own default is documented in the field description. Dumping a
+  spec emits only the fields you set (an explicit `None` is kept as `null`,
+  since TensorStore gives `null` meaning for e.g. `compressor`).
+- **KvStore URLs pass through.** `file://`, `memory://`, `s3://`, `gs://` and
+  `http(s)://` URLs are parsed into models; any other URL string (including
+  pipelines such as `"memory://a.zip|zip:"`) is kept verbatim and handed to
+  TensorStore unchanged.
+
+## Known differences from TensorStore
+
+A few deliberate or documented divergences, so they don't surprise you:
+
+- **Partial specs are rejected.** TensorStore accepts `{"driver": "zarr3"}` with no
+  `kvstore`, to be filled in later via `ts.Spec.update()` or an `open()` argument.
+  The models require `kvstore` (and `cast`'s `dtype`), trading that pattern for a
+  clear "you forgot the kvstore" error. Specs produced by a real store always
+  include it.
+- **Non-finite numbers become strings in JSON.** `model_dump_json()` writes
+  `"NaN"`, `"Infinity"` and `"-Infinity"`, which TensorStore reads back as floats.
+  Python-mode `model_dump()` keeps the float. Note that re-validating that JSON
+  gives you the string back, since `fill_value` is untyped.
+- **`schema` is spelled `schema_` on the model,** because `schema` collides with a
+  Pydantic attribute. Both work at runtime, but mypy only accepts `schema_=`;
+  `validate_spec()` takes plain `"schema"` in a dict either way.
+- **Arrays are not silently truncated.** `ArraySpec` refuses a `dtype` that would
+  lose data, rather than quietly rounding.
+
+## Coverage
+
+Every driver, kvstore, and context resource documented in tensorstore
+`TENSORSTORE_VERSION` has a model.
+
+| Kind | Models |
+|---|---|
+| Chunked drivers | `Zarr2Spec` (`zarr`/`zarr2`), `Zarr3Spec`, `N5Spec`, `NeuroglancerPrecomputedSpec` |
+| Image drivers | `AvifSpec`, `BmpSpec`, `JpegSpec`, `PngSpec`, `TiffSpec`, `WebpSpec` |
+| Other drivers | `ArraySpec`, `AutoSpec`, `CastSpec`, `DownsampleSpec`, `JsonSpec`, `StackSpec` |
+| KvStores | `FileKvStore`, `MemoryKvStore`, `S3KvStore`, `GCSKvStore`, `HTTPKvStore`, `TsGrpcKvStore` |
+| KvStore adapters | `OcdbtKvStore`, `ZipKvStore`, `KvStackKvStore`, `NeuroglancerUint64ShardedKvStore`, `Zarr3ShardingIndexedKvStore` |
+| Codecs | `Zarr2Codec`, `Zarr3Codec` (+ every zarr3 codec), `N5Codec`, `NeuroglancerPrecomputedCodec` |
+| Core | `Schema`, `ChunkLayout`, `IndexDomain`, `IndexTransform`, `Context` (+ every context resource), `Unit` |
+
+`TensorStoreSpec` and `KvStore` are discriminated unions over all of the above;
+`validate_spec()` and `validate_kvstore()` parse into them.
+
+## Development
+
+Tests compare the models against the vendored schema files in `tests/ts_schema/`
+and, when tensorstore is installed, round-trip every spec through
+`tensorstore.Spec`. To move to a newer tensorstore release:
+
+```bash
+uv run scripts/update_ts_schema.py --latest   # refresh tests/ts_schema/
+# bump TENSORSTORE_VERSION in src/pydantic_tensorstore/__init__.py
+uv run pytest tests/test_schema_conformance.py  # shows exactly what changed
+```