Add Index and CTableIndex classes to the sphinx docs

Author: FrancescAlted

doc/reference/ctable.rst

@@ -240,16 +240,6 @@ snapshot that can be indexed like any other stored column.  New rows inserted
 later via :meth:`CTable.append` or :meth:`CTable.extend` auto-fill omitted
 materialized-column values from the recorded expression metadata.
 
-CTable indexes can also target **direct expressions** over stored columns via
-``create_index(expression=...)``.  This lets queries reuse indexes for derived
-predicates without adding either a computed column or a materialized stored one.
-A matching ``FULL`` direct-expression index can also be reused by ordering paths
-such as :meth:`CTable.sort_by` when sorting by a computed column backed by the
-same expression.  ``OPSI`` indexes are a separate exact-filtering tier with a
-tunable number of iterative ordering cycles; they are not intended to converge
-to a completely sorted ``FULL``/CSI index, so use ``FULL`` when globally sorted
-ordered reuse is required.
-
 .. autosummary::
 
     CTable.delete
@@ -271,6 +261,56 @@ ordered reuse is required.
 .. automethod:: CTable.rename_column
 
 
+Indexes
+-------
+
+CTable indexes are created with :meth:`CTable.create_index` and returned as
+:class:`blosc2.ctable.CTableIndex` handles.  A ``CTableIndex`` is the table
+counterpart to :class:`blosc2.Index`: it refers to an index stored in the table
+index catalog, and delegates maintenance operations such as ``drop()``,
+``rebuild()``, and ``compact()`` back to the owning table.
+
+Indexes can target stored columns or **direct expressions** over stored columns
+via ``create_index(expression=...)``.  This lets queries reuse indexes for
+derived predicates without adding either a computed column or a materialized
+stored one.  A matching ``FULL`` direct-expression index can also be reused by
+ordering paths such as :meth:`CTable.sort_by` when sorting by a computed column
+backed by the same expression.  ``OPSI`` indexes are a separate exact-filtering
+tier with a tunable number of iterative ordering cycles; they are not intended
+to converge to a completely sorted ``FULL``/CSI index, so use ``FULL`` when
+globally sorted ordered reuse is required.
+
+.. autosummary::
+
+    CTable.create_index
+    CTable.index
+    CTable.indexes
+    CTable.drop_index
+    CTable.rebuild_index
+    CTable.compact_index
+
+.. automethod:: CTable.create_index
+.. automethod:: CTable.index
+.. autoattribute:: CTable.indexes
+.. automethod:: CTable.drop_index
+.. automethod:: CTable.rebuild_index
+.. automethod:: CTable.compact_index
+
+.. autoclass:: blosc2.ctable.CTableIndex
+
+.. autoattribute:: blosc2.ctable.CTableIndex.col_name
+.. autoattribute:: blosc2.ctable.CTableIndex.kind
+.. autoattribute:: blosc2.ctable.CTableIndex.stale
+.. autoattribute:: blosc2.ctable.CTableIndex.name
+.. autoattribute:: blosc2.ctable.CTableIndex.nbytes
+.. autoattribute:: blosc2.ctable.CTableIndex.cbytes
+.. autoattribute:: blosc2.ctable.CTableIndex.cratio
+.. automethod:: blosc2.ctable.CTableIndex.storage_stats
+.. automethod:: blosc2.ctable.CTableIndex.drop
+.. automethod:: blosc2.ctable.CTableIndex.rebuild
+.. automethod:: blosc2.ctable.CTableIndex.compact
+
+
 Persistence
 -----------
 

doc/reference/index_class.rst

