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

numbers_parser/cell.py

@@ -13,17 +13,28 @@ from pendulum import instance as pendulum_instance
 
 from numbers_parser.cell_storage import CellStorage, CellType
 from numbers_parser.constants import (
+    DATETIME_FIELD_MAP,
+    DECIMAL_PLACES_AUTO,
     DEFAULT_ALIGNMENT,
     DEFAULT_BORDER_COLOR,
     DEFAULT_BORDER_STYLE,
     DEFAULT_BORDER_WIDTH,
+    DEFAULT_DATETIME_FORMAT,
     DEFAULT_FONT,
     DEFAULT_FONT_SIZE,
     DEFAULT_TEXT_INSET,
     DEFAULT_TEXT_WRAP,
     EMPTY_STORAGE_BUFFER,
+    MAX_BASE,
     MAX_SIGNIFICANT_DIGITS,
+    CustomFormattingType,
+    FormattingType,
+    FormatType,
+    FractionAccuracy,
+    NegativeNumberStyle,
+    PaddingType,
 )
+from numbers_parser.currencies import CURRENCIES
 from numbers_parser.exceptions import UnsupportedError, UnsupportedWarning
 from numbers_parser.generated import TSTArchives_pb2 as TSTArchives
 from numbers_parser.generated.TSWPArchives_pb2 import (
@@ -40,10 +51,12 @@ __all__ = [
     "BulletedTextCell",
     "Cell",
     "CellBorder",
+    "CustomFormatting",
     "DateCell",
     "DurationCell",
     "EmptyCell",
     "ErrorCell",
+    "Formatting",
     "HorizontalJustification",
     "MergeAnchor",
     "MergeReference",
@@ -132,8 +145,49 @@ RGB = namedtuple("RGB", ["r", "g", "b"])
 
 @dataclass
 class Style:
-    alignment: Alignment = DEFAULT_ALIGNMENT_CLASS
-    bg_image: object = None
+    """
+    A named document style that can be applied to cells.
+
+    Parameters
+    ----------
+    alignment: Alignment, optional, default: Alignment("auto", "top")
+        Horizontal and vertical alignment of the cell
+    bg_color: RGB | List[RGB], optional, default: RGB(0, 0, 0)
+        Background color or list of colors for gradients
+    bold: bool, optional, default: False
+        ``True`` if the cell font is bold
+    font_color: RGB, optional, default: RGB(0, 0, 0)) – Font color
+    font_size: float, optional, default: DEFAULT_FONT_SIZE
+        Font size in points
+    font_name: str, optional, default: DEFAULT_FONT_SIZE
+        Font name
+    italic: bool, optional, default: False
+        ``True`` if the cell font is italic
+    name: str, optional
+        Style name
+    underline: bool, optional, default: False) – True if the
+        cell font is underline
+    strikethrough: bool, optional, default: False) – True if
+        the cell font is strikethrough
+    first_indent: float, optional, default: 0.0) – First line
+        indent in points
+    left_indent: float, optional, default: 0.0
+        Left indent in points
+    right_indent: float, optional, default: 0.0
+        Right indent in points
+    text_inset: float, optional, default: DEFAULT_TEXT_INSET
+        Text inset in points
+    text_wrap: str, optional, default: True
+        ``True`` if text wrapping is enabled
+
+    Raises
+    ------
+    TypeError:
+        If arguments do not match the specified type or for objects have invalid arguments
+    """
+
+    alignment: Alignment = DEFAULT_ALIGNMENT_CLASS  # : horizontal and vertical alignment
+    bg_image: object = None  # : backgroung image
     bg_color: Union[RGB, List[RGB]] = None
     font_color: RGB = RGB(0, 0, 0)
     font_size: float = DEFAULT_FONT_SIZE
@@ -409,48 +463,53 @@ class MergeAnchor:
 
 
 class Cell(Cacheable):
+    """
+    .. NOTE::
+       Do not instantiate directly. Cells are created by :py:class:`~numbers_parser.Document`.
+    """
+
     @classmethod
-    def empty_cell(cls, table_id: int, row_num: int, col_num: int, model: object):
-        cell = EmptyCell(row_num, col_num)
+    def empty_cell(cls, table_id: int, row: int, col: int, model: object):
+        cell = EmptyCell(row, col)
         cell._model = model
         cell._table_id = table_id
         merge_cells = model.merge_cells(table_id)
-        cell._set_merge(merge_cells.get((row_num, col_num)))
+        cell._set_merge(merge_cells.get((row, col)))
 
         return cell
 
     @classmethod
-    def merged_cell(cls, table_id: int, row_num: int, col_num: int, model: object):
-        cell = MergedCell(row_num, col_num)
+    def merged_cell(cls, table_id: int, row: int, col: int, model: object):
+        cell = MergedCell(row, col)
         cell._model = model
         cell._table_id = table_id
         merge_cells = model.merge_cells(table_id)
-        cell._set_merge(merge_cells.get((row_num, col_num)))
+        cell._set_merge(merge_cells.get((row, col)))
         return cell
 
     @classmethod
     def from_storage(cls, cell_storage: CellStorage):
         if cell_storage.type == CellType.EMPTY:
-            cell = EmptyCell(cell_storage.row_num, cell_storage.col_num)
+            cell = EmptyCell(cell_storage.row, cell_storage.col)
         elif cell_storage.type == CellType.NUMBER:
-            cell = NumberCell(cell_storage.row_num, cell_storage.col_num, cell_storage.value)
+            cell = NumberCell(cell_storage.row, cell_storage.col, cell_storage.value)
         elif cell_storage.type == CellType.TEXT:
-            cell = TextCell(cell_storage.row_num, cell_storage.col_num, cell_storage.value)
+            cell = TextCell(cell_storage.row, cell_storage.col, cell_storage.value)
         elif cell_storage.type == CellType.DATE:
-            cell = DateCell(cell_storage.row_num, cell_storage.col_num, cell_storage.value)
+            cell = DateCell(cell_storage.row, cell_storage.col, cell_storage.value)
         elif cell_storage.type == CellType.BOOL:
-            cell = BoolCell(cell_storage.row_num, cell_storage.col_num, cell_storage.value)
+            cell = BoolCell(cell_storage.row, cell_storage.col, cell_storage.value)
         elif cell_storage.type == CellType.DURATION:
             value = duration(seconds=cell_storage.value)
-            cell = DurationCell(cell_storage.row_num, cell_storage.col_num, value)
+            cell = DurationCell(cell_storage.row, cell_storage.col, value)
         elif cell_storage.type == CellType.ERROR:
-            cell = ErrorCell(cell_storage.row_num, cell_storage.col_num)
+            cell = ErrorCell(cell_storage.row, cell_storage.col)
         elif cell_storage.type == CellType.RICH_TEXT:
-            cell = RichTextCell(cell_storage.row_num, cell_storage.col_num, cell_storage.value)
+            cell = RichTextCell(cell_storage.row, cell_storage.col, cell_storage.value)
         else:
             raise UnsupportedError(
                 f"Unsupported cell type {cell_storage.type} "
-                + f"@:({cell_storage.row_num},{cell_storage.col_num})"
+                + f"@:({cell_storage.row},{cell_storage.col})"
             )
 
         cell._table_id = cell_storage.table_id
@@ -458,18 +517,18 @@ class Cell(Cacheable):
         cell._storage = cell_storage
         cell._formula_key = cell_storage.formula_id
         merge_cells = cell_storage.model.merge_cells(cell_storage.table_id)
-        cell._set_merge(merge_cells.get((cell_storage.row_num, cell_storage.col_num)))
+        cell._set_merge(merge_cells.get((cell_storage.row, cell_storage.col)))
         return cell
 
     @classmethod
-    def from_value(cls, row_num: int, col_num: int, value):
+    def from_value(cls, row: int, col: int, value):
         # TODO: write needs to retain/init the border
         if isinstance(value, str):
-            return TextCell(row_num, col_num, value)
+            return TextCell(row, col, value)
         elif isinstance(value, bool):
-            return BoolCell(row_num, col_num, value)
+            return BoolCell(row, col, value)
         elif isinstance(value, int):
-            return NumberCell(row_num, col_num, value)
+            return NumberCell(row, col, value)
         elif isinstance(value, float):
             rounded_value = sigfig.round(value, sigfigs=MAX_SIGNIFICANT_DIGITS, warn=False)
             if rounded_value != value:
@@ -478,22 +537,22 @@ class Cell(Cacheable):
                     RuntimeWarning,
                     stacklevel=2,
                 )
-            return NumberCell(row_num, col_num, rounded_value)
+            return NumberCell(row, col, rounded_value)
         elif isinstance(value, (DateTime, builtin_datetime)):
-            return DateCell(row_num, col_num, pendulum_instance(value))
+            return DateCell(row, col, pendulum_instance(value))
         elif isinstance(value, (Duration, builtin_timedelta)):
-            return DurationCell(row_num, col_num, value)
+            return DurationCell(row, col, value)
         else:
             raise ValueError("Can't determine cell type from type " + type(value).__name__)
 
-    def set_formatting(self, formatting: dict):
-        raise TypeError(f"Cannot set formatting for cells of type {type(self).__name__}")
+    def _set_formatting(self, format_id: int, format_type: FormattingType) -> None:
+        self._storage._set_formatting(format_id, format_type)
 
-    def __init__(self, row_num: int, col_num: int, value):
+    def __init__(self, row: int, col: int, value):
         self._value = value
-        self.row = row_num
-        self.col = col_num
-        self.is_bulleted = False
+        self.row = row
+        self.col = col
+        self._is_bulleted = False
         self._formula_key = None
         self._storage = None
         self._style = None
@@ -553,13 +612,26 @@ class Cell(Cacheable):
             return None
 
     @property
-    def is_formula(self):
+    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)
 
     @property
     @cache(num_args=0)
