Table Class¶

Each Table object represents a single table in a Numbers sheet. Tables are returned by the the Sheet property tables and can be indexed using either list style or dict style indexes:

>>> 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'

Note

Do not instantiate directly. Tables are created by Document.

class numbers_parser.Table[source]¶

Add or insert columns to the table.

Parameters:

num_cols (int, optional, default: 1) – The number of columns to add to the table.
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.

Warns:

RuntimeWarning – If the default value is a float that is rounded to the maximum number of supported digits.

Raises:

IndexError: – If the start_col is out of range for the table.
ValueError: – If the default value is unsupported by numbers_parser.Table.write().

Add or insert rows to the table.

Parameters:

num_rows (int, optional, default: 1) – The number of rows to add to the table.
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.

Warns:

RuntimeWarning – If the default value is a float that is rounded to the maximum number of supported digits.

Raises:

IndexError: – If the start_row is out of range for the table.
ValueError: – If the default value is unsupported by numbers_parser.Table.write().

property caption: str¶

The table’s caption text.

Type:: str

property caption_enabled: int¶

True if the table caption is visible, False otherwise.

Type:: bool

categorized_data() → dict | None[source]¶

Return the table’s data organised into categories, if enabled or None if the table has not had categoried enabled.

The data is a dictionary with the category names as keys and a list dictionaries for each row in that category of the table. The table heading row is used as the keys for the row dictionary.

Example

"Transport": [
    {"Description": "Airplane", "Category": "Transport" },
    {"Description": "Bicycle", "Category": "Transport" },
    {"Description": "Bus", "Category": "Transport"},
],
"Fruit": [
    {"Description": "Apple", "Category": "Fruit" },
    {"Description": "Banana", "Category": "Fruit" },
],

For tables with multiple categories, the top-level dictionary is nested.

cell(*args) → Cell | MergedCell[source]¶

Return a single cell in the table.

The cell() method supports two forms of notation to designate the position of cells: Row-column notation and A1 notation:

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

Parameters:

param1 (int) – The row number (zero indexed).
param2 (int) – The column number (zero indexed).

Returns:

A cell with the base class Cell or, if merged, a MergedCell.

Return type:

Cell | MergedCell

Example

>>> doc = Document("mydoc.numbers")
>>> sheets = doc.sheets
>>> tables = sheets["Sheet 1"].tables
>>> table = tables["Table 1"]
>>> table.cell(1,0)
<numbers_parser.cell.TextCell object at 0x105a80a10>
>>> table.cell(1,0).value
'Debit'
>>> table.cell("B2")
<numbers_parser.cell.TextCell object at 0x105a80b90>
>>> table.cell("B2").value
1234.50

col_width(col: int, width: int | None = None) → int[source]¶

The width of a table column in points.

Parameters:

col (int) – The column number (zero indexed).
width (int) – The width of the column in points. If not None, set the column width.

Returns:

The width of the table column.

Return type:

int

property coordinates: tuple[float]¶

The table’s x, y offsets in points.

Type:: Tuple[float]

delete_column(num_cols: int | None = 1, start_col: int | None = None) → None[source]¶

Add or delete columns columns from the table.

Parameters:

num_cols (int, optional, default: 1) – The number of columns to add to the table.
start_col (int, optional, default: None) – The start column number (zero indexed), or None to add delete columns from the end of the table.

Raises:

IndexError: – If the start_col is out of range for the table.

delete_row(num_rows: int | None = 1, start_row: int | None = None) → None[source]¶

Delete rows from the table.

Parameters:

num_rows (int, optional, default: 1) – The number of rows to add to the table.
start_row (int, optional, default: None) – The start row number (zero indexed), or None to delete rows from the end of the table.

Warns:

RuntimeWarning – If the default value is a float that is rounded to the maximum number of supported digits.

Raises:

IndexError: – If the start_row is out of range for the table.

property height: int¶

The table’s height in points.

Type:: int

Produces cells from a table, by column.

Specify the iteration range using the indexes of the rows and columns.

Parameters:

min_col (int, optional) – Starting column number (zero indexed) or 0 if None.
max_col (int, optional) – End column number (zero indexed), or all columns if None.
min_row (int, optional) – Starting row number (zero indexed), or 0 if None.
max_row (int, optional) – End row number (zero indexed), or all rows if None.
values_only (bool, optional) – If True, yield cell values rather than Cell objects.

Yields:

Tuple[Cell] | Tuple[str] – Cell objects or string values for the row

Raises:

IndexError: – If row or column values are out of range for the table

Example

for col in table.iter_cols(min_row=2, max_row=7):
    sum += col.value

Produces cells from a table, by row.

Specify the iteration range using the indexes of the rows and columns.

Parameters:

min_row (int, optional) – Starting row number (zero indexed), or 0 if None.
max_row (int, optional) – End row number (zero indexed), or all rows if None.
min_col (int, optional) – Starting column number (zero indexed) or 0 if None.
max_col (int, optional) – End column number (zero indexed), or all columns if None.
values_only (bool, optional) – If True, yield cell values rather than Cell objects

