numbers-parser 4.14.4__py3-none-any.whl → 4.16.1__py3-none-any.whl

numbers_parser/__init__.py

@@ -13,6 +13,7 @@ with warnings.catch_warnings():
     from numbers_parser.constants import *  # noqa: F403
     from numbers_parser.document import *  # noqa: F403
     from numbers_parser.exceptions import *  # noqa: F403
+    from numbers_parser.xrefs import *  # noqa: F403
 
 __version__ = importlib.metadata.version("numbers-parser")
 

numbers_parser/_unpack_numbers.py

@@ -49,13 +49,7 @@ class NumbersUnpacker(IWorkHandler):
                 if self.compact_json or self.pretty:
                     formatter = Formatter()
                     formatter.indent_spaces = 2
-                    formatter.max_inline_complexity = 100
-                    formatter.max_compact_list_complexity = 100
-                    formatter.max_inline_length = 160
-                    formatter.max_compact_list_complexity = 2
-                    formatter.simple_bracket_padding = True
-                    formatter.nested_bracket_padding = False
-                    formatter.always_expand_depth = 10
+                    formatter.max_inline_length = 180
                     pretty_json = formatter.serialize(data)
                     out.write(pretty_json)
                 else:

numbers_parser/cell.py

@@ -22,6 +22,7 @@ from numbers_parser.constants import (
     CURRENCY_CELL_TYPE,
     CUSTOM_TEXT_PLACEHOLDER,
     DATETIME_FIELD_MAP,
+    DECIMAL128_BIAS,
     DECIMAL_PLACES_AUTO,
     DEFAULT_ALIGNMENT,
     DEFAULT_BORDER_COLOR,
@@ -55,6 +56,7 @@ from numbers_parser.constants import (
 )
 from numbers_parser.currencies import CURRENCIES, CURRENCY_SYMBOLS
 from numbers_parser.exceptions import UnsupportedError, UnsupportedWarning
+from numbers_parser.formula import Formula
 from numbers_parser.generated import TSPMessages_pb2 as TSPMessages
 from numbers_parser.generated import TSTArchives_pb2 as TSTArchives
 from numbers_parser.generated.TSWPArchives_pb2 import (
@@ -62,12 +64,14 @@ from numbers_parser.generated.TSWPArchives_pb2 import (
 )
 from numbers_parser.numbers_cache import Cacheable, cache
 from numbers_parser.numbers_uuid import NumbersUUID
+from numbers_parser.xrefs import xl_range
 
 logger = logging.getLogger(numbers_parser_name)
 debug = logger.debug
 
 
 __all__ = [
+    "RGB",
     "Alignment",
     "BackgroundImage",
     "BoolCell",
@@ -88,14 +92,9 @@ __all__ = [
     "MergedCell",
     "NumberCell",
     "RichTextCell",
-    "RGB",
     "Style",
     "TextCell",
     "VerticalJustification",
-    "xl_cell_to_rowcol",
-    "xl_col_to_name",
-    "xl_range",
-    "xl_rowcol_to_cell",
 ]
 
 
@@ -562,8 +561,6 @@ class CellStorageFlags:
     _rich_id: int = None
     _cell_style_id: int = None
     _text_style_id: int = None
-    # _cond_style_id: int = None
-    # _cond_rule_style_id: int = None
     _formula_id: int = None
     _control_id: int = None
     _formula_error_id: int = None
@@ -574,8 +571,6 @@ class CellStorageFlags:
     _duration_format_id: int = None
     _text_format_id: int = None
     _bool_format_id: int = None
-    # _comment_id: int = None
-    # _import_warning_id: int = None
 
     def __str__(self) -> str:
         fields = [
@@ -599,6 +594,7 @@ class Cell(CellStorageFlags, Cacheable):
         self.row = row
         self.col = col
         self._is_bulleted = False
+        self._formula_id = None
         self._storage = None
         self._style = None
         self._d128 = None
@@ -641,11 +637,9 @@ class Cell(CellStorageFlags, Cacheable):
     @property
     def is_formula(self) -> bool:
         """bool: ``True`` if the cell contains a formula."""
-        table_formulas = self._model.table_formulas(self._table_id)
-        return table_formulas.is_formula(self.row, self.col)
+        return self._formula_id is not None
 
     @property
-    @cache(num_args=0)
     def formula(self) -> str:
         """
         str: The formula in a cell.
@@ -666,6 +660,17 @@ class Cell(CellStorageFlags, Cacheable):
             return table_formulas.formula(self._formula_id, self.row, self.col)
         return None
 
+    @formula.setter
+    def formula(self, value: str) -> None:
+        self._formula_id = Formula.from_str(
+            self._model,
+            self._table_id,
+            self.row,
+            self.col,
+            value,
+        )
+        self._model.add_formula_dependency(self.row, self.col, self._table_id)
+
     @property
     def is_bulleted(self) -> bool:
         """bool: ``True`` if the cell contains text bullets."""
@@ -740,7 +745,7 @@ class Cell(CellStorageFlags, Cacheable):
             or self._bool_format_id is not None
         ):
             return self._custom_format()
-        return str(self.value)
+        return str(self.value).upper() if isinstance(self.value, bool) else str(self.value)
 
     @property
     def style(self) -> Style | None:
@@ -872,20 +877,16 @@ class Cell(CellStorageFlags, Cacheable):
             storage_flags._text_style_id = unpack("<i", buffer[offset : offset + 4])[0]
             offset += 4
         if flags & 0x80:
-            # storage_flags._cond_style_id = unpack("<i", buffer[offset : offset + 4])[0]
+            # cond_style_id skipped
             offset += 4
-        # if flags & 0x100:
-        #     storage_flags._cond_rule_style_id = unpack("<i", buffer[offset : offset + 4])[0]
-        #     offset += 4
+        # Skip flag 0x100 (cond_rule_style_id)
         if flags & 0x200:
             storage_flags._formula_id = unpack("<i", buffer[offset : offset + 4])[0]
             offset += 4
         if flags & 0x400:
             storage_flags._control_id = unpack("<i", buffer[offset : offset + 4])[0]
             offset += 4
-        # if flags & 0x800:
-        #     storage_flags._formula_error_id = unpack("<i", buffer[offset : offset + 4])[0]
-        #     offset += 4
+        # Skip flag 0x800 (formula_error_id)
         if flags & 0x1000:
             storage_flags._suggest_id = unpack("<i", buffer[offset : offset + 4])[0]
             offset += 4
@@ -909,12 +910,7 @@ class Cell(CellStorageFlags, Cacheable):
         if flags & 0x40000:
             storage_flags._bool_format_id = unpack("<i", buffer[offset : offset + 4])[0]
             offset += 4
-        # if flags & 0x80000:
-        #     cstorage_flags._omment_id = unpack("<i", buffer[offset : offset + 4])[0]
-        #     offset += 4
-        # if flags & 0x100000:
-        #     storage_flags._import_warning_id = unpack("<i", buffer[offset : offset + 4])[0]
-        #     offset += 4
+        # Skip 0x80000 (comment_id) and 0x100000 (import_warning_id)
 
         cell_type = buffer[1]
         if cell_type == TSTArchives.genericCellType:
@@ -1032,7 +1028,6 @@ class Cell(CellStorageFlags, Cacheable):
             flags = 4
             length += 8
             cell_type = TSTArchives.dateCellType
-            # date_delta = self._value.astimezone() - EPOCH
             if self._value.tzinfo is None:
                 date_delta = self._value - EPOCH
             else:
@@ -1104,7 +1099,6 @@ class Cell(CellStorageFlags, Cacheable):
             length += 4
             storage += pack("<i", self._num_format_id)
             storage[6] |= 1
-            # storage[6:8] = pack("<h", 1)
         if self._currency_format_id is not None:
             flags |= 0x4000
             length += 4
@@ -1560,8 +1554,8 @@ class MergedCell(Cell):
 def _pack_decimal128(value: float) -> bytearray:
     buffer = bytearray(16)
     exp = math.floor(math.log10(math.e) * math.log(abs(value))) if value != 0.0 else 0
-    exp += 0x1820 - 16
-    mantissa = abs(int(value / math.pow(10, exp - 0x1820)))
+    exp += DECIMAL128_BIAS - 16
+    mantissa = abs(int(value / math.pow(10, exp - DECIMAL128_BIAS)))
     buffer[15] |= exp >> 7
     buffer[14] |= (exp & 0x7F) << 1
     i = 0
@@ -1575,7 +1569,7 @@ def _pack_decimal128(value: float) -> bytearray:
 
 
 def _unpack_decimal128(buffer: bytearray) -> float:
-    exp = (((buffer[15] & 0x7F) << 7) | (buffer[14] >> 1)) - 0x1820
+    exp = (((buffer[15] & 0x7F) << 7) | (buffer[14] >> 1)) - DECIMAL128_BIAS
     mantissa = buffer[14] & 1
     for i in range(13, -1, -1):
         mantissa = mantissa * 256 + buffer[i]
@@ -1756,16 +1750,6 @@ def _decode_number_format(number_format, value, name):  # noqa: PLR0912
         int_pad = None
         int_width = num_integers
 
-    # value_1 = str(value).split(".")[0]
-    # value_2 = sigfig(str(value).split(".")[1], sigfig=MAX_SIGNIFICANT_DIGITS, warn=False)
-    # int_pad_space_as_zero = (
-    #     num_integers > 0
-    #     and num_decimals > 0
-    #     and int_pad == CellPadding.SPACE
-    #     and dec_pad is None
-    #     and num_integers > len(value_1)
-    #     and num_decimals > len(value_2)
-    # )
     int_pad_space_as_zero = False
 
     # Formatting integer zero:
@@ -1779,16 +1763,11 @@ def _decode_number_format(number_format, value, name):  # noqa: PLR0912
         formatted_value = "".rjust(int_width)
     elif integer == 0 and int_pad is None and dec_pad == CellPadding.SPACE:
         formatted_value = ""
-    elif (
+    elif (integer == 0 and int_pad == CellPadding.SPACE and dec_pad is not None) or (
         integer == 0
         and int_pad == CellPadding.SPACE
-        and dec_pad is not None
-        or (
-            integer == 0
-            and int_pad == CellPadding.SPACE
-            and dec_pad is None
-            and len(str(decimal)) > num_decimals
-        )
+        and dec_pad is None
+        and len(str(decimal)) > num_decimals
     ):
         formatted_value = "".rjust(int_width)
     elif int_pad_space_as_zero or int_pad == CellPadding.ZERO:
@@ -2016,159 +1995,6 @@ def _auto_units(cell_value, number_format):
     return unit_smallest, unit_largest
 
 
-# Cell reference conversion from  https://github.com/jmcnamara/XlsxWriter
-# Copyright (c) 2013-2021, John McNamara <jmcnamara@cpan.org>
-range_parts = re.compile(r"(\$?)([A-Z]{1,3})(\$?)(\d+)")
-
-
-def xl_cell_to_rowcol(cell_str: str) -> tuple:
-    """
-    Convert a cell reference in A1 notation to a zero indexed row and column.
-
-    Parameters
-    ----------
-    cell_str:  str
-        A1 notation cell reference
-
-    Returns
-    -------
-    row, col: int, int
-        Cell row and column numbers (zero indexed).
-
-    """
-    if not cell_str:
-        return 0, 0
-
-    match = range_parts.match(cell_str)
-    if not match:
-        msg = f"invalid cell reference {cell_str}"
-        raise IndexError(msg)
-
-    col_str = match.group(2)
-    row_str = match.group(4)
-
-    # Convert base26 column string to number.
-    col = 0
-    for expn, char in enumerate(reversed(col_str)):
-        col += (ord(char) - ord("A") + 1) * (26**expn)
-
-    # Convert 1-index to zero-index
-    row = int(row_str) - 1
-    col -= 1
-
-    return row, col
-
-
-def xl_range(first_row, first_col, last_row, last_col):
-    """
-    Convert zero indexed row and col cell references to a A1:B1 range string.
-
-    Parameters
-    ----------
-    first_row: int
-        The first cell row.
-    first_col: int
-        The first cell column.
-    last_row: int
-        The last cell row.
-    last_col: int
-        The last cell column.
-
-    Returns
-    -------
-    str:
-        A1:B1 style range string.
-
-    """
-    range1 = xl_rowcol_to_cell(first_row, first_col)
-    range2 = xl_rowcol_to_cell(last_row, last_col)
-
-    if range1 == range2:
-        return range1
-    return range1 + ":" + range2
-
-
-def xl_rowcol_to_cell(row, col, row_abs=False, col_abs=False):
-    """
-    Convert a zero indexed row and column cell reference to a A1 style string.
-
-    Parameters
-    ----------
-    row: int
-         The cell row.
-    col: int
-        The cell column.
-    row_abs: bool
-        If ``True``, make the row absolute.
-    col_abs: bool
-        If ``True``, make the column absolute.
-
-    Returns
-    -------
-    str:
-        A1 style string.
-
-    """
-    if row < 0:
-        msg = f"row reference {row} below zero"
-        raise IndexError(msg)
-
-    if col < 0:
-        msg = f"column reference {col} below zero"
-        raise IndexError(msg)
-
-    row += 1  # Change to 1-index.
-    row_abs = "$" if row_abs else ""
-
-    col_str = xl_col_to_name(col, col_abs)
-
-    return col_str + row_abs + str(row)
-
-
-def xl_col_to_name(col, col_abs=False):
-    """
-    Convert a zero indexed column cell reference to a string.
-
-    Parameters
-    ----------
-    col: int
-        The column number (zero indexed).
-    col_abs: bool, default: False
-        If ``True``, make the column absolute.
-
-    Returns
-    -------
-        str:
-            Column in A1 notation.
-
-    """
-    if col < 0:
-        msg = f"column reference {col} below zero"
-        raise IndexError(msg)
-
-    col += 1  # Change to 1-index.
-    col_str = ""
-    col_abs = "$" if col_abs else ""
-
-    while col:
-        # Set remainder from 1 .. 26
-        remainder = col % 26
-
-        if remainder == 0:
-            remainder = 26
-
-        # Convert the remainder to a character.
-        col_letter = chr(ord("A") + remainder - 1)
-
-        # Accumulate the column letters, right to left.
-        col_str = col_letter + col_str
-
-        # Get the next order of magnitude.
-        col = int((col - 1) / 26)
-
-    return col_abs + col_str
-
-
 @dataclass()
 class Formatting:
     allow_none: bool = False

numbers_parser/constants.py

@@ -5,23 +5,24 @@ from math import ceil
 
 import enum_tools.documentation
 
+# Path to package date varies by Python version
 try:
     from importlib.resources import files
-# Can't cover exception using modern python
 except ImportError:  # pragma: nocover
     from importlib_resources import files
 
 __all__ = [
-    "CellType",
-    "PaddingType",
     "CellPadding",
+    "CellType",
+    "CellValueType",
+    "ControlFormattingType",
     "DurationStyle",
     "DurationUnits",
     "FormatType",
     "FormattingType",
-    "NegativeNumberStyle",
     "FractionAccuracy",
-    "ControlFormattingType",
+    "NegativeNumberStyle",
+    "PaddingType",
 ]
 
 DEFAULT_DOCUMENT = files("numbers_parser") / "data" / "empty.numbers"
@@ -51,6 +52,8 @@ DEFAULT_DATETIME_FORMAT = "dd MMM YYY HH:MM"
 CHECKBOX_FALSE_VALUE = "☐"
 CHECKBOX_TRUE_VALUE = "☑"
 STAR_RATING_VALUE = "★"
+OPERATOR_PRECEDENCE = {"%": 6, "^": 5, "×": 4, "*": 4, "/": 4, "÷": 4, "+": 3, "-": 3, "&": 2}
+
 
 # Numbers limits
 MAX_TILE_SIZE = 256
@@ -69,6 +72,7 @@ EPOCH = datetime(2001, 1, 1)  # noqa: DTZ001
 SECONDS_IN_HOUR = 60 * 60
 SECONDS_IN_DAY = SECONDS_IN_HOUR * 24
 SECONDS_IN_WEEK = SECONDS_IN_DAY * 7
+DECIMAL128_BIAS = 0x1820
 
 # File format enumerations
 DECIMAL_PLACES_AUTO = 253
@@ -91,6 +95,7 @@ SUPPORTED_NUMBERS_VERSIONS = [
     "14.1",
     "14.2",
     "14.3",
+    "14.4",
 ]
 
 
@@ -108,7 +113,7 @@ def _day_of_year(value: datetime) -> int:
 
 def _week_of_month(value: datetime) -> int:
     """Return the week number in a month for a datetime."""
-    return int(ceil((value.day + value.replace(day=1).weekday()) / 7.0))
+    return ceil((value.day + value.replace(day=1).weekday()) / 7.0)
 
 
 DATETIME_FIELD_MAP = OrderedDict(
@@ -395,6 +400,14 @@ class CellInteractionType(IntEnum):
     TOGGLE = 8
 
 
+class CellValueType(IntEnum):
+    NIL_TYPE = 1
+    BOOLEAN_TYPE = 2
+    DATE_TYPE = 3
+    NUMBER_TYPE = 4
+    STRING_TYPE = 5
+
+
 CONTROL_CELL_TYPE_MAP = {
     FormattingType.POPUP: CellInteractionType.POPUP,
     FormattingType.SLIDER: CellInteractionType.SLIDER,

numbers_parser/document.py

@@ -17,8 +17,6 @@ from numbers_parser.cell import (
     Style,
     TextCell,
     UnsupportedWarning,
-    xl_cell_to_rowcol,
-    xl_range,
 )
 from numbers_parser.constants import (
     CUSTOM_FORMATTING_ALLOWED_CELLS,
@@ -33,6 +31,7 @@ from numbers_parser.constants import (
 from numbers_parser.containers import ItemsList
 from numbers_parser.model import _NumbersModel
 from numbers_parser.numbers_cache import Cacheable
+from numbers_parser.xrefs import xl_cell_to_rowcol, xl_range
 
 if TYPE_CHECKING:  # pragma: nocover
     from collections.abc import Iterator
@@ -41,14 +40,6 @@ if TYPE_CHECKING:  # pragma: nocover
 __all__ = ["Document", "Sheet", "Table"]
 
 
-# class Sheet:
-#     pass
-
-
-# class Table:
-#     pass
-
-
 class Document:
     """
     Create an instance of a new Numbers document.
@@ -379,6 +370,8 @@ class Sheet:
         y: float | None = None,
         num_rows: int | None = DEFAULT_ROW_COUNT,
         num_cols: int | None = DEFAULT_COLUMN_COUNT,
+        num_header_rows: int | None = 1,
+        num_header_cols: int | None = 1,
     ) -> Table:
         """
         Add a new table to the current sheet.
@@ -411,6 +404,10 @@ class Sheet:
             The number of rows for the new table.
         num_cols: int, optional, default: 10
             The number of columns for the new table.
+        num_header_rows: int, optional, default: 1
+            The number of header rows for the new table.
+        num_header_cols: int, optional, default: 1
+            The number of header columns for the new table.
 
         Returns
         -------
@@ -423,7 +420,16 @@ class Sheet:
 
         """
         from_table_id = self._tables[-1]._table_id
-        return self._add_table(table_name, from_table_id, x, y, num_rows, num_cols)
+        return self._add_table(
+            table_name,
+            from_table_id,
+            x,
+            y,
+            num_rows,
+            num_cols,
+            num_header_rows,
+            num_header_cols,
+        )
 
     def _add_table(
         self,
@@ -433,6 +439,8 @@ class Sheet:
         y,
         num_rows,
         num_cols,
+        num_header_rows,
+        num_header_cols,
     ) -> object:
         if table_name is not None:
             if table_name in self._tables:
@@ -452,6 +460,8 @@ class Sheet:
             y,
             num_rows,
             num_cols,
+            num_header_rows,
+            num_header_cols,
         )
         self._tables.append(Table(self._model, new_table_id))
         return self._tables[-1]
@@ -968,6 +978,11 @@ class Table(Cacheable):
         self._data[row][col]._model = self._model
         self._data[row][col]._set_merge(merge_cells.get((row, col)))
 
+        if row < self._model.num_header_rows(self._table_id) or col < self._model.num_header_cols(
+            self._table_id,
+        ):
+            self._model.name_ref_cache.mark_dirty()
+
         if style is not None:
             self.set_cell_style(row, col, style)
 
@@ -984,6 +999,34 @@ class Table(Cacheable):
             msg = "style must be a Style object or style name"
             raise TypeError(msg)
 
+    def categorized_data(self) -> dict | None:
+        """
+        Return the table's data organised into categories, if enabled or ``None``
+        if the table has not had categoried enabled.
+
+        The data is a dictionary with the category names as keys and a list
+        dictionaries for each row in that category of the table. The table heading
+        row is used as the keys for the row dictionary.
+
+        Example
+        -------
+        .. code:: python
+
+            "Transport": [
+                {"Description": "Airplane", "Category": "Transport" },
+                {"Description": "Bicycle", "Category": "Transport" },
+                {"Description": "Bus", "Category": "Transport"},
+            ],
+            "Fruit": [
+                {"Description": "Apple", "Category": "Fruit" },
+                {"Description": "Banana", "Category": "Fruit" },
+            ],
+
+        For tables with multiple categories, the top-level dictionary is nested.
+
+        """
+        return self._model.table_category_data(self._table_id)
+
     def add_row(
         self,
         num_rows: int | None = 1,