[python] Connect resizers to Python API

apis/python/src/tiledbsoma/_dataframe.py

@@ -417,7 +417,9 @@ def tiledbsoma_has_upgraded_domain(self) -> bool:
         """
         return self._handle.tiledbsoma_has_upgraded_domain
 
-    def resize_soma_joinid_shape(self, newshape: int) -> None:
+    def resize_soma_joinid_shape(
+        self, newshape: int, check_only: bool = False
+    ) -> Tuple[bool, str]:
         """Increases the shape of the dataframe on the ``soma_joinid`` index
         column, if it indeed is an index column, leaving all other index columns
         as-is. If the ``soma_joinid`` is not an index column, no change is made.
@@ -427,7 +429,25 @@ def resize_soma_joinid_shape(self, newshape: int) -> None:
         domain: in that case please call ``tiledbsoma_upgrade_domain`` (WIP for
         1.15).
         """
-        self._handle._handle.resize_soma_joinid_shape(newshape)
+        if check_only:
+            return cast(
+                Tuple[bool, str], self._handle._handle.can_resize_soma_joinid_shape(newshape)
+            )
+        else:
+            self._handle._handle.resize_soma_joinid_shape(newshape)
+            return (True, "")
+
+    def upgrade_soma_joinid_shape(
+        self, newshape: int, check_only: bool = False
+    ) -> Tuple[bool, str]:
+        """XXX TO WRITE"""
+        if check_only:
+            return cast(
+                Tuple[bool, str], self._handle._handle.can_upgrade_soma_joinid_shape(newshape)
+            )
+        else:
+            self._handle._handle.upgrade_soma_joinid_shape(newshape)
+            return (True, "")
 
     def __len__(self) -> int:
         """Returns the number of rows in the dataframe. Same as ``df.count``."""

apis/python/src/tiledbsoma/_sparse_nd_array.py

@@ -296,14 +296,20 @@ def read(
 
         return SparseNDArrayRead(sr, self, coords)
 
-    def resize(self, newshape: Sequence[Union[int, None]]) -> None:
+    def resize(
+        self, newshape: Sequence[Union[int, None]], dry_run: bool = False
+    ) -> Tuple[bool, str]:
         """Increases the shape of the array as specfied. Raises an error if the new
         shape is less than the current shape in any dimension. Raises an error if
         the new shape exceeds maxshape in any dimension. Raises an error if the
         array doesn't already have a shape: in that case please call
         tiledbsoma_upgrade_shape.
         """
-        self._handle.resize(newshape)
+        if dry_run:
+            return self._handle.tiledbsoma_can_resize(newshape)
+        else:
+            self._handle.resize(newshape)
+            return (True, "")
 
     def tiledbsoma_upgrade_shape(self, newshape: Sequence[Union[int, None]]) -> None:
         """Allows the array to have a resizeable shape as described in the TileDB-SOMA

apis/python/src/tiledbsoma/_tdb_handles.py

@@ -459,6 +459,12 @@ def resize(self, newshape: Sequence[Union[int, None]]) -> None:
         """Not implemented for DataFrame."""
         raise NotImplementedError
 
+    def tiledbsoma_can_resize(
+        self, newshape: Sequence[Union[int, None]]
+    ) -> Tuple[bool, str]:
+        """Not implemented for DataFrame."""
+        raise NotImplementedError
+
     def tiledbsoma_upgrade_shape(self, newshape: Sequence[Union[int, None]]) -> None:
         """Not implemented for DataFrame."""
         raise NotImplementedError
@@ -467,6 +473,18 @@ def resize_soma_joinid_shape(self, newshape: int) -> None:
         """Only implemented for DataFrame."""
         raise NotImplementedError
 
+    def can_resize_soma_joinid(self, newshape: int) -> Tuple[bool, str]:
+        """Only implemented for DataFrame."""
+        raise NotImplementedError
+
+    def upgrade_soma_joinid_shape(self, newshape: int) -> None:
+        """Only implemented for DataFrame."""
+        raise NotImplementedError
+
+    def can_upgrade_soma_joinid(self, newshape: int) -> Tuple[bool, str]:
+        """Only implemented for DataFrame."""
+        raise NotImplementedError
+
 
 class DataFrameWrapper(SOMAArrayWrapper[clib.SOMADataFrame]):
     """Wrapper around a Pybind11 SOMADataFrame handle."""
