Add overlay/stack/concat API

This adds C++ and Python APIs for creating a stack-driver-backed
TensorStore from a given sequence of layers.

This also extends the capabilities of the stack driver to also support
layers backed by an already-open TensorStore rather than a Spec.

PiperOrigin-RevId: 581131840
Change-Id: Id27347e1ad90aa1d5c62b433759e16c852610e1e

docs/conf.py

@@ -217,7 +217,11 @@
 
 """
 
-python_module_names_to_strip_from_xrefs = ['tensorstore']
+python_module_names_to_strip_from_xrefs = [
+    'tensorstore',
+    'collections.abc',
+    'numbers',
+]
 
 python_type_aliases = {
     'dtype': 'numpy.dtype',

python/tensorstore/BUILD

@@ -50,6 +50,7 @@ pybind11_py_extension(
         ":python_imports",
         ":serialization",
         ":spec",
+        ":stack",
         ":tensorstore_class",
         ":tensorstore_module_components",
         ":transaction",
@@ -182,6 +183,16 @@ tensorstore_pytest_test(
     ],
 )
 
+tensorstore_pytest_test(
+    name = "stack_test",
+    size = "small",
+    srcs = ["tests/stack_test.py"],
+    deps = [
+        ":tensorstore",
+        "@pypa_numpy//:numpy",
+    ],
+)
+
 pybind11_cc_library(
     name = "subscript_method",
     hdrs = ["subscript_method.h"],
@@ -830,6 +841,29 @@ pybind11_cc_library(
     alwayslink = True,
 )
 
+pybind11_cc_library(
+    name = "stack",
+    srcs = ["stack.cc"],
+    deps = [
+        ":dim_expression",
+        ":index",
+        ":keyword_arguments",
+        ":result_type_caster",
+        ":sequence_parameter",
+        ":spec",
+        ":tensorstore_class",
+        ":tensorstore_module_components",
+        "//tensorstore",
+        "//tensorstore:index",
+        "//tensorstore:spec",
+        "//tensorstore:stack",
+        "//tensorstore/internal:global_initializer",
+        "//tensorstore/util:executor",
+        "@com_github_pybind_pybind11//:pybind11",
+    ],
+    alwayslink = True,
+)
+
 pybind11_cc_library(
     name = "cast",
     srcs = ["cast.cc"],