b2view is now installed by default in blosc2 package

Author: FrancescAlted

README.rst

@@ -48,6 +48,20 @@ Conda users can install from conda-forge:
 
     conda install -c conda-forge python-blosc2
 
+Command line tools
+==================
+
+Two CLI tools are installed along with the package:
+
+- ``b2view``: an interactive terminal browser (TUI) for TreeStore bundles
+  (``.b2d`` directories or ``.b2z`` files), with paged views of NDArray and
+  CTable data of any size
+  (`walkthrough <https://www.blosc.org/python-blosc2/getting_started/b2view.html>`_).
+- ``parquet-to-blosc2``: converts Parquet files to Blosc2 columnar table
+  stores, and back
+  (`walkthrough <https://www.blosc.org/python-blosc2/getting_started/parquet_to_blosc2.html>`_;
+  requires ``pip install "blosc2[parquet]"``).
+
 Documentation
 =============
 

doc/getting_started/b2view.rst

@@ -0,0 +1,79 @@
+b2view: Browse TreeStore Bundles in the Terminal
+================================================
+
+The ``b2view`` CLI opens an interactive terminal browser (TUI) for Blosc2
+TreeStore bundles, either sparse directories (``.b2d``) or compact
+zip-backed files (``.b2z``).  It shows the tree of groups and nodes, the
+metadata and vlmeta of the selected node, and a paged view of the data
+itself — NDArrays of any dimensionality as well as CTables.
+
+``b2view`` is installed with python-blosc2; no extra dependencies are
+needed.
+
+Step 1 — Create a sample store
+------------------------------
+
+Run the snippet below once to produce ``sample.b2z`` with a couple of
+arrays and some metadata:
+
+.. code-block:: python
+
+    import blosc2
+
+    with blosc2.TreeStore("sample.b2z", mode="w") as tstore:
+        tstore.vlmeta["author"] = "me"
+        a = blosc2.linspace(0, 1, num=1_000_000, shape=(1000, 1000))
+        a.vlmeta["description"] = "a 2-D linspace"
+        tstore["/dense/a"] = a
+        tstore["/dense/b"] = blosc2.arange(10_000, shape=(10, 100, 10))
+
+Any existing TreeStore bundle works too — for instance the output of the
+``parquet-to-blosc2`` converter (see :doc:`parquet_to_blosc2`).
+
+Step 2 — Open it
+----------------
+
+.. code-block:: console
+
+    b2view sample.b2z
+
+The screen is split into four panels: the **tree** of the bundle on the
+left, and **meta**, **vlmeta** and **data** panels for the node selected
+in the tree.  Move between panels with ``tab`` / ``shift+tab``, maximize
+the focused one with ``m`` (``r`` restores it), and quit with ``q``.
+
+You can also jump straight to a node and panel:
+
+.. code-block:: console
+
+    b2view sample.b2z /dense/a --panel data
+
+Step 3 — Navigate the data panel
+--------------------------------
+
+The data panel pages through objects far larger than the screen.  Press
+``?`` at any time for the full key reference; the essentials are:
+
+================================  =============================================
+Key                               Action
+================================  =============================================
+``up`` / ``down``                 move the cursor; pages at the edges
+``pageup`` / ``pagedown``         previous / next page of rows
+``t`` / ``b``                     first / last row
+``g``                             go to a row number
+``left`` / ``right``              move across columns; pages at the edges
+``s`` / ``e`` (``home``/``end``)  first / last column window
+``c``                             go to a column index or name
+================================  =============================================
+
+For N-D arrays, press ``d`` to enter *dim mode*: ``left`` / ``right``
+select the active dimension, ``up`` / ``down`` change its fixed index (or
+scroll the viewport), ``enter`` toggles a dimension between fixed and
+navigable, and ``escape`` leaves dim mode.
+
+CLI options
+-----------
+
+``--preview-rows N`` and ``--preview-cols N`` bound the size of each data
+page (20 rows by 10 columns by default), and ``--panel`` chooses the panel
+focused on startup (``tree``, ``meta``, ``vlmeta`` or ``data``).

doc/getting_started/index.rst

@@ -9,3 +9,4 @@ Getting Started
     tutorials
     dsl_syntax
     parquet_to_blosc2
+    b2view

pyproject.toml

@@ -38,6 +38,8 @@ dependencies = [
     "numexpr>=2.14.1; platform_machine != 'wasm32'",
     "pydantic",
     "requests",
+    "rich",
+    "textual",
     "threadpoolctl; platform_machine != 'wasm32'",
 ]
 version = "4.4.4.dev0"
@@ -50,7 +52,6 @@ documentation = "https://www.blosc.org/python-blosc2/python-blosc2.html"
 
 [project.optional-dependencies]
 parquet = ["pyarrow"]
-tui = ["textual", "rich"]
 
 [project.scripts]
 parquet-to-blosc2 = "blosc2.cli.parquet_to_blosc2:main"
@@ -74,7 +75,7 @@ dev = [
 ]
 test = [
     "pytest",
-    # for the b2view Pilot tests (which also need the 'tui' extra)
+    # for the b2view Pilot tests
     "pytest-asyncio",
     "psutil; platform_machine != 'wasm32'",
     # torch is optional because it is quite large (but will still be used if found)

src/blosc2/b2view/cli.py

@@ -27,9 +27,7 @@ def main(argv: list[str] | None = None) -> int:
         from blosc2.b2view.app import B2ViewApp
     except ImportError as exc:
         print(
-            "b2view requires the optional TUI dependencies. Install them with:\n"
-            "\n"
-            '    pip install "blosc2[tui]"\n',
+            "b2view could not import its TUI dependencies. Install them with:\n\n    pip install textual\n",
             file=sys.stderr,
         )
         print(f"Original import error: {exc}", file=sys.stderr)