scverse · ilan-gold · Sep 19, 2024 · Sep 19, 2024 · Sep 19, 2024 · Sep 19, 2024
diff --git a/docs/api.md b/docs/api.md
@@ -33,8 +33,8 @@ Reading anndata’s native formats `.h5ad` and `zarr`.
 .. autosummary::
    :toctree: generated/
 
-   read_h5ad
-   read_zarr
+   io.read_h5ad
+   io.read_zarr
 ```
 
 Reading individual portions ({attr}`~AnnData.obs`, {attr}`~AnnData.varm` etc.) of the {class}`AnnData` object.
@@ -43,8 +43,8 @@ Reading individual portions ({attr}`~AnnData.obs`, {attr}`~AnnData.varm` etc.) o
 .. autosummary::
    :toctree: generated/
 
-   read_elem
-   sparse_dataset
+   io.read_elem
+   io.sparse_dataset
 ```
 
 Reading file formats that cannot represent all aspects of {class}`AnnData` objects.
@@ -57,13 +57,13 @@ You might have more success by assembling the {class}`AnnData` object yourself f
 .. autosummary::
    :toctree: generated/
 
-   read_csv
-   read_excel
-   read_hdf
-   read_loom
-   read_mtx
-   read_text
-   read_umi_tools
+   io.read_csv
+   io.read_excel
+   io.read_hdf
+   io.read_loom
+   io.read_mtx
+   io.read_text
+   io.read_umi_tools
 ```
 
 ## Writing
@@ -84,7 +84,7 @@ Writing individual portions ({attr}`~AnnData.obs`, {attr}`~AnnData.varm` etc.) o
 .. autosummary::
    :toctree: generated/
 
-   write_elem
+   io.write_elem
 ```
 
 Writing formats that cannot represent all aspects of {class}`AnnData` objects.

diff --git a/docs/benchmark-read-write.ipynb b/docs/benchmark-read-write.ipynb
@@ -159,7 +159,7 @@
    ],
    "source": [
     "%%time\n",
-    "adata = ad.read_loom(\"test.loom\")"
+    "adata = ad.io.read_loom(\"test.loom\")"
    ]
   }
  ],