-    def formula(self):
+    def formula(self) -> str:
+        """
+        str: The formula in a cell.
+
+        Formula evaluation relies on Numbers storing current values which should
+        usually be the case. In cells containing a formula, :py:meth:`numbers_parser.Cell.value`
+        returns computed value of the formula.
+
+        Returns:
+            str:
+                The text of the foruma in a cell, or `None` if there is no formula
+                present in a cell.
+        """
         if self._formula_key is not None:
             table_formulas = self._model.table_formulas(self._table_id)
             return table_formulas.formula(self._formula_key, self.row, self.col)
@@ -567,18 +639,56 @@ class Cell(Cacheable):
             return None
 
     @property
-    def bullets(self) -> str:
+    def is_bulleted(self) -> bool:
+        """bool: ``True`` if the cell contains text bullets."""
+        return self._is_bulleted
+
+    @property
+    def bullets(self) -> Union[List[str], None]:
+        r"""
+        List[str] | None: The bullets in a cell, or ``None``
+
+        Cells that contain bulleted or numbered lists are identified
+        by :py:attr:`numbers_parser.Cell.is_bulleted`. For these cells,
+        :py:attr:`numbers_parser.Cell.value` returns the whole cell contents.
+        Bullets can also be extracted into a list of paragraphs cell without the
+        bullet or numbering character. Newlines are not included in the
+        bullet list.
+
+        Example
+        -------
+
+        .. code-block:: python
+
+            doc = Document("bullets.numbers")
+            sheets = doc.sheets
+            tables = sheets[0].tables
+            table = tables[0]
+            if not table.cell(0, 1).is_bulleted:
+                print(table.cell(0, 1).value)
+            else:
+                bullets = ["* " + s for s in table.cell(0, 1).bullets]
+                print("\n".join(bullets))
+                    return None
+        """
         return None
 
     @property
