numbers-parser

https://masaccio.github.io/numbers-parser/
Admin
A Python module for parsing Apple Numbers .numbers files, supporting Numbers version 10.3 and later...
Tokens:80,201
Snippets:485
Trust Score:8.3
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install numbers-parser with Homebrew and pipx

Source: https://masaccio.github.io/numbers-parser/_sources/installation.rst.txt

Installs the snappy binary library and Python via Homebrew, then uses pipx to install the numbers-parser package. This is the recommended setup for macOS.

```bash
brew install snappy python3 pipx
pipx install numbers-parser
```

--------------------------------

### Install libsnappy-dev on Linux

Source: https://masaccio.github.io/numbers-parser/_sources/installation.rst.txt

Installs the snappy binary library on Linux using apt. Your package manager may differ.

```bash
sudo apt-get -y install libsnappy-dev
```

--------------------------------

### Install python-snappy wheel on Windows Arm

Source: https://masaccio.github.io/numbers-parser/_sources/installation.rst.txt

Installs a pre-compiled python-snappy wheel for Windows on Arm. No x86 pre-compiled packages are available for Windows.

```text
pip install python_snappy-0.6.1-cp312-cp312-win_arm64.whl
```

--------------------------------

### categorized_data() example output

Source: https://masaccio.github.io/numbers-parser/_modules/numbers_parser/document.html

Example output structure for categorized_data() when categories are enabled. Shows a dictionary with category keys mapping to lists of rows, where each row is a list of cell values.

```python
"Transport": [
    {"Airplane", "Air": 5 },
    {"Helicopter": "Air", 2 },
    {"Bus": "Road", 10 },
],
"Fruit": [
    {"Apple", "Green": 7 },
    {"Banana", "Yellow", 6 },
],
```

--------------------------------

### Border Class

Source: https://masaccio.github.io/numbers-parser/api/border.html

Documentation for the Border class constructor, including parameters, valid border types, and an example usage.

```APIDOC
## Border Class

### Description
Creates a cell border to use with the `Table` method `set_cell_border()`.

### Constructor
`Border(width: float = 0.35, color: RGB = None, style: BorderType = None)`

### Parameters
- **width** (float, optional, default: 0.35) - Line width in points.
- **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.

### Example
```python
border_style = Border(8.0, RGB(29, 177, 0), "solid")
table.set_cell_border("B6", "left", border_style, 3)
table.set_cell_border(6, 1, "right", border_style)
```
```

--------------------------------

### numbers_parser.BackgroundImage

Source: https://masaccio.github.io/numbers-parser/api/style.html

Documentation for the BackgroundImage class in numbers_parser, including constructor parameters, properties, and usage example.

```APIDOC
## BackgroundImage Class

### Description
Represents a background image for a cell style. It stores raw image data and a filename.

### Class
`numbers_parser.BackgroundImage`

### Constructor Parameters
- **data** (bytes | None, optional) - Raw image data for a cell background image.
- **filename** (str | None, optional) - Path to the image file. Only the basename is stored.

### Properties
- **data** (bytes | None) - The background image as bytes for a cell, or None if no image.
- **filename** (str | None) - The image filename for a cell, or None if no image.

### Example
```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)
```
```

--------------------------------

### Create and apply a BackgroundImage style

Source: https://masaccio.github.io/numbers-parser/_modules/numbers_parser/cell.html

Example from the BackgroundImage docstring showing how to create a cell background image style and apply it to a cell. Only standard image files are supported; tiling and scaling are not reported back and cannot be changed when saving new cells.

```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)
```

--------------------------------

### Transform columns with --transform (POS, NEG, LOOKUP)

Source: https://masaccio.github.io/numbers-parser/cli.html

Transforms columns using the NEW:FUNC=OLD syntax. The first example creates 'Paid In' from positive Amount values and 'Withdrawn' from negative Amount values. The second example uses LOOKUP with a mapping file (mapping.numbers) that must contain a single two-column table; values are matched by longest substring.

```bash
csv2numbers --transform="Paid In"=POS:Amount,Withdrawn=NEG:Amount file1.csv

```

```bash
csv2numbers --transform='Category=LOOKUP:Transaction;mapping.numbers' file1.csv

```

--------------------------------

### Build protobuf with C++ support for make bootstrap

Source: https://masaccio.github.io/numbers-parser/_sources/api/development.rst.txt

