numbers-parser 4.17.0.post1__py3-none-any.whl → 4.18.0__py3-none-any.whl

numbers_parser/_cat_numbers.py

@@ -16,11 +16,19 @@ from numbers_parser import (
 )
 from numbers_parser import __name__ as numbers_parser_name
 from numbers_parser.constants import MAX_SIGNIFICANT_DIGITS
-from numbers_parser.experimental import _enable_experimental_features
+from numbers_parser.experimental import ExperimentalFeatures, enable_experimental_feature
 
 logger = logging.getLogger(numbers_parser_name)
 
 
+def experimental_feature_choice(s: str) -> ExperimentalFeatures:
+    try:
+        return ExperimentalFeatures[s]
+    except KeyError:
+        msg = f"invalid experimental feature: {s}"
+        raise argparse.ArgumentTypeError(msg)  # noqa: B904
+
+
 def command_line_parser():
     parser = argparse.ArgumentParser(
         description="Export data from Apple Numbers spreadsheet tables",
@@ -70,10 +78,13 @@ def command_line_parser():
     )
     parser.add_argument("document", nargs="*", help="Document(s) to export")
     parser.add_argument("--debug", default=False, action="store_true", help="Enable debug logging")
+    experimental_choices = [
+        f.name for f in ExperimentalFeatures if f is not ExperimentalFeatures.NONE
+    ]
     parser.add_argument(
         "--experimental",
-        default=False,
-        action="store_true",
+        type=experimental_feature_choice,
+        choices=[ExperimentalFeatures[name] for name in experimental_choices],
         help=argparse.SUPPRESS,
     )
     return parser
@@ -136,7 +147,7 @@ def main() -> None:
         else:
             logger.setLevel("ERROR")
         if args.experimental:
-            _enable_experimental_features(True)
+            enable_experimental_feature(args.experimental)
         for filename in args.document:
             try:
                 if args.list_sheets:

numbers_parser/cell.py

