anndata 0.12.4__tar.gz → 0.12.6__tar.gz

{anndata-0.12.4 → anndata-0.12.6}/.github/workflows/test-gpu.yml

@@ -66,7 +66,8 @@ jobs:
         uses: astral-sh/setup-uv@v6 # TODO: upgrade once cirun image supports node 24
         with:
           enable-cache: true
-          python-version: ${{ env.max_python_version }}
+          # Any Cuda 14+ will support Python 3.14: https://github.com/cupy/cupy/issues/9346
+          python-version: '3.13'  # ${{ env.max_python_version }}
 
       - name: Install AnnData
         run: |

{anndata-0.12.4 → anndata-0.12.6}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: anndata
-Version: 0.12.4
+Version: 0.12.6
 Summary: Annotated data.
 Project-URL: Documentation, https://anndata.readthedocs.io/
 Project-URL: Source, https://github.com/scverse/anndata
 Project-URL: Home-page, https://github.com/scverse/anndata
-Author: Philipp Angerer, Alex Wolf, Isaac Virshup, Sergei Rybakov
-Maintainer-email: Isaac Virshup <ivirshup@gmail.com>, Philipp Angerer <philipp.angerer@helmholtz-munich.de>, Ilan Gold <ilan.gold@helmholtz-munich.de>
+Author: Philipp Angerer, Alex Wolf, Isaac Virshup, Sergei Rybakov, Ilan Gold
+Maintainer-email: Philipp Angerer <philipp.angerer@helmholtz-munich.de>, Ilan Gold <ilan.gold@helmholtz-munich.de>
 License-Expression: BSD-3-Clause
 License-File: LICENSE
 Classifier: Environment :: Console
@@ -21,6 +21,7 @@ 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 :: Bio-Informatics
 Classifier: Topic :: Scientific/Engineering :: Visualization
 Requires-Python: >=3.11
@@ -78,7 +79,7 @@ Requires-Dist: joblib; extra == 'test'
 Requires-Dist: loompy>=3.0.5; extra == 'test'
 Requires-Dist: matplotlib; extra == 'test'
 Requires-Dist: openpyxl; extra == 'test'
-Requires-Dist: pyarrow<21; extra == 'test'
+Requires-Dist: pyarrow; extra == 'test'
 Requires-Dist: pytest-cov; extra == 'test'
 Requires-Dist: pytest-memray; extra == 'test'
 Requires-Dist: pytest-mock; extra == 'test'
@@ -100,7 +101,7 @@ Requires-Dist: joblib; extra == 'test-min'
 Requires-Dist: loompy>=3.0.5; extra == 'test-min'
 Requires-Dist: matplotlib; extra == 'test-min'
 Requires-Dist: openpyxl; extra == 'test-min'
-Requires-Dist: pyarrow<21; extra == 'test-min'
+Requires-Dist: pyarrow; extra == 'test-min'
 Requires-Dist: pytest-cov; extra == 'test-min'
 Requires-Dist: pytest-memray; extra == 'test-min'
 Requires-Dist: pytest-mock; extra == 'test-min'

