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
'Categories'
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 = 'Sheet 1', table_name: str = 'Table 1', num_header_rows: int = 1, num_header_cols: int = 1, num_rows: int = 12, num_cols: int = 8, password: str | None = None)[source]¶
Create an instance of a new Numbers document.
If
filenameisNone, an empty document is created using the defaults defined by the class constructor. You can optionally 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 documenttable_name (str, optional, default:
Table 1) – Name of the first table in the first sheet of a newnum_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.
- add_custom_format(*, type: str = 'number', name: str | None = 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') CustomFormatting[source]¶
Add a new custom format to the current document.
long_date = doc.add_custom_format( name="Long Date", type="datetime", 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 schemeCustom 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) -Trueif the number should include a thousands separator.
- “datetime”:
format (
str, optional, default:"d MMM y") - A POSIX strftime-like formatting string of Numbers date/time directives.
- “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
- Raises:
KeyError – If the named custom format already exists.:
- add_sheet(sheet_name: str | None = None, table_name: str = 'Table 1', num_rows: int = 12, num_cols: int = 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 sheetnum_rows (int, optional, default: 12) – The number of rows 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(*, alignment: Alignment | None = None, bg_image: BackgroundImage | None = None, bg_color: RGB | list[RGB] | None = None, font_color: RGB | None = None, font_size: float | None = None, font_name: str | None = None, bold: bool | None = None, italic: bool | None = None, strikethrough: bool | None = None, underline: bool | None = None, first_indent: float | None = None, left_indent: float | None = None, right_indent: float | None = None, text_inset: float | None = None, text_wrap: bool | None = None, name: str | None = None) 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:
alignment (Alignment, optional, default: Alignment("auto", "top")) – Horizontal and vertical alignment of the cell
bg_image (BackgroundImage, optional, default: None) – Background image for the cell
bg_color (RGB | List[RGB], optional, default: None) – Background color or list of colors for gradients
bold (bool, optional, default: False) –
Trueif the cell font is boldfont_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) –
Trueif the cell font is italicname (str, optional) – Style name
underline (bool, optional, default: False) –
Trueif the cell font is underlinedstrikethrough (bool, optional, default: False) –
Trueif the cell font uses strikethroughfirst_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) –
Trueif text wrapping is enabled
- Raises:
IndexError: – If the style name already exists.
TypeError: – If
font_sizeis not afloat,font_nameis not astr,bg_imageis not aBackgroundImage, or if any of theboolparameters are invalid.
- property custom_formats: dict[str, CustomFormatting]¶
Map custom format names to their definitions.
The keys are names and the values are
CustomFormattinginstances.
- save(filename: str | Path, package: bool = False, password: str | None = None, hint: str = 'No hint') 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 filepassword (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.
- Warns:
RuntimeWarning – If saving a document that contains a pivot table.
numbers-parserwill automatically update the coordinate metadata so that pivot tables can be safely refreshed in Numbers, but this is considered unproven functionality.