This closes #33 and #38, upgrade version to v0.0.8

- Add new 6 rows iterator functions to support stream reader
- rows
- rows.close
- rows.columns
- rows.error
- rows.get_row_opts
- rows.next
- Fix get_rows function skip the empty rows
- Upgrade the dependencies package version
- Using escape tab control character in the code doc blocks

Author: xuri

excelize.py

@@ -99,7 +99,7 @@ def load_lib() -> Optional[str]:
 
 lib = CDLL(os.path.join(os.path.dirname(__file__), load_lib()))
 ENCODE = "utf-8"
-__version__ = "0.0.7"
+__version__ = "0.0.8"
 uppercase_words = ["id", "rgb", "sq", "xml"]
 
 
@@ -537,6 +537,93 @@ def get_end_axis(self) -> str:
         return self.arr[0].split(":")[1]
 
 
+class Rows:
+    """
+    Rows defines an iterator to a sheet.
+    """
+
+    index: int
+
+    def __init__(self, index: int):
+        self.index = index
+
+    def close(self) -> None:
+        """
+        Closes the open worksheet XML file in the system temporary directory.
+        """
+        lib.RowsClose.restype = c_char_p
+        err = lib.RowsClose(self.index).decode(ENCODE)
+        if err != "":
+            raise RuntimeError(err)
+
+    def columns(self, *opts: Options) -> List[str]:
+        """
+        Return the current row's column values. This fetches the worksheet data
+        as a stream, returns each cell in a row as is, and will not skip empty
+        rows in the tail of the worksheet.
+
+        Args:
+            *opts (Options): Optional parameters for get column cells value.
+
+        Returns:
+            List[str]: Return the current row's column values if no error
+            occurred, otherwise return an empty list.
+        """
+        prepare_args(
+            [opts[0]] if opts else [],
+            [argsRule("opts", [Options], True)],
+        )
+        lib.RowsColumns.restype, options = types_go._StringArrayErrorResult, None
+        if len(opts) > 0:
+            options = byref(py_value_to_c(opts[0], types_go._Options()))
+        res = lib.RowsColumns(self.index, options)
+        arr = c_value_to_py(res, StringArrayErrorResult()).arr
+        return arr if arr else []
+
+    def error(self) -> None:
+        """
+        Return the error when the error occurs.
+
+        Returns:
+            None: Return None if no error occurred, otherwise raise a
+            RuntimeError with the message.
+        """
+        lib.RowsError.restype = c_char_p
+        err = lib.RowsError(self.index).decode(ENCODE)
+        if err != "":
+            raise RuntimeError(err)
+
+    def get_row_opts(self) -> Optional[RowOpts]:
+        """
+        Return the row options of the current row.
+
+        Returns:
+            Optional[RowOpts]: Return the row options of the current row if no
+            error occurred, otherwise raise a RuntimeError with the message.
+        """
+        lib.RowsGetRowOpts.restype = types_go._GetRowOptsResult
+        res = lib.RowsGetRowOpts(self.index)
+        err = res.err.decode(ENCODE)
+        if not err:
+            return c_value_to_py(res.opts, RowOpts())
+        raise RuntimeError(err)
+
+    def next(self) -> bool:
+        """
+        Return `True` if it finds the next row element.
+
+        Returns:
+            bool: Return if it finds the next row element if no error occurred,
+            otherwise raise a RuntimeError with the message.
+        """
+        lib.RowsNext.restype = types_go._BoolErrorResult
+        res = lib.RowsNext(self.index)
+        err = res.err.decode(ENCODE)
+        if not err:
+            return res.val
+        raise RuntimeError(err)
+
+
 class StreamWriter:
     """
     StreamWriter is a streaming writer for writing large amounts of data to a
@@ -3177,7 +3264,7 @@ def get_rows(self, sheet: str, *opts: Options) -> List[List[str]]:
             rows = f.get_rows("Sheet1")
             for row in rows:
                 for cell in row:
-                    print(f"{cell}\t", end="")
+                    print(f"{cell}\\t", end="")
                 print()
             ```
         """
@@ -3197,8 +3284,7 @@ def get_rows(self, sheet: str, *opts: Options) -> List[List[str]]:
         result = c_value_to_py(res, GetRowsResult()).row
         if result:
             for row in result:
-                if row.cell:
-                    rows.append([cell for cell in row.cell])
+                rows.append([cell for cell in row.cell] if row.cell else [])
         if not err:
             return rows
         raise RuntimeError(err)
@@ -4062,6 +4148,41 @@ def remove_row(self, sheet: str, row: int) -> None:
         if err != "":
             raise RuntimeError(err)
 