diff --git a/docs/fileformat-prose.md b/docs/fileformat-prose.md
@@ -635,7 +635,7 @@ function:
 
 ```python
 >>> import awkward as ak
->>> from anndata import read_elem
+>>> from anndata.io import read_elem
 >>> awkward_group = store["varm/transcript"]
 >>> ak.from_buffers(
 ...     awkward_group.attrs["form"],

diff --git a/docs/release-notes/0.10.0.md b/docs/release-notes/0.10.0.md
@@ -13,7 +13,7 @@
 
 * Concatenate on-disk anndata objects with {func}`anndata.experimental.concat_on_disk` {pr}`955` {user}`selmanozleyen`
 * AnnData can now hold dask arrays with `scipy.sparse.spmatrix` chunks {pr}`1114` {user}`ivirshup`
-* Public API for interacting with on disk sparse arrays: {func}`~anndata.sparse_dataset`, {class}`~anndata.abc.CSRDataset`, and {class}`~anndata.abc.CSCDataset` {pr}`765` {user}`ilan-gold` {user}`ivirshup`
+* Public API for interacting with on disk sparse arrays: {func}`~anndata.io.sparse_dataset`, {class}`~anndata.abc.CSRDataset`, and {class}`~anndata.abc.CSCDataset` {pr}`765` {user}`ilan-gold` {user}`ivirshup`
 * Improved performance for simple slices of OOC sparse arrays {pr}`1131` {user}`ivirshup`
 
 **Improved errors and warnings**
@@ -37,7 +37,7 @@
 
 #### Deprecations
 
-* Deprecate `anndata.read`, which was just an alias for {func}`anndata.read_h5ad` {pr}`1108` {user}`ivirshup`.
+* Deprecate `anndata.read`, which was just an alias for {func}`anndata.io.read_h5ad` {pr}`1108` {user}`ivirshup`.
 * `dtype` argument to `AnnData` constructor is now deprecated {pr}`1153` {user}`ivirshup`
 
 #### Bug fixes

diff --git a/docs/release-notes/0.10.2.md b/docs/release-notes/0.10.2.md
@@ -4,7 +4,7 @@
 #### Bug fixes
 
 * Added compatibility layer for packages relying on `anndata._core.sparse_dataset.SparseDataset`.
-  Note that this API is *deprecated* and new code should use {class}`~anndata.abc.CSRDataset`, {class}`~anndata.abc.CSCDataset`, and {func}`~anndata.sparse_dataset` instead.
+  Note that this API is *deprecated* and new code should use {class}`~anndata.abc.CSRDataset`, {class}`~anndata.abc.CSCDataset`, and {func}`~anndata.io.sparse_dataset` instead.
   {pr}`1185` {user}`ivirshup`
 * Handle deprecation warning from `pd.Categorical.map` thrown during `anndata.concat` {pr}`1189` {user}`flying-sheep` {user}`ivirshup`
 * Fixed extra steps being included in IO tracebacks {pr}`1193` {user}`flying-sheep`

diff --git a/docs/release-notes/0.10.8.md b/docs/release-notes/0.10.8.md
@@ -5,8 +5,8 @@
 
 * Write out `64bit` indptr when appropriate for {func}`~anndata.experimental.concat_on_disk` {pr}`1493` {user}`ilan-gold`
 * Support for Numpy 2 {pr}`1499` {user}`flying-sheep`
-* Fix {func}`~anndata.sparse_dataset` docstring test on account of new {mod}`scipy` version {pr}`1514` {user}`ilan-gold`
+* Fix {func}`~anndata.io.sparse_dataset` docstring test on account of new {mod}`scipy` version {pr}`1514` {user}`ilan-gold`
 
 #### Documentation
 
-* Improved example for {func}`~anndata.sparse_dataset` {pr}`1468` {user}`ivirshup`
+* Improved example for {func}`~anndata.io.sparse_dataset` {pr}`1468` {user}`ivirshup`
diff --git a/docs/release-notes/0.11.0rc1.md b/docs/release-notes/0.11.0rc1.md
@@ -4,7 +4,7 @@
 ### Breaking changes
 
 - Removed deprecated modules `anndata.core` and `anndata.readwrite` {user}`ivirshup` ({pr}`1197`)
-- No longer export `sparse_dataset` from `anndata.experimental`, instead exporting {func}`anndata.sparse_dataset` {user}`ilan-gold` ({pr}`1642`)
+- No longer export `sparse_dataset` from `anndata.experimental`, instead exporting {func}`anndata.io.sparse_dataset` {user}`ilan-gold` ({pr}`1642`)
 - Move `RWAble` and `InMemoryElem` out of `experimental`, renaming `RWAble` to {type}`~anndata.typing.AxisStorable` and `InMemoryElem` to {type}`~anndata.typing.RWAble` {user}`ilan-gold` ({pr}`1643`)
 
 ### Development Process
@@ -28,5 +28,5 @@
 - Read and write support for nullable string arrays ({class}`pandas.arrays.StringArray`).
   Use pandas’ {doc}`pandas:user_guide/options` `mode.string_storage` to control which storage mode is used when reading `dtype="string"` columns.
   {user}`flying-sheep` ({pr}`1558`)
-- Export {func}`~anndata.write_elem` and {func}`~anndata.read_elem` directly from the main package instead of `experimental` {user}`ilan-gold` ({pr}`1598`)
-- Allow reading sparse data (via {func}`~anndata.read_elem` or {func}`~anndata.sparse_dataset`) into either {class}`scipy.sparse.csr_array` or {class}`scipy.sparse.csc_array` via {attr}`anndata.settings.shall_use_sparse_array_on_read` {user}`ilan-gold` ({pr}`1633`)
+- Export {func}`~anndata.io.write_elem` and {func}`~anndata.io.read_elem` directly from the main package instead of `experimental` {user}`ilan-gold` ({pr}`1598`)
+- Allow reading sparse data (via {func}`~anndata.io.read_elem` or {func}`~anndata.io.sparse_dataset`) into either {class}`scipy.sparse.csr_array` or {class}`scipy.sparse.csc_array` via {attr}`anndata.settings.shall_use_sparse_array_on_read` {user}`ilan-gold` ({pr}`1633`)
diff --git a/docs/release-notes/0.5.0.md b/docs/release-notes/0.5.0.md
@@ -5,6 +5,6 @@
 - automatically remove unused categories after slicing
 - read/write [.loom](https://loompy.org) files using loompy 2
 - fixed read/write for a few text file formats
-- read [UMI tools] files: {func}`~anndata.read_umi_tools`
+- read [UMI tools] files: {func}`~anndata.io.read_umi_tools`
 
 [umi tools]: https://github.com/CGATOxford/UMI-tools
diff --git a/docs/release-notes/0.6.x.md b/docs/release-notes/0.6.x.md
@@ -15,9 +15,9 @@
   `0.6.16` {smaller}`A Wolf`
 - maintain dtype upon copy.
   `0.6.13` {smaller}`A Wolf`
-- {attr}`~anndata.AnnData.layers` inspired by [.loom](https://loompy.org) files allows their information lossless reading via {func}`~anndata.read_loom`.
+- {attr}`~anndata.AnnData.layers` inspired by [.loom](https://loompy.org) files allows their information lossless reading via {func}`~anndata.io.read_loom`.
   `0.6.7`–`0.6.9` {pr}`46` & {pr}`48` {smaller}`S Rybakov`
-- support for reading zarr files: {func}`~anndata.read_zarr`
+- support for reading zarr files: {func}`~anndata.io.read_zarr`
   `0.6.7` {pr}`38` {smaller}`T White`
 - initialization from pandas DataFrames
   `0.6.` {smaller}`A Wolf`

diff --git a/docs/release-notes/0.7.6.md b/docs/release-notes/0.7.6.md
@@ -18,5 +18,5 @@
 
 #### Deprecations
 
-- Passing positional arguments to {func}`anndata.read_loom` besides the path is now deprecated {pr}`538` {smaller}`I Virshup`
-- {func}`anndata.read_loom` arguments `obsm_names` and `varm_names` are now deprecated in favour of `obsm_mapping` and `varm_mapping` {pr}`538` {smaller}`I Virshup`
+- Passing positional arguments to {func}`anndata.io.read_loom` besides the path is now deprecated {pr}`538` {smaller}`I Virshup`
+- {func}`anndata.io.read_loom` arguments `obsm_names` and `varm_names` are now deprecated in favour of `obsm_mapping` and `varm_mapping` {pr}`538` {smaller}`I Virshup`
diff --git a/docs/release-notes/0.8.0.md b/docs/release-notes/0.8.0.md
@@ -15,14 +15,14 @@ This should make it much easier to support new datatypes, use partial access, an
 
 - Each element should be tagged with an `encoding_type` and `encoding_version`. See updated docs on the {doc}`file format </fileformat-prose>`
 - Support for nullable integer and boolean data arrays. More data types to come!
-- Experimental support for low level access to the IO API via {func}`~anndata.read_elem` and {func}`~anndata.write_elem`
+- Experimental support for low level access to the IO API via {func}`~anndata.io.read_elem` and {func}`~anndata.io.write_elem`
 
 #### Features
 
 - Added PyTorch dataloader {class}`~anndata.experimental.AnnLoader` and lazy concatenation object {class}`~anndata.experimental.AnnCollection`. See the [tutorials] {pr}`416` {smaller}`S Rybakov`
 - Compatibility with `h5ad` files written from Julia {pr}`569` {smaller}`I Kats`
 - Many logging messages that should have been warnings are now warnings {pr}`650` {smaller}`I Virshup`
-- Significantly more efficient {func}`anndata.read_umi_tools` {pr}`661` {smaller}`I Virshup`
+- Significantly more efficient {func}`anndata.io.read_umi_tools` {pr}`661` {smaller}`I Virshup`
 - Fixed deepcopy of a copy of a view retaining sparse matrix view mixin type {pr}`670` {smaller}`M Klein`
 - In many cases {attr}`~anndata.AnnData.X` can now be `None` {pr}`463` {smaller}`R Cannoodt` {pr}`677` {smaller}`I Virshup`. Remaining work is documented in {issue}`467`.
 - Removed hard `xlrd` dependency {smaller}`I Virshup`

diff --git a/docs/release-notes/0.9.0.md b/docs/release-notes/0.9.0.md
@@ -21,7 +21,7 @@
 
 - {doc}`/interoperability`: new page on interoperability with other packages {pr}`831` {user}`ivirshup`
 
-- Expanded docstring more documentation for `backed` argument of {func}`anndata.read_h5ad` {pr}`812` {user}`jeskowagner`
+- Expanded docstring more documentation for `backed` argument of {func}`anndata.io.read_h5ad` {pr}`812` {user}`jeskowagner`
 
 - Documented how to use alternative compression methods for the `h5ad` file format, see {meth}`AnnData.write_h5ad() <anndata.AnnData.write_h5ad>` {pr}`857` {user}`nigeil`
 

diff --git a/docs/release-notes/0.9.2.md b/docs/release-notes/0.9.2.md
@@ -6,4 +6,4 @@
 * Views of `awkward.Array`s now work with `awkward>=2.3` {pr}`1040` {user}`ivirshup`
 * Fix ufuncs of views like `adata.X[:10].cov(axis=0)` returning views {pr}`1043` {user}`flying-sheep`
 * Fix instantiating AnnData where `.X` is a `DataFrame` with an integer valued index  {pr}`1002` {user}`flying-sheep`
-* Fix {func}`~anndata.read_zarr` when used on `zarr.Group` {pr}`1057` {user}`ivirshup`
+* Fix {func}`~anndata.io.read_zarr` when used on `zarr.Group` {pr}`1057` {user}`ivirshup`
diff --git a/src/anndata/__init__.py b/src/anndata/__init__.py
@@ -2,6 +2,12 @@
 
 from __future__ import annotations
 
+from types import MappingProxyType
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing import Any
+
 try:  # See https://github.com/maresb/hatch-vcs-footgun-example
     from setuptools_scm import get_version
 
@@ -24,32 +30,21 @@
 from ._core.anndata import AnnData
 from ._core.merge import concat
 from ._core.raw import Raw
-from ._core.sparse_dataset import sparse_dataset
-from ._io import (
-    read_csv,
-    read_excel,
-    read_h5ad,
-    read_hdf,
-    read_loom,
-    read_mtx,
-    read_text,
-    read_umi_tools,
-    read_zarr,
-)
-from ._io.specs import read_elem, write_elem
 from ._settings import settings
 from ._warnings import (
     ExperimentalFeatureWarning,
     ImplicitModificationWarning,
     OldFormatWarning,
     WriteWarning,
 )
+from .io import read_h5ad, read_zarr
+from .utils import module_get_attr_redirect
 
 # Submodules need to be imported last
-from . import abc, experimental, typing  # noqa: E402 isort: skip
+from . import abc, experimental, typing, io  # noqa: E402 isort: skip
 
 # We use these in tests by attribute access
-from . import _io, logging  # noqa: F401, E402 isort: skip
+from . import logging  # noqa: F401, E402 isort: skip
 
 
 def read(*args, **kwargs):
@@ -63,6 +58,26 @@ def read(*args, **kwargs):
     return read_h5ad(*args, **kwargs)
 
 
+_DEPRECATED = MappingProxyType(
+    dict(
+        (method, f"io.{method}")
+        for method in [
+            "read_loom",
+            "read_hdf",
+            "read_excel",
+            "read_umi_tools",
+            "read_csv",
+            "read_text",
+            "read_mtx",
+        ]
+    )
+)
+
+
+def __getattr__(attr_name: str) -> Any:
+    return module_get_attr_redirect(attr_name, deprecated_mapping=_DEPRECATED)
+
+
 __all__ = [
     # Attributes
     "__version__",
@@ -71,23 +86,15 @@ def read(*args, **kwargs):
     "abc",
     "experimental",
     "typing",
+    "io",
     # Classes
     "AnnData",
     "Raw",
     # Functions
     "concat",
-    "sparse_dataset",
-    "read_h5ad",
-    "read_loom",
-    "read_hdf",
-    "read_excel",
-    "read_umi_tools",
-    "read_csv",
-    "read_text",
-    "read_mtx",
     "read_zarr",
-    "read_elem",
-    "write_elem",
+    "read_h5ad",
+    "read",
     # Warnings
     "OldFormatWarning",
     "WriteWarning",

diff --git a/src/anndata/_core/anndata.py b/src/anndata/_core/anndata.py
@@ -134,15 +134,15 @@
 
     See Also
     --------
-    read_h5ad
-    read_csv
-    read_excel
-    read_hdf
-    read_loom
-    read_zarr
-    read_mtx
-    read_text
-    read_umi_tools
+    io.read_h5ad
+    io.read_csv
+    io.read_excel
+    io.read_hdf
+    io.read_loom
+    io.read_zarr
+    io.read_mtx
+    io.read_text
+    io.read_umi_tools
 
     Notes
     -----
@@ -996,7 +996,7 @@
             self._X = None
 
     def _set_backed(self, attr, value):
-        from .._io.utils import write_attribute
+        from ..io.utils import write_attribute
 
         write_attribute(self.file._file, attr, value)
 
@@ -1399,7 +1399,7 @@
         .. code:: python
 
             import anndata
-            backed = anndata.read_h5ad("file.h5ad", backed="r")
+            backed = anndata.io.read_h5ad("file.h5ad", backed="r")
             mem = backed[backed.obs["cluster"] == "a", :].to_memory()
         """
         new = {}
@@ -1444,7 +1444,7 @@
             else:
                 return self._mutated_copy()
         else:
-            from .._io import read_h5ad, write_h5ad
+            from ..io import read_h5ad, write_h5ad
 
             if filename is None:
                 raise ValueError(
@@ -1858,7 +1858,7 @@
             Sparse arrays in AnnData object to write as dense. Currently only
             supports `X` and `raw/X`.
         """
-        from .._io import write_h5ad
+        from ..io import write_h5ad
 
         if filename is None and not self.isbacked:
             raise ValueError("Provide a filename!")
@@ -1894,7 +1894,7 @@
         sep
              Separator for the data.
         """
-        from .._io import write_csvs
+        from ..io import write_csvs
 
         write_csvs(dirname, self, skip_data=skip_data, sep=sep)
 
@@ -1907,7 +1907,7 @@
         filename
             The filename.
         """
-        from .._io import write_loom
+        from ..io import write_loom
 
         write_loom(filename, self, write_obsm_varm=write_obsm_varm)
 
@@ -1926,7 +1926,7 @@
         chunks
             Chunk shape.
         """
-        from .._io import write_zarr
+        from ..io import write_zarr
 
         write_zarr(store, self, chunks=chunks)
 

diff --git a/src/anndata/_core/sparse_dataset.py b/src/anndata/_core/sparse_dataset.py
@@ -613,8 +613,8 @@ def sparse_dataset(group: GroupStorageType) -> abc.CSRDataset | abc.CSCDataset:
 
     >>> import scanpy as sc
     >>> import h5py
-    >>> from anndata import sparse_dataset
-    >>> from anndata import read_elem
+    >>> from anndata.io import sparse_dataset
+    >>> from anndata.io import read_elem
     >>> sc.datasets.pbmc68k_reduced().raw.to_adata().write_h5ad("pbmc.h5ad")
 
     Initialize a sparse dataset from storage