-    def formatted_value(self):
+    def formatted_value(self) -> str:
+        """str: The formatted value of the cell as it appears in Numbers."""
         if self._storage is None:
             return ""
         else:
             return self._storage.formatted
 
     @property
-    def style(self):
+    def style(self) -> Union[Style, None]:
+        """Style | None: The :class:`Style` associated with the cell or ``None``.
+
+        Warns:
+            UnsupportedWarning: On assignment; use
+                :py:meth:`numbers_parser.Table.set_cell_style` instead.
+        """
         if self._storage is None:
             self._storage = CellStorage(
                 self._model, self._table_id, EMPTY_STORAGE_BUFFER, self.row, self.col
@@ -596,7 +706,13 @@ class Cell(Cacheable):
         )
 
     @property
-    def border(self):
+    def border(self) -> Union[CellBorder, None]:
+        """CellBorder| None: The :class:`CellBorder` associated with the cell or ``None``.
+
+        Warns:
+            UnsupportedWarning: On assignment; use
+                :py:meth:`numbers_parser.Table.set_cell_border` instead.
+        """
         self._model.extract_strokes(self._table_id)
         return self._border
 
@@ -608,24 +724,29 @@ class Cell(Cacheable):
             stacklevel=2,
         )
 
+    def update_storage(self, storage: CellStorage) -> None:
+        self._storage = storage
+
 
 class NumberCell(Cell):