Build Google protobuf with C++ support, required to avoid the error 'This script requires the Protobuf installation to use the C++ implementation. Please reinstall Protobuf with C++ support.' when running make bootstrap. As of April 2023, these commands were useful; build instructions may change over time.

```shell
bazel build :protoc :protobuf
cmake . -DCMAKE_CXX_STANDARD=14
cmake --build . --parallel 8
export PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION=cpp
export LD_LIBRARY_PATH=../bazel-bin/src/google
cd python
python3 setup.py -q bdist_wheel --cpp_implementation --warnings_as_errors --compile_static_extension
```

--------------------------------

### numbers_parser.Style

Source: https://masaccio.github.io/numbers-parser/api/style.html

Documentation for the Style class in numbers_parser, including constructor parameters, exceptions, and usage example.

```APIDOC
## Style Class

### Description
Represents a named document style that can be applied to cells. It encapsulates all styling attributes such as font, alignment, background, and indentation.

### Class
`numbers_parser.Style`

### Constructor Parameters
- **alignment** (Alignment, optional, default: Alignment("auto", "top")) - Horizontal and vertical alignment of the cell
- **bg_color** (RGB | List[RGB], optional, default: None) - 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 | tuple[str, str], optional, default: DEFAULT_FONT) - Font name or a tuple of font family and style
- **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 underlined
- **strikethrough** (bool, optional, default: False) - True if the cell font uses 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** (bool, optional, default: True) - True if text wrapping is enabled

### Exceptions
- **TypeError** - If arguments do not match the specified type or for objects have invalid arguments
- **IndexError** - If an image filename already exists in document
- **ValueError** - If a font name is not known.

### Example
```python
red_text = doc.add_style(
    name="Red Text",
    font_name="Lucida Grande",
    font_color=RGB(230, 25, 25),
    font_size=14.0,
    bold=True,
    italic=True,
    alignment=Alignment("right", "top"),
)
table.write("B2", "Red", style=red_text)
table.set_cell_style("C2", red_text)
```
```

--------------------------------

### csv2numbers conversion example

Source: https://masaccio.github.io/numbers-parser/_sources/cli.rst.txt

Example invocation of csv2numbers converting two CSV files to Numbers documents. If -o is omitted, output files are created by replacing the input file suffix with .numbers.

```text
csv2numbers file1.csv file2.csv -o file1.numbers file2.numbers
```

--------------------------------

### Module imports and __all__ for numbers_parser.cell

Source: https://masaccio.github.io/numbers-parser/_modules/numbers_parser/cell.html

Imports and module-level definitions for the numbers_parser.cell module, including logging setup and the public API list in __all__.

```python
from __future__ import annotations

import logging
import math
import re
from dataclasses import asdict, dataclass, field, fields
from datetime import datetime, timedelta
from enum import IntEnum
from fractions import Fraction
from hashlib import sha1
from os.path import basename
from struct import pack, unpack
from typing import Any, NamedTuple
from warnings import warn

from sigfig import round as sigfig

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,
    DECIMAL128_BIAS,
    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,
    EPOCH,
    FONT_FAMILY_DEFAULT,
    FONT_TUPLE_MAP,
    MAX_BASE,
    MAX_SIGNIFICANT_DIGITS,
    PACKAGE_ID,
    SECONDS_IN_DAY,
    SECONDS_IN_HOUR,
    SECONDS_IN_WEEK,
    STAR_RATING_VALUE,
    CellPadding,
    CellType,
    ControlFormattingType,
    CustomFormattingType,
    DurationStyle,
    DurationUnits,
    FormattingType,
    FormatType,
    FractionAccuracy,
    NegativeNumberStyle,
    NumberFormatConditionType,
    PaddingType,
)
from numbers_parser.currencies import CURRENCIES, CURRENCY_SYMBOLS
from numbers_parser.exceptions import UnsupportedError, UnsupportedWarning
from numbers_parser.generated import TSKArchives_pb2 as TSKArchives
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 (
    ParagraphStylePropertiesArchive as ParagraphStyle,
)
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",
    "Border",
    "BorderType",
    "BulletedTextCell",
    "Cell",
    "CellBorder",
    "CustomFormatting",
    "DateCell",
    "DurationCell",
    "EmptyCell",
    "ErrorCell",
    "Formatting",
    "HorizontalJustification",
    "MergeAnchor",
    "MergeReference",
    "MergedCell",
    "NumberCell",
    "RichTextCell",
    "Style",
    "TextCell",
    "VerticalJustification",
]
```