Yields:

Tuple[Cell] | Tuple[str] – Cell objects or string values for the row

Raises:

IndexError: – If row or column values are out of range for the table

Example

for row in table.iter_rows(min_row=2, max_row=7, values_only=True):
    sum += row

merge_cells(cell_range: str | list[str]) → None[source]¶

Convert a cell range or list of cell ranges into merged cells.

Parameters:: cell_range (str | List[str]) – Cell range(s) to merge in A1 notation

Example

>>> table.cell("B2")
<numbers_parser.cell.TextCell object at 0x102c0d390>
>>> table.cell("B2").is_merged
False
>>> table.merge_cells("B2:C2")
>>> table.cell("B2").is_merged
True

property merge_ranges: list[str]¶

The merge ranges of cells in A1 notation.

Example

>>> table.merge_ranges
['A4:A10']
>>> table.cell("A4")
<numbers_parser.cell.TextCell object at 0x1035f4a90>
>>> table.cell("A5")
<numbers_parser.cell.MergedCell object at 0x1035f5310>

Type:: List[str]

property name: str¶

The table’s name.

Type:: str

property num_header_cols: int¶

The number of header columns.

Example

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

Raises:: ValueError: – If the number of headers is negative, exceeds the number of rows in the table, or exceeds Numbers maxinum number of headers (MAX_HEADER_COUNT).
Type:: int

property num_header_rows: int¶

The number of header rows.

Example

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

Raises:: ValueError: – If the number of headers is negative, exceeds the number of rows in the table, or exceeds Numbers maxinum number of headers (MAX_HEADER_COUNT).
Type:: int

row_height(row: int, height: int | None = None) → int[source]¶

The height of a table row in points.

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

Parameters:

row (int) – The row number (zero indexed).
height (int) – The height of the row in points. If not None, set the row height.

Returns:

The height of the table row.

Return type:

int

rows(values_only: bool = False) → list[list[Cell]] | list[list[str]][source]¶

Return all rows of cells for the Table.

Parameters:: values_only – If True, return cell values instead of Cell objects
Returns:: List of rows; each row is a list of Cell objects, or string values.
Return type:: List[List[Cell]] | List[List[str]]

set_cell_border(*args) → None[source]¶

Set the borders for a cell.

Cell references can be row-column offsers or Excel/Numbers-style A1 notation. Borders can be applied to multiple sides of a cell by passing a list of sides. The name(s) of the side(s) must be one of "top", "right", "bottom" or "left".

Numbers supports different border styles for each cell within a merged cell range for those cells that are on the outer part of the merge. numbers-parser will ignore attempts to set these invisible cell edges and issue a RuntimeWarning.

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

Args (row-column):

param1 (int): The row number (zero indexed).
param2 (int): The column number (zero indexed).
param3 (str | List[str]): Which side(s) of the cell to apply the border to.
param4 (Border): The border to add.
param5 (int, optinal, default: 1): The length of the stroke to add.

Args (A1):

param1 (str): A cell reference using Excel/Numbers-style A1 notation.
param2 (str | List[str]): Which side(s) of the cell to apply the border to.
param3 (Border): The border to add.
param4 (int, optional, default: 1): The length of the stroke to add.

Raises:

TypeError: – If an invalid number of arguments is passed or if the types of the arguments are invalid.
Warns: –
----- –
RuntimeWarning: – If any of the sides to which the border is applied have been merged.

set_cell_formatting(*args: str, **kwargs) → None[source]¶

Set the data format for a cell.

Cell references can be row-column offsers or Excel/Numbers-style A1 notation.

table.set_cell_formatting(
    "C1",
    "datetime",
    date_time_format="EEEE, d MMMM yyyy"
)
table.set_cell_formatting(
    0,
    4,
    "number",
    decimal_places=3,
    negative_style=NegativeNumberStyle.RED
)
table.set_cell_formatting(
    3,
    0,
    "popup",
    popup_values=["Cat", "Dog", "Rabbit"],
    allow_none=True
)

Parameters:

args (list, optional) - Positional arguments for cell reference and data format type (see below)
kwargs (dict, optional) - Key-value pairs defining a formatting options for each data format (see below).

Args (row-column):

param1 (int): The row number (zero indexed).
param2 (int): The column number (zero indexed).
param3 (str): Data format type for the cell (see “data formats” below).

Args (A1):

param1 (str): A cell reference using Excel/Numbers-style A1 notation.
param2 (str): Data format type for the cell (see “data formats” below).

Raises:

TypeError -
If a tickbox is chosen for anything other than bool values.
IndexError -
If the current cell value does not match a list of popup items.

Warns:

RuntimeWarning -
If use_accounting_style is used with any negative_style other than NegativeNumberStyle.MINUS, or if a rating is out of range 0 to 5 (rating is clamped to these values).

All formatting styles share a name and a type, described in the Common parameters in the following table. Additional key-value pairs configure the format depending upon the value of kwargs["type"].

Common Args:

