[python] Expose tiledbsoma stats as JSON string or Python-parsed (#2958)

* [python] Expose tiledbsoma stats as JSON string or Python dict

* code-review feedback

apis/python/src/tiledbsoma/__init__.py

@@ -172,6 +172,10 @@
     tiledbsoma_stats_enable,
     tiledbsoma_stats_reset,
 )
+from .stats import (
+    tiledbsoma_stats_json,
+    tiledbsoma_stats_as_py,
+)
 
 __version__ = get_implementation_version()
 

apis/python/src/tiledbsoma/pytiledbsoma.cc

@@ -98,6 +98,13 @@ PYBIND11_MODULE(pytiledbsoma, m) {
             py::print(stats);
         },
         "Print TileDB internal statistics. Lifecycle: experimental.");
+    m.def(
+        "tiledbsoma_stats_string",
+        []() {
+            std::string stats = tiledbsoma::stats::dump();
+            return stats;
+        },
+        "Print TileDB internal statistics. Lifecycle: experimental.");
 
     py::class_<PlatformConfig>(m, "PlatformConfig")
         .def(py::init<>())

apis/python/src/tiledbsoma/stats.py

@@ -0,0 +1,22 @@
+# Copyright (c) 2024 TileDB, Inc.
+#
+# Licensed under the MIT License.
+
+import json
+from typing import Dict, List, Literal, Union, cast
+
+from .pytiledbsoma import tiledbsoma_stats_string
+
+ParsedStats = List[Dict[Literal["counters", "timers"], Dict[str, Union[float, int]]]]
+
+
+def tiledbsoma_stats_json() -> str:
+    """Returns tiledbsoma stats as a JSON string"""
+    # cast is needed for pybind11 things
+    return cast(str, tiledbsoma_stats_string())
+
+
+def tiledbsoma_stats_as_py() -> ParsedStats:
+    """Returns tiledbsoma stats as a Python dict"""
+    # cast is needed for pybind11 things
+    return cast(ParsedStats, json.loads(tiledbsoma_stats_string()))

apis/python/tests/test_stats.py

@@ -0,0 +1,14 @@
+import tiledbsoma
+
+
+def test_stats_json():
+    out = tiledbsoma.tiledbsoma_stats_json()
+    assert isinstance(out, str)
+    assert out[0] == "["
+    assert out[-2] == "]"
+    assert out[-1] == "\n"
+
+
+def test_stats_as_py():
+    out = tiledbsoma.tiledbsoma_stats_as_py()
+    assert isinstance(out, list)