feat: allow list of ints or callable for skip_rows (#367)

Author: PrettyWood

README.md

@@ -9,16 +9,16 @@ Docs available [here](https://fastexcel.toucantoco.dev/).
 ## Installation
 
 ```bash
-# Lightweight installation (no pyarrow dependency)
+# Lightweight installation (no PyArrow dependency)
 pip install fastexcel
 
-# With Polars support only (no pyarrow needed)
+# With Polars support only (no PyArrow needed)
 pip install fastexcel[polars]
 
-# With pandas support (includes pyarrow)
+# With Pandas support (includes PyArrow)
 pip install fastexcel[pandas]
 
-# With pyarrow support
+# With PyArrow support
 pip install fastexcel[pyarrow]
 
 # With all integrations

python/fastexcel/__init__.py

@@ -285,7 +285,7 @@ def load_sheet(
         *,
         header_row: int | None = 0,
         column_names: list[str] | None = None,
-        skip_rows: int | None = None,
+        skip_rows: int | list[int] | Callable[[int], bool] | None = None,
         n_rows: int | None = None,
         schema_sample_rows: int | None = 1_000,
         dtype_coercion: Literal["coerce", "strict"] = "coerce",
@@ -306,13 +306,15 @@ def load_sheet(
                              If `column_names` is used, `header_row` will be ignored.
         :param n_rows: Specifies how many rows should be loaded.
                        If `None`, all rows are loaded
-        :param skip_rows: Specifies how many rows should be skipped after the `header_row`.
+        :param skip_rows: Specifies which rows should be skipped after the `header_row`.
                           Any rows before the `header_row` are automatically skipped.
-                          If `header_row` is `None`:
-                            - if `skip_rows` is `None` (default): it skips all empty rows
-                            at the beginning of the sheet.
-                            - if `skip_rows` is a number, it skips the specified number
-                            of rows from the start of the sheet.
+                          It means row indices are relative to data rows, not the sheet!
+                          Can be one of:
+                          - `int`: Skip this many rows after the header row
+                          - `list[int]`: Skip specific row indices (0-based relative to data rows)
+                          - `Callable[[int], bool]`: Function that receives row index (0-based
+                          relative to data rows) and returns True to skip the row
+                          - `None`: If `header_row` is None, skips empty rows at beginning
         :param schema_sample_rows: Specifies how many rows should be used to determine
                                    the dtype of a column. Cannot be 0. A specific dtype can be
                                    enforced for some or all columns through the `dtypes` parameter.
@@ -382,6 +384,7 @@ def load_table(
         dtypes: DType | DTypeMap | None = None,
         eager: Literal[False] = ...,
     ) -> ExcelTable: ...
+
     @typing.overload
     def load_table(
         self,
@@ -401,6 +404,7 @@ def load_table(
         dtypes: DType | DTypeMap | None = None,
         eager: Literal[True] = ...,
     ) -> "pa.RecordBatch": ...
+
     def load_table(
         self,
         name: str,
@@ -493,7 +497,7 @@ def load_sheet_eager(
         *,
         header_row: int | None = 0,
         column_names: list[str] | None = None,
-        skip_rows: int | None = None,
+        skip_rows: int | list[int] | Callable[[int], bool] | None = None,
         n_rows: int | None = None,
         schema_sample_rows: int | None = 1_000,
         dtype_coercion: Literal["coerce", "strict"] = "coerce",
@@ -601,11 +605,11 @@ def read_excel(source: Path | str | bytes) -> ExcelReader:
 
 
 __all__ = (
-    ## version
+    # version
     "__version__",
-    ## main entrypoint
+    # main entrypoint
     "read_excel",
-    ## Python types
+    # Python types
     "DType",
     "DTypeMap",
     # Excel reader

python/fastexcel/_fastexcel.pyi

@@ -169,7 +169,7 @@ class _ExcelReader:
         *,
         header_row: int | None = 0,
         column_names: list[str] | None = None,
-        skip_rows: int | None = None,
+        skip_rows: int | list[int] | Callable[[int], bool] | None = None,
         n_rows: int | None = None,
         schema_sample_rows: int | None = 1_000,
         dtype_coercion: Literal["coerce", "strict"] = "coerce",
@@ -188,7 +188,7 @@ class _ExcelReader:
         *,
         header_row: int | None = 0,
         column_names: list[str] | None = None,
-        skip_rows: int | None = None,
+        skip_rows: int | list[int] | Callable[[int], bool] | None = None,
         n_rows: int | None = None,
         schema_sample_rows: int | None = 1_000,
         dtype_coercion: Literal["coerce", "strict"] = "coerce",
@@ -207,7 +207,7 @@ class _ExcelReader:
         *,
         header_row: int | None = None,
         column_names: list[str] | None = None,
-        skip_rows: int = 0,
+        skip_rows: int | list[int] | Callable[[int], bool] = 0,
         n_rows: int | None = None,
         schema_sample_rows: int | None = 1_000,
         dtype_coercion: Literal["coerce", "strict"] = "coerce",
@@ -226,7 +226,7 @@ class _ExcelReader:
         *,
         header_row: int | None = None,
         column_names: list[str] | None = None,
-        skip_rows: int = 0,
+        skip_rows: int | list[int] | Callable[[int], bool] = 0,
         n_rows: int | None = None,
         schema_sample_rows: int | None = 1_000,
         dtype_coercion: Literal["coerce", "strict"] = "coerce",

python/tests/fixtures/no-header.xlsx

@@ -566,17 +566,79 @@ def test_sheet_with_decimal_numbers() -> None:
 @pytest.mark.parametrize(
     "header_row, skip_rows, expected",
     [
-        (0, None, {"a": ["b"], "0": [1.0]}),  # default
-        (None, 0, {"__UNNAMED__0": [None, None, "a", "b"], "__UNNAMED__1": [None, None, 0.0, 1.0]}),
-        (None, None, {"__UNNAMED__0": ["a", "b"], "__UNNAMED__1": [0.0, 1.0]}),
-        (0, 0, {"__UNNAMED__0": [None, "a", "b"], "__UNNAMED__1": [None, 0.0, 1.0]}),
-        (0, 1, {"__UNNAMED__0": ["a", "b"], "__UNNAMED__1": [0.0, 1.0]}),
-        (None, 2, {"__UNNAMED__0": ["a", "b"], "__UNNAMED__1": [0.0, 1.0]}),
-        (None, 3, {"__UNNAMED__0": ["b"], "__UNNAMED__1": [1.0]}),
-        (1, 0, {"__UNNAMED__0": ["a", "b"], "__UNNAMED__1": [0.0, 1.0]}),
-        (2, 0, {"a": ["b"], "0": [1.0]}),
-        (2, None, {"a": ["b"], "0": [1.0]}),
-        (2, 1, {"a": [], "0": []}),
+        (0, None, {"a": ["b", "c", "d", "e", "f"], "0": [1.0, 2.0, 3.0, 4.0, 5.0]}),  # default
+        (
+            None,
+            0,
+            {
+                "__UNNAMED__0": [None, None, "a", "b", "c", "d", "e", "f"],
+                "__UNNAMED__1": [None, None, 0.0, 1.0, 2.0, 3.0, 4.0, 5.0],
+            },
+        ),
+        (
+            None,
+            None,
+            {
+                "__UNNAMED__0": ["a", "b", "c", "d", "e", "f"],
+                "__UNNAMED__1": [0.0, 1.0, 2.0, 3.0, 4.0, 5.0],
+            },
+        ),
+        (
+            0,
+            0,
+            {
+                "__UNNAMED__0": [None, "a", "b", "c", "d", "e", "f"],
+                "__UNNAMED__1": [None, 0.0, 1.0, 2.0, 3.0, 4.0, 5.0],
+            },
+        ),
+        (
+            0,
+            1,
+            {
+                "__UNNAMED__0": ["a", "b", "c", "d", "e", "f"],
+                "__UNNAMED__1": [0.0, 1.0, 2.0, 3.0, 4.0, 5.0],
+            },
+        ),
+        (
+            None,
+            2,
+            {
+                "__UNNAMED__0": ["a", "b", "c", "d", "e", "f"],
+                "__UNNAMED__1": [0.0, 1.0, 2.0, 3.0, 4.0, 5.0],
+            },
+        ),
+        (
+            None,
+            3,
+            {"__UNNAMED__0": ["b", "c", "d", "e", "f"], "__UNNAMED__1": [1.0, 2.0, 3.0, 4.0, 5.0]},
+        ),
+        (
+            1,
+            0,
+            {
+                "__UNNAMED__0": ["a", "b", "c", "d", "e", "f"],
+                "__UNNAMED__1": [0.0, 1.0, 2.0, 3.0, 4.0, 5.0],
+            },
+        ),
+        (2, 0, {"a": ["b", "c", "d", "e", "f"], "0": [1.0, 2.0, 3.0, 4.0, 5.0]}),
+        (2, None, {"a": ["b", "c", "d", "e", "f"], "0": [1.0, 2.0, 3.0, 4.0, 5.0]}),
+        (2, 1, {"a": ["c", "d", "e", "f"], "0": [2.0, 3.0, 4.0, 5.0]}),
+        (2, [1, 3], {"a": ["b", "d", "f"], "0": [1.0, 3.0, 5.0]}),
+        (2, [0], {"a": ["c", "d", "e", "f"], "0": [2.0, 3.0, 4.0, 5.0]}),
+        (
+            None,
+            [2, 4],
+            {
+                "__UNNAMED__0": [None, None, "b", "d", "e", "f"],
+                "__UNNAMED__1": [None, None, 1.0, 3.0, 4.0, 5.0],
+            },
+        ),
+        (2, [], {"a": ["b", "c", "d", "e", "f"], "0": [1.0, 2.0, 3.0, 4.0, 5.0]}),
+        (2, [0, 1, 2, 3], {"a": ["f"], "0": [5.0]}),
+        (2, lambda x: x % 2 == 0, {"a": ["c", "e"], "0": [2.0, 4.0]}),
+        (2, lambda x: x in [0, 4], {"a": ["c", "d", "e"], "0": [2.0, 3.0, 4.0]}),
+        (2, lambda x: False, {"a": ["b", "c", "d", "e", "f"], "0": [1.0, 2.0, 3.0, 4.0, 5.0]}),
+        (2, lambda x: x != 2, {"a": ["d"], "0": [3.0]}),
     ],
 )
 def test_header_row_and_skip_rows(