--------------------------------

### add_column(num_cols, start_col, default)

Source: https://masaccio.github.io/numbers-parser/_modules/numbers_parser/document.html

Adds or inserts columns to the table. The number of columns must be positive, and the start column is zero-indexed. If start_col is None, columns are added to the end of the table.

```APIDOC
## add_column(num_cols, start_col, default)

### Description
Add or insert columns to the table. The number of columns must be positive, and the start column is zero-indexed. If start_col is None, columns are added to the end of the table.

### Method
add_column

### Parameters
- **num_cols** (int) - Optional, default: 1 - The number of columns to add to the table. Must be positive.
- **start_col** (int) - Optional, default: None - The start column number (zero indexed), or None to add a column to the end of the table.
- **default** (str | int | float | bool | DateTime | Duration) - Optional, default: None - The default value for cells. Supported values are those supported by numbers_parser.Table.write which will determine the new cell type.

### Raises
- **RuntimeWarning** - If the default value is a float that is rounded to the maximum number of supported digits.
- **IndexError** - If the start_col is out of range for the table.
- **ValueError** - If the default value is unsupported by numbers_parser.Table.write.

### Returns
None
```

--------------------------------

### Access tables from a sheet

Source: https://masaccio.github.io/numbers-parser/_sources/api/table.rst.txt

Shows how to retrieve a Table object from a Sheet using list-style or dict-style indexing. The example loads a document, accesses a sheet by name, and then accesses a table by index or by name.

```python
>>> from numbers_parser import Document
>>> doc = Document("mydoc.numbers")
>>> sheet = doc.sheets["Sheet 1"]
>>> sheet.tables[0]
<numbers_parser.document.Table object at 0x1063e5d10>
>>> sheet.tables[0].name
'Table 1'
>>> sheet.tables["Table 1"].name
'Table 1'
```

--------------------------------

### Transform columns with --transform

Source: https://masaccio.github.io/numbers-parser/_sources/cli.rst.txt

Transforms columns using --transform. The first example uses POS and NEG functions to isolate positive and negative amounts. The second uses LOOKUP to map values from an external Apple Numbers file.

```text
csv2numbers --transform="Paid In"=POS:Amount,Withdrawn=NEG:Amount file1.csv
```

```text
csv2numbers --transform='Category=LOOKUP:Transaction;mapping.numbers' file1.csv
```

--------------------------------

### add_row(num_rows, start_row, default)

Source: https://masaccio.github.io/numbers-parser/_modules/numbers_parser/document.html

Adds or inserts rows to the table. The number of rows must be positive, and the start row is zero-indexed. If start_row is None, rows are added to the end of the table.

```APIDOC
## add_row(num_rows, start_row, default)

### Description
Add or insert rows to the table. The number of rows must be positive, and the start row is zero-indexed. If start_row is None, rows are added to the end of the table.

### Method
add_row

### Parameters
- **num_rows** (int) - Optional, default: 1 - The number of rows to add to the table. Must be positive.
- **start_row** (int) - Optional, default: None - The start row number (zero indexed), or None to add a row to the end of the table.
- **default** (str | int | float | bool | DateTime | Duration) - Optional, default: None - The default value for cells. Supported values are those supported by numbers_parser.Table.write which will determine the new cell type.

### Raises
- **RuntimeWarning** - If the default value is a float that is rounded to the maximum number of supported digits.
- **IndexError** - If the start_row is out of range for the table.
- **ValueError** - If the default value is unsupported by numbers_parser.Table.write.

### Returns
None
```

--------------------------------

### cell() notation examples

Source: https://masaccio.github.io/numbers-parser/_modules/numbers_parser/document.html

Illustrates the two forms of notation accepted by the cell() method: row-column (zero-indexed) and A1 notation. The comment shows that (0, 0) and "A1" refer to the same cell.

```python
(0, 0)      # Row-column notation.
("A1")      # The same cell in A1 notation.
```

--------------------------------

### Access sheets via Document.sheets

Source: https://masaccio.github.io/numbers-parser/_sources/api/sheet.rst.txt

Shows how to access sheets from a Numbers document using list-style and dict-style indexing. The example creates a Document from "mydoc.numbers" and retrieves the first sheet, its name, and a sheet by name. Note that Sheet objects should not be instantiated directly; they are created by the Document class.