-    def __init__(self, row_num: int, col_num: int, value: float):
+    """
+    .. NOTE::
+       Do not instantiate directly. Cells are created by :py:class:`~numbers_parser.Document`.
+    """
+
+    def __init__(self, row: int, col: int, value: float):
         self._type = TSTArchives.numberCellType
-        super().__init__(row_num, col_num, value)
+        super().__init__(row, col, value)
 
     @property
     def value(self) -> int:
         return self._value
 
-    def set_formatting(self, formatting: dict):
-        self._storage.set_number_formatting(formatting)
-
 
 class TextCell(Cell):
-    def __init__(self, row_num: int, col_num: int, value: str):
+    def __init__(self, row: int, col: int, value: str):
         self._type = TSTArchives.textCellType
-        super().__init__(row_num, col_num, value)
+        super().__init__(row, col, value)
 
     @property
     def value(self) -> str:
@@ -633,34 +754,60 @@ class TextCell(Cell):
 
 
 class RichTextCell(Cell):
-    def __init__(self, row_num: int, col_num: int, value):
+    """
+    .. NOTE::
+       Do not instantiate directly. Cells are created by :py:class:`~numbers_parser.Document`.
+    """
+
+    def __init__(self, row: int, col: int, value):
         self._type = TSTArchives.automaticCellType
-        super().__init__(row_num, col_num, value["text"])
+        super().__init__(row, col, value["text"])
         self._bullets = value["bullets"]
         self._hyperlinks = value["hyperlinks"]
         if value["bulleted"]:
             self._formatted_bullets = [
-                value["bullet_chars"][i] + " " + value["bullets"][i]
-                if value["bullet_chars"][i] is not None
-                else value["bullets"][i]
+                (
+                    value["bullet_chars"][i] + " " + value["bullets"][i]
+                    if value["bullet_chars"][i] is not None
+                    else value["bullets"][i]
+                )
                 for i in range(len(self._bullets))
             ]
-            self.is_bulleted = True
+            self._is_bulleted = True
 
     @property
     def value(self) -> str:
         return self._value
 
     @property
-    def bullets(self) -> str:
+    def bullets(self) -> List[str]:
+        """List[str]: A list of the text bullets in the cell."""
         return self._bullets
 
     @property
     def formatted_bullets(self) -> str:
+        """str: The bullets as a formatted multi-line string."""
         return self._formatted_bullets
 
     @property
-    def hyperlinks(self) -> List[Tuple]:
+    def hyperlinks(self) -> Union[List[Tuple], None]:
+        """
+        List[Tuple] | None: the hyperlinks in a cell or ``None``
+
+        Numbers does not support hyperlinks to cells within a spreadsheet, but does
+        allow embedding links in cells. When cells contain hyperlinks,
+        `numbers_parser` returns the text version of the cell. The `hyperlinks` property
+        of cells where :py:attr:`numbers_parser.Cell.is_bulleted` is ``True`` is a
+        list of text and URL tuples.
+
+        Example
+        -------
+
+        .. code-block:: python
+
+            cell = table.cell(0, 0)
+            (text, url) = cell.hyperlinks[0]
+        """
         return self._hyperlinks
 
 
@@ -670,8 +817,13 @@ class BulletedTextCell(RichTextCell):
 
 
 class EmptyCell(Cell):
-    def __init__(self, row_num: int, col_num: int):
-        super().__init__(row_num, col_num, None)
+    """
+    .. NOTE::
+       Do not instantiate directly. Cells are created by :py:class:`~numbers_parser.Document`.
+    """
+
+    def __init__(self, row: int, col: int):
+        super().__init__(row, col, None)
         self._type = None
 
     @property
