feat: Add Opt-in Formula Reading Support

python/python_calamine/_python_calamine.pyi

@@ -73,21 +73,15 @@ class CalamineSheet:
                 For suppress this behaviour, set `skip_empty_area` to `False`.
         """
 
-    def iter_rows(
-        self,
-    ) -> typing.Iterator[
-        list[
-            int
-            | float
-            | str
-            | bool
-            | datetime.time
-            | datetime.date
-            | datetime.datetime
-            | datetime.timedelta
-        ]
-    ]:
-        """Retunrning data from sheet as iterator of lists."""
+    def iter_rows(self) -> CalamineCellIterator:
+        """Return data from sheet as an iterator."""
+
+    def iter_formulas(self) -> CalamineFormulaIterator:
+        """Return formulas from sheet as an iterator.
+
+        Raises:
+            ValueError: If read_formulas=False when creating the workbook.
+        """
 
     @property
     def merged_cell_ranges(
@@ -101,35 +95,79 @@ class CalamineSheet:
             list of merged cell ranges (tuple[start coordinate, end coordinate]) or None for unsuported format
         """
 
+@typing.final
+class CalamineCellIterator:
+    """Iterator for cell data in a CalamineSheet."""
+
+    position: int
+    start: tuple[int, int]
+    height: int
+    width: int
+
+    def __iter__(self) -> "CalamineCellIterator": ...
+    def __next__(
+        self,
+    ) -> list[
+        int
+        | float
+        | str
+        | bool
+        | datetime.time
+        | datetime.date
+        | datetime.datetime
+        | datetime.timedelta
+    ]: ...
+
+@typing.final
+class CalamineFormulaIterator:
+    """Iterator for formula data in a CalamineSheet."""
+
+    position: int
+    start: tuple[int, int]
+    width: int
+    height: int
+
+    def __iter__(self) -> "CalamineFormulaIterator": ...
+    def __next__(self) -> list[str]: ...
+
 @typing.final
 class CalamineWorkbook(contextlib.AbstractContextManager):
     path: str | None
     sheet_names: list[str]
     sheets_metadata: list[SheetMetadata]
     @classmethod
     def from_object(
-        cls, path_or_filelike: str | os.PathLike | ReadBuffer
+        cls,
+        path_or_filelike: str | os.PathLike | ReadBuffer,
+        read_formulas: bool = False,
     ) -> "CalamineWorkbook":
         """Determining type of pyobject and reading from it.
 
         Args:
             path_or_filelike (str | os.PathLike | ReadBuffer): path to file or IO (must imlpement read/seek methods).
+            read_formulas (bool): Enable formula reading support. Default is False.
         """
 
     @classmethod
-    def from_path(cls, path: str | os.PathLike) -> "CalamineWorkbook":
+    def from_path(
+        cls, path: str | os.PathLike, read_formulas: bool = False
+    ) -> "CalamineWorkbook":
         """Reading file from path.
 
         Args:
             path (str | os.PathLike): path to file.
+            read_formulas (bool): Enable formula reading support. Default is False.
         """
 
     @classmethod
-    def from_filelike(cls, filelike: ReadBuffer) -> "CalamineWorkbook":
+    def from_filelike(
+        cls, filelike: ReadBuffer, read_formulas: bool = False
+    ) -> "CalamineWorkbook":
         """Reading file from IO.
 
         Args:
             filelike : IO (must imlpement read/seek methods).
+            read_formulas (bool): Enable formula reading support. Default is False.
         """
 
     def close(self) -> None:
@@ -185,10 +223,11 @@ class ZipError(CalamineError): ...
 class WorkbookClosed(CalamineError): ...
 
 def load_workbook(
-    path_or_filelike: str | os.PathLike | ReadBuffer,
+    path_or_filelike: str | os.PathLike | ReadBuffer, read_formulas: bool = False
 ) -> CalamineWorkbook:
     """Determining type of pyobject and reading from it.
 
     Args:
         path_or_filelike (str | os.PathLike | ReadBuffer): path to file or IO (must imlpement read/seek methods).
+        read_formulas (bool): Enable formula reading support. Default is False.
     """

src/lib.rs

@@ -3,20 +3,27 @@ use pyo3::prelude::*;
 mod types;
 mod utils;
 use crate::types::{
-    CalamineError, CalamineSheet, CalamineWorkbook, CellValue, Error, PasswordError, SheetMetadata,
-    SheetTypeEnum, SheetVisibleEnum, WorkbookClosed, WorksheetNotFound, XmlError, ZipError,
+    CalamineError, CalamineFormulaIterator, CalamineSheet, CalamineWorkbook, CellValue, Error,
+    PasswordError, SheetMetadata, SheetTypeEnum, SheetVisibleEnum, WorkbookClosed,
+    WorksheetNotFound, XmlError, ZipError,
 };
 
 #[pyfunction]
