python-calamine-reducto 0.7.19__tar.gz → 0.7.20__tar.gz

{python_calamine_reducto-0.7.19 → python_calamine_reducto-0.7.20}/Cargo.lock

@@ -80,7 +80,7 @@ checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b"
 [[package]]
 name = "calamine"
 version = "0.32.0"
-source = "git+https://github.com/reductoai/calamine.git?branch=main#297ee32c41c7449e22f9fb94e93c0291b0b4d15d"
+source = "git+https://github.com/reductoai/calamine.git?branch=main#5a6418cb25f78e47a841f51c42c85363ee2cd06b"
 dependencies = [
  "atoi_simd",
  "byteorder",
@@ -612,7 +612,7 @@ dependencies = [
 
 [[package]]
 name = "python-calamine-reducto"
-version = "0.7.19"
+version = "0.7.20"
 dependencies = [
  "calamine",
  "chrono",

{python_calamine_reducto-0.7.19 → python_calamine_reducto-0.7.20}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "python-calamine-reducto"
-version = "0.7.19"
+version = "0.7.20"
 edition = "2021"
 readme = "README.md"
 

{python_calamine_reducto-0.7.19 → python_calamine_reducto-0.7.20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-calamine-reducto
-Version: 0.7.19
+Version: 0.7.20
 Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: 3.11

{python_calamine_reducto-0.7.19 → python_calamine_reducto-0.7.20}/README.md

@@ -25,7 +25,8 @@ Our additions live on `main`.
 - **`get_sheet_grid(name, rows, cols, include_styles=True)`** → `CellGrid` from the dense range.
 - **`get_sheet_layout(name)`** → dict with row heights, column widths, defaults
 - **`get_sheet_formulas`**, **`get_sheet_merged_ranges`**, **`get_sheet_images`**,
-  **`get_sheet_data_validations`**, **`get_sheet_freeze_panes`**,
+  **`get_sheet_data_validations`**, **`get_sheet_hyperlinks`**, **`get_sheet_hyperlink_formulas`**,
+  **`get_sheet_freeze_panes`**,
   **`get_sheet_filled_count`**, **`get_sheet_uncached_formula_count`**,
   **`get_all_tables_metadata`**
 

{python_calamine_reducto-0.7.19 → python_calamine_reducto-0.7.20}/python/python_calamine/_python_calamine.pyi

@@ -204,6 +204,21 @@ class DataValidation(typing.TypedDict):
     formula2: str | None
     allow_blank: bool
 
+@typing.type_check_only
+class Hyperlink(typing.TypedDict):
+    ref: str
+    """Cell or range reference, e.g. `A1` or `A1:C3`."""
+    rel_id: str | None
+    """The `r:id` of the link, if any."""
+    target: str | None
+    """Relationship target, e.g. a URL. `None` for a link with only a `location`, and for an
+    `r:id` that has no hyperlink relationship."""
+    location: str | None
+    """Place inside the target or the workbook, e.g. `Sheet2!A1` or a URL fragment."""
+    display: str | None
+    external: bool
+    """`True` when the relationship has `TargetMode="External"`."""
+
 @typing.final
 class CellProxy:
     """One cell of a `CellGrid`. Read a field with `cell["value"]`."""
@@ -261,7 +276,9 @@ class CellGrid:
     def apply_formatting_rust(self) -> None:
         """Format each value with its number format (SSF, in Rust)."""
 
-    def apply_dateutil_reformat(self, date_parse: Callable[[str], float | None]) -> None:
+    def apply_dateutil_reformat(
+        self, date_parse: Callable[[str], float | None]
+    ) -> None:
         """Reformat text cells that have a date format. `date_parse` gives a date serial."""
 
     def apply_raw_as_formatted(self) -> None: ...
@@ -428,6 +445,16 @@ class CalamineWorkbook:
         """`(data, extension, anchor_row, anchor_col)` for each image."""
 
     def get_sheet_data_validations(self, name: str) -> list[DataValidation]: ...
+    def get_sheet_hyperlinks(
+        self, name: str, limit: int | None = None
+    ) -> list[Hyperlink]:
+        """The links of the sheet's `<hyperlinks>` element, at most `limit`. Empty for xlsb, xls, and ods."""
+
+    def get_sheet_hyperlink_formulas(
+        self, name: str, limit: int | None = None
+    ) -> list[tuple[int, int, str]]:
+        """`(row, col, formula)` for each formula that contains `HYPERLINK`, at most `limit`. Empty for xlsb, xls, and ods."""
+
     def get_sheet_freeze_panes(self, name: str) -> tuple[int, int]:
         """`(frozen_rows, frozen_cols)`."""
 

{python_calamine_reducto-0.7.19 → python_calamine_reducto-0.7.20}/src/types/workbook.rs

@@ -133,6 +133,14 @@ impl SheetsEnum {
         with_xlsx!(self, x => Ok(x.worksheet_data_validations(name)?), else Ok(Vec::new()))
     }
 
+    fn worksheet_hyperlinks(
+        &mut self,
+        name: &str,
+        limit: Option<usize>,
+    ) -> Result<Vec<calamine::Hyperlink>, Error> {
+        with_xlsx!(self, x => Ok(x.worksheet_hyperlinks(name, limit)?), else Ok(Vec::new()))
+    }
+
     fn worksheet_freeze_panes(&mut self, name: &str) -> Result<calamine::FreezePanes, Error> {
         with_xlsx!(
             self,
@@ -183,10 +191,14 @@ impl SheetsEnum {
         }, else Ok(None))
     }
 
-    /// Stream the formulas of an xlsx sheet with `XlsxCellReader::next_formula`, with no dense
-    /// `Range<String>`. Keyed by position, the last duplicate kept, as `worksheet_formula`
-    /// gives them. `Ok(None)` for non-xlsx workbooks.
-    fn xlsx_formulas(&mut self, name: &str) -> Result<Option<Formulas>, Error> {
+    /// Stream the xlsx formulas that `keep` accepts, at most `limit`, with no dense `Range<String>`.
+    /// Keyed by position, the last duplicate kept, as `worksheet_formula` gives them. `Ok(None)` for non-xlsx.
+    fn xlsx_formulas(
+        &mut self,
+        name: &str,
+        keep: fn(&str) -> bool,
+        limit: usize,
+    ) -> Result<Option<Formulas>, Error> {
         with_xlsx!(self, x => {
             let mut formulas = BTreeMap::new();
             let mut reader = match x.worksheet_cells_reader(name) {
@@ -194,9 +206,13 @@ impl SheetsEnum {
                 Err(calamine::XlsxError::NotAWorksheet(_)) => return Ok(Some(formulas)),
                 Err(e) => return Err(e.into()),
             };
-            while let Some(cell) = reader.next_formula()? {
-                if !cell.get_value().is_empty() {
-                    formulas.insert(cell.get_position(), cell.get_value().clone());
+            while formulas.len() < limit {
+                let Some(cell) = reader.next_formula()? else {
+                    break;
+                };
+                let formula = cell.get_value();
+                if !formula.is_empty() && keep(formula) {
+                    formulas.insert(cell.get_position(), formula.clone());
                 }
             }
             Ok(Some(formulas))
@@ -577,6 +593,50 @@ impl CalamineWorkbook {
             .collect()
     }
 
+    /// Get the hyperlinks of a sheet as a list of dicts, at most `limit` of them.
+    /// Each dict has: ref, rel_id, target, location, display, external. Empty for xlsb, xls, and ods.
+    #[pyo3(name = "get_sheet_hyperlinks", signature = (name, limit = None))]
+    fn py_get_sheet_hyperlinks(
+        &mut self,
+        py: Python<'_>,
+        name: &str,
+        limit: Option<usize>,
+    ) -> PyResult<Vec<Py<PyAny>>> {
+        let links = py.detach(|| -> PyResult<Vec<calamine::Hyperlink>> {
+            Ok(self.sheets.worksheet_hyperlinks(name, limit)?)
+        })?;
+        links
+            .into_iter()
+            .map(|link| {
+                let dict = pyo3::types::PyDict::new(py);
+                dict.set_item("ref", &link.cell_ref)?;
+                dict.set_item("rel_id", link.rel_id.as_deref())?;
+                dict.set_item("target", link.target.as_deref())?;
+                dict.set_item("location", link.location.as_deref())?;
+                dict.set_item("display", link.display.as_deref())?;
+                dict.set_item("external", link.external)?;
+                Ok(dict.into_any().unbind())
+            })
+            .collect()
+    }
+
+    /// Get `(row, col, formula)` for each formula that contains `HYPERLINK` (any case), at most
+    /// `limit` of them. The read streams the cells. Empty for xlsb, xls, and ods.
+    #[pyo3(name = "get_sheet_hyperlink_formulas", signature = (name, limit = None))]
+    fn py_get_sheet_hyperlink_formulas(
+        &mut self,
+        py: Python<'_>,
+        name: &str,
+        limit: Option<usize>,
+    ) -> PyResult<Vec<(usize, usize, String)>> {
+        py.detach(|| {
+            let formulas =
+                self.sheets
+                    .xlsx_formulas(name, contains_hyperlink, limit.unwrap_or(usize::MAX))?;
+            Ok(formula_triples(formulas.unwrap_or_default()))
+        })
+    }
+
     /// Get freeze pane info for a sheet as (frozen_rows, frozen_cols).
     #[pyo3(name = "get_sheet_freeze_panes")]
     fn py_get_sheet_freeze_panes(&mut self, py: Python<'_>, name: &str) -> PyResult<(u32, u32)> {
@@ -743,11 +803,8 @@ impl CalamineWorkbook {
 
     /// Get formulas as (row, col, formula_string) triples.
     fn get_sheet_formulas(&mut self, name: &str) -> PyResult<Vec<(usize, usize, String)>> {
-        if let Some(formulas) = self.sheets.xlsx_formulas(name)? {
-            return Ok(formulas
-                .into_iter()
-                .map(|((row, col), f)| (row as usize, col as usize, with_leading_eq(f)))
-                .collect());
+        if let Some(formulas) = self.sheets.xlsx_formulas(name, |_| true, usize::MAX)? {
+            return Ok(formula_triples(formulas));
         }
         let range = self.sheets.worksheet_formula(name)?;
         let range_start = range.start().unwrap_or((0, 0));
@@ -1740,6 +1797,22 @@ fn coverage_cut(fill: &HashMap<usize, u64>, max: usize, filled: u64, coverage: f
     max
 }
 
+/// `(row, col, formula)` for each formula, each with a leading `=`.
+fn formula_triples(formulas: Formulas) -> Vec<(usize, usize, String)> {
+    formulas
+        .into_iter()
+        .map(|((row, col), f)| (row as usize, col as usize, with_leading_eq(f)))
+        .collect()
+}
+
+/// Whether a formula contains `HYPERLINK` in any letter case.
+fn contains_hyperlink(formula: &str) -> bool {
+    formula
+        .as_bytes()
+        .windows(b"HYPERLINK".len())
+        .any(|w| w.eq_ignore_ascii_case(b"HYPERLINK"))
+}
+
 /// Calamine formula strings have no leading `=`, but the API expects one.
 fn with_leading_eq(formula: String) -> String {
     if formula.starts_with('=') {

python_calamine_reducto-0.7.20/tests/create_hyperlink_fixture.py

@@ -0,0 +1,30 @@
+"""Write tests/data/hyperlink_test.xlsx: links, an internal link, HYPERLINK formulas, and a sheet with no links.
+Run once: python tests/create_hyperlink_fixture.py"""
+
+from pathlib import Path
+
+import openpyxl
+from openpyxl.worksheet.hyperlink import Hyperlink
+
+wb = openpyxl.Workbook()
+
+ws = wb.active
+ws.title = "Links"
+ws["A1"] = "Reducto"
+ws["A1"].hyperlink = "https://reducto.ai/"
+ws["A2"] = "Search"
+ws["A2"].hyperlink = "https://example.com/search?q=a&page=2"
+ws["A3"] = "Go to Other"
+ws["A3"].hyperlink = Hyperlink(ref="A3", location="Other!B2", display="Go to Other")
+ws["B1"] = "no link"
+ws["C1"] = '=HYPERLINK("https://example.com/f","F")'
+ws["C2"] = "=SUM(1,2)"
+ws["C3"] = '=hyperlink("https://example.com/g")'
+
+other = wb.create_sheet("Other")
+other["B2"] = "target"
+other["A1"] = "=SUM(1,2)"
+
+out = Path(__file__).parent / "data" / "hyperlink_test.xlsx"
+wb.save(out)
+print(f"Created {out}")

{python_calamine_reducto-0.7.19 → python_calamine_reducto-0.7.20}/tests/test_images.py

@@ -1,4 +1,4 @@
-"""Tests for native image, formula, and data validation extraction via calamine bindings.
+"""Tests for native image, formula, data validation, and hyperlink extraction via calamine bindings.
 
 Uses pre-built xlsx fixtures in tests/data/ (created with openpyxl).
 """
@@ -6,7 +6,6 @@ Uses pre-built xlsx fixtures in tests/data/ (created with openpyxl).
 from pathlib import Path
 
 import pytest
-
 from python_calamine import CalamineWorkbook
 
 DATA = Path(__file__).parent / "data"
@@ -14,6 +13,7 @@ IMAGE_TEST = DATA / "image_test.xlsx"
 MULTI_IMAGE_TEST = DATA / "multi_image_test.xlsx"
 FORMULA_TEST = DATA / "formula_test.xlsx"
 DROPDOWN_TEST = DATA / "dropdown_test.xlsx"
+HYPERLINK_TEST = DATA / "hyperlink_test.xlsx"
 
 
 class TestGetSheetImages:
@@ -126,3 +126,84 @@ class TestGetSheetDataValidations:
         wb = CalamineWorkbook.from_path(IMAGE_TEST)
         dvs = wb.get_sheet_data_validations("Images")
         assert dvs == []
+
+
+class TestGetSheetHyperlinks:
+    def test_returns_external_and_internal_links(self) -> None:
+        """Catches a lost target, an escaped `&` in a URL, or a dropped location-only link."""
+        wb = CalamineWorkbook.from_path(HYPERLINK_TEST)
+        links = wb.get_sheet_hyperlinks("Links")
+
+        assert links == [
+            {
+                "ref": "A1",
+                "rel_id": "rId1",
+                "target": "https://reducto.ai/",
+                "location": None,
+                "display": None,
+                "external": True,
+            },
+            {
+                "ref": "A2",
+                "rel_id": "rId2",
+                "target": "https://example.com/search?q=a&page=2",
+                "location": None,
+                "display": None,
+                "external": True,
+            },
+            {
+                "ref": "A3",
+                "rel_id": None,
+                "target": None,
+                "location": "Other!B2",
+                "display": "Go to Other",
+                "external": False,
+            },
+        ]
+
+    def test_limit_stops_the_read(self) -> None:
+        """Catches a limit that the reader ignores, which lets a hostile sheet fill the memory."""
+        wb = CalamineWorkbook.from_path(HYPERLINK_TEST)
+        links = wb.get_sheet_hyperlinks("Links", limit=2)
+        assert [link["ref"] for link in links] == ["A1", "A2"]
+
+    def test_sheet_without_links_returns_empty(self) -> None:
+        """Catches links of one sheet that leak into another sheet."""
+        wb = CalamineWorkbook.from_path(HYPERLINK_TEST)
+        assert wb.get_sheet_hyperlinks("Other") == []
+
+    @pytest.mark.parametrize(
+        "name", ["any_sheets.xlsb", "any_sheets.ods", "any_sheets.xls"]
+    )
+    def test_non_xlsx_returns_empty(self, name: str) -> None:
+        """Catches an error, not an empty list, for formats with no hyperlink reader."""
+        wb = CalamineWorkbook.from_path(DATA / name)
+        assert wb.get_sheet_hyperlinks(wb.sheet_names[0]) == []
+        assert wb.get_sheet_hyperlink_formulas(wb.sheet_names[0]) == []
+
+
+class TestGetSheetHyperlinkFormulas:
+    def test_returns_only_hyperlink_formulas_in_any_case(self) -> None:
+        """Catches other formulas that cross into Python, or a lower-case `hyperlink(` that is lost."""
+        wb = CalamineWorkbook.from_path(HYPERLINK_TEST)
+        assert wb.get_sheet_hyperlink_formulas("Links") == [
+            (0, 2, '=HYPERLINK("https://example.com/f","F")'),
+            (2, 2, '=hyperlink("https://example.com/g")'),
+        ]
+        assert wb.get_sheet_hyperlink_formulas("Other") == []
+
+    def test_limit_stops_the_read(self) -> None:
+        """Catches a limit that the reader ignores, which lets a formula-heavy sheet fill the memory."""
+        wb = CalamineWorkbook.from_path(HYPERLINK_TEST)
+        assert wb.get_sheet_hyperlink_formulas("Links", limit=1) == [
+            (0, 2, '=HYPERLINK("https://example.com/f","F")'),
+        ]
+
+    def test_limit_counts_only_hyperlink_formulas(self) -> None:
+        """Catches a limit that counts the other formulas, which cuts a link after many plain formulas."""
+        wb = CalamineWorkbook.from_path(HYPERLINK_TEST)
+        assert wb.get_sheet_hyperlink_formulas("Links", limit=2) == [
+            (0, 2, '=HYPERLINK("https://example.com/f","F")'),
+            (2, 2, '=hyperlink("https://example.com/g")'),
+        ]
+        assert wb.get_sheet_hyperlink_formulas("Links", limit=0) == []