```python
>>> from numbers_parser import Document
>>> doc = Document("mydoc.numbers")
>>> doc.sheets[0]
<numbers_parser.document.Sheet object at 0x105f12390>
>>> doc.sheets[0].name
'Sheet 1'
>>> doc.sheets["Sheet 1"].name
'Sheet 1'
```

--------------------------------

### set_cell_border usage with row-column and A1 references

Source: https://masaccio.github.io/numbers-parser/_modules/numbers_parser/document.html

Example usage of set_cell_border with both row-column offsets and A1 notation. The first call sets a dashed border on the right side of cell B7, and the second sets a solid border starting at B7's left border extending for 3 rows. Borders on invisible edges of merged cells are ignored with a RuntimeWarning.

```python
# Dashed line for B7's right border
table.set_cell_border(6, 1, "right", Border(5.0, RGB(29, 177, 0), "dashes"))
# Solid line starting at B7's left border and running for 3 rows
table.set_cell_border("B7", "left", Border(8.0, RGB(29, 177, 0), "solid"), 3)
```

--------------------------------

### csv2numbers usage and options help

Source: https://masaccio.github.io/numbers-parser/cli.html

Command-line help output for csv2numbers. Lists all options: --whitespace, --reverse, --no-header, --day-first, --date, --rename, --transform, --delete, and -o/--output. Defaults for the boolean options are false.

```text
usage: csv2numbers [-h] [-V] [--whitespace] [--reverse] [--no-header]
                   [--day-first] [--date COLUMNS] [--rename COLUMNS-MAP]
                   [--transform COLUMNS-MAP] [--delete COLUMNS]
                   [-o [FILENAME ...]]
                   [csvfile ...]

positional arguments:
  csvfile               CSV file to convert

options:
  -h, --help            show this help message and exit
  -V, --version
  --whitespace          strip whitespace from beginning and end of strings
                        and collapse other whitespace into single space
                        (default: false)
  --reverse             reverse the order of the data rows (default:
                        false)
  --no-header           CSV file has no header row (default: false)
  --day-first           dates are represented day first in the CSV file
                        (default: false)
  --date COLUMNS        comma-separated list of column names/indexes to
                        parse as dates
  --rename COLUMNS-MAP  comma-separated list of column names/indexes to
                        renamed as 'OLD:NEW'
  --transform COLUMNS-MAP
                        comma-separated list of column names/indexes to
                        transform as 'NEW:FUNC=OLD'
  --delete COLUMNS      comma-separated list of column names/indexes to
                        delete
  -o [FILENAME ...], --output [FILENAME ...]
                        output filename (default: use source file with
                        .numbers)

```

--------------------------------

### Sheet.name

Source: https://masaccio.github.io/numbers-parser/_modules/numbers_parser/document.html

Gets or sets the name of the sheet.

```APIDOC
## Sheet.name

### Description
Gets or sets the name of the sheet.

### Property
name

### Returns
- **str** - The name of the sheet.

### Setter Parameters
- **value** (str) - The new name for the sheet.
```

--------------------------------

### Style.__post_init__ validation

Source: https://masaccio.github.io/numbers-parser/_modules/numbers_parser/cell.html

Post-initialization validation for Style dataclass. Converts colors, validates font size/name, resolves font details, and ensures boolean attributes. Raises TypeError or ValueError on invalid input.

```python
    def __post_init__(self):
        self.bg_color = rgb_color(self.bg_color)
        self.font_color = rgb_color(self.font_color)

        if not isinstance(self.font_size, (float, int)):
            msg = "size must be a float number of points"
            raise TypeError(msg)

        if not isinstance(self.font_name, (str, tuple)):
            msg = "font name must be a string or name/style tuple"
            raise TypeError(msg)

        if isinstance(self.font_name, str) and self.font_name in FONT_FAMILY_DEFAULT:
            self._font_details = FONT_FAMILY_DEFAULT[self.font_name]
        elif isinstance(self.font_name, tuple) and self.font_name in FONT_TUPLE_MAP:
            self._font_details = FONT_TUPLE_MAP[self.font_name]
        else:
            msg = f"font '{self.font_name}' does not exist"
            raise ValueError(msg)

        for attr in ["bold", "italic", "underline", "strikethrough"]:
            if not isinstance(getattr(self, attr), bool):
                msg = f"{attr} argument must be boolean"
                raise TypeError(msg)
```