anndata-0.12.6/benchmarks/benchmarks/dataset2d.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import h5py
+import numpy as np
+import pandas as pd
+import zarr
+
+import anndata as ad
+
+if TYPE_CHECKING:
+    from typing import Literal
+
+
+class Dataset2D:
+    param_names = ("store_type", "chunks", "array_type")
+    params = (
+        ("zarr", "h5ad"),
+        ((-1,), None),
+        ("cat", "numeric", "string-array", "nullable-string-array"),
+    )
+
+    def setup_cache(self):
+        n_obs = 10000
+        array_types = {
+            "numeric": np.arange(n_obs),
+            "string-array": np.array(["a"] * n_obs),
+            "nullable-string-array": pd.array(
+                ["a", pd.NA] * (n_obs // 2), dtype="string"
+            ),
+            "cat": pd.Categorical(np.array(["a"] * n_obs)),
+        }
+        for k, v in array_types.items():
+            for store in [
+                h5py.File(f"data_{k}.h5ad", mode="w"),
+                zarr.open(f"data_{k}.zarr", mode="w", zarr_version=2),
+            ]:
+                df = pd.DataFrame({"a": v}, index=[f"cell{i}" for i in range(n_obs)])
+                if writing_string_array_on_disk := (
+                    isinstance(v, np.ndarray) and df["a"].dtype == "string"
+                ):
+                    df["a"] = df["a"].to_numpy()
+                with ad.settings.override(allow_write_nullable_strings=True):
+                    ad.io.write_elem(store, "df", df)
+                if writing_string_array_on_disk:
+                    assert store["df"]["a"].attrs["encoding-type"] == "string-array"
+
+    def setup(
+        self,
+        store_type: Literal["zarr", "h5ad"],
+        chunks: None | tuple[int],
+        array_type: Literal["cat", "numeric", "string-array", "nullable-string-array"],
+    ):
+        self.store = (
+            h5py.File(f"data_{array_type}.h5ad", mode="r")
+            if store_type == "h5ad"
+            else zarr.open(f"data_{array_type}.zarr")
+        )
+        self.ds = ad.experimental.read_elem_lazy(self.store["df"], chunks=chunks)
+        self.n_obs = self.ds.shape[0]
+
+    def time_read_lazy_default(self, *_):
+        ad.experimental.read_elem_lazy(self.store["df"])
+
+    def peakmem_read_lazy_default(self, *_):
+        ad.experimental.read_elem_lazy(self.store["df"])
+
+    def time_getitem_slice(self, *_):
+        self.ds.iloc[0 : (self.n_obs // 2)].to_memory()
+
+    def peakmem_getitem_slice(self, *_):
+        self.ds.iloc[0 : (self.n_obs // 2)].to_memory()
+
+    def time_full_to_memory(self, *_):
+        self.ds.to_memory()
+
+    def peakmem_full_to_memory(self, *_):
+        self.ds.to_memory()
+
+    def time_getitem_bool_mask(self, *_):
+        self.ds.iloc[np.random.randint(0, self.n_obs, self.n_obs // 2)].to_memory()
+
+    def peakmem_getitem_bool_mask(self, *_):
+        self.ds.iloc[np.random.randint(0, self.n_obs, self.n_obs // 2)].to_memory()
+
+    def time_concat(self, *_):
+        adatas = [ad.AnnData(obs=self.ds)] * 50
+        ad.concat(adatas, join="outer")

{anndata-0.12.4 → anndata-0.12.6}/benchmarks/benchmarks/sparse_dataset.py

@@ -7,7 +7,7 @@ import zarr
 from dask.array.core import Array as DaskArray
 from scipy import sparse
 
-from anndata import AnnData
+from anndata import AnnData, concat
 from anndata._core.sparse_dataset import sparse_dataset
 from anndata._io.specs import write_elem
 from anndata.experimental import read_elem_lazy
@@ -77,3 +77,34 @@ class SparseCSRContiguousSlice:
         res = self.adata[self.index]
         if isinstance(res, DaskArray):
             res.compute()
+
+
+class SparseCSRDask:
+    filepath = "data.zarr"
+
+    def setup_cache(self):
+        X = sparse.random(
+            10_000,
+            10_000,
+            density=0.01,
+            format="csr",
+            random_state=np.random.default_rng(42),
+        )
+        g = zarr.group(self.filepath)
+        write_elem(g, "X", X)
+
+    def setup(self):
+        self.group = zarr.group(self.filepath)
+        self.adata = AnnData(X=read_elem_lazy(self.group["X"]))
+
+    def time_concat(self):
+        concat([self.adata for i in range(100)])
+
+    def peakmem_concat(self):
+        concat([self.adata for i in range(100)])
+
+    def time_read(self):
+        AnnData(X=read_elem_lazy(self.group["X"]))
+
+    def peakmem_read(self):
+        AnnData(X=read_elem_lazy(self.group["X"]))

anndata-0.12.6/ci/min-constraints.txt

@@ -0,0 +1 @@
+pyarrow<21

{anndata-0.12.4 → anndata-0.12.6}/docs/conf.py

@@ -134,6 +134,7 @@ intersphinx_mapping = dict(
     obstore=("https://developmentseed.org/obstore/latest/", None),
     pandas=("https://pandas.pydata.org/pandas-docs/stable", None),
     # TODO: switch to `/3` once docs are built with Python 3.14
+    # https://github.com/readthedocs/readthedocs.org/issues/12523
     python=("https://docs.python.org/3.13", None),
     scipy=("https://docs.scipy.org/doc/scipy", None),
     sklearn=("https://scikit-learn.org/stable", None),

anndata-0.12.6/docs/release-notes/0.12.5.md

@@ -0,0 +1,12 @@
+(v0.12.5)=
+### 0.12.5 {small}`2025-11-03`
+
+#### Bug fixes
+
+- Remove use of private `read_dataset` internally inside {func}`anndata.experimental.read_elem_lazy` {user}`ilan-gold` ({pr}`2158`)
+- Unblock version restriction on `dask` distributed writing by using threading scheduler always (see {pr}`2172`) {user}`ilan-gold` ({pr}`2183`)
+
+#### Performance
+
+- Use `name` on {func}`dask.array.map_blocks` internally when concatenating {class}`anndata.experimental.backed.Dataset2D` objects whose categoricals/nullable types must be converted to dask arrays {user}`ilan-gold` ({pr}`2121`)
+- Enable automatic sharding in zarr v3 via {attr}`anndata.settings.auto_shard_zarr_v3` (via {mod}`zarr`'s own auto sharding mechanism i.e., `shards="auto"`) for all types except {class}`numpy.recarray` {user}`ilan-gold` ({pr}`2167`)

anndata-0.12.6/docs/release-notes/0.12.6.md

@@ -0,0 +1,6 @@
+(v0.12.6)=
+### 0.12.6 {small}`2025-11-06`
+
+#### Bug fixes
+
+- Attach {class}`h5py.File` object to {class}`~anndata.AnnData` at the `file` attribute returned from  {func}`~anndata.experimental.read_lazy` {user}`ilan-gold` ({pr}`2204`)

{anndata-0.12.4 → anndata-0.12.6}/docs/tutorials/zarr-v3.md

@@ -38,7 +38,8 @@ There are two ways of opening remote `zarr` stores from the `zarr-python` packag
 Local data generally poses a different set of challenges.
 First, write speeds can be somewhat slow and second, the creation of many small files on a file system can slow down a filesystem.
 For the "many small files" problem, `zarr` has introduced {ref}`sharding <zarr:user-guide-sharding>` in the v3 file format.
-Sharding requires knowledge of the array element you are writing (such as shape or data type), though, and therefore you will need to use {func}`anndata.experimental.write_dispatched` to use sharding.
+We offer {attr}`anndata.settings.auto_shard_zarr_v3` to hook into zarr's ability to automatically compute shards, which is experimental at the moment.
+Manual sharding requires knowledge of the array element you are writing (such as shape or data type), though, and therefore you will need to use {func}`anndata.experimental.write_dispatched` to use custom sharding.
 For example, you cannot shard a 1D array with `shard` sizes `(256, 256)`.
 Here is a short example, although you should tune the sizes to your own use-case and also use the compression that makes the most sense for you:
 

{anndata-0.12.4 → anndata-0.12.6}/hatch.toml

@@ -21,7 +21,7 @@ env-vars.UV_CONSTRAINT = "ci/constraints.txt"
 overrides.matrix.deps.env-vars = [
     { if = [ "pre" ], key = "UV_PRERELEASE", value = "allow" },
     { if = [ "pre" ], key = "UV_CONSTRAINT", value = "ci/pre-deps.txt" },
-    { if = [ "min" ], key = "UV_CONSTRAINT", value = "ci/constraints.txt ci/min-deps.txt" },
+    { if = [ "min" ], key = "UV_CONSTRAINT", value = "ci/constraints.txt ci/min-constraints.txt ci/min-deps.txt" },
 ]
 overrides.matrix.deps.pre-install-commands = [
     { if = [
@@ -35,7 +35,10 @@ overrides.matrix.deps.pre-install-commands = [
 ]
 overrides.matrix.deps.python = [
     { if = [ "min" ], value = "3.11" },
-    { if = [ "stable", "pre" ], value = "3.13" },
+    # transitive test dep numba doesn’t support 3.14 in a stable release yet:
+    # https://github.com/numba/numba/issues/9957
+    { if = [ "stable" ], value = "3.13" },
+    { if = [ "pre" ], value = "3.14" },
 ]
 overrides.matrix.deps.features = [
     { if = [ "stable", "pre" ], value = "test" },

{anndata-0.12.4 → anndata-0.12.6}/pyproject.toml

@@ -12,9 +12,9 @@ authors = [
     { name = "Alex Wolf" },
     { name = "Isaac Virshup" },
     { name = "Sergei Rybakov" },
+    { name = "Ilan Gold" },
 ]
 maintainers = [
-    { name = "Isaac Virshup", email = "ivirshup@gmail.com" },
     { name = "Philipp Angerer", email = "philipp.angerer@helmholtz-munich.de" },
     { name = "Ilan Gold", email = "ilan.gold@helmholtz-munich.de" },
 ]
@@ -32,6 +32,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Scientific/Engineering :: Bio-Informatics",
     "Topic :: Scientific/Engineering :: Visualization",
 ]
@@ -96,7 +97,7 @@ test-min = [
     "httpx<1.0",         # For data downloading
     "dask[distributed]",
     "awkward>=2.3.2",
-    "pyarrow<21",        # https://github.com/scikit-hep/awkward/issues/3579
+    "pyarrow",
     "anndata[dask]",
 ]
 test = [ "anndata[test-min,lazy]" ]
@@ -164,6 +165,7 @@ filterwarnings_when_strict = [
     "default:Consolidated metadata is:UserWarning",
     "default:.*Structured:zarr.core.dtype.common.UnstableSpecificationWarning",
     "default:.*FixedLengthUTF32:zarr.core.dtype.common.UnstableSpecificationWarning",
+    "default:Automatic shard shape inference is experimental",
 ]
 python_files = "test_*.py"
 testpaths = [

{anndata-0.12.4 → anndata-0.12.6}/src/anndata/_core/anndata.py

@@ -964,7 +964,11 @@ class AnnData(metaclass=utils.DeprecationMixinMeta):  # noqa: PLW1641
     @property
     def isbacked(self) -> bool:
         """`True` if object is backed on disk, `False` otherwise."""
-        return self.filename is not None
+        is_filename_none = self.filename is not None
+        is_x_none = (
+            getattr(self._adata_ref if self._is_view else self, "_X", None) is None
+        )
+        return is_filename_none and is_x_none
 
     @property
     def is_view(self) -> bool:
@@ -1418,7 +1422,7 @@ class AnnData(metaclass=utils.DeprecationMixinMeta):  # noqa: PLW1641
 
     @old_positionals("copy")
     def to_memory(self, *, copy: bool = False) -> AnnData:
-        """Return a new AnnData object with all backed arrays loaded into memory.
+        """Return a new AnnData object with all non-in-memory arrays loaded into memory.
 
         Params
         ------

{anndata-0.12.4 → anndata-0.12.6}/src/anndata/_core/file_backing.py

@@ -27,15 +27,24 @@ class AnnDataFileManager:
     def __init__(
         self,
         adata: anndata.AnnData,
-        filename: PathLike[str] | str | None = None,
-        filemode: Literal["r", "r+"] | None = None,
+        file_name: PathLike[str] | str | None = None,
+        file_mode: Literal["r", "r+"] | None = None,
+        file_obj: h5py.File | None = None,
     ):
+        if file_obj is not None and (file_name is not None or file_mode is not None):
+            msg = "Cannot provide both a h5py.File and the name and/or mode arguments to constructor"
+            raise ValueError(msg)
         self._adata_ref = weakref.ref(adata)
-        self.filename = filename
-        self._filemode = filemode
-        self._file = None
-        if filename:
-            self.open()
+        if file_obj is not None:
+            self.filename = filename(file_obj)
+            self._filemode = file_obj.mode
+            self._file = file_obj
+        else:
+            self.filename = file_name
+            self._filemode = file_mode
+            self._file = file_obj
+            if file_name and not self._file:
+                self.open()
 
     def __getstate__(self):
         state = self.__dict__.copy()
@@ -82,16 +91,16 @@ class AnnDataFileManager:
         return self._filename
 
     @filename.setter
-    def filename(self, filename: PathLike[str] | str | None):
-        self._filename = None if filename is None else Path(filename)
+    def filename(self, file_name: PathLike[str] | str | None):
+        self._filename = None if file_name is None else Path(file_name)
 
     def open(
         self,
-        filename: PathLike[str] | str | None = None,
+        file_name: PathLike[str] | str | None = None,
         filemode: Literal["r", "r+"] | None = None,
     ):
-        if filename is not None:
-            self.filename = filename
+        if file_name is not None:
+            self.filename = file_name
         if filemode is not None:
             self._filemode = filemode
         if self.filename is None:

{anndata-0.12.4 → anndata-0.12.6}/src/anndata/_core/merge.py

@@ -4,6 +4,7 @@ Code for merging/ concatenating AnnData objects.
 
 from __future__ import annotations
 
+import uuid
 from collections import OrderedDict
 from collections.abc import Callable, Mapping, MutableSet
 from functools import partial, reduce, singledispatch
@@ -1251,6 +1252,7 @@ def make_dask_col_from_extension_dtype(
             chunks=chunk_size,
             meta=np.array([], dtype=dtype),
             dtype=dtype,
+            name=f"{uuid.uuid4()}/{base_path_or_zarr_group}/{elem_name}-{dtype}",
         )
 
     return da.from_array(col.values, chunks=-1)  # in-memory

{anndata-0.12.4 → anndata-0.12.6}/src/anndata/_io/specs/lazy_methods.py

@@ -25,7 +25,7 @@ from anndata.compat import (
     ZarrGroup,
 )
 
-from .registry import _LAZY_REGISTRY, IOSpec
+from .registry import _LAZY_REGISTRY, IOSpec, read_elem
 
 if TYPE_CHECKING:
     from collections.abc import Generator, Mapping, Sequence
@@ -195,6 +195,9 @@ def resolve_chunks(
     return elem.chunks
 
 
+# TODO: `map_blocks` of a string array in h5py is so insanely slow on benchmarking that in the case someone has
+# a pure string annotation (not categoricals! or nullables strings!), it's probably better to pay the memory penalty.
+# In the long run, it might be good to figure out what exactly is going on here but for now, this will do.
 @_LAZY_REGISTRY.register_read(H5Array, IOSpec("string-array", "0.2.0"))
 def read_h5_string_array(
     elem: H5Array,
@@ -204,10 +207,8 @@ def read_h5_string_array(
 ) -> DaskArray:
     import dask.array as da
 
-    from anndata._io.h5ad import read_dataset
-
     chunks = resolve_chunks(elem, chunks, tuple(elem.shape))
-    return da.from_array(read_dataset(elem), chunks=chunks)
+    return da.from_array(read_elem(elem), chunks=chunks)
 
 
 @_LAZY_REGISTRY.register_read(H5Array, IOSpec("array", "0.2.0"))
@@ -303,7 +304,7 @@ def read_dataframe(
     # which is used below as well.
     if not use_range_index:
         dim_name = elem.attrs["_index"]
-        # no sense in reading this in multiple times
+        # no sense in reading this in multiple times since xarray requires an in-memory index
         index = elem_dict[dim_name].compute()
     else:
         dim_name = DUMMY_RANGE_INDEX_KEY

{anndata-0.12.4 → anndata-0.12.6}/src/anndata/_io/specs/methods.py

@@ -102,6 +102,12 @@ def zarr_v3_compressor_compat(dataset_kwargs) -> dict:
     return dataset_kwargs
 
 
+def zarr_v3_sharding(dataset_kwargs) -> dict:
+    if "shards" not in dataset_kwargs and ad.settings.auto_shard_zarr_v3:
+        dataset_kwargs = {**dataset_kwargs, "shards": "auto"}
+    return dataset_kwargs
+
+
 def _to_cpu_mem_wrapper(write_func):
     """
     Wrapper to bring cupy types into cpu memory before writing.
@@ -432,6 +438,7 @@ def write_basic(
         f.create_dataset(k, data=elem, shape=elem.shape, dtype=dtype, **dataset_kwargs)
     else:
         dataset_kwargs = zarr_v3_compressor_compat(dataset_kwargs)
+        dataset_kwargs = zarr_v3_sharding(dataset_kwargs)
         f.create_array(k, shape=elem.shape, dtype=dtype, **dataset_kwargs)
         # see https://github.com/zarr-developers/zarr-python/discussions/2712
         if isinstance(elem, ZarrArray | H5Array):
@@ -506,26 +513,17 @@ def write_basic_dask_dask_dense(
     dataset_kwargs: Mapping[str, Any] = MappingProxyType({}),
 ):
     import dask.array as da
-    import dask.config as dc
-
-    is_distributed = dc.get("scheduler", None) == "dask.distributed"
-    is_h5 = isinstance(f, H5Group)
-    if is_distributed and is_h5:
-        msg = "Cannot write dask arrays to hdf5 when using distributed scheduler"
-        raise ValueError(msg)
 
     dataset_kwargs = dataset_kwargs.copy()
+    is_h5 = isinstance(f, H5Group)
     if not is_h5:
         dataset_kwargs = zarr_v3_compressor_compat(dataset_kwargs)
-        # See https://github.com/dask/dask/issues/12109
-        if Version(version("dask")) < Version("2025.4.0") and is_distributed:
-            msg = "Writing dense data with a distributed scheduler to zarr could produce corrupted data with a Lock and will error without one when dask is older than 2025.4.0: https://github.com/dask/dask/issues/12109"
-            raise RuntimeError(msg)
+        dataset_kwargs = zarr_v3_sharding(dataset_kwargs)
     if is_zarr_v2() or is_h5:
         g = f.require_dataset(k, shape=elem.shape, dtype=elem.dtype, **dataset_kwargs)
     else:
         g = f.require_array(k, shape=elem.shape, dtype=elem.dtype, **dataset_kwargs)
-    da.store(elem, g)
+    da.store(elem, g, scheduler="threads")
 
 
 @_REGISTRY.register_read(H5Array, IOSpec("array", "0.2.0"))
@@ -626,6 +624,7 @@ def write_vlen_string_array_zarr(
         filters, fill_value = None, None
         if f.metadata.zarr_format == 2:
             filters, fill_value = [VLenUTF8()], ""
+        dataset_kwargs = zarr_v3_sharding(dataset_kwargs)
         f.create_array(
             k,
             shape=elem.shape,
@@ -694,6 +693,9 @@ def write_recarray_zarr(
     else:
         dataset_kwargs = dataset_kwargs.copy()
         dataset_kwargs = zarr_v3_compressor_compat(dataset_kwargs)
+        # https://github.com/zarr-developers/zarr-python/issues/3546
+        # if "shards" not in dataset_kwargs and ad.settings.auto_shard_zarr_v3:
+        #     dataset_kwargs = {**dataset_kwargs, "shards": "auto"}
         f.create_array(k, shape=elem.shape, dtype=elem.dtype, **dataset_kwargs)
         f[k][...] = elem
 
@@ -730,6 +732,7 @@ def write_sparse_compressed(
                 attr_name, data=attr, shape=attr.shape, dtype=dtype, **dataset_kwargs
             )
         else:
+            dataset_kwargs = zarr_v3_sharding(dataset_kwargs)
             arr = g.create_array(
                 attr_name, shape=attr.shape, dtype=dtype, **dataset_kwargs
             )

{anndata-0.12.4 → anndata-0.12.6}/src/anndata/_settings.py

@@ -17,7 +17,7 @@ from .compat import is_zarr_v2, old_positionals
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Sequence
-    from typing import Any, TypeGuard
+    from typing import Any, Self, TypeGuard
 
 T = TypeVar("T")
 
@@ -55,7 +55,7 @@ class RegisteredOption(NamedTuple, Generic[T]):
     option: str
     default_value: T
     description: str
-    validate: Callable[[T], None]
+    validate: Callable[[T, SettingsManager], None]
     type: object
 
     describe = describe
@@ -206,7 +206,7 @@ class SettingsManager:
         *,
         default_value: T,
         description: str,
-        validate: Callable[[T], None],
+        validate: Callable[[T, Self], None],
         option_type: object | None = None,
         get_from_env: Callable[[str, T], T] = lambda x, y: y,
     ) -> None:
@@ -229,7 +229,7 @@ class SettingsManager:
             Default behavior is to return `default_value` without checking the environment.
         """
         try:
-            validate(default_value)
+            validate(default_value, self)
         except (ValueError, TypeError) as e:
             e.add_note(f"for option {option!r}")
             raise e
@@ -307,7 +307,7 @@ class SettingsManager:
             )
             raise AttributeError(msg)
         registered_option = self._registered_options[option]
-        registered_option.validate(val)
+        registered_option.validate(val, self)
         self._config[option] = val
 
     def __getattr__(self, option: str) -> object:
@@ -364,10 +364,13 @@ class SettingsManager:
         """
         restore = {a: getattr(self, a) for a in overrides}
         try:
-            for attr, value in overrides.items():
-                setattr(self, attr, value)
+            # Preserve order so that settings that depend on each other can be overridden together i.e., always override zarr version before sharding
+            for k in self._config:
+                if k in overrides:
+                    setattr(self, k, overrides.get(k))
             yield None
         finally:
+            # TODO: does the order need to be preserved when restoring?
             for attr, value in restore.items():
                 setattr(self, attr, value)
 
@@ -395,7 +398,7 @@ V = TypeVar("V")
 
 
 def gen_validator(_type: type[V]) -> Callable[[V], None]:
-    def validate_type(val: V) -> None:
+    def validate_type(val: V, settings: SettingsManager) -> None:
         if not isinstance(val, _type):
             msg = f"{val} not valid {_type}"
             raise TypeError(msg)
@@ -434,14 +437,28 @@ settings.register(
 )
 
 
-def validate_zarr_write_format(format: int):
-    validate_int(format)
+def validate_zarr_write_format(format: int, settings: SettingsManager):
+    validate_int(format, settings)
     if format not in {2, 3}:
         msg = "non-v2 zarr on-disk format not supported"
         raise ValueError(msg)
     if format == 3 and is_zarr_v2():
         msg = "Cannot write v3 format against v2 package"
         raise ValueError(msg)
+    if format == 2 and getattr(settings, "auto_shard_zarr_v3", False):
+        msg = "Cannot set `zarr_write_format` to 2 with autosharding on.  Please set to `False` `anndata.settings.auto_shard_zarr_v3`"
+        raise ValueError(msg)
+
+
+def validate_zarr_sharding(auto_shard: bool, settings: SettingsManager):  # noqa: FBT001
+    validate_bool(auto_shard, settings)
+    if auto_shard:
+        if is_zarr_v2():
+            msg = "Cannot use sharding with `zarr-python<3`. Please upgrade package and set `anndata.settings.zarr_write_format` to 3."
+            raise ValueError(msg)
+        if settings.zarr_write_format == 2:
+            msg = "Cannot shard v2 format data. Please set `anndata.settings.zarr_write_format` to 3."
+            raise ValueError(msg)
 
 
 settings.register(
@@ -458,8 +475,8 @@ settings.register(
 )
 
 
-def validate_sparse_settings(val: Any) -> None:
-    validate_bool(val)
+def validate_sparse_settings(val: Any, settings: SettingsManager) -> None:
+    validate_bool(val, settings)
 
 
 settings.register(
@@ -486,6 +503,14 @@ settings.register(
     get_from_env=check_and_get_bool,
 )
 
+settings.register(
+    "auto_shard_zarr_v3",
+    default_value=False,
+    description="Whether or not to use zarr's auto computation of sharding for v3.  For v2 this setting will be ignored. The setting will apply to all calls to anndata's writing mechanism (write_zarr / write_elem) and will **not** override any user-defined kwargs for shards.",
+    validate=validate_zarr_sharding,
+    get_from_env=check_and_get_bool,
+)
+
 
 ##################################################################################
 ##################################################################################

{anndata-0.12.4 → anndata-0.12.6}/src/anndata/_settings.pyi

@@ -2,7 +2,7 @@ from collections.abc import Callable as Callable
 from collections.abc import Generator, Iterable
 from contextlib import contextmanager
 from dataclasses import dataclass
-from typing import Literal, TypeVar
+from typing import Literal, Self, TypeVar
 
 _T = TypeVar("_T")
 
@@ -25,7 +25,7 @@ class SettingsManager:
         *,
         default_value: _T,
         description: str,
-        validate: Callable[[_T], None],
+        validate: Callable[[_T, Self], None],
         option_type: object | None = None,
         get_from_env: Callable[[str, _T], _T] = ...,
     ) -> None: ...
@@ -46,5 +46,6 @@ class _AnnDataSettingsManager(SettingsManager):
     use_sparse_array_on_read: bool = False
     min_rows_for_chunked_h5_copy: int = 1000
     disallow_forward_slash_in_h5ad: bool = False
+    auto_shard_zarr_v3: bool = False
 
 settings: _AnnDataSettingsManager