numbers-parser 4.8.0__py3-none-any.whl → 4.9.0__py3-none-any.whl

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
@@ -333,6 +363,36 @@ class BorderType(IntEnum):
 
 
 class Border:
+    """
+    Create a cell border to use with the :py:class:`~numbers_parser.Table` method
+    :py:meth:`~numbers_parser.Table.set_cell_border`.
+
+    .. code-block:: python
+
+        border_style = Border(8.0, RGB(29, 177, 0)
+        table.set_cell_border("B6", "left", border_style, "solid"), 3)
+        table.set_cell_border(6, 1, "right", border_style, "dashes"))
+
+    Parameters
+    ----------
+    width: float, optional, default: 0.35
+        Number of rows in the first table of a new document.
+    color: RGB, optional, default: RGB(0, 0, 0)
+        The line color for the border if present
+    style: BorderType, optional, default: ``None``
+        The type of border to create or ``None`` if there is no border defined. Valid
+        border types are:
+
+        * ``"solid"``: a solid line
+        * ``"dashes"``: a dashed line
+        * ``"dots"``: a dotted line
+
+    Raises
+    ------
+    TypeError:
+        If the width is not a float, or the border type is invalid.
+    """
+
     def __init__(
         self,
         width: float = DEFAULT_BORDER_WIDTH,
@@ -545,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
@@ -675,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:
@@ -1049,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/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

numbers_parser/constants.py

@@ -20,6 +20,7 @@ __all__ = [
     "FormattingType",
     "NegativeNumberStyle",
     "FractionAccuracy",
+    "ControlFormattingType",
 ]
 
 DEFAULT_DOCUMENT = files("numbers_parser") / "data" / "empty.numbers"
@@ -44,8 +45,11 @@ DEFAULT_TEXT_INSET = 4.0
 DEFAULT_TEXT_WRAP = True
 EMPTY_STORAGE_BUFFER = b"\x05\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00"
 
-# Formatting defaults
+# Formatting values and defaults
 DEFAULT_DATETIME_FORMAT = "dd MMM YYY HH:MM"
+CHECKBOX_FALSE_VALUE = "☐"
+CHECKBOX_TRUE_VALUE = "☑"
+STAR_RATING_VALUE = "★"
 
 # Numbers limits
 MAX_TILE_SIZE = 256
@@ -179,6 +183,39 @@ class FormattingType(IntEnum):
     NUMBER = 5
     PERCENTAGE = 6
     SCIENTIFIC = 7
+    TICKBOX = 8
+    RATING = 9
+    SLIDER = 10
+    STEPPER = 11
+    POPUP = 12
+    TEXT = 13
+
+
+class ControlFormattingType(IntEnum):
+    BASE = 1
+    CURRENCY = 2
+    FRACTION = 4
+    NUMBER = 5
+    PERCENTAGE = 6
+    SCIENTIFIC = 7
+
+
+FORMATTING_ALLOWED_CELLS = {
+    "base": ["NumberCell"],
+    "currency": ["NumberCell"],
+    "datetime": ["DateCell"],
+    "fraction": ["NumberCell"],
+    "number": ["NumberCell"],
+    "percentage": ["NumberCell"],
+    "popup": ["NumberCell", "TextCell"],
+    "rating": ["NumberCell"],
+    "scientific": ["NumberCell"],
+    "slider": ["NumberCell"],
+    "stepper": ["NumberCell"],
+    "tickbox": ["BoolCell"],
+}
+
+FORMATTING_ACTION_CELLS = ["tickbox", "rating", "popup", "slider", "stepper"]
 
 
 class CustomFormattingType(IntEnum):
@@ -187,6 +224,13 @@ class CustomFormattingType(IntEnum):
     TEXT = 103
 
 
+CUSTOM_FORMATTING_ALLOWED_CELLS = {
+    "number": ["NumberCell"],
+    "datetime": ["DateCell"],
+    "text": ["TextCell"],
+}
+
+
 @enum_tools.documentation.document_enum
 class NegativeNumberStyle(IntEnum):
     """
@@ -236,19 +280,47 @@ class FractionAccuracy(IntEnum):
 
 
 ALLOWED_FORMATTING_PARAMETERS = {
-    FormattingType.BASE: ["base", "base_places", "base_use_minus_sign"],
+    FormattingType.BASE: [
+        "base",
+        "base_places",
+        "base_use_minus_sign",
+    ],
     FormattingType.CURRENCY: [
+        "currency_code",
         "decimal_places",
-        "show_thousands_separator",
         "negative_style",
+        "show_thousands_separator",
         "use_accounting_style",
-        "currency_code",
     ],
     FormattingType.DATETIME: ["date_time_format"],
     FormattingType.FRACTION: ["fraction_accuracy"],
-    FormattingType.NUMBER: ["decimal_places", "show_thousands_separator", "negative_style"],
-    FormattingType.PERCENTAGE: ["decimal_places", "show_thousands_separator", "negative_style"],
+    FormattingType.NUMBER: [
+        "decimal_places",
+        "show_thousands_separator",
+        "negative_style",
+    ],
+    FormattingType.PERCENTAGE: [
+        "decimal_places",
+        "show_thousands_separator",
+        "negative_style",
+    ],
     FormattingType.SCIENTIFIC: ["decimal_places"],
+    FormattingType.POPUP: ["popup_values", "allow_none"],
+    FormattingType.RATING: [],
+    FormattingType.SLIDER: [
+        "control_format",
+        "increment",
+        "maximum",
+        "minimum",
+    ],
+    FormattingType.STEPPER: [
+        "control_format",
+        "increment",
+        "maximum",
+        "minimum",
+    ],
+    FormattingType.TICKBOX: [],
+    FormattingType.TEXT: [],
 }
 
 FORMAT_TYPE_MAP = {
@@ -258,7 +330,13 @@ FORMAT_TYPE_MAP = {
     FormattingType.FRACTION: FormatType.FRACTION,
     FormattingType.NUMBER: FormatType.DECIMAL,
     FormattingType.PERCENTAGE: FormatType.PERCENT,
+    FormattingType.POPUP: FormatType.TEXT,
+    FormattingType.RATING: FormatType.RATING,
     FormattingType.SCIENTIFIC: FormatType.SCIENTIFIC,
+    FormattingType.SLIDER: FormatType.DECIMAL,
+    FormattingType.STEPPER: FormatType.DECIMAL,
+    FormattingType.TICKBOX: FormatType.CHECKBOX,
+    FormattingType.TEXT: FormatType.TEXT,
 }
 
 CUSTOM_FORMAT_TYPE_MAP = {
@@ -268,7 +346,32 @@ CUSTOM_FORMAT_TYPE_MAP = {
 }
 
 
+class CellInteractionType(IntEnum):
+    VALUE_EDITING = 0
+    FORMULA_EDITING = 1
+    STOCK = 2
+    CATEGORY_SUMMARY = 3
+    STEPPER = 4
+    SLIDER = 5
+    RATING = 6
+    POPUP = 7
+    TOGGLE = 8
+
+
+CONTROL_CELL_TYPE_MAP = {
+    FormattingType.POPUP: CellInteractionType.POPUP,
+    FormattingType.SLIDER: CellInteractionType.SLIDER,
+    FormattingType.STEPPER: CellInteractionType.STEPPER,
+}
+
+
+@enum_tools.documentation.document_enum
 class PaddingType(IntEnum):
+    """How integers and decimals are padded in custom number formats"""
+
     NONE = 0
+    """No number padding."""
     ZEROS = 1
+    """Pad integers with leading spaces and decimals with trailing spaces."""
     SPACES = 2
+    """Pad integers with leading zeroes and decimals with trailing zeroes."""

numbers_parser/containers.py

@@ -59,7 +59,7 @@ class ObjectStore:
         self._objects[PACKAGE_ID].last_object_identifier = self._max_id
         return self._max_id
 
-    def create_object_from_dict(self, iwa_file: str, object_dict: dict, cls: object):
+    def create_object_from_dict(self, iwa_file: str, object_dict: dict, cls: object, append=False):
         """Create a new object and store the associated IWA segment. Return the
         message ID for the object and the newly created object. If the IWA
         file cannot be found, it will be created.
@@ -70,7 +70,7 @@ class ObjectStore:
         new_id = self.new_message_id()
         iwa_segment = create_iwa_segment(new_id, cls, object_dict)
 
-        if iwa_pathname is None:
+        if iwa_pathname is None and not append:
             iwa_pathname = iwa_file.format(new_id) + ".iwa"
             chunks = {"chunks": [{"archives": [iwa_segment.to_dict()]}]}
             self._file_store[iwa_pathname] = IWAFile.from_dict(chunks)