Different amendments in docs for CTable methods

Author: FrancescAlted

doc/reference/classes.rst

@@ -3,12 +3,11 @@ Blosc2 Classes
 
 .. currentmodule:: blosc2
 
+
 Main Classes
 ------------
 .. autosummary::
 
-    CTable
-    Column
     NDArray
     NDField
     LazyArray
@@ -17,39 +16,42 @@ Main Classes
     BatchArray
     ListArray
     ObjectArray
-    SChunk
-    DictStore
-    TreeStore
-    EmbedStore
-    Index
     Ref
     Proxy
     ProxySource
     ProxyNDSource
     SimpleProxy
+    DictStore
+    TreeStore
+    EmbedStore
+    CTable
+    Column
+    Index
+    SChunk
 
 .. toctree::
     :maxdepth: 1
 
-    ctable
     ndarray
-    index_class
+    ndfield
     lazyarray
     c2array
     array
-    schunk
-    dict_store
-    tree_store
-    embed_store
     batch_array
     list_array
     objectarray
-    ndfield
     ref
     proxy
     proxysource
     proxyndsource
     simpleproxy
+    dict_store
+    tree_store
+    embed_store
+    ctable
+    index_class
+    schunk
+
 
 Other Classes
 -------------

doc/reference/ctable.rst

@@ -225,18 +225,6 @@ When a NumPy structured array is needed, materialize explicitly::
 .. automethod:: CTable.iter_sorted
 
 
-Aggregates & statistics
------------------------
-
-.. autosummary::
-
-    CTable.describe
-    CTable.cov
-
-.. automethod:: CTable.describe
-.. automethod:: CTable.cov
-
-
 Mutations
 ---------
 
@@ -286,31 +274,54 @@ ordered reuse is required.
 Persistence
 -----------
 
+Persist CTables to disk or interchange formats, and restore them later without
+losing schema information. These methods cover native Blosc2 persistence as
+well as import/export paths for CSV, Arrow, and Parquet data.
+
 .. autosummary::
 
+    CTable.load
+    CTable.open
     CTable.save
     CTable.to_csv
     CTable.to_arrow
     CTable.to_parquet
+    CTable.from_arrow
+    CTable.from_parquet
+    CTable.from_csv
 
+.. automethod:: CTable.load
+.. automethod:: CTable.open
 .. automethod:: CTable.save
 .. automethod:: CTable.to_csv
 .. automethod:: CTable.to_arrow
 .. automethod:: CTable.to_parquet
+.. automethod:: CTable.from_arrow
+.. automethod:: CTable.from_parquet
+.. automethod:: CTable.from_csv
 
 
-Inspection
-----------
+Inspection & statistics
+-----------------------
+
+Compute common descriptive statistics directly on ``CTable`` data without
+materializing rows first. These methods operate column-wise on the compressed
+representation, making it easy to summarize distributions or measure
+relationships between numeric columns.
 
 .. autosummary::
 
+    CTable.column_schema
     CTable.info
     CTable.schema_dict
-    CTable.column_schema
+    CTable.describe
+    CTable.cov
 
+.. automethod:: CTable.column_schema
 .. automethod:: CTable.info
 .. automethod:: CTable.schema_dict
-.. automethod:: CTable.column_schema
+.. automethod:: CTable.describe
+.. automethod:: CTable.cov
 
 
 ----

src/blosc2/ctable.py

@@ -3338,7 +3338,119 @@ def from_parquet(
         blosc2_items_per_block: int | None = None,
         **kwargs,
     ) -> CTable:
