Document Class

Document 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:

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

A new document is created when Document is constructed without a filename argument:

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")
class numbers_parser.Document(filename: str | Path | None = None, sheet_name: str | None = 'Sheet 1', table_name: str | None = 'Table 1', num_header_rows: int | None = 1, num_header_cols: int | None = 1, num_rows: int | None = 12, num_cols: int | None = 8)[source]

Create 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 optionionally override these defaults at object construction time.

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

  • 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.

Raises:

  • IndexError: – If the sheet name already exists in the document.

  • IndexError: – If the table name already exists in the first sheet.

add_custom_format(**kwargs) → CustomFormatting[source]

Add a new custom format to the current document.

long_date = doc.add_custom_format(
    name="Long Date",
    type="date",
    date_time_format="EEEE, d MMMM yyyy"
)
table.set_cell_formatting("C1", "custom", format=long_date)

All custom 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:

    • "datetime": A date and time value with custom formatting.

    • "number": A decimal number.

    • "text": A simple text string.

“number”:

  • integer_format (PaddingType, optional, default: PaddingType.NONE) – How to pad integers.

  • decimal_format (PaddingType, optional, default: PaddingType.NONE) – How to pad decimals.

  • num_integers (int, optional, default: 0) – Integer precision when integers are padded.

  • num_decimals (int, optional, default: 0) – Integer precision when decimals are padded.

  • show_thousands_separator (bool, optional, default: False) – True if the number should include a thousands seperator.

“datetime”:
“text”:

  • format (str, optional, default: "%s") – Text format. The cell value is inserted in place of %s. Only one substitution is allowed by Numbers, and multiple %s formatting references raise a TypeError exception

add_sheet(sheet_name: str | None = None, table_name: str | None = 'Table 1', num_rows: int | None = 12, num_cols: int | None = 8) → None[source]

Add a new sheet to the current document.

If no sheet name is provided, the next available numbered sheet will be generated in the series Sheet 1, Sheet 2, etc.

Parameters:

  • sheet_name (str, optional) – The name of the sheet to add to the document

  • table_name (str, optional, default: Table 1) – The name of the table created in the new sheet

  • num_rows (int, optional, default: 12) – The number of columns in the newly created table

  • num_cols (int, optional, default: 8) – The number of columns in the newly created table

  • Raises – IndexError: If the sheet name already exists in the document.

add_style(**kwargs) → Style[source]

Add a new style to the current document.

If no style name is provided, the next available numbered style will be generated in the series Custom Style 1, Custom Style 2, etc.

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)
Parameters:

kwargs (dict, optional) – Key-value pairs to pass to the Style constructor.

Raises:

TypeError: – If font_size is not a float, font_name is not a str, bg_image is not a BackgroundImage, or if any of the bool parameters are invalid.

property custom_formats: Dict[str, CustomFormatting]

A dict mapping custom format names to the corresponding custom format.

Type:

Dict[str, CustomFormatting]

property default_table: Table

return the first table of the first sheet in the document.

Type:

Table

save(filename: str | Path, package: bool = False) → None[source]

Save the document in the specified filename.

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

Raises:

FileFormatError: – If attempting to write a package into a folder that is not an existing Numbers document.

property sheets: List[Sheet]

A list of sheets in the document.

Type:

List[Sheet]

property styles: Dict[str, Style]

A dict mapping style names to to the corresponding style.

Type:

Dict[str, Style]