+    def rows(self, sheet: str) -> Rows:
+        """
+        Returns a rows iterator, used for streaming reading data for a worksheet
+        with a large data.
+
+        Args:
+            sheet (str): The worksheet name
+
+        Returns:
+            Rows: Return the rows iterator object if no error occurred,
+            otherwise raise a RuntimeError with the message.
+
+        Example:
+            For example:
+
+            ```python
+            try:
+                rows = f.rows("Sheet1")
+                while rows.next():
+                    for cell in rows.columns():
+                        print(f"{cell}\\t", end="")
+                    print()
+                rows.close()
+            except (RuntimeError, TypeError) as err:
+                print(err)
+            ```
+        """
+        prepare_args([sheet], [argsRule("sheet", [str])])
+        lib.Rows.restype = types_go._IntErrorResult
+        res = lib.Rows(self.file_index, sheet.encode(ENCODE))
+        err = res.err.decode(ENCODE)
+        if not err:
+            return Rows(res.val)
+        raise RuntimeError(err)
+
     def search_sheet(self, sheet: str, value: str, *reg: bool) -> List[str]:
         """
         Get cell reference by given worksheet name, cell value, and regular

go.mod

@@ -3,7 +3,7 @@ module github.com/xuri/excelize-py
 go 1.24.0
 
 require (
-	github.com/xuri/excelize/v2 v2.10.1-0.20251128004124-f1ac51e63bc8
+	github.com/xuri/excelize/v2 v2.10.1-0.20251205010452-4ff4208b3c6c
 	golang.org/x/image v0.33.0
 )
 

go.sum

@@ -13,8 +13,8 @@ github.com/tiendc/go-deepcopy v1.7.2 h1:Ut2yYR7W9tWjTQitganoIue4UGxZwCcJy3orjrrI
 github.com/tiendc/go-deepcopy v1.7.2/go.mod h1:4bKjNC2r7boYOkD2IOuZpYjmlDdzjbpTRyCx+goBCJQ=
 github.com/xuri/efp v0.0.1 h1:fws5Rv3myXyYni8uwj2qKjVaRP30PdjeYe2Y6FDsCL8=
 github.com/xuri/efp v0.0.1/go.mod h1:ybY/Jr0T0GTCnYjKqmdwxyxn2BQf2RcQIIvex5QldPI=
-github.com/xuri/excelize/v2 v2.10.1-0.20251128004124-f1ac51e63bc8 h1:BMTZwsTDkAGubaojDitcn7jw+VbPCRT5vpV2C4eD/gY=
-github.com/xuri/excelize/v2 v2.10.1-0.20251128004124-f1ac51e63bc8/go.mod h1:B1Yl9Szv1D018lVoZttJ5lJkw8AP40Ysb0uKP4VO2hA=
+github.com/xuri/excelize/v2 v2.10.1-0.20251205010452-4ff4208b3c6c h1:ooy51XVFN19WdNWLKed+dzBmKySvFDiCoV7qe+ar9ic=
+github.com/xuri/excelize/v2 v2.10.1-0.20251205010452-4ff4208b3c6c/go.mod h1:B1Yl9Szv1D018lVoZttJ5lJkw8AP40Ysb0uKP4VO2hA=
 github.com/xuri/nfp v0.0.2-0.20250530014748-2ddeb826f9a9 h1:+C0TIdyyYmzadGaL/HBLbf3WdLgC29pgyhTjAT/0nuE=
 github.com/xuri/nfp v0.0.2-0.20250530014748-2ddeb826f9a9/go.mod h1:WwHg+CVyzlv/TX9xqBFXEZAuxOPxn2k1GNHwG41IIUQ=
 golang.org/x/crypto v0.45.0 h1:jMBrvKuj23MTlT0bQEOBcAE0mjg8mK9RXFhRH6nyF3Q=

main.go

@@ -52,11 +52,12 @@ const (
 )
 
 var (
-	files, sw          = sync.Map{}, sync.Map{}
-	emptyString        string
-	errFilePtr         = "can not find file pointer"
-	errStreamWriterPtr = "can not find stream writer pointer"
-	errArgType         = errors.New("invalid argument data type")
+	files, rowsIterator, sw = sync.Map{}, sync.Map{}, sync.Map{}
+	emptyString             string
+	errFilePtr              = "can not find file pointer"
+	errRowsIteratorPtr      = "can not find rows iterator pointer"
+	errStreamWriterPtr      = "can not find stream writer pointer"
+	errArgType              = errors.New("invalid argument data type")
 
 	// goBaseTypes defines Go's basic data types.
 	goBaseTypes = map[reflect.Kind]bool{
@@ -1754,6 +1755,116 @@ func NewStreamWriter(idx int, sheet *C.char) C.struct_IntErrorResult {
 	return C.struct_IntErrorResult{val: C.int(swIdx), err: C.CString(emptyString)}
 }
 
+// Rows returns a rows iterator, used for streaming reading data for a worksheet
+// with a large data. This function is concurrency safe.
+//
+//export Rows
+func Rows(idx int, sheet *C.char) C.struct_IntErrorResult {
+	f, ok := files.Load(idx)
+	if !ok {
+		return C.struct_IntErrorResult{val: C.int(0), err: C.CString(errFilePtr)}
+	}
+	rows, err := f.(*excelize.File).Rows(C.GoString(sheet))
+	if err != nil {
+		return C.struct_IntErrorResult{val: C.int(0), err: C.CString(err.Error())}
+	}
+	var rIdx int
+	rowsIterator.Range(func(_, _ interface{}) bool {
+		rIdx++
+		return true
+	})
+	rIdx++
+	rowsIterator.Store(rIdx, rows)
+	return C.struct_IntErrorResult{val: C.int(rIdx), err: C.CString(emptyString)}
+}
+
+// RowsClose closes the open worksheet XML file in the system temporary
+// directory.
+//
+//export RowsClose
+func RowsClose(rIdx int) *C.char {
+	row, ok := rowsIterator.Load(rIdx)
+	if !ok {
+		return C.CString(errRowsIteratorPtr)
+	}
+	defer rowsIterator.Delete(rIdx)
+	if err := row.(*excelize.Rows).Close(); err != nil {
+		return C.CString(err.Error())
+	}
+	return C.CString(emptyString)
+}
+
+// RowsColumns return the current row's column values. This fetches the
+// worksheet data as a stream, returns each cell in a row as is, and will not
+// skip empty rows in the tail of the worksheet.
+//
+//export RowsColumns
+func RowsColumns(rIdx int, opts *C.struct_Options) C.struct_StringArrayErrorResult {
+	var options excelize.Options
+	if opts != nil {
+		goVal, err := cValueToGo(reflect.ValueOf(*opts), reflect.TypeOf(excelize.Options{}))
+		if err != nil {
+			return C.struct_StringArrayErrorResult{Err: C.CString(err.Error())}
+		}
+		options = goVal.Elem().Interface().(excelize.Options)
+	}
+	row, ok := rowsIterator.Load(rIdx)
+	if !ok {
+		return C.struct_StringArrayErrorResult{Err: C.CString(errRowsIteratorPtr)}
+	}
+	result, err := row.(*excelize.Rows).Columns(options)
+	if err != nil {
+		return C.struct_StringArrayErrorResult{Err: C.CString(err.Error())}
+	}
+	cArray := C.malloc(C.size_t(len(result)) * C.size_t(unsafe.Sizeof(uintptr(0))))
+	for i, v := range result {
+		*(*unsafe.Pointer)(unsafe.Pointer(uintptr(unsafe.Pointer(cArray)) + uintptr(i)*unsafe.Sizeof(uintptr(0)))) = unsafe.Pointer(C.CString(v))
+	}
+	return C.struct_StringArrayErrorResult{ArrLen: C.int(len(result)), Arr: (**C.char)(cArray), Err: C.CString(emptyString)}
+}
+
+// RowsError will return the error when the error occurs.
+//
+//export RowsError
+func RowsError(rIdx int) *C.char {
+	row, ok := rowsIterator.Load(rIdx)
+	if !ok {
+		return C.CString(errRowsIteratorPtr)
+	}
+	err := row.(*excelize.Rows).Error()
+	if err != nil {
+		return C.CString(err.Error())
+	}
+	return C.CString(emptyString)
+}
+
+// RowsGetRowOpts will return the RowOpts of the current row.
+//
+//export RowsGetRowOpts
+func RowsGetRowOpts(rIdx int) C.struct_GetRowOptsResult {
+	row, ok := rowsIterator.Load(rIdx)
+	if !ok {
+		return C.struct_GetRowOptsResult{err: C.CString(errRowsIteratorPtr)}
+	}
+	opts := row.(*excelize.Rows).GetRowOpts()
+	cVal, err := goValueToC(reflect.ValueOf(opts), reflect.ValueOf(&C.struct_RowOpts{}))
+	if err != nil {
+		return C.struct_GetRowOptsResult{err: C.CString(err.Error())}
+	}
+	return C.struct_GetRowOptsResult{opts: cVal.Elem().Interface().(C.struct_RowOpts), err: C.CString(emptyString)}
+}
+
+// RowsNext will return true if it finds the next row element.
+//
+//export RowsNext
+func RowsNext(rIdx int) C.struct_BoolErrorResult {
+	row, ok := rowsIterator.Load(rIdx)
+	if !ok {
+		return C.struct_BoolErrorResult{val: C._Bool(false), err: C.CString(errRowsIteratorPtr)}
+	}
+	return C.struct_BoolErrorResult{val: C._Bool(row.(*excelize.Rows).Next()), err: C.CString(emptyString)}
+}
+
 // StreamAddTable creates an Excel table for the StreamWriter using the given
 // cell range and format set.
 //
@@ -1874,6 +1985,7 @@ func StreamFlush(swIdx int) *C.char {
 	if !ok {
 		return C.CString(errStreamWriterPtr)
 	}
+	defer sw.Delete(swIdx)
 	if err := streamWriter.(*excelize.StreamWriter).Flush(); err != nil {
 		return C.CString(err.Error())
 	}

setup.py

@@ -42,7 +42,7 @@ def run(self):
 
 setup(
     name="excelize",
-    version="0.0.7",
+    version="0.0.8",
     license="BSD 3-Clause",
     license_files=("LICENSE"),
     description="A Python build of the Go Excelize library for reading and writing Microsoft Excel™ (XLAM / XLSM / XLSX / XLTM / XLTX) spreadsheets",