@@ -680,10 +832,15 @@ class EmptyCell(Cell):
 
 
 class BoolCell(Cell):
-    def __init__(self, row_num: int, col_num: int, value: bool):
+    """
+    .. NOTE::
+       Do not instantiate directly. Cells are created by :py:class:`~numbers_parser.Document`.
+    """
+
+    def __init__(self, row: int, col: int, value: bool):
         self._type = TSTArchives.boolCellType
         self._value = value
-        super().__init__(row_num, col_num, value)
+        super().__init__(row, col, value)
 
     @property
     def value(self) -> bool:
@@ -691,24 +848,24 @@ class BoolCell(Cell):
 
 
 class DateCell(Cell):
-    def __init__(self, row_num: int, col_num: int, value: DateTime):
+    """
+    .. NOTE::
+       Do not instantiate directly. Cells are created by :py:class:`~numbers_parser.Document`.
+    """
+
+    def __init__(self, row: int, col: int, value: DateTime):
         self._type = TSTArchives.dateCellType
-        super().__init__(row_num, col_num, value)
+        super().__init__(row, col, value)
 
     @property
     def value(self) -> duration:
         return self._value
 
-    def set_formatting(self, formatting: dict):
-        if "date_time_format" not in formatting:
-            raise TypeError("No date_time_format specified for DateCell formatting")
-        self._storage.set_date_time_formatting(formatting["date_time_format"])
-
 
 class DurationCell(Cell):
-    def __init__(self, row_num: int, col_num: int, value: Duration):
+    def __init__(self, row: int, col: int, value: Duration):
         self._type = TSTArchives.durationCellType
-        super().__init__(row_num, col_num, value)
+        super().__init__(row, col, value)
 
     @property
     def value(self) -> duration:
@@ -716,9 +873,14 @@ class DurationCell(Cell):
 
 
 class ErrorCell(Cell):
-    def __init__(self, row_num: int, col_num: int):
+    """
+    .. NOTE::
+       Do not instantiate directly. Cells are created by :py:class:`~numbers_parser.Document`.
+    """
+
+    def __init__(self, row: int, col: int):
         self._type = TSTArchives.formulaErrorCellType
-        super().__init__(row_num, col_num, None)
+        super().__init__(row, col, None)
 
     @property
     def value(self):
@@ -726,8 +888,13 @@ class ErrorCell(Cell):
 
 
 class MergedCell(Cell):
-    def __init__(self, row_num: int, col_num: int):
-        super().__init__(row_num, col_num, None)
+    """
+    .. NOTE::
+       Do not instantiate directly. Cells are created by :py:class:`~numbers_parser.Document`.
+    """
+
+    def __init__(self, row: int, col: int):
+        super().__init__(row, col, None)
 
     @property
     def value(self):
@@ -740,11 +907,18 @@ 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.
-    Args:
-        cell_str:  A1 style string.
-    Returns:
-        row, col: Zero indexed cell row and column indices.
+    """
+    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
@@ -771,13 +945,23 @@ def xl_cell_to_rowcol(cell_str: str) -> tuple:
 
 
 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.
-    Args:
-       first_row: The first cell row.    Int.
-       first_col: The first cell column. Int.
-       last_row:  The last cell row.     Int.
-       last_col:  The last cell column.  Int.
-    Returns:
+    """
+    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)
@@ -790,13 +974,23 @@ def xl_range(first_row, first_col, last_row, last_col):
 
 
 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.
-    Args:
-       row:     The cell row.    Int.
-       col:     The cell column. Int.
-       row_abs: Optional flag to make the row absolute.    Bool.
-       col_abs: Optional flag to make the column absolute. Bool.
-    Returns:
+    """
+    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:
@@ -814,24 +1008,29 @@ def xl_rowcol_to_cell(row, col, row_abs=False, col_abs=False):
 
 
 def xl_col_to_name(col, col_abs=False):
-    """Convert a zero indexed column cell reference to a string.
-    Args:
-       col:     The cell column. Int.
-       col_abs: Optional flag to make the column absolute. Bool.
+    """
+    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:
-        Column style string.
+        str:
+            Column in A1 notation.
     """