@@ -525,6 +543,26 @@ def resize_soma_joinid_shape(self, newshape: int) -> None:
         """
         self._handle.resize_soma_joinid_shape(newshape)
 
+    def can_resize_soma_joinid(self, newshape: int) -> Tuple[bool, str]:
+        """Increases the shape of the dataframe on the ``soma_joinid`` index
+        column, if it indeed is an index column, leaving all other index columns
+        as-is. If the ``soma_joinid`` is not an index column, no change is made.
+        This is a special case of ``upgrade_domain`` (WIP for 1.15), but simpler
+        to keystroke, and handles the most common case for dataframe domain
+        expansion.  Raises an error if the dataframe doesn't already have a
+        domain: in that case please call ``tiledbsoma_upgrade_domain`` (WIP for
+        1.15).
+        """
+        return cast(Tuple[bool, str], self._handle.can_resize_soma_joinid(newshape))
+
+    def upgrade_soma_joinid_shape(self, newshape: int) -> None:
+        """XXX TO WRITE"""
+        self._handle.upgrade_soma_joinid_shape(newshape)
+
+    def can_upgrade_soma_joinid(self, newshape: int) -> Tuple[bool, str]:
+        """XXX TO WRITE"""
+        return cast(Tuple[bool, str], self._handle.can_upgrade_soma_joinid(newshape))
+
 
 class PointCloudDataFrameWrapper(SOMAArrayWrapper[clib.SOMAPointCloudDataFrame]):
     """Wrapper around a Pybind11 SOMAPointCloudDataFrame handle."""
@@ -563,6 +601,16 @@ def resize(self, newshape: Sequence[Union[int, None]]) -> None:
         # https://github.com/single-cell-data/TileDB-SOMA/issues/2955
         raise NotImplementedError()
 
+    def tiledbsoma_can_resize(
+        self, newshape: Sequence[Union[int, None]]
+    ) -> Tuple[bool, str]:
+        """Supported for ``SparseNDArray``; scheduled for implementation for
+        ``DenseNDArray`` in TileDB-SOMA 1.15
+        """
+        # TODO: support current domain for dense arrays once we have core support.
+        # https://github.com/single-cell-data/TileDB-SOMA/issues/2955
+        raise NotImplementedError()
+
 
 class SparseNDArrayWrapper(SOMAArrayWrapper[clib.SOMASparseNDArray]):
     """Wrapper around a Pybind11 SparseNDArrayWrapper handle."""
@@ -593,6 +641,12 @@ def resize(self, newshape: Sequence[Union[int, None]]) -> None:
         """
         self._handle.resize(newshape)
 
+    def tiledbsoma_can_resize(
+        self, newshape: Sequence[Union[int, None]]
+    ) -> Tuple[bool, str]:
+        """XXX WRITE ME"""
+        return cast(Tuple[bool, str], self._handle.can_resize(newshape))
+
     def tiledbsoma_upgrade_shape(self, newshape: Sequence[Union[int, None]]) -> None:
         """Allows the array to have a resizeable shape as described in the TileDB-SOMA
         1.15 release notes.  Raises an error if the new shape exceeds maxshape in

apis/python/src/tiledbsoma/soma_dataframe.cc

@@ -167,6 +167,42 @@ void load_soma_dataframe(py::module& m) {
                     throw TileDBSOMAError(e.what());
                 }
             },
+            "newshape"_a)
+
+        .def(
+            "can_resize_soma_joinid_shape",
+            [](SOMADataFrame& sdf, int64_t newshape) {
+                try {
+                    return sdf.can_resize_soma_joinid_shape(
+                        newshape, "can_resize_soma_joinid_shape");
+                } catch (const std::exception& e) {
+                    throw TileDBSOMAError(e.what());
+                }
+            },
+            "newshape"_a)
+
+        .def(
+            "upgrade_soma_joinid_shape",
+            [](SOMADataFrame& sdf, int64_t newshape) {
+                try {
+                    sdf.upgrade_soma_joinid_shape(
+                        newshape, "upgrade_soma_joinid_shape");
+                } catch (const std::exception& e) {
+                    throw TileDBSOMAError(e.what());
+                }
+            },
+            "newshape"_a)
+
+        .def(
+            "can_upgrade_soma_joinid_shape",
+            [](SOMADataFrame& sdf, int64_t newshape) {
+                try {
+                    return sdf.can_upgrade_soma_joinid_shape(
+                        newshape, "can_upgrade_soma_joinid_shape");
+                } catch (const std::exception& e) {
+                    throw TileDBSOMAError(e.what());
+                }
+            },
             "newshape"_a);
 }
 }  // namespace libtiledbsomacpp

apis/python/src/tiledbsoma/soma_sparse_ndarray.cc

@@ -128,6 +128,17 @@ void load_soma_sparse_ndarray(py::module& m) {
             },
             "newshape"_a)
 
+        .def(
+            "can_resize",
+            [](SOMAArray& array, const std::vector<int64_t>& newshape) {
+                try {
+                    return array.can_resize(newshape, "can_resize");
+                } catch (const std::exception& e) {
+                    throw TileDBSOMAError(e.what());
+                }
+            },
+            "newshape"_a)
+
         .def(
             "tiledbsoma_upgrade_shape",
             [](SOMAArray& array, const std::vector<int64_t>& newshape) {

libtiledbsoma/src/soma/soma_array.cc

@@ -29,10 +29,10 @@
  *   This file defines the SOMAArray class.
  */
 
-#include "soma_array.h"
 #include <tiledb/array_experimental.h>
 #include "../utils/logger.h"
 #include "../utils/util.h"
+#include "soma_array.h"
 namespace tiledbsoma {
 using namespace tiledb;