-fn load_workbook(py: Python, path_or_filelike: Py<PyAny>) -> PyResult<CalamineWorkbook> {
-    CalamineWorkbook::from_object(py, path_or_filelike)
+#[pyo3(signature = (path_or_filelike, read_formulas=false))]
+fn load_workbook(
+    py: Python,
+    path_or_filelike: Py<PyAny>,
+    read_formulas: bool,
+) -> PyResult<CalamineWorkbook> {
+    CalamineWorkbook::from_object(py, path_or_filelike, read_formulas)
 }
 
 #[pymodule(gil_used = false)]
 fn _python_calamine(py: Python, m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(load_workbook, m)?)?;
     m.add_class::<CalamineWorkbook>()?;
     m.add_class::<CalamineSheet>()?;
+    m.add_class::<CalamineFormulaIterator>()?;
     m.add_class::<SheetMetadata>()?;
     m.add_class::<SheetTypeEnum>()?;
     m.add_class::<SheetVisibleEnum>()?;

src/types/mod.rs

@@ -6,5 +6,7 @@ pub use cell::CellValue;
 pub use errors::{
     CalamineError, Error, PasswordError, WorkbookClosed, WorksheetNotFound, XmlError, ZipError,
 };
-pub use sheet::{CalamineSheet, SheetMetadata, SheetTypeEnum, SheetVisibleEnum};
+pub use sheet::{
+    CalamineFormulaIterator, CalamineSheet, SheetMetadata, SheetTypeEnum, SheetVisibleEnum,
+};
 pub use workbook::CalamineWorkbook;

src/types/sheet.rs

@@ -134,18 +134,21 @@ pub struct CalamineSheet {
     #[pyo3(get)]
     name: String,
     range: Arc<Range<Data>>,
+    formula_range: Option<Arc<Range<String>>>,
     merged_cell_ranges: Option<Vec<Dimensions>>,
 }
 
 impl CalamineSheet {
     pub fn new(
         name: String,
         range: Range<Data>,
+        formula_range: Option<Range<String>>,
         merged_cell_ranges: Option<Vec<Dimensions>>,
     ) -> Self {
         CalamineSheet {
             name,
             range: Arc::new(range),
+            formula_range: formula_range.map(Arc::new),
             merged_cell_ranges,
         }
     }
@@ -224,6 +227,23 @@ impl CalamineSheet {
         CalamineCellIterator::from_range(Arc::clone(&self.range))
     }
 
+    fn iter_formulas(&self) -> PyResult<CalamineFormulaIterator> {
+        match &self.formula_range {
+            Some(formula_range) => {
+                let data_start = self.range.start().unwrap_or((0, 0));
+                let data_end = self.range.end().unwrap_or((0, 0));
+                Ok(CalamineFormulaIterator::from_range_with_data_bounds(
+                    Arc::clone(formula_range),
+                    data_start,
+                    data_end
+                ))
+            },
+            None => Err(pyo3::exceptions::PyValueError::new_err(
+                "Formula iteration is disabled. Use read_formulas=True when creating the workbook to enable formula access."
+            )),
+        }
+    }
+
     #[getter]
     fn merged_cell_ranges(slf: PyRef<'_, Self>) -> Option<Vec<MergedCellRange>> {
         slf.merged_cell_ranges
@@ -234,7 +254,9 @@ impl CalamineSheet {
 
 #[pyclass]
 pub struct CalamineCellIterator {
+    #[pyo3(get)]
     position: u32,
+    #[pyo3(get)]
     start: (u32, u32),
     empty_row: Vec<CellValue>,
     iter: Rows<'static, Data>,
@@ -250,7 +272,7 @@ impl CalamineCellIterator {
         CalamineCellIterator {
             empty_row,
             position: 0,
-            start: range.start().unwrap(),
+            start: range.start().unwrap_or((0, 0)),
             iter: unsafe {
                 std::mem::transmute::<
                     calamine::Rows<'_, calamine::Data>,
@@ -279,4 +301,89 @@ impl CalamineCellIterator {
             Some(PyList::new(slf.py(), slf.empty_row.clone())).transpose()
         }
     }
+
+    #[getter]
+    fn height(&self) -> usize {
+        self.range.height()
+    }
+    #[getter]
+    fn width(&self) -> usize {
+        self.range.width()
+    }
+}
+
+#[pyclass]
+pub struct CalamineFormulaIterator {
+    #[pyo3(get)]
+    position: u32,
+    #[pyo3(get)]
+    start: (u32, u32),
+    #[allow(dead_code)]
+    range: Arc<Range<String>>,
+    // Data range dimensions for coordinate mapping
+    #[pyo3(get)]
+    width: usize,
+    #[pyo3(get)]
+    height: usize,
+}
+
+impl CalamineFormulaIterator {
+    fn from_range_with_data_bounds(
+        range: Arc<Range<String>>,
+        data_start: (u32, u32),
+        data_end: (u32, u32),
+    ) -> CalamineFormulaIterator {
+        let width = if data_start <= data_end {
+            (data_end.1 - data_start.1 + 1) as usize
+        } else {
+            0
+        };
+
+        let height = if data_start <= data_end {
+            (data_end.0 - data_start.0 + 1) as usize
+        } else {
+            0
+        };
+
+        CalamineFormulaIterator {
+            position: 0,
+            start: data_start,
+            range,
+            width,
+            height,
+        }
+    }
+}
+
+#[pymethods]
+impl CalamineFormulaIterator {
+    fn __iter__(slf: PyRef<'_, Self>) -> PyRef<'_, Self> {
+        slf
+    }
+
+    fn __next__(mut slf: PyRefMut<'_, Self>) -> PyResult<Option<Bound<'_, PyList>>> {
+        // Check if we've exceeded the data range height
+        if slf.position >= slf.height as u32 {
+            return Ok(None);
+        }
+
+        // Calculate the current absolute row position
+        let current_row = slf.start.0 + slf.position;
+        slf.position += 1;
+
+        // Create the result row with proper width, filled with empty strings
+        let mut result_row = vec!["".to_string(); slf.width];
+
+        // Fill in formulas for this row by checking each column position
+        for (col_idx, result_cell) in result_row.iter_mut().enumerate() {
+            let current_col = slf.start.1 + col_idx as u32;
+            if let Some(formula) = slf.range.get_value((current_row, current_col)) {
+                if !formula.is_empty() {
+                    *result_cell = formula.clone();
+                }
+            }
+        }
+
+        Some(PyList::new(slf.py(), result_row)).transpose()
+    }
 }