numbers-parser 4.8.1__tar.gz → 4.9.0__tar.gz

{numbers_parser-4.8.1 → numbers_parser-4.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: numbers-parser
-Version: 4.8.1
+Version: 4.9.0
 Summary: Read and write Apple Numbers spreadsheets
 Home-page: https://github.com/masaccio/numbers-parser
 License: MIT
@@ -187,8 +187,8 @@ Whilst support for writing numbers files has been stable since version
 and instead save data to a new file.
 
 Cell values are written using
-[Table.write()](https://masaccio.github.io/numbers-parser/#numbers_parser.Table.write)
-and `numbers-parser` will automatically create empty rows and columns
+[Table.write()](https://masaccio.github.io/numbers-parser/api/table.html#numbers_parser.Table.write) and
+`numbers-parser` will automatically create empty rows and columns
 for any cell references that are out of range of the current table.
 
 ```python
@@ -201,12 +201,9 @@ table.write("B7", datetime(2020, 12, 25))
 doc.save("new-sheet.numbers")
 ```
 
-Additional tables and worksheets can be added to a `Document` before
-saving using
-[Document.add_sheet()](https://masaccio.github.io/numbers-parser/#numbers_parser.Document.add_sheet)
-and
-[Sheet.add_table()](https://masaccio.github.io/numbers-parser/#numbers_parser.Sheet.add_table)
-respectively:
+Additional tables and worksheets can be added to a `Document` before saving using
+[Document.add_sheet()](https://masaccio.github.io/numbers-parser/api/document.html#numbers_parser.Document.add_sheet) and
+[Sheet.add_table()](https://masaccio.github.io/numbers-parser/api/sheet.html#numbers_parser.Sheet.add_table) respectively:
 
 ```python
 doc = Document()
@@ -222,27 +219,28 @@ doc.save("sheet.numbers")
 ### Styles
 
 `numbers_parser` currently only supports paragraph styles and cell
-styles. The following paragraph styles are supported:
+styles. The following styles are supported:
 
 - font attributes: bold, italic, underline, strikethrough
 - font selection and size
 - text foreground color
 - horizontal and vertical alignment
 - cell background color
+- cell background images
 - cell indents (first line, left, right, and text inset)
 
 Numbers conflates style attributes that can be stored in paragraph
 styles (the style menu in the text panel) with the settings that are
 available on the Style tab of the Text panel. Some attributes in Numbers
-are not applied to new cells when a style is applied. To keep the API
-simple, `numbers-parser` packs all styling into a single
-[Style](https://masaccio.github.io/numbers-parser/api/style.html)
-object. When a document is saved, the attributes not stored in a
-paragraph style are applied to each cell that includes it.
+are not applied to new cells when a style is applied.
+
+To keep the API simple, `numbers-parser` packs all styling into a single
+[Style](https://masaccio.github.io/numbers-parser/api/style.html) object. When a document is saved, the attributes
+not stored in a paragraph style are applied to each cell that includes it.
 
 Styles are read from cells using the
-[Cell.style](https://masaccio.github.io/numbers-parser/api/cells.html#numbers_parser.Cell.style)
-property and you can add new styles with
+[Cell.style](https://masaccio.github.io/numbers-parser/api/cells.html#numbers_parser.Cell.style) property and you can
+add new styles with
 [Document.add_style](https://masaccio.github.io/numbers-parser/api/document.html#numbers_parser.Document.add_style).
 
 ```python
@@ -272,7 +270,7 @@ internally by the package. Changing a data format for cell has no impact
 on any other cells.
 
 Cell formats are changed using
-[Table.set_cell_formatting](https://masaccio.github.io/numbers-parser/#numbers_parser.Table.set_cell_formatting):
+[Table.set_cell_formatting()](https://masaccio.github.io/numbers-parser/api/table.html#numbers_parser.Table.set_cell_formatting):
 
 ```python
 table.set_cell_formatting(
@@ -293,9 +291,9 @@ Custom formats are shared across a Document and can be applied to
 multiple cells in multiple tables. Editing a custom format changes the
 appearance of data in all cells that share that format. You must first
 add a custom format to the document using
-[Document.add_custom_format](https://masaccio.github.io/numbers-parser/#numbers_parser.Document.add_custom_format)
+[Document.add_custom_format()](https://masaccio.github.io/numbers-parser/api/document.html#numbers_parser.Document.add_custom_format)
 before assigning it to cells using
-[Table.set_cell_formatting](https://masaccio.github.io/numbers-parser/#numbers_parser.Table.set_cell_formatting):
+[Table.set_cell_formatting()](https://masaccio.github.io/numbers-parser/api/table.html#numbers_parser.Table.set_cell_formatting):
 
 ```python
 long_date = doc.add_custom_format(
@@ -322,13 +320,11 @@ table to allow for drawing borders across multiple cells. Setting the
 border of merged cells is not possible unless the edge of the cells is
 at the end of the merged region.
 
-Borders are represented using the
-[Border](https://masaccio.github.io/numbers-parser/#numbers_parser.Border)
-class that can be initialized with line width, color and line style. The
+Borders are represented using the [Border](https://masaccio.github.io/numbers-parser/api/border.html) class
+that can be initialized with line width, color and line style. The
 current state of a cell border is read using the
-[Cell.border](https://masaccio.github.io/numbers-parser/#numbers_parser.Cell.border)
-property. The
-[Table.set_cell_border](https://masaccio.github.io/numbers-parser/#numbers_parser.Table.set_cell_border)
+[Cell.border](https://masaccio.github.io/numbers-parser/api/cells.html#numbers_parser.Cell.border) property
+and [Table.set_cell_border()](https://masaccio.github.io/numbers-parser/api/table.html#numbers_parser.Table.set_cell_border)
 sets the border for a cell edge or a range of cells.
 
 ## API
@@ -400,6 +396,5 @@ Current known limitations of `numbers-parser` are:
 
 ## License
 
-All code in this repository is licensed under the [MIT
-License](https://github.com/masaccio/numbers-parser/blob/master/LICENSE.rst)
+All code in this repository is licensed under the [MIT License](https://github.com/masaccio/numbers-parser/blob/master/LICENSE.rst).
 

{numbers_parser-4.8.1 → numbers_parser-4.9.0}/README.md

@@ -157,8 +157,8 @@ Whilst support for writing numbers files has been stable since version
 and instead save data to a new file.
 
 Cell values are written using
-[Table.write()](https://masaccio.github.io/numbers-parser/#numbers_parser.Table.write)
-and `numbers-parser` will automatically create empty rows and columns
+[Table.write()](https://masaccio.github.io/numbers-parser/api/table.html#numbers_parser.Table.write) and
+`numbers-parser` will automatically create empty rows and columns
 for any cell references that are out of range of the current table.
 
 ```python
@@ -171,12 +171,9 @@ table.write("B7", datetime(2020, 12, 25))
 doc.save("new-sheet.numbers")
 ```
 
-Additional tables and worksheets can be added to a `Document` before
-saving using
-[Document.add_sheet()](https://masaccio.github.io/numbers-parser/#numbers_parser.Document.add_sheet)
-and
-[Sheet.add_table()](https://masaccio.github.io/numbers-parser/#numbers_parser.Sheet.add_table)
-respectively:
+Additional tables and worksheets can be added to a `Document` before saving using
+[Document.add_sheet()](https://masaccio.github.io/numbers-parser/api/document.html#numbers_parser.Document.add_sheet) and
+[Sheet.add_table()](https://masaccio.github.io/numbers-parser/api/sheet.html#numbers_parser.Sheet.add_table) respectively:
 
 ```python
 doc = Document()
@@ -192,27 +189,28 @@ doc.save("sheet.numbers")
 ### Styles
 
 `numbers_parser` currently only supports paragraph styles and cell
-styles. The following paragraph styles are supported:
+styles. The following styles are supported:
 
 - font attributes: bold, italic, underline, strikethrough
 - font selection and size
 - text foreground color
 - horizontal and vertical alignment
 - cell background color
+- cell background images
 - cell indents (first line, left, right, and text inset)
 
 Numbers conflates style attributes that can be stored in paragraph
 styles (the style menu in the text panel) with the settings that are
 available on the Style tab of the Text panel. Some attributes in Numbers
-are not applied to new cells when a style is applied. To keep the API
-simple, `numbers-parser` packs all styling into a single
-[Style](https://masaccio.github.io/numbers-parser/api/style.html)
-object. When a document is saved, the attributes not stored in a
-paragraph style are applied to each cell that includes it.
+are not applied to new cells when a style is applied.
+
+To keep the API simple, `numbers-parser` packs all styling into a single
+[Style](https://masaccio.github.io/numbers-parser/api/style.html) object. When a document is saved, the attributes
+not stored in a paragraph style are applied to each cell that includes it.
 
 Styles are read from cells using the
-[Cell.style](https://masaccio.github.io/numbers-parser/api/cells.html#numbers_parser.Cell.style)
-property and you can add new styles with
+[Cell.style](https://masaccio.github.io/numbers-parser/api/cells.html#numbers_parser.Cell.style) property and you can
+add new styles with
 [Document.add_style](https://masaccio.github.io/numbers-parser/api/document.html#numbers_parser.Document.add_style).
 
 ```python
@@ -242,7 +240,7 @@ internally by the package. Changing a data format for cell has no impact
 on any other cells.
 
 Cell formats are changed using
-[Table.set_cell_formatting](https://masaccio.github.io/numbers-parser/#numbers_parser.Table.set_cell_formatting):
+[Table.set_cell_formatting()](https://masaccio.github.io/numbers-parser/api/table.html#numbers_parser.Table.set_cell_formatting):
 
 ```python
 table.set_cell_formatting(
@@ -263,9 +261,9 @@ Custom formats are shared across a Document and can be applied to
 multiple cells in multiple tables. Editing a custom format changes the
 appearance of data in all cells that share that format. You must first
 add a custom format to the document using
-[Document.add_custom_format](https://masaccio.github.io/numbers-parser/#numbers_parser.Document.add_custom_format)
+[Document.add_custom_format()](https://masaccio.github.io/numbers-parser/api/document.html#numbers_parser.Document.add_custom_format)
 before assigning it to cells using
-[Table.set_cell_formatting](https://masaccio.github.io/numbers-parser/#numbers_parser.Table.set_cell_formatting):
+[Table.set_cell_formatting()](https://masaccio.github.io/numbers-parser/api/table.html#numbers_parser.Table.set_cell_formatting):
 
 ```python
 long_date = doc.add_custom_format(
@@ -292,13 +290,11 @@ table to allow for drawing borders across multiple cells. Setting the
 border of merged cells is not possible unless the edge of the cells is
 at the end of the merged region.
 
-Borders are represented using the
-[Border](https://masaccio.github.io/numbers-parser/#numbers_parser.Border)
-class that can be initialized with line width, color and line style. The
+Borders are represented using the [Border](https://masaccio.github.io/numbers-parser/api/border.html) class
+that can be initialized with line width, color and line style. The
 current state of a cell border is read using the
-[Cell.border](https://masaccio.github.io/numbers-parser/#numbers_parser.Cell.border)
-property. The
-[Table.set_cell_border](https://masaccio.github.io/numbers-parser/#numbers_parser.Table.set_cell_border)
+[Cell.border](https://masaccio.github.io/numbers-parser/api/cells.html#numbers_parser.Cell.border) property
+and [Table.set_cell_border()](https://masaccio.github.io/numbers-parser/api/table.html#numbers_parser.Table.set_cell_border)
 sets the border for a cell edge or a range of cells.
 
 ## API
@@ -370,5 +366,4 @@ Current known limitations of `numbers-parser` are:
 
 ## License
 
-All code in this repository is licensed under the [MIT
-License](https://github.com/masaccio/numbers-parser/blob/master/LICENSE.rst)
+All code in this repository is licensed under the [MIT License](https://github.com/masaccio/numbers-parser/blob/master/LICENSE.rst).

{numbers_parser-4.8.1 → numbers_parser-4.9.0}/pyproject.toml

@@ -12,7 +12,7 @@ name = "numbers-parser"
 packages = [{include = "numbers_parser", from = "src"}]
 readme = "README.md"
 repository = "https://github.com/masaccio/numbers-parser"
-version = "4.8.1"
+version = "4.9.0"
 
 [tool.poetry.scripts]
 cat-numbers = "numbers_parser._cat_numbers:main"

{numbers_parser-4.8.1 → numbers_parser-4.9.0}/src/numbers_parser/cell.py

@@ -1,9 +1,10 @@
 import re
 from collections import namedtuple
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from datetime import datetime as builtin_datetime
 from datetime import timedelta as builtin_timedelta
 from enum import IntEnum
+from os.path import basename
 from typing import Any, List, Tuple, Union
 from warnings import warn
 
@@ -27,6 +28,7 @@ from numbers_parser.constants import (
     EMPTY_STORAGE_BUFFER,
     MAX_BASE,
     MAX_SIGNIFICANT_DIGITS,
+    ControlFormattingType,
     CustomFormattingType,
     FormattingType,
     FormatType,
@@ -75,18 +77,43 @@ __all__ = [
 
 
 class BackgroundImage:
-    def __init__(self, image_data: bytes = None, filename: str = None):
-        self._data = image_data
-        self._filename = filename
+    """
+    A named document style that can be applied to cells.
+
+    .. code-block:: python
+
+        fh = open("cats.png", mode="rb")
+        image_data = fh.read()
+        cats_bg = doc.add_style(
+            name="Cats",
+            bg_image=BackgroundImage(image_data, "cats.png")
+        )
+        table.write(0, 0, "❤️ cats", style=cats_bg)
+
+    Currently only standard image files and not 'advanced' image fills are
+    supported. Tiling and scaling is not reported back and cannot be changed
+    when saving new cells.
+
+    Parameters
+    ----------
+    data: bytes
+        Raw image data for a cell background image.
+    filename: str
+        Path to the image file.
+    """
+
+    def __init__(self, data: bytes = None, filename: str = None):
+        self._data = data
+        self._filename = basename(filename)
 
     @property
     def data(self) -> bytes:
-        """The background image as byts for a cell, or None if no image."""
+        """bytes: The background image as bytes for a cell, or None if no image."""
         return self._data
 
     @property
     def filename(self) -> str:
-        """The image filename for a cell, or None if no image."""
+        """str: The image filename for a cell, or None if no image."""
         return self._filename
 
 
@@ -184,6 +211,8 @@ class Style:
     ------
     TypeError:
         If arguments do not match the specified type or for objects have invalid arguments
+    IndexError:
+        If an image filename already exists in document
     """
 
     alignment: Alignment = DEFAULT_ALIGNMENT_CLASS  # : horizontal and vertical alignment
@@ -230,6 +259,7 @@ class Style:
         return [
             "alignment",
             "bg_color",
+            "bg_image",
             "first_indent",
             "left_indent",
             "right_indent",
@@ -273,9 +303,9 @@ class Style:
         if not isinstance(self.font_name, str):
             raise TypeError("font name must be a string")
 
-        for field in ["bold", "italic", "underline", "strikethrough"]:
-            if not isinstance(getattr(self, field), bool):
-                raise TypeError(f"{field} argument must be boolean")
+        for attr in ["bold", "italic", "underline", "strikethrough"]:
+            if not isinstance(getattr(self, attr), bool):
+                raise TypeError(f"{attr} argument must be boolean")
 
     def __setattr__(self, name: str, value: Any) -> None:
         """Detect changes to cell styles and flag the style for
@@ -575,8 +605,14 @@ class Cell(Cacheable):
         else:
             raise ValueError("Can't determine cell type from type " + type(value).__name__)
 
-    def _set_formatting(self, format_id: int, format_type: FormattingType) -> None:
-        self._storage._set_formatting(format_id, format_type)
+    def _set_formatting(
+        self,
+        format_id: int,
+        format_type: FormattingType,
+        control_id: int = None,
+        is_currency: bool = False,
+    ) -> None:
+        self._storage.set_formatting(format_id, format_type, control_id, is_currency)
 
     def __init__(self, row: int, col: int, value):
         self._value = value
@@ -705,7 +741,32 @@ class Cell(Cacheable):
 
     @property
     def formatted_value(self) -> str:
-        """str: The formatted value of the cell as it appears in Numbers."""
+        """
+        str: The formatted value of the cell as it appears in Numbers.
+
+        Interactive elements are converted into a suitable text format where
+        supported, or as their number values where there is no suitable
+        visual representation. Currently supported mappings are:
+
+        * Checkboxes are U+2610 (Ballow Box) or U+2611 (Ballot Box with Check)
+        * Ratings are their star value represented using (U+2605) (Black Star)
+
+        .. code-block:: python
+
+            >>> table = doc.sheets[0].tables[0]
+            >>> table.cell(0,0).value
+            False
+            >>> table.cell(0,0).formatted_value
+            '☐'
+            >>> table.cell(0,1).value
+            True
+            >>> table.cell(0,1).formatted_value
+            '☑'
+            >>> table.cell(1,1).value
+            3.0
+            >>> table.cell(1,1).formatted_value
+            '★★★'
+        """
         if self._storage is None:
             return ""
         else:
@@ -1079,16 +1140,22 @@ def xl_col_to_name(col, col_abs=False):
 
 @dataclass()
 class Formatting:
-    type: FormattingType = FormattingType.NUMBER
+    allow_none: bool = False
     base_places: int = 0
     base_use_minus_sign: bool = True
     base: int = 10
+    control_format: ControlFormattingType = ControlFormattingType.NUMBER
     currency_code: str = "GBP"
     date_time_format: str = DEFAULT_DATETIME_FORMAT
     decimal_places: int = None
     fraction_accuracy: FractionAccuracy = FractionAccuracy.THREE
+    increment: float = 1.0
+    maximum: float = 100.0
+    minimum: float = 1.0
+    popup_values: List[str] = field(default_factory=lambda: ["Item 1"])
     negative_style: NegativeNumberStyle = NegativeNumberStyle.MINUS
     show_thousands_separator: bool = False
+    type: FormattingType = FormattingType.NUMBER
     use_accounting_style: bool = False
     _format_id = None
 

{numbers_parser-4.8.1 → numbers_parser-4.9.0}/src/numbers_parser/cell_storage.py

@@ -11,6 +11,8 @@ from pendulum import datetime, duration
 
 from numbers_parser import __name__ as numbers_parser_name
 from numbers_parser.constants import (
+    CHECKBOX_FALSE_VALUE,
+    CHECKBOX_TRUE_VALUE,
     CURRENCY_CELL_TYPE,
     CUSTOM_TEXT_PLACEHOLDER,
     DATETIME_FIELD_MAP,
@@ -21,6 +23,7 @@ from numbers_parser.constants import (
     SECONDS_IN_DAY,
     SECONDS_IN_HOUR,
     SECONDS_IN_WEEK,
+    STAR_RATING_VALUE,
     CellPadding,
     CellType,
     CustomFormattingType,
@@ -60,7 +63,7 @@ class CellStorage(Cacheable):
         # "cond_style_id",
         # "cond_rule_style_id",
         "formula_id",
-        # "control_id",
+        "control_id",
         "formula_error_id",
         "suggest_id",
         "num_format_id",
@@ -95,7 +98,7 @@ class CellStorage(Cacheable):
         # self.cond_style_id = None
         # self.cond_rule_style_id = None
         self.formula_id = None
-        # self.control_id = None
+        self.control_id = None
         self.formula_error_id = None
         self.suggest_id = None
         self.num_format_id = None
@@ -148,9 +151,9 @@ class CellStorage(Cacheable):
         if flags & 0x200:
             self.formula_id = unpack("<i", buffer[offset : offset + 4])[0]
             offset += 4
-        # if flags & 0x400:
-        #     self.control_id = unpack("<i", buffer[offset : offset + 4])[0]
-        #     offset += 4
+        if flags & 0x400:
+            self.control_id = unpack("<i", buffer[offset : offset + 4])[0]
+            offset += 4
         # if flags & 0x800:
         #     self.formula_error_id = unpack("<i", buffer[offset : offset + 4])[0]
         #     offset += 4
@@ -158,7 +161,7 @@ class CellStorage(Cacheable):
             self.suggest_id = unpack("<i", buffer[offset : offset + 4])[0]
             offset += 4
         # Skip unused flags
-        offset += 4 * bin(flags & 0xD00).count("1")
+        offset += 4 * bin(flags & 0x900).count("1")
         #
         if flags & 0x2000:
             self.num_format_id = unpack("<i", buffer[offset : offset + 4])[0]
@@ -300,13 +303,15 @@ class CellStorage(Cacheable):
             format = self.model.table_format(self.table_id, self.text_format_id)
         elif self.currency_format_id is not None:
             format = self.model.table_format(self.table_id, self.currency_format_id)
+        elif self.bool_format_id is not None and self.type == CellType.BOOL:
+            format = self.model.table_format(self.table_id, self.bool_format_id)
         elif self.num_format_id is not None:
             format = self.model.table_format(self.table_id, self.num_format_id)
-        elif self.bool_format_id is not None:
-            format = self.model.table_format(self.table_id, self.bool_format_id)
         else:
             return str(self.value)
 
+        debug("custom_format: @[%d,%d]: format_type=%s, ", self.row, self.col, format.format_type)
+
         if format.HasField("custom_uid"):
             format_uuid = NumbersUUID(format.custom_uid).hex
             format_map = self.model.custom_format_map()
@@ -336,6 +341,10 @@ class CellStorage(Cacheable):
             return format_fraction(self.d128, format)
         elif format.format_type == FormatType.SCIENTIFIC:
             return format_scientific(self.d128, format)
+        elif format.format_type == FormatType.CHECKBOX:
+            return CHECKBOX_TRUE_VALUE if self.value else CHECKBOX_FALSE_VALUE
+        elif format.format_type == FormatType.RATING:
+            return STAR_RATING_VALUE * int(self.d128)
         else:
             formatted_value = str(self.value)
         return formatted_value
@@ -362,6 +371,14 @@ class CellStorage(Cacheable):
 
     def duration_format(self) -> str:
         format = self.model.table_format(self.table_id, self.duration_format_id)
+        debug(
+            "duration_format: @[%d,%d]: table_id=%d, duration_format_id=%d, duration_style=%s",
+            self.row,
+            self.col,
+            self.table_id,
+            self.duration_format_id,
+            format.duration_style,
+        )
 
         duration_style = format.duration_style
         unit_largest = format.duration_unit_largest
@@ -431,15 +448,34 @@ class CellStorage(Cacheable):
 
         return duration_str
 
-    def _set_formatting(
-        self, format_id: int, format_type: Union[FormattingType, CustomFormattingType]
+    def set_formatting(
+        self,
+        format_id: int,
+        format_type: Union[FormattingType, CustomFormattingType],
+        control_id: int = None,
+        is_currency: bool = False,
     ) -> None:
+        self.is_currency = is_currency
         if format_type == FormattingType.CURRENCY:
             self.currency_format_id = format_id
-            self.is_currency = True
+        elif format_type == FormattingType.TICKBOX:
+            self.bool_format_id = format_id
+            self.control_id = control_id
+        elif format_type == FormattingType.RATING:
+            self.num_format_id = format_id
+            self.control_id = control_id
+        elif format_type in [FormattingType.SLIDER, FormattingType.STEPPER]:
+            if is_currency:
+                self.currency_format_id = format_id
+            else:
+                self.num_format_id = format_id
+            self.control_id = control_id
+        elif format_type == FormattingType.POPUP:
+            self.text_format_id = format_id
+            self.control_id = control_id
         elif format_type in [FormattingType.DATETIME, CustomFormattingType.DATETIME]:
             self.date_format_id = format_id
-        elif format_type == CustomFormattingType.TEXT:
+        elif format_type in [FormattingType.TEXT, CustomFormattingType.TEXT]:
             self.text_format_id = format_id
         else:
             self.num_format_id = format_id