@@ -0,0 +1,33 @@
+.. _Index:
+
+Index
+=====
+
+Handle for an index attached to a :class:`~blosc2.NDArray`.
+
+``Index`` objects are returned by NDArray indexing APIs such as
+:meth:`blosc2.NDArray.create_index`, :meth:`blosc2.NDArray.index`, and
+:attr:`blosc2.NDArray.indexes`.  Use this handle to inspect index metadata and
+storage usage, or to drop, rebuild, and compact the index.  Users normally do
+not instantiate ``Index`` directly.
+
+For table indexes, see :class:`blosc2.ctable.CTableIndex`, documented in the
+:ref:`CTable` reference.
+
+.. currentmodule:: blosc2
+
+.. autoclass:: Index
+
+.. autoattribute:: Index.descriptor
+.. autoattribute:: Index.kind
+.. autoattribute:: Index.field
+.. autoattribute:: Index.name
+.. autoattribute:: Index.target
+.. autoattribute:: Index.persistent
+.. autoattribute:: Index.stale
+.. autoattribute:: Index.nbytes
+.. autoattribute:: Index.cbytes
+.. autoattribute:: Index.cratio
+.. automethod:: Index.drop
+.. automethod:: Index.rebuild
+.. automethod:: Index.compact

src/blosc2/indexing.py

@@ -4034,6 +4034,15 @@ def _component_cbytes(array: blosc2.NDArray, descriptor: dict, component: IndexC
 
 
 class Index(Mapping):
+    """Handle for an index attached to an :class:`blosc2.NDArray`.
+
+    ``Index`` objects are returned by NDArray indexing helpers such as
+    :meth:`blosc2.NDArray.create_index`, :meth:`blosc2.NDArray.index`, and
+    :attr:`blosc2.NDArray.indexes`.  They expose descriptor metadata and
+    convenience methods for dropping, rebuilding, or compacting the underlying
+    index.  Users should not instantiate this class directly.
+    """
+
     def __init__(self, array: blosc2.NDArray, token: str):
         self._array = array
         self._token = token
@@ -4043,34 +4052,42 @@ def _descriptor(self) -> dict:
 
     @property
     def descriptor(self) -> dict:
+        """Copy of the index descriptor dictionary."""
         return _copy_descriptor_for_token(self._array, self._token)
 
     @property
     def kind(self) -> blosc2.IndexKind:
+        """Kind of index, as an :class:`blosc2.IndexKind`."""
         return blosc2.IndexKind(self._descriptor()["kind"])
 
     @property
     def field(self) -> str | None:
+        """Structured-array field indexed by this handle, if any."""
         return self._descriptor()["field"]
 
     @property
     def name(self) -> str | None:
+        """Optional human-readable name assigned at creation time."""
         return self._descriptor()["name"]
 
     @property
     def target(self) -> dict:
+        """Descriptor of the indexed target."""
         return self.descriptor["target"]
 
     @property
     def persistent(self) -> bool:
+        """True when index sidecars are stored persistently on disk."""
         return bool(self._descriptor()["persistent"])
 
     @property
     def stale(self) -> bool:
+        """True if the index needs rebuilding before it can be reused."""
         return bool(self._descriptor()["stale"])
 
     @property
     def nbytes(self) -> int:
+        """Total uncompressed size in bytes for this index payload."""
         descriptor = self._descriptor()
         return sum(
             _component_nbytes(self._array, descriptor, component)
@@ -4079,6 +4096,7 @@ def nbytes(self) -> int:
 
     @property
     def cbytes(self) -> int:
+        """Total compressed size in bytes for this index payload."""
         descriptor = self._descriptor()
         return sum(
             _component_cbytes(self._array, descriptor, component)
@@ -4087,19 +4105,23 @@ def cbytes(self) -> int:
 
     @property
     def cratio(self) -> float:
+        """Compression ratio for this index payload."""
         cbytes = self.cbytes
         if cbytes == 0:
             return math.inf
         return self.nbytes / cbytes
 
     def drop(self) -> None:
+        """Drop this index and delete its sidecar payloads."""
         drop_index(self._array, field=self.field, name=self.name)
 
     def rebuild(self) -> Index:
+        """Rebuild this index and return this handle."""
         rebuild_index(self._array, field=self.field, name=self.name)
         return self
 
     def compact(self) -> Index:
+        """Compact this index, merging incremental runs, and return this handle."""
         compact_index(self._array, field=self.field, name=self.name)
         return self