name (str) - The name of the custom format. If no name is provided, one is generated using the scheme Custom Format, Custom Format 1, Custom Format 2, etc.
type (str, optional, default: number) - The type of format to create:
- "base": A number base in the range 2-36.
- "currency": A decimal formatted with a currency symbol.
- "custom": A named custom cell format that is applied to multiple cells.
- "datetime": A date and time value with custom formatting.
- "fraction": A number formatted as the nearest fraction.
- "percentage": A number formatted as a percentage
- "number": A decimal number.
- "scientific": A decimal number with scientific notation.
- "tickbox": A checkbox (bool values only).
- "rating": A star rating from 0 to 5.
- "slider": A range slider.
- "stepper": An up/down value stepper.
- "popup": A menu of options.

“base”:

base_use_minus_sign (int, optional, default: 10) - The integer base to represent the number from 2-36.
base_use_minus_sign (bool, optional, default: True) - If True use a standard minus sign, otherwise format as two’s compliment (only possible for binary, octal and hexadecimal.
base_places (int, optional, default: 0) - The number of decimal places, or None for automatic.

“custom”:

format (str | CustomFormating) - The name of a custom
formatin the document or a CustomFormatting object.

“currency”:

currency (str, optional, default: “GBP”) - An ISO currency code, e.g. "GBP" or "USD".
decimal_places (int, optional, default: 2) - The number of decimal places, or None for automatic.
negative_style (:py:class:`~numbers_parser.NegativeNumberStyle`, optional, default: NegativeNumberStyle.MINUS) - How negative numbers are represented. See Negative number formats.
show_thousands_separator (bool, optional, default: False) - True if the number should include a thousands seperator, e.g. ,
use_accounting_style (bool, optional, default: False) - True if the currency symbol should be formatted to the left of the cell and separated from the number value by a tab.

“datetime”:

date_time_format (str, optional, default: “dd MMM YYY HH:MM”) - A POSIX
strftime-like formatting string of Numbers date/time directives.

“fraction”:

fraction_accuracy (:py:class:`~numbers_parser.FractionAccuracy`, optional, default: FractionAccuracy.THREE - The
precision of the faction.

“percentage”:

decimal_places (float, optional, default: None) - number of decimal places, or None for automatic.
negative_style (:py:class:`~numbers_parser.NegativeNumberStyle`, optional, default: NegativeNumberStyle.MINUS) - How negative numbers are represented. See Negative number formats.
show_thousands_separator (bool, optional, default: False) - True if the number should include a thousands seperator, e.g. ,

“scientific”:

decimal_places (float, optional, default: None) - number of decimal places, or None for automatic.

“tickbox”:

No additional parameters defined.

“rating”:

No additional parameters defined.

“slider”:

control_format (ControlFormattingType, optional, default: ControlFormattingType.NUMBER) - the format
of the data in the slider. Valid options are "base", "currency", "datetime", "fraction", "percentage", "number", or "scientific". Each format allows additional parameters identical to those available for the formats themselves. For example, a slider using fractions is configured with ``fraction_accuracy.
increment (float, optional, default: 1) - the slider’s minimum value
maximum (float, optional, default: 100) - the slider’s maximum value
minimum (float, optional, default: 1) - increment value for the slider

“stepper”`:

control_format (ControlFormattingType, optional, default: ControlFormattingType.NUMBER) - the format
of the data in the stepper. Valid options are "base", "currency", "datetime", "fraction", "percentage", "number", or "scientific". Each format allows additional parameters identical to those available for the formats themselves. For example, a stepper using fractions is configured with fraction_accuracy.
increment (float, optional, default: 1) - the stepper’s minimum value
maximum (float, optional, default: 100) - the stepper’s maximum value
minimum (float, optional, default: 1) - increment value for the stepper

“popup”`:

popup_values (List[str|int|float], optional, default: None) - values
for the popup menu
allow_none (bool, optional, default: True) - If True
include a blank value in the list

property table_name_enabled: bool¶

True if the table name is visible, False otherwise.

Type:: bool

property width: int¶

The table’s width in points.

Type:: int

write(*args, style: Style | str | None = None) → None[source]¶

Write a value to a cell and update the style/cell type.

The write() method supports two forms of notation to designate the position of cells: Row-column notation and A1 notation:

doc = Document("write.numbers")
sheets = doc.sheets
tables = sheets[0].tables
table = tables[0]
table.write(1, 1, "This is new text")
table.write("B7", datetime(2020, 12, 25))
doc.save("new-sheet.numbers")

Parameters:

row (int) – The row number (zero indexed)
col (int) – The column number (zero indexed)
value (str | int | float | bool | DateTime | Duration) – The value to write to the cell. The generated cell type is automatically created based on the type of value.
style (Style | str | None) – The name of a document custom style or a Style object.

Warns:

RuntimeWarning – If the default value is a float that is rounded to the maximum number of supported digits.

Raises:

IndexError: – If the style name cannot be foiund in the document.
TypeError: – If the style parameter is an invalid type.
ValueError: – If the cell type cannot be determined from the type of param3.