-    col_num = col
-    if col_num < 0:
-        raise IndexError(f"column reference {col_num} below zero")
+    if col < 0:
+        raise IndexError(f"column reference {col} below zero")
 
-    col_num += 1  # Change to 1-index.
+    col += 1  # Change to 1-index.
     col_str = ""
     col_abs = "$" if col_abs else ""
 
-    while col_num:
+    while col:
         # Set remainder from 1 .. 26
-        remainder = col_num % 26
+        remainder = col % 26
 
         if remainder == 0:
             remainder = 26
@@ -843,6 +1042,92 @@ def xl_col_to_name(col, col_abs=False):
         col_str = col_letter + col_str
 
         # Get the next order of magnitude.
-        col_num = int((col_num - 1) / 26)
+        col = int((col - 1) / 26)
 
     return col_abs + col_str
+
+
+@dataclass()
+class Formatting:
+    type: FormattingType = FormattingType.NUMBER
+    base_places: int = 0
+    base_use_minus_sign: bool = True
+    base: int = 10
+    currency_code: str = "GBP"
+    date_time_format: str = DEFAULT_DATETIME_FORMAT
+    decimal_places: int = None
+    fraction_accuracy: FractionAccuracy = FractionAccuracy.THREE
+    negative_style: NegativeNumberStyle = NegativeNumberStyle.MINUS
+    show_thousands_separator: bool = False
+    use_accounting_style: bool = False
+    _format_id = None
+
+    def __post_init__(self):
+        if not isinstance(self.type, FormattingType):
+            type_name = type(self.type).__name__
+            raise TypeError(f"Invalid format type '{type_name}'")
+
+        if self.use_accounting_style and self.negative_style != NegativeNumberStyle.MINUS:
+            warn(
+                "use_accounting_style overriding negative_style",
+                RuntimeWarning,
+                stacklevel=4,
+            )
+
+        if self.type == FormattingType.DATETIME:
+            formats = re.sub(r"[^a-zA-Z\s]", " ", self.date_time_format).split()
+            for el in formats:
+                if el not in DATETIME_FIELD_MAP.keys():
+                    raise TypeError(f"Invalid format specifier '{el}' in date/time format")
+
+        if self.type == FormattingType.CURRENCY:
+            if self.currency_code not in CURRENCIES:
+                raise TypeError(f"Unsupported currency code '{self.currency_code}'")
+
+        if self.decimal_places is None:
+            if self.type == FormattingType.CURRENCY:
+                self.decimal_places = 2
+            else:
+                self.decimal_places = DECIMAL_PLACES_AUTO
+
+        if (
+            self.type == FormattingType.BASE
+            and not self.base_use_minus_sign
+            and self.base not in (2, 8, 16)
+        ):
+            raise TypeError(f"base_use_minus_sign must be True for base {self.base}")
+
+        if self.type == FormattingType.BASE and (self.base < 2 or self.base > MAX_BASE):
+            raise TypeError("base must be in range 2-36")
+
+
+@dataclass
+class CustomFormatting:
+    type: CustomFormattingType = CustomFormattingType.NUMBER
+    name: str = None
+    integer_format: PaddingType = PaddingType.NONE
+    decimal_format: PaddingType = PaddingType.NONE
+    num_integers: int = 0
+    num_decimals: int = 0
+    show_thousands_separator: bool = False
+    format: str = "%s"
+
+    def __post_init__(self):
+        if not isinstance(self.type, CustomFormattingType):
+            type_name = type(self.type).__name__
+            raise TypeError(f"Invalid format type '{type_name}'")
+
+        if self.type == CustomFormattingType.TEXT:
+            if self.format.count("%s") > 1:
+                raise TypeError("Custom formats only allow one text substitution")
+
+    @classmethod
+    def from_archive(cls, archive: object):
+        if archive.format_type == FormatType.CUSTOM_DATE:
+            format_type = CustomFormattingType.DATETIME
+        elif archive.format_type == FormatType.CUSTOM_NUMBER:
+            format_type = CustomFormattingType.NUMBER
+        else:
+            format_type = CustomFormattingType.TEXT
+
+        return CustomFormatting(name=archive.name, type=format_type)