--------------------------------

### Document.__init__

Source: https://masaccio.github.io/numbers-parser/_modules/numbers_parser/document.html

Constructor for the Document class, used to create a new Numbers document or read an existing one.

```APIDOC
## Document(filename=None, sheet_name='Sheet 1', table_name='Table 1', num_header_rows=1, num_header_cols=1, num_rows=12, num_cols=8, password=None)

### Description
Creates 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 optionally override these defaults at object construction time.

### Method
Constructor

### Parameters
- **filename** (str | Path) - Optional - Apple Numbers document to read.
- **sheet_name** (str) - Optional, default: 'Sheet 1' - Name of the first sheet in a new document.
- **table_name** (str) - Optional, default: 'Table 1' - Name of the first table in the first sheet of a new document.
- **num_header_rows** (int) - Optional, default: 1 - Number of header rows in the first table of a new document.
- **num_header_cols** (int) - Optional, default: 1 - Number of header columns in the first table of a new document.
- **num_rows** (int) - Optional, default: 12 - Number of rows in the first table of a new document.
- **num_cols** (int) - Optional, default: 8 - Number of columns in the first table of a new document.
- **password** (str) - Optional, default: None - Password for encrypted documents.

### Raises
- **IndexError** - If the sheet name already exists in the document.
- **IndexError** - If the table name already exists in the first sheet.
- **UnsupportedError** - If the document is encrypted.

### Example
```python
doc = Document()
doc = Document('example.numbers')
doc = Document('example.numbers', password='secret')
```
```

--------------------------------

### Table.name

Source: https://masaccio.github.io/numbers-parser/_modules/numbers_parser/document.html

Property to get or set the name of a table.

```APIDOC
## Table.name

### Description
Gets or sets the table's name.

### Property
`name` (str) - The table's name.

### Getter
Returns the table's name.

### Setter
Sets the table's name to the provided value.
```

--------------------------------

### col_width

Source: https://masaccio.github.io/numbers-parser/api/table.html

Gets or sets the width of a table column in points.

```APIDOC
## col_width

### Description
The width of a table column in points.

### Method
col_width

### Parameters
- **col** (int) - The column index.
- **width** (int, optional) - The width to set. If not provided, returns the current width.

### Returns
- **int** - The width of the column in points.
```

--------------------------------

### row_height

Source: https://masaccio.github.io/numbers-parser/api/table.html

Method to get or set the height of a table row in points.

```APIDOC
## row_height(row: int, height: int | None = None) -> int

### Description
Gets or sets the height of a table row in points. If `height` is provided, sets the row height; otherwise, returns the current height.

### Parameters
- **row** (int) – The row number (zero indexed).
- **height** (int | None) – The height of the row in points. If not `None`, set the row height.

### Returns
- **int** – The height of the table row.

### Example
```python
# Double the row's height
_ = table.row_height(4, table.row_height(4) * 2)
```
```

--------------------------------

### Add a style with a background image using BackgroundImage

Source: https://masaccio.github.io/numbers-parser/api/style.html

Reads an image file and creates a style with a background image, then writes a cell with that style. Note that only standard image files are supported; tiling and scaling are not reported or changeable.

```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)

```

--------------------------------

### num_header_rows

Source: https://masaccio.github.io/numbers-parser/api/table.html

Property to get or set the number of header rows in a table.

```APIDOC
## num_header_rows

### Description
Gets or sets the number of header rows in the table.

### Property
`num_header_rows` (int)

### Raises
- **ValueError** – If the number of headers is negative, exceeds the number of rows in the table, or exceeds Numbers maximum number of headers (`MAX_HEADER_COUNT`).

### Example
```python
# Add an extra header row
table.num_header_rows += 1
```
```

--------------------------------

### Document.add_style

Source: https://masaccio.github.io/numbers-parser/_modules/numbers_parser/document.html

Adds a new style to the document. Accepts keyword arguments for style properties and an optional BackgroundImage. Returns the created Style object.

