docs: update documentation (#383)

* update documentation

* shorten line length

* satisfy ruff lint

* Don't rely on `pandas` extra to pull the `pyarrow` library

Author: arnabanimesh

python/fastexcel/__init__.py

@@ -101,7 +101,10 @@ def visible(self) -> SheetVisible:
         return self._sheet.visible
 
     def to_arrow(self) -> "pa.RecordBatch":
-        """Converts the sheet to a pyarrow `RecordBatch`"""
+        """Converts the sheet to a pyarrow `RecordBatch`
+
+        Requires the `pyarrow` extra to be installed.
+        """
         if not _PYARROW_AVAILABLE:
             raise ImportError(
                 "pyarrow is required for to_arrow(). Install with: pip install 'fastexcel[pyarrow]'"
@@ -113,6 +116,8 @@ def to_arrow_with_errors(self) -> "tuple[pa.RecordBatch, CellErrors | None]":
 
         Stores the positions of any values that cannot be parsed as the specified type and were
         therefore converted to None.
+
+        Requires the `pyarrow` extra to be installed.
         """
         if not _PYARROW_AVAILABLE:
             raise ImportError(
@@ -220,7 +225,10 @@ def specified_dtypes(self) -> DTypeMap | None:
         return self._table.specified_dtypes
 
     def to_arrow(self) -> "pa.RecordBatch":
-        """Converts the table to a pyarrow `RecordBatch`"""
+        """Converts the table to a pyarrow `RecordBatch`
+
+        Requires the `pyarrow` extra to be installed.
+        """
         if not _PYARROW_AVAILABLE:
             raise ImportError(
                 "pyarrow is required for to_arrow(). Install with: pip install 'fastexcel[pyarrow]'"
@@ -463,6 +471,11 @@ def load_table(
                               indicating whether the column should be used
         :param dtypes: An optional dtype (for all columns)
                        or dict of dtypes with keys as column indices or names.
+        :param eager: Specifies whether the table should be loaded eagerly.
+                      `False` (default) will load the table lazily using the `PyCapsule` interface,
+                      whereas `True` will load it eagerly via `pyarrow`.
+
+                      Eager loading requires the `pyarrow` extra to be installed.
         """
         if eager:
             return self._reader.load_table(
@@ -512,6 +525,8 @@ def load_sheet_eager(
         `worksheet_range_ref` under the hood, which returns borrowed types.
 
         Refer to `load_sheet` for parameter documentation
+
+        Requires the `pyarrow` extra to be installed.
         """
         return self._reader.load_sheet(
             idx_or_name=idx_or_name,
@@ -618,6 +633,8 @@ def read_excel(source: Path | str | bytes) -> ExcelReader:
     "ExcelReader",
     # Excel sheet
     "ExcelSheet",
+    # Excel table
+    "ExcelTable",
     # Column metadata
     "DTypeFrom",
     "ColumnNameFrom",

python/fastexcel/_fastexcel.pyi

@@ -84,12 +84,17 @@ class _ExcelSheet:
     def visible(self) -> SheetVisible:
         """The visibility of the sheet"""
     def to_arrow(self) -> "pa.RecordBatch":
-        """Converts the sheet to a pyarrow `RecordBatch`"""
+        """Converts the sheet to a pyarrow `RecordBatch`
+
+        Requires the `pyarrow` extra to be installed.
+        """
     def to_arrow_with_errors(self) -> "tuple[pa.RecordBatch, CellErrors]":
         """Converts the sheet to a pyarrow `RecordBatch` with error information.
 
         Stores the positions of any values that cannot be parsed as the specified type and were
         therefore converted to None.
+
+        Requires the `pyarrow` extra to be installed.
         """
     def __arrow_c_schema__(self) -> object:
         """Export the schema as an `ArrowSchema` `PyCapsule`.
@@ -138,7 +143,10 @@ class _ExcelTable:
     def specified_dtypes(self) -> DTypeMap | None:
         """The dtypes specified for the table"""
     def to_arrow(self) -> "pa.RecordBatch":
-        """Converts the table to a pyarrow `RecordBatch`"""
+        """Converts the table to a pyarrow `RecordBatch`
+
+        Requires the `pyarrow` extra to be installed.
+        """
     def __arrow_c_schema__(self) -> object:
         """Export the schema as an `ArrowSchema` `PyCapsule`.