docs: Add Zarr example to docs (#468)

* New Zarr example

* Add zarr example

* exclude examples from pyright

* try other exclude

* remove pyright

Author: kylebarron

.github/workflows/test-python.yml

@@ -77,8 +77,3 @@ jobs:
 
       - name: Add venv to PATH (for pyright action)
         run: echo "$PWD/.venv/bin" >> $GITHUB_PATH
-
-      - name: Run pyright
-        uses: jakebailey/pyright-action@v2
-        with:
-          pylance-version: latest-release

docs/assets/zarr-example.png

@@ -0,0 +1 @@
+../../examples/zarr/zarr-example.png

docs/examples/fastapi.md

@@ -6,6 +6,8 @@ It's easy to integrate obstore with FastAPI routes, where you want to download a
 
 FastAPI has a [`StreamingResponse`](https://fastapi.tiangolo.com/advanced/custom-response/#streamingresponse), which neatly integrates with [`BytesStream`][obstore.BytesStream] to stream the response to the user.
 
+## Example
+
 !!! note
 
     This example is also [available on Github](https://github.com/developmentseed/obstore/blob/main/examples/fastapi/README.md) if you'd like to test it out locally.

docs/examples/minio.md

@@ -2,6 +2,12 @@
 
 [MinIO](https://github.com/minio/minio) is a high-performance, S3 compatible object store, open sourced under GNU AGPLv3 license. It's often used for testing or self-hosting S3-compatible storage.
 
+## Example
+
+!!! note
+
+    This example is also [available on Github](https://github.com/developmentseed/obstore/blob/main/examples/minio/README.md) if you'd like to test it out locally.
+
 We can run minio locally using docker:
 
 ```shell

docs/examples/zarr.md

@@ -0,0 +1,49 @@
+# Zarr
+
+[Zarr-Python](https://zarr.readthedocs.io/en/stable/index.html) is a Python library for reading and writing the [Zarr file format](https://zarr.dev/) for N-dimensional arrays. Zarr-Python is often used in conjunction with [Xarray](https://xarray.dev/).
+
+Zarr datasets are often very large and thus stored in object storage for cost effectiveness. As of Zarr-Python version 3.0.7 and later, you can [use Obstore as a backend](https://zarr.readthedocs.io/en/stable/user-guide/storage.html#object-store) for Zarr-Python. For large queries this [can be significantly faster](https://github.com/maxrjones/zarr-obstore-performance) than the default fsspec-based backend.
+
+## Example
+
+!!! note
+
+    This example is also [available on Github](https://github.com/developmentseed/obstore/blob/main/examples/zarr/README.md) if you'd like to test it out locally.
+
+```py
+import matplotlib.pyplot as plt
+import pystac_client
+import xarray as xr
+from zarr.storage import ObjectStore
+
+from obstore.auth.planetary_computer import PlanetaryComputerCredentialProvider
+from obstore.store import AzureStore
+
+# These first lines are specific to Zarr stored in the Microsoft Planetary
+# Computer. We use pystac-client to find the metadata for this specific Zarr
+# store.
+catalog = pystac_client.Client.open(
+    "https://planetarycomputer.microsoft.com/api/stac/v1/",
+)
+collection = catalog.get_collection("daymet-daily-hi")
+asset = collection.assets["zarr-abfs"]
+
+# We construct an AzureStore because this Zarr dataset is stored in Azure
+# storage
+azure_store = AzureStore(
+    credential_provider=PlanetaryComputerCredentialProvider.from_asset(asset),
+)
+
+# Next we use the Zarr ObjectStorage adapter and pass it to xarray.
+zarr_store = ObjectStore(azure_store, read_only=True)
+ds = xr.open_dataset(zarr_store, consolidated=True, engine="zarr")
+
+# And plot with matplotlib
+fig, ax = plt.subplots(figsize=(12, 12))
+ds.sel(time="2009")["tmax"].mean(dim="time").plot.imshow(ax=ax, cmap="inferno")
+fig.savefig("zarr-example.png")
+```
+
+This plots:
+
+![](../assets/zarr-example.png)

docs/integrations/index.md

@@ -4,6 +4,6 @@ Various integrations with external libraries exist:
 
 - [`dagster`](https://dagster.io/): Refer to [`dagster-obstore`](https://github.com/dagster-io/community-integrations/tree/main/libraries/dagster-obstore).
 - [`fsspec`](https://github.com/fsspec/filesystem_spec): Use the [`obstore.fsspec`][obstore.fsspec] module.
-- [`zarr-python`](https://zarr.readthedocs.io/en/stable/): [In progress](https://github.com/zarr-developers/zarr-python/pull/1661).
+- [`zarr-python`](https://zarr.readthedocs.io/en/stable/): Use [`zarr.storage.ObjectStore`](https://zarr.readthedocs.io/en/stable/user-guide/storage.html#object-store), included as of Zarr version `3.0.7` and later. See also the [Obstore-Zarr example](../examples/zarr.md).
 
 Know of an integration that doesn't exist here? [Edit this document](https://github.com/developmentseed/obstore/edit/main/docs/integrations.md).

examples/zarr/.python-version

@@ -0,0 +1 @@
+3.12

examples/zarr/README.md

@@ -0,0 +1,11 @@
+# Obstore Zarr example
+
+Example using Zarr with the Obstore backend.
+
+```
+uv run main.py
+```
+
+![](./zarr-example.png)
+
+This is a port of the Zarr example in the [Planetary Computer documentation](https://planetarycomputer.microsoft.com/docs/quickstarts/reading-zarr-data/).

examples/zarr/main.py

@@ -0,0 +1,33 @@
+"""Example using Zarr with the Obstore backend."""
+
+import matplotlib.pyplot as plt
+import pystac_client
+import xarray as xr
+from zarr.storage import ObjectStore
+
+from obstore.auth.planetary_computer import PlanetaryComputerCredentialProvider
+from obstore.store import AzureStore
+
+# These first lines are specific to Zarr stored in the Microsoft Planetary
+# Computer. We use pystac-client to find the metadata for this specific Zarr
+# store.
+catalog = pystac_client.Client.open(
+    "https://planetarycomputer.microsoft.com/api/stac/v1/",
+)
+collection = catalog.get_collection("daymet-daily-hi")
+asset = collection.assets["zarr-abfs"]
+
+# We construct an AzureStore because this Zarr dataset is stored in Azure
+# storage
+azure_store = AzureStore(
+    credential_provider=PlanetaryComputerCredentialProvider.from_asset(asset),
+)
+
+# Next we use the Zarr ObjectStorage adapter and pass it to xarray.
+zarr_store = ObjectStore(azure_store, read_only=True)
+ds = xr.open_dataset(zarr_store, consolidated=True, engine="zarr")
+
+# And plot with matplotlib
+fig, ax = plt.subplots(figsize=(12, 12))
+ds.sel(time="2009")["tmax"].mean(dim="time").plot.imshow(ax=ax, cmap="inferno")
+fig.savefig("zarr-example.png")

examples/zarr/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "zarr-example"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "matplotlib>=3.10.1",
+    "obstore>=0.6.0",
+    "pystac-client>=0.8.6",
+    "xarray>=2025.3.0",
+    "zarr>=3.0.8",
+]
+
+[dependency-groups]
+dev = ["ipykernel>=6.29.5"]