-        """Read a Parquet file into a :class:`CTable` batch-wise using pyarrow."""
+        """Read a Parquet file into a :class:`CTable`.
+
+        The Parquet file is streamed batch by batch through :mod:`pyarrow` and then
+        converted into a typed :class:`CTable`. By default, the result is created in
+        memory, but you can also persist it on disk via ``urlpath``.
+
+        This method delegates the actual table construction to
+        :meth:`CTable.from_arrow`, so Arrow schema handling, nullable-column support,
+        and Blosc2 write tuning follow the same rules as that method.
+
+        Parameters
+        ----------
+        path : str or path-like
+            Path to the source Parquet file.
+
+        columns : list[str] or None, optional
+            Subset of columns to read from the Parquet file. If provided, only these
+            columns are loaded and their order in the resulting table matches the
+            order in this list. Column names must be unique.
+
+        batch_size : int, optional
+            Number of rows per Arrow batch read from the Parquet file. This controls
+            how much data is pulled from the file at a time before being handed off
+            to the CTable builder. Must be greater than 0.
+
+        urlpath : str or None, optional
+            Destination storage path for the resulting CTable. If ``None`` (the
+            default), the table is created in memory. If provided, the table is backed
+            by persistent on-disk storage.
+
+        mode : str, optional
+            Storage open mode for ``urlpath``. Defaults to ``"w"``. This is passed
+            through to :meth:`CTable.from_arrow`.
+
+        cparams : object, optional
+            Compression parameters for the created Blosc2 containers. Passed through
+            to :meth:`CTable.from_arrow`.
+
+        dparams : object, optional
+            Decompression parameters for the created Blosc2 containers. Passed through
+            to :meth:`CTable.from_arrow`.
+
+        validate : bool, optional
+            Whether to enable extra internal validation while building the table.
+            Defaults to ``False``.
+
+        auto_null_sentinels : bool, optional
+            If ``True`` (default), nullable scalar columns imported from Parquet may
+            automatically receive per-column null sentinel values when needed. Sentinel
+            selection follows the current null-policy rules used by CTable schema
+            handling.
+
+        blosc2_batch_size : int or None, optional
+            Number of items written to Blosc2 containers per internal write batch.
+            Passed through to :meth:`CTable.from_arrow`.
+
+        blosc2_items_per_block : int or None, optional
+            Target number of items per internal Blosc2 block. Passed through to
+            :meth:`CTable.from_arrow`.
+
+        **kwargs
+            Additional keyword arguments forwarded to ``pyarrow.parquet.ParquetFile``.
+            Use these for Parquet-reader-specific options supported by PyArrow.
+
+        Returns
+        -------
+        CTable
+            A new :class:`CTable` populated from the Parquet file. The table contains
+            all selected columns and all rows from the file. If ``urlpath`` is
+            provided, the returned table is disk-backed; otherwise it is in-memory.
+
+        Raises
+        ------
+        ImportError
+            If :mod:`pyarrow` is not installed.
+        ValueError
+            If ``batch_size`` is not greater than 0.
+        ValueError
+            If ``columns`` contains duplicate names.
+        Exception
+            Any exception raised by :mod:`pyarrow` while opening or reading the Parquet
+            file, or by :meth:`CTable.from_arrow` while converting Arrow data into a
+            CTable.
+
+        Examples
+        --------
+        Load an entire Parquet file into an in-memory table:
+
+        >>> import blosc2
+        >>> t = blosc2.CTable.from_parquet("data.parquet")
+
+        Load only a subset of columns:
+
+        >>> t = blosc2.CTable.from_parquet(
+        ...     "data.parquet",
+        ...     columns=["user_id", "amount", "country"],
+        ... )
+
+        Create a disk-backed table while reading in batches:
+
+        >>> t = blosc2.CTable.from_parquet(
+        ...     "data.parquet",
+        ...     batch_size=50_000,
+        ...     urlpath="data.ctable",
+        ... )
+
+        Pass additional options through to PyArrow's Parquet reader:
+
+        >>> t = blosc2.CTable.from_parquet(
+        ...     "data.parquet",
+        ...     memory_map=True,
+        ... )
+        """
         pq = cls._require_pyarrow_parquet("from_parquet()")
         pa = cls._require_pyarrow("from_parquet()")
         cls._validate_arrow_batch_size(batch_size)