@@ -56,7 +56,6 @@ 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 (
@@ -257,7 +256,7 @@ class Style:
     """
 
     alignment: Alignment = DEFAULT_ALIGNMENT_CLASS  # : horizontal and vertical alignment
-    bg_image: object = None  # : backgroung image
+    bg_image: object = None  # : background image
     bg_color: RGB | list[RGB] = None
     font_color: RGB = field(default_factory=default_color)
     font_size: float = DEFAULT_FONT_SIZE
@@ -651,7 +650,7 @@ class Cell(CellStorageFlags, Cacheable):
         Returns
         -------
             str:
-                The text of the foruma in a cell, or `None` if there is no formula
+                The text of the formula in a cell, or `None` if there is no formula
                 present in a cell.
 
         """
@@ -660,17 +659,6 @@ 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."""
@@ -933,7 +921,7 @@ class Cell(CellStorageFlags, Cacheable):
         elif cell_type == CURRENCY_CELL_TYPE:
             cell = NumberCell(row, col, d128, cell_type=CellType.CURRENCY)
         else:
-            msg = f"Cell type ID {cell_type} is not recognised"
+            msg = f"Cell type ID {cell_type} is not recognized"
             raise UnsupportedError(msg)
 
         cell._copy_flags(storage_flags)

numbers_parser/document.py

@@ -45,7 +45,7 @@ class Document:
     Create an instance of a new Numbers document.
 
     If ``filename`` is ``None``, an empty document is created using the defaults
-    defined by the class constructor. You can optionionally override these
+    defined by the class constructor. You can optionally override these
     defaults at object construction time.
 
     Parameters
@@ -303,7 +303,7 @@ class Document:
             * **num_decimals** (``int``, *optional*, default: ``0``) - Integer precision
               when decimals are padded.
             * **show_thousands_separator** (``bool``, *optional*, default: ``False``) - ``True``
-              if the number should include a thousands seperator.
+              if the number should include a thousands separator.
 
         :``"datetime"``:
             * **format** (``str``, *optional*, default: ``"d MMM y"``) - A POSIX strftime-like
@@ -327,7 +327,7 @@ class Document:
             try:
                 kwargs["type"] = CustomFormattingType[format_type]
             except (KeyError, AttributeError):
-                msg = f"unsuported cell format type '{format_type}'"
+                msg = f"unsupported cell format type '{format_type}'"
                 raise TypeError(msg) from None
 
         custom_format = CustomFormatting(**kwargs)
@@ -474,7 +474,7 @@ class Table(Cacheable):
         self._table_id = table_id
         self.num_rows = self._model.number_of_rows(self._table_id)
         self.num_cols = self._model.number_of_columns(self._table_id)
-        # Cache all data now to facilite write(). Performance impact
+        # Cache all data now to facilitate write(). Performance impact
         # of computing all cells is minimal compared to file IO
         self._data = []
         self._model.set_table_data(table_id, self._data)
@@ -545,7 +545,7 @@ class Table(Cacheable):
         ------
         ValueError:
             If the number of headers is negative, exceeds the number of rows in the
-            table, or exceeds Numbers maxinum number of headers (``MAX_HEADER_COUNT``).
+            table, or exceeds Numbers maximum number of headers (``MAX_HEADER_COUNT``).
 
         """
         return self._model.num_header_rows(self._table_id)
@@ -579,7 +579,7 @@ class Table(Cacheable):
         ------
         ValueError:
             If the number of headers is negative, exceeds the number of rows in the
-            table, or exceeds Numbers maxinum number of headers (``MAX_HEADER_COUNT``).
+            table, or exceeds Numbers maximum number of headers (``MAX_HEADER_COUNT``).
 
         """
         return self._model.num_header_cols(self._table_id)
@@ -756,6 +756,8 @@ class Table(Cacheable):
             msg = f"column {col} out of range"
             raise IndexError(msg)
 
+        if (row_mapper := self._model.table_category_row_map(self._table_id)) is not None:
+            return self._data[row_mapper[row]][col]
         return self._data[row][col]
 
     def iter_rows(
@@ -803,10 +805,10 @@ class Table(Cacheable):
                 sum += row
 
         """
-        min_row = min_row or 0
-        max_row = max_row or self.num_rows - 1
-        min_col = min_col or 0
-        max_col = max_col or self.num_cols - 1
+        min_row = min_row if min_row is not None else 0
+        max_row = max_row if max_row is not None else self.num_rows - 1
+        min_col = min_col if min_col is not None else 0
+        max_col = max_col if max_col is not None else self.num_cols - 1
 
         if min_row < 0:
             msg = f"row {min_row} out of range"
@@ -822,11 +824,16 @@ class Table(Cacheable):
             raise IndexError(msg)
 
         rows = self.rows()
-        for row in range(min_row, max_row + 1):
+        if (row_mapper := self._model.table_category_row_map(self._table_id)) is not None:
+            rows = [rows[row_mapper[row]] for row in range(min_row, max_row + 1)]
+        else:
+            rows = rows[min_row : max_row + 1]
+
+        for row in rows:
             if values_only:
-                yield tuple(cell.value for cell in rows[row][min_col : max_col + 1])
+                yield tuple(cell.value for cell in row[min_col : max_col + 1])
             else:
-                yield tuple(rows[row][min_col : max_col + 1])
+                yield tuple(row[min_col : max_col + 1])
 
     def iter_cols(
         self,
@@ -873,10 +880,10 @@ class Table(Cacheable):
                 sum += col.value
 
         """
-        min_row = min_row or 0
-        max_row = max_row or self.num_rows - 1
-        min_col = min_col or 0
-        max_col = max_col or self.num_cols - 1
+        min_row = min_row if min_row is not None else 0
+        max_row = max_row if max_row is not None else self.num_rows - 1
+        min_col = min_col if min_col is not None else 0
+        max_col = max_col if max_col is not None else self.num_cols - 1
 
         if min_row < 0:
             msg = f"row {min_row} out of range"
@@ -892,11 +899,16 @@ class Table(Cacheable):
             raise IndexError(msg)
 
         rows = self.rows()
+        if (row_mapper := self._model.table_category_row_map(self._table_id)) is not None:
+            rows = [rows[row_mapper[row_num]] for row_num in range(min_row, max_row + 1)]
+        else:
+            rows = rows[min_row : max_row + 1]
+
         for col in range(min_col, max_col + 1):
             if values_only:
-                yield tuple(row[col].value for row in rows[min_row : max_row + 1])
+                yield tuple(row[col].value for row in rows)
             else:
-                yield tuple(row[col] for row in rows[min_row : max_row + 1])
+                yield tuple(row[col] for row in rows)
 
     def _validate_cell_coords(self, *args):
         if isinstance(args[0], str):
@@ -961,7 +973,7 @@ class Table(Cacheable):
         Raises
         ------
         IndexError:
-            If the style name cannot be foiund in the document.
+            If the style name cannot be found in the document.
         TypeError:
             If the style parameter is an invalid type.
         ValueError:
@@ -1001,8 +1013,8 @@ class Table(Cacheable):
 
     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.
+        Return the table's data organized into categories, if enabled or ``None``
+        if the table has not had categories 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
@@ -1279,7 +1291,7 @@ class Table(Cacheable):
         """
         Set the borders for a cell.
 
-        Cell references can be row-column offsers or Excel/Numbers-style A1 notation. Borders
+        Cell references can be row-column offsets or Excel/Numbers-style A1 notation. Borders
         can be applied to multiple sides of a cell by passing a list of sides. The name(s)
         of the side(s) must be one of ``"top"``, ``"right"``, ``"bottom"`` or ``"left"``.
 
@@ -1299,7 +1311,7 @@ class Table(Cacheable):
             * **param2** (*int*): The column number (zero indexed).
             * **param3** (*str | List[str]*): Which side(s) of the cell to apply the border to.
             * **param4** (:py:class:`Border`): The border to add.
-            * **param5** (*int*, *optinal*, default: 1): The length of the stroke to add.
+            * **param5** (*int*, *optional*, default: 1): The length of the stroke to add.
 
         :Args (A1):
             * **param1** (*str*): A cell reference using Excel/Numbers-style A1 notation.
@@ -1380,7 +1392,7 @@ class Table(Cacheable):
         r"""
         Set the data format for a cell.
 
-        Cell references can be **row-column** offsers or Excel/Numbers-style **A1** notation.
+        Cell references can be **row-column** offsets or Excel/Numbers-style **A1** notation.
 
         .. code:: python
 
@@ -1463,8 +1475,8 @@ class Table(Cacheable):
               decimal places, or ``None`` for automatic.
 
         :``"custom"``:
-            * **format** (*str | CustomFormating*) - The name of a custom
-                formatin the document or a :py:class:`~numbers_parser.CustomFormatting`
+            * **format** (*str | CustomFormatting*) - The name of a custom
+                formatting the document or a :py:class:`~numbers_parser.CustomFormatting`
                 object.
 
         :``"currency"``:
@@ -1475,7 +1487,7 @@ class Table(Cacheable):
             * **negative_style** (*:py:class:`~numbers_parser.NegativeNumberStyle`, optional, default: NegativeNumberStyle.MINUS*) - How negative numbers are represented.
               See `Negative number formats <#negative-formats>`_.
             * **show_thousands_separator** (*bool, optional, default: False*) - ``True``
-              if the number should include a thousands seperator, e.g. ``,``
+              if the number should include a thousands separator, e.g. ``,``
             * **use_accounting_style** (*bool, optional, default: False*) -  ``True``
               if the currency symbol should be formatted to the left of the cell and
               separated from the number value by a tab.
@@ -1495,7 +1507,7 @@ class Table(Cacheable):
             * **negative_style** (*:py:class:`~numbers_parser.NegativeNumberStyle`, optional, default: NegativeNumberStyle.MINUS*) - How negative numbers are represented.
               See `Negative number formats <#negative-formats>`_.
             * **show_thousands_separator** (*bool, optional, default: False*) - ``True``
-              if the number should include a thousands seperator, e.g. ``,``
+              if the number should include a thousands separator, e.g. ``,``
 
         :``"scientific"``:
             * **decimal_places** (*float, optional, default: None*) - number of
@@ -1586,7 +1598,7 @@ class Table(Cacheable):
             format_type = FormattingType[format_type_name.upper()]
             _ = FORMATTING_ALLOWED_CELLS[format_type_name]
         except (KeyError, AttributeError):
-            msg = f"unsuported cell format type '{format_type_name}'"
+            msg = f"unsupported cell format type '{format_type_name}'"
             raise TypeError(msg) from None
 
         cell = self._data[row][col]

numbers_parser/exceptions.py

@@ -7,7 +7,7 @@ class UnsupportedError(NumbersError):
 
 
 class NotImplementedError(NumbersError):
-    """Raised for unsuported Protobufs/Formats."""
+    """Raised for unsupported Protobufs/Formats."""
 
 
 class FileError(NumbersError):

numbers_parser/experimental.py

@@ -1,16 +1,30 @@
 import logging
+from enum import Flag, auto
 
 logger = logging.getLogger(__name__)
 debug = logger.debug
 
-_EXPERIMENTAL_FEATURES = False
 
+class ExperimentalFeatures(Flag):
+    NONE = auto()
+    TESTING = auto()
+    GROUPED_CATEGORIES = auto()
 
-def _enable_experimental_features(status: bool) -> None:
-    global _EXPERIMENTAL_FEATURES
-    _EXPERIMENTAL_FEATURES = status
-    debug("Experimental features %s", "on" if status else "off")
 
+EXPERIMENTAL_FEATURES = ExperimentalFeatures.NONE
 
-def _experimental_features() -> bool:
-    return _EXPERIMENTAL_FEATURES
+
+def enable_experimental_feature(flags: ExperimentalFeatures) -> None:
+    global EXPERIMENTAL_FEATURES
+    EXPERIMENTAL_FEATURES |= flags
+    debug("Experimental features: enabling %s, flags=%s", flags, EXPERIMENTAL_FEATURES)
+
+
+def disable_experimental_feature(flags: ExperimentalFeatures) -> None:
+    global EXPERIMENTAL_FEATURES
+    EXPERIMENTAL_FEATURES ^= flags
+    debug("Experimental features: disabling %s, flags=%s", flags, EXPERIMENTAL_FEATURES)
+
+
+def experimental_features() -> ExperimentalFeatures:
+    return EXPERIMENTAL_FEATURES