feat(python): add support for defined names (named ranges) (#393)

Author: AmdyTran

python/fastexcel/__init__.py

@@ -35,6 +35,7 @@
     ColumnInfo,
     ColumnInfoNoDtype,
     ColumnNotFoundError,
+    DefinedName,
     FastExcelError,
     InvalidParametersError,
     SheetNotFoundError,
@@ -420,6 +421,16 @@ def table_names(self, sheet_name: str | None = None) -> list[str]:
         """
         return self._reader.table_names(sheet_name)
 
+    def defined_names(self) -> list[DefinedName]:
+        """The list of defined names (named ranges) in the workbook.
+
+        Returns a list of DefinedName objects with 'name' and 'formula' attributes.
+        The formula is a string representation of the range or expression.
+
+        Will return an empty list if no defined names are found.
+        """
+        return self._reader.defined_names()
+
     @typing.overload
     def load_table(
         self,
@@ -684,6 +695,8 @@ def read_excel(source: Path | str | bytes) -> ExcelReader:
     "DTypeFrom",
     "ColumnNameFrom",
     "ColumnInfo",
+    # Defined names
+    "DefinedName",
     # Parse error information
     "CellError",
     "CellErrors",

python/fastexcel/_fastexcel.pyi

@@ -42,6 +42,12 @@ class ColumnInfo:
     @property
     def dtype_from(self) -> DTypeFrom: ...
 
+class DefinedName:
+    @property
+    def name(self) -> str: ...
+    @property
+    def formula(self) -> str: ...
+
 class CellError:
     @property
     def position(self) -> tuple[int, int]: ...
@@ -268,6 +274,7 @@ class _ExcelReader:
     @property
     def sheet_names(self) -> list[str]: ...
     def table_names(self, sheet_name: str | None = None) -> list[str]: ...
+    def defined_names(self) -> list[DefinedName]: ...
 
 def read_excel(source: str | bytes) -> _ExcelReader:
     """Reads an excel file and returns an ExcelReader"""

python/tests/test_defined_names.py

@@ -0,0 +1,18 @@
+import fastexcel
+import pytest
+
+from .utils import path_for_fixture
+
+
+@pytest.mark.parametrize("path", ("sheet-with-defined-names.xlsx",))
+def test_defined_names(path: str) -> None:
+    excel_reader = fastexcel.read_excel(path_for_fixture(path))
+    defined_names = excel_reader.defined_names()
+
+    names_dict = {dn.name: dn.formula for dn in defined_names}
+
+    assert names_dict == {
+        "AddingValues": "SUM(sheet1!$K$5:$K$6)",
+        "DefinedRange": "sheet1!$A$5:$D$7",
+        "NamedConstant": "3.4",
+    }

src/lib.rs

@@ -16,8 +16,9 @@ pub use data::{FastExcelColumn, FastExcelSeries};
 use error::ErrorContext;
 pub use error::{FastExcelError, FastExcelErrorKind, FastExcelResult};
 pub use types::{
-    ColumnInfo, ColumnNameFrom, DType, DTypeCoercion, DTypeFrom, DTypes, ExcelReader, ExcelSheet,
-    ExcelTable, IdxOrName, LoadSheetOrTableOptions, SelectedColumns, SheetVisible, SkipRows,
+    ColumnInfo, ColumnNameFrom, DType, DTypeCoercion, DTypeFrom, DTypes, DefinedName, ExcelReader,
+    ExcelSheet, ExcelTable, IdxOrName, LoadSheetOrTableOptions, SelectedColumns, SheetVisible,
+    SkipRows,
 };
 
 /// Reads an excel file and returns an object allowing to access its sheets, tables, and a bit of metadata.
@@ -72,6 +73,7 @@ fn _fastexcel(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(py_read_excel, m)?)?;
     m.add_class::<ColumnInfo>()?;
     m.add_class::<ColumnInfoNoDtype>()?;
+    m.add_class::<DefinedName>()?;
     m.add_class::<CellError>()?;
     m.add_class::<CellErrors>()?;
     m.add_class::<ExcelSheet>()?;

src/types/excelreader/mod.rs

@@ -58,6 +58,18 @@ impl ExcelSheets {
         Ok(names.into_iter().map(String::as_str).collect())
     }
 
+    fn defined_names(&mut self) -> FastExcelResult<Vec<DefinedName>> {
+        let defined_names = match self {
+            Self::File(sheets) => sheets.defined_names(),
+            Self::Bytes(sheets) => sheets.defined_names(),
+        }
+        .to_vec()
+        .into_iter()
+        .map(|(name, formula)| DefinedName { name, formula })
+        .collect();
+        Ok(defined_names)
+    }
+
     #[cfg(feature = "python")]
     fn supports_by_ref(&self) -> bool {
         matches!(
@@ -100,6 +112,13 @@ impl ExcelSheets {
     }
 }
 
+#[derive(Debug)]
+#[cfg_attr(feature = "python", pyclass(name = "DefinedName"))]
+pub struct DefinedName {
+    pub name: String,
+    pub formula: String,
+}
+
 /// Options for loading a sheet or table.
 #[derive(Debug)]
 pub struct LoadSheetOrTableOptions {
@@ -338,6 +357,10 @@ impl ExcelReader {
     pub fn table_names(&mut self, sheet_name: Option<&str>) -> FastExcelResult<Vec<&str>> {
         self.sheets.table_names(sheet_name)
     }
+
+    pub fn defined_names(&mut self) -> FastExcelResult<Vec<DefinedName>> {
+        self.sheets.defined_names()
+    }
 }
 
 impl TryFrom<&[u8]> for ExcelReader {

src/types/excelreader/python.rs

@@ -1,7 +1,8 @@
 use arrow_array::RecordBatch;
 use pyo3::{Bound, IntoPyObjectExt, PyAny, PyResult, Python, pymethods, types::PyString};
 
-use super::ExcelReader;
+use super::{DefinedName, ExcelReader};
+
 use crate::{
     ExcelSheet,
     data::{ExcelSheetData, record_batch_from_data_and_columns},
@@ -199,6 +200,11 @@ impl ExcelReader {
         self.sheets.table_names(sheet_name).into_pyresult()
     }
 
+    #[pyo3(name = "defined_names")]
+    pub(crate) fn py_defined_names(&mut self) -> PyResult<Vec<DefinedName>> {
+        self.defined_names().into_pyresult()
+    }
+
     #[pyo3(name = "load_sheet", signature = (
         idx_or_name,
         *,
@@ -308,3 +314,16 @@ impl ExcelReader {
         self.sheet_names()
     }
 }
+
+#[pymethods]
+impl DefinedName {
+    #[getter("name")]
+    pub fn py_name(&self) -> &str {
+        &self.name
+    }
+
+    #[getter("formula")]
+    pub fn py_formula(&self) -> &str {
+        &self.formula
+    }
+}

src/types/mod.rs

@@ -5,7 +5,7 @@ pub(crate) mod exceltable;
 pub(crate) mod idx_or_name;
 
 pub use dtype::{DType, DTypeCoercion, DTypes};
-pub use excelreader::{ExcelReader, LoadSheetOrTableOptions};
+pub use excelreader::{DefinedName, ExcelReader, LoadSheetOrTableOptions};
 pub use excelsheet::{
     ExcelSheet, SelectedColumns, SheetVisible, SkipRows,
     column_info::{ColumnInfo, ColumnNameFrom, DTypeFrom},