```APIDOC
## Document.add_style

### Description
Adds a new style to the current document. Accepts keyword arguments for style properties and an optional BackgroundImage. Returns the created Style object.

### Method
add_style

### Parameters
#### Keyword Arguments
- **bg_image** (BackgroundImage, optional) - A BackgroundImage object to store with the style. Must be a BackgroundImage instance or TypeError is raised.
- **kwargs** (Style properties) - Additional keyword arguments passed to the Style constructor. If no name is provided, a unique name is generated.

### Returns
- **Style** - The newly created style object.

### Raises
- **TypeError** - If bg_image is not a BackgroundImage object.
```

--------------------------------

### num_header_cols

Source: https://masaccio.github.io/numbers-parser/api/table.html

Property to get or set the number of header columns in a table.

```APIDOC
## num_header_cols

### Description
Gets or sets the number of header columns in the table.

### Property
`num_header_cols` (int)

### Raises
- **ValueError** – If the number of headers is negative, exceeds the number of columns in the table, or exceeds Numbers maximum number of headers (`MAX_HEADER_COUNT`).

### Example
```python
# Add an extra header column
table.num_header_cols += 1
```
```

--------------------------------

### Sheet.tables

Source: https://masaccio.github.io/numbers-parser/_modules/numbers_parser/document.html

Gets the list of tables in the sheet, indexed by position or name.

```APIDOC
## Sheet.tables

### Description
Gets the list of tables in the sheet, indexed by position or name.

### Property
tables

### Returns
- **ItemsList[Table]** - The tables in the sheet.
```

--------------------------------

### save(filename: str | Path, package: bool = False, password: str | None = None, hint: str = 'No hint') -> None

Source: https://masaccio.github.io/numbers-parser/api/document.html

Saves the document to a file, optionally as a package or encrypted with a password.

```APIDOC
## save(filename: str | Path, package: bool = False, password: str | None = None, hint: str = 'No hint') -> None

### Description
Save the document in the specified filename. If the file already exists, it will be overwritten.

### Method
save

### Parameters
- **filename** (_str_ | _Path_) – The path to save the document to. If the file already exists, it will be overwritten.
- **package** (_bool_, optional, default: False) – If `True`, create a package format document (a folder) instead of a single file
- **password** (_str_, optional, default: None) – If not None, the document is encrypted using the password.
- **hint** (_str_, optional, default: "No hint") – The hint stored with an encrypted document.

### Raises
- **FileFormatError** – If attempting to write a package into a folder that is not an existing Numbers document.
```

--------------------------------

### Cell __init__ method

Source: https://masaccio.github.io/numbers-parser/_modules/numbers_parser/cell.html

Initializes a Cell instance with row, column, and value. Sets internal attributes for formula, storage, style, and numeric values.

```python
    def __init__(self, row: int, col: int, value) -> None:
        self._value = value
        self.row = row
        self.col = col
        self._is_bulleted = False
        self._formula_id = None
        self._storage = None
        self._style = None
        self._d128 = None
        self._double = None
        self._seconds = None
        super().__init__()
```

--------------------------------

### Document

Source: https://masaccio.github.io/numbers-parser/_sources/api/document.rst.txt

Documentation for the Document class in the numbers_parser library, including constructor, methods, and usage examples.

```APIDOC
## Document

### Description
Represents a single Numbers document which contains multiple sheets. Sheets can contain multiple tables. The contents of the document are read once on construction of a Document.

### Constructor
- `Document(filename: str)` - Creates a Document from an existing Numbers file.
- `Document()` - Creates a new empty Document.

### Methods
- `add_sheet(name: str, table_name: str)` - Adds a new sheet with a table to the document.
- `save(filename: str)` - Saves the document to the specified file.

### Properties
- `sheets` - List of sheets in the document. Access by index or name.

### Example
```python
from numbers_parser import Document
doc = Document("mydoc.numbers")
doc.sheets[0].name
# 'Sheet 1'
table = doc.sheets[0].tables[0]
table.name
# 'Table 1'
```

### Creating a New Document
```python
doc = Document()
doc.add_sheet("New Sheet", "New Table")
sheet = doc.sheets["New Sheet"]
table = sheet.tables["New Table"]
table.write(1, 1, 1000)
table.write(1, 2, 2000)
table.write(1, 3, 3000)
doc.save("mydoc.numbers")
```
```

--------------------------------

### styles (property)

Source: https://masaccio.github.io/numbers-parser/api/document.html

Returns a dictionary of styles by name.

```APIDOC
## styles (property)

### Description
A dict mapping style names to the corresponding style.

### Type
Dict[str, `Style`]
```
Tokens:
Raw