Automating Numbers

Automating Numbers (JXA-first, AppleScript discovery)

Relationship to the macOS automation skill

• Standalone for Numbers, aligned with automating-mac-apps patterns.
• Use automating-mac-apps for permissions, shell, and UI scripting guidance.
• PyXA Installation: To use PyXA examples in this skill, see the installation instructions in automating-mac-apps skill (PyXA Installation section).

Core Framing

• Numbers AppleScript dictionary is AppleScript-first; discover there.
• JXA provides logic and data processing.
• Objects are specifiers; read via methods, write via assignments.
• Handle errors from Numbers operations using try/catch blocks and Application error checking.

Workflow (default)

1) [ ] Discover terms in Script Editor (Numbers dictionary). 2) [ ] Prototype minimal AppleScript commands. 3) [ ] Port to JXA and add defensive checks. 4) [ ] Prefer batch reads and clipboard shim for writes. 5) [ ] Use UI scripting only for dictionary gaps.

Validation Checklist

• [ ] Empty document handling works without errors
• [ ] Data integrity verified after batch operations
• [ ] Numbers UI remains responsive after automation runs
• [ ] Errors logged with specific Numbers object paths
• [ ] Sheet/table indices validated before access
• [ ] Clipboard shim restores original clipboard contents

Examples

Basic table read (JXA - Legacy):

const numbers = Application('Numbers');
const doc = numbers.documents[0];
const sheet = doc.sheets[0];
const table = sheet.tables[0];
const data = table.rows.whose({_not: [{cells: []}]})().map(row => row.cells().map(c => c.value()));

Basic table read (PyXA - Recommended):

import PyXA

numbers = PyXA.Numbers()

# Get first document, sheet, and table
doc = numbers.documents()[0]
sheet = doc.sheets()[0]
table = sheet.tables()[0]

# Read all rows with data
rows = table.rows()
data = []

for row in rows:
    cells = row.cells()
    if cells:  # Skip empty rows
        row_data = [cell.value() for cell in cells]
        data.append(row_data)

print("Table data:", data)

PyObjC with Scripting Bridge:

from ScriptingBridge import SBApplication

numbers = SBApplication.applicationWithBundleIdentifier_("com.apple.Numbers")

# Access document and table
doc = numbers.documents()[0]
sheet = doc.sheets()[0]
table = sheet.tables()[0]

# Read table data
rows = table.rows()
data = []

for row in rows:
    cells = row.cells()
    if cells:
        row_data = [cell.value() for cell in cells]
        data.append(row_data)

print("Table data:", data)

Batch write with clipboard shim (JXA - Legacy):

const numbers = Application('Numbers');
// Prepare data array
const data = [['Name', 'Age'], ['Alice', 25], ['Bob', 30]];
// Use clipboard for bulk insertion
const app = Application.currentApplication();
app.includeStandardAdditions = true;
app.setTheClipboardTo(data.map(row => row.join('\t')).join('\n'));
numbers.activate();
delay(0.5);
// UI scripting to paste
SystemEvents = Application('System Events');
SystemEvents.keystroke('v', {using: 'command down'});

Batch write (PyXA - Modern):

import PyXA

numbers = PyXA.Numbers()

# Prepare data
data = [
    ['Name', 'Age'],
    ['Alice', 25],
    ['Bob', 30]
]

# Get table to write to
doc = numbers.documents()[0]
sheet = doc.sheets()[0]
table = sheet.tables()[0]

# Clear existing data and write new data
table.clear()  # Clear table first

for i, row_data in enumerate(data):
    # Add row if needed
    if i >= len(table.rows()):
        table.rows().push({})

    # Set cell values
    row = table.rows()[i]
    for j, value in enumerate(row_data):
        if j >= len(row.cells()):
            row.cells().push({})
        cell = row.cells()[j]
        cell.value = value

PyObjC Batch Write:

from ScriptingBridge import SBApplication

numbers = SBApplication.applicationWithBundleIdentifier_("com.apple.Numbers")

# Prepare data
data = [
    ['Name', 'Age'],
    ['Alice', 25],
    ['Bob', 30]
]

# Get table
doc = numbers.documents()[0]
sheet = doc.sheets()[0]
table = sheet.tables()[0]

# Clear and write data
table.clear()

for i, row_data in enumerate(data):
    # Ensure row exists
    while len(table.rows()) <= i:
        table.rows().push({})

    row = table.rows()[i]

    for j, value in enumerate(row_data):
        # Ensure cell exists
        while len(row.cells()) <= j:
            row.cells().push({})

        cell = row.cells()[j]
        cell.value = value

When Not to Use

• General macOS automation without Numbers involvement
• AppleScript alone suffices (no JXA logic needed)
• Complex UI interactions beyond data operations (use automating-mac-apps)
• Cross-platform compatibility required (use CSV/pandas)
• Real-time collaborative editing scenarios

What to load

• JXA Numbers basics: automating-numbers/references/numbers-basics.md
• Recipes (tables, ranges, formatting): automating-numbers/references/numbers-recipes.md
• Advanced patterns (clipboard, performance, ObjC): automating-numbers/references/numbers-advanced.md
• Dictionary translation table: automating-numbers/references/numbers-dictionary.md
• Formulas and locale notes: automating-numbers/references/numbers-formulas.md
• Sorting patterns: automating-numbers/references/numbers-sorting.md
• UI scripting patterns: automating-numbers/references/numbers-ui-scripting.md
• PyXA API Reference (complete class/method docs): automating-numbers/references/numbers-pyxa-api-reference.md

Numbers JXA advanced patterns

Clipboard shim for bulk writes

function bulkWrite(table, dataMatrix) {
  const app = Application.currentApplication();
  app.includeStandardAdditions = true;
  const tsv = dataMatrix.map(r => r.join("\t")).join("\n");
  app.setTheClipboardTo(tsv);
  Numbers.activate();
  delay(0.2);
  const se = Application("System Events");
  se.keystroke("v", { using: "command down" });
}

16-bit color conversion

function toJXAColor(r, g, b) {
  return [r * 257, g * 257, b * 257];
}

ObjC bridge (file existence)

ObjC.import("Foundation");
const fm = $.NSFileManager.defaultManager;
const exists = fm.fileExistsAtPath("/Users/you/Documents/report.numbers");

Numbers JXA basics

Bootstrapping

'use strict';
const Numbers = Application("Numbers");
Numbers.includeStandardAdditions = true;
Numbers.activate();

Open document

const doc = Numbers.open(Path("/Users/you/Documents/report.numbers"));

Sheets and tables

const sheet = doc.sheets.byName("Sheet 1");
const table = sheet.tables.byName("Table 1");

Numbers dictionary translation table

AppleScript                         JXA
----------------------------------- ------------------------------------------
front document                      Numbers.documents[0]
active sheet                        doc.activeSheet
sheet "Sheet 1"                     doc.sheets.byName("Sheet 1")
 table "Table 1"                    sheet.tables.byName("Table 1")
value of cell "A1"                  table.cells["A1"].value()
value of range "A1:C10"             table.ranges["A1:C10"].value()
selection range                     table.selectionRange

Notes:

• Collections are specifiers; call methods to read values.
• Prefer byName access for sheets/tables.

Numbers formulas

Set a formula

const cell = table.cells["B2"];
cell.value = "=SUM(A1:A10)";

Freeze a formula (value only)

const val = cell.value();
cell.value = val;

Locale note

• Formula separators may be , or ; depending on system locale.

PyXA Numbers Module API Reference

New in PyXA version 0.0.8 - Control macOS Numbers using JXA-like syntax from Python.

This reference documents all classes, methods, properties, and enums in the PyXA Numbers module. Numbers inherits table, cell, row, column, and range functionality from the shared iWork base classes. For practical examples and usage patterns, see numbers-basics.md.

Contents

• Class Hierarchy
• XANumbersApplication
• XANumbersDocument
• XANumbersSheet
• XANumbersTemplate
• XANumbersWindow
• XANumbersContainer
• Table Classes (iWork Base)
• XAiWorkTable
• XAiWorkRange
• XAiWorkRow
• XAiWorkColumn
• XAiWorkCell
• XAiWorkChart
• List Classes
• Enumerations
• Quick Reference Tables

---

Class Hierarchy

XAObject
├── XANumbersApplication (XAiWorkApplication)
│   ├── XANumbersDocument (XAiWorkDocument)
│   │   ├── XANumbersSheet (XANumbersContainer)
│   │   │   ├── XAiWorkTable (XAiWorkiWorkItem)
│   │   │   │   ├── XAiWorkRange
│   │   │   │   │   ├── XAiWorkRow
│   │   │   │   │   ├── XAiWorkColumn
│   │   │   │   │   └── XAiWorkCell
│   │   │   │   └── XAiWorkChart
│   │   │   └── [images, shapes, lines, etc.]
│   │   └── XANumbersTemplate
│   └── XANumbersWindow (XAiWorkWindow)
└── XANumbersContainerList

---

XANumbersApplication

Bases: XAiWorkApplication

Main entry point for interacting with Numbers.app.

Properties

Methods

documents(filter=None) -> XANumbersDocumentList

Returns a list of open documents matching the filter.

Parameters:

• filter (dict | None) - Property-value pairs to filter by

Example:

import PyXA
numbers = PyXA.Application("Numbers")
docs = numbers.documents()
for doc in docs:
    print(doc.name)

templates(filter=None) -> XANumbersTemplateList

Returns available templates matching the filter.

Parameters:

• filter (dict | None) - Property-value pairs to filter by

Example:

templates = numbers.templates()
print(templates.name())
# ['Blank', 'Checklist', 'Invoice', ...]

new_document(file_path='./Untitled.numbers', template=None) -> XANumbersDocument

Creates a new document.

Parameters:

• file_path (str | XAPath) - Path to create document at
• template (XANumbersTemplate | None) - Template to initialize with

Returns: The newly created document

Example:

# Create blank document
doc = numbers.new_document("~/Documents/report.numbers")

# Create from template
template = numbers.templates().by_name("Invoice")
doc = numbers.new_document("~/Documents/invoice.numbers", template=template)

new_sheet(document, properties=None) -> XANumbersSheet

Creates a new sheet in the specified document.

Parameters:

• document (XANumbersDocument) - Document to add sheet to
• properties (dict | None) - Properties for the new sheet

Returns: The newly created sheet

make(specifier, properties=None, data=None)

Creates a new element without adding to any list. Use XAList.push() to add.

Parameters:

• specifier (str | ObjectType) - Class name to create
• properties (dict) - Properties for the object
• data (Any) - Initialization data

Example:

# Create a new table
new_table = numbers.make("table", {"name": "Sales Data", "row_count": 10, "column_count": 5})
doc.sheets()[0].tables().push(new_table)

# Create a new line
new_line = numbers.make("line", {"startPoint": (100, 100), "endPoint": (200, 200)})
doc.sheets()[0].lines().push(new_line)

---

XANumbersDocument

Bases: XAiWorkDocument

Represents an open Numbers spreadsheet.

Properties

Methods

sheets(filter=None) -> XANumbersSheetList

Returns sheets matching the filter.

Example:

doc = numbers.documents()[0]
all_sheets = doc.sheets()
first_sheet = doc.sheets()[0]
named_sheet = doc.sheets().by_name("Sales")

new_sheet(properties=None) -> XANumbersSheet

Creates a new sheet at the end of the document.

Parameters:

• properties (dict) - Properties for the new sheet (e.g., {"name": "Q4 Data"})

Returns: The newly created sheet

Example:

new_sheet = doc.new_sheet({"name": "Summary"})

export(file_path=None, format=ExportFormat.PDF)

Exports the spreadsheet.

Parameters:

• file_path (str | XAPath | None) - Export destination
• format (ExportFormat) - Export format (default: PDF)

Example:

# Export to PDF
doc.export("/path/to/output.pdf", XANumbersApplication.ExportFormat.PDF)

# Export to Excel
doc.export("/path/to/output.xlsx", XANumbersApplication.ExportFormat.MICROSOFT_EXCEL)

# Export to CSV
doc.export("/path/to/output.csv", XANumbersApplication.ExportFormat.CSV)

save()

Saves the document in Numbers format.

Example:

doc.save()

---

XANumbersSheet

Bases: XANumbersContainer

Represents a single sheet in a Numbers spreadsheet.

Properties

Methods

tables(filter=None) -> XAiWorkTableList

Returns tables in the sheet.

Example:

sheet = doc.sheets()[0]
tables = sheet.tables()
first_table = tables[0]
named_table = tables.by_name("Data")

charts(filter=None) -> XAiWorkChartList

Returns charts in the sheet.

images(filter=None) -> XAiWorkImageList

Returns images in the sheet.

shapes(filter=None) -> XAiWorkShapeList

Returns shapes in the sheet.

lines(filter=None) -> XAiWorkLineList

Returns lines in the sheet.

text_items(filter=None) -> XAiWorkTextItemList

Returns text items in the sheet.

groups(filter=None) -> XAiWorkGroupList

Returns groups in the sheet.

iwork_items(filter=None) -> XAiWorkiWorkItemList

Returns all iWork items in the sheet.

audio_clips(filter=None) -> XAiWorkAudioClipList

Returns audio clips in the sheet.

movies(filter=None) -> XAiWorkMovieList

Returns movies in the sheet.

add_image(file_path) -> XAiWorkImage

Adds an image to the sheet.

Parameters:

• file_path (str | XAPath | XAImage) - Path to image file

Returns: The newly created image object

Example:

image = sheet.add_image("/path/to/chart.png")

---

XANumbersTemplate

Bases: XAObject

Represents a Numbers template.

Properties

---

XANumbersWindow

Bases: XAiWorkWindow

Represents a Numbers window.

Properties

---

XANumbersContainer

Bases: XAiWorkContainer

Base class for containers (sheets) in Numbers.

---

Table Classes (iWork Base)

Numbers uses shared iWork base classes for tables, cells, rows, columns, and ranges. These classes are defined in iWorkApplicationBase and inherited by Numbers.

XAiWorkTable

Bases: XAiWorkiWorkItem

Represents a table in a Numbers sheet.

Properties

Methods

cells(filter=None) -> XAiWorkCellList

Returns all cells in the table.

Example:

table = sheet.tables()[0]
all_cells = table.cells()
cell_a1 = table.cells().by_name("A1")

rows(filter=None) -> XAiWorkRowList

Returns all rows in the table.

Example:

rows = table.rows()
first_row = rows[0]
row_by_address = rows.by_address(5)  # Get row 5

columns(filter=None) -> XAiWorkColumnList

Returns all columns in the table.

Example:

columns = table.columns()
first_column = columns[0]
col_by_address = columns.by_address(2)  # Get column B (index 2)

ranges(filter=None) -> XAiWorkRangeList

Returns named ranges in the table.

sort(by_column, in_rows=None, direction=SortDirection.ASCENDING) -> XAiWorkTable

Sorts the table by the specified column.

Parameters:

• by_column (XAiWorkColumn) - Column to sort by
• in_rows (list[XAiWorkRow] | XAiWorkRowList | None) - Rows to include in sort (None = all rows)
• direction (SortDirection) - ASCENDING or DESCENDING

Returns: The sorted table

Example:

# Sort by column A ascending
table.sort(table.columns()[0], direction=XAiWorkApplication.SortDirection.ASCENDING)

# Sort by column B descending
table.sort(table.columns()[1], direction=XAiWorkApplication.SortDirection.DESCENDING)

---

XAiWorkRange

Bases: XAObject

Represents a range of cells in a table.

Properties

Methods

clear() -> XAiWorkRange

Clears the content of every cell in the range.

Returns: The range (for method chaining)

Example:

# Clear a specific range
table.cell_range.clear()

# Clear specific cells
table.rows()[0].clear()

merge() -> XAiWorkRange

Merges all cells in the range into one cell.

Returns: The range

Example:

# Merge header cells
header_range = table.rows()[0]
header_range.merge()

unmerge() -> XAiWorkRange

Unmerges previously merged cells.

Returns: The range

cells(filter=None) -> XAiWorkCellList

Returns cells within the range.

rows(filter=None) -> XAiWorkRowList

Returns rows within the range.

columns(filter=None) -> XAiWorkColumnList

Returns columns within the range.

---

XAiWorkRow

Bases: XAiWorkRange

Represents a single row in a table. Inherits all properties and methods from XAiWorkRange.

Properties

Example:

row = table.rows()[0]
print(f"Row {row.address} height: {row.height}")
row.height = 30  # Set row height

---

XAiWorkColumn

Bases: XAiWorkRange

Represents a single column in a table. Inherits all properties and methods from XAiWorkRange.

Properties

Example:

col = table.columns()[0]
print(f"Column {col.address} width: {col.width}")
col.width = 150  # Set column width

---

XAiWorkCell

Bases: XAiWorkRange

Represents a single cell in a table. Inherits all properties and methods from XAiWorkRange.

Properties

Example:

cell = table.cells()[0]

# Read value
print(cell.value)
print(cell.formatted_value)

# Write value
cell.value = 42
cell.value = "Hello"
cell.value = 3.14

# Check for formula
if cell.formula:
    print(f"Formula: {cell.formula}")

---

XAiWorkChart

Bases: XAiWorkiWorkItem

Represents a chart in a Numbers sheet. Charts are created from table data.

---

List Classes

PyXA provides list wrapper classes with fast enumeration and bulk property access.

XANumbersDocumentList

Bulk methods for document lists:

docs = numbers.documents()
docs.name()                  # -> list[str]
docs.modified()              # -> list[bool]
docs.password_protected()    # -> list[bool]
docs.active_sheet()          # -> XANumbersSheetList
docs.document_template()     # -> XANumbersTemplateList
docs.properties()            # -> list[dict]

Filter methods:

docs.by_name("Budget")
docs.by_modified(True)
docs.by_active_sheet(sheet)
docs.by_document_template(template)
docs.by_properties({"name": "Budget"})

XANumbersSheetList

Bulk methods for sheet lists:

sheets = doc.sheets()
sheets.name()        # -> list[str]
sheets.properties()  # -> list[dict]

Filter methods:

sheets.by_name("Summary")
sheets.by_properties({"name": "Summary"})

XANumbersTemplateList

templates = numbers.templates()
templates.id()       # -> list[str]
templates.name()     # -> list[str]
templates.by_name("Invoice")
templates.by_id("template-id")

XAiWorkTableList

tables = sheet.tables()
tables.name()                # -> list[str]
tables.row_count()           # -> list[int]
tables.column_count()        # -> list[int]
tables.header_row_count()    # -> list[int]
tables.header_column_count() # -> list[int]
tables.footer_row_count()    # -> list[int]
tables.cell_range()          # -> XAiWorkRangeList
tables.selection_range()     # -> XAiWorkRangeList

Filter methods:

tables.by_name("Sales Data")
tables.by_row_count(100)
tables.by_column_count(10)

XAiWorkRangeList

ranges = table.ranges()
ranges.name()              # -> list[str]
ranges.font_name()         # -> list[str]
ranges.font_size()         # -> list[float]
ranges.format()            # -> list[CellFormat]
ranges.alignment()         # -> list[Alignment]
ranges.text_color()        # -> list[XAColor]
ranges.background_color()  # -> list[XAColor]
ranges.text_wrap()         # -> list[bool]
ranges.vertical_alignment() # -> list[Alignment]

Filter methods:

ranges.by_name("A1:B5")
ranges.by_font_name("Helvetica")
ranges.by_format(CellFormat.CURRENCY)

XAiWorkRowList

rows = table.rows()
rows.address()   # -> list[int]
rows.height()    # -> list[float]

Filter methods:

rows.by_address(5)    # Get row 5
rows.by_height(30)    # Get rows with height 30

XAiWorkColumnList

columns = table.columns()
columns.address()  # -> list[int]
columns.width()    # -> list[float]

Filter methods:

columns.by_address(3)   # Get column C (index 3)
columns.by_width(150)   # Get columns with width 150

XAiWorkCellList

cells = table.cells()
cells.value()            # -> list[Any]
cells.formatted_value()  # -> list[str]
cells.formula()          # -> list[str]
cells.row()              # -> XAiWorkRowList
cells.column()           # -> XAiWorkColumnList

Filter methods:

cells.by_value(100)
cells.by_formatted_value("$100.00")
cells.by_formula("=SUM(A1:A10)")
cells.by_row(row)
cells.by_column(column)

---

Enumerations

ExportFormat

Export format options for Numbers documents.

Example:

from PyXA.apps.Numbers import XANumbersApplication

doc.export("/path/output.pdf", XANumbersApplication.ExportFormat.PDF)
doc.export("/path/output.xlsx", XANumbersApplication.ExportFormat.MICROSOFT_EXCEL)
doc.export("/path/output.csv", XANumbersApplication.ExportFormat.CSV)

ObjectType

Creatable object types for the make() method.

CellFormat (iWork Base)

Cell format options for table cells.

Example:

from PyXA.apps.iWorkApplicationBase import XAiWorkApplication

cell.format = XAiWorkApplication.CellFormat.CURRENCY
cell.format = XAiWorkApplication.CellFormat.PERCENT

Alignment (iWork Base)

Alignment options for cell content.

Example:

cell.alignment = XAiWorkApplication.Alignment.CENTER_HORIZONTAL
cell.vertical_alignment = XAiWorkApplication.Alignment.TOP

SortDirection (iWork Base)

Sort direction options.

Example:

table.sort(table.columns()[0], direction=XAiWorkApplication.SortDirection.DESCENDING)

---

Quick Reference Tables

Common Operations

Table Operations

Cell Operations

Row/Column Operations

Range Operations

Property Access Patterns

# Single object property access
table = sheet.tables()[0]
print(table.name)
print(table.row_count)

# Bulk property access on lists
tables = sheet.tables()
print(tables.name())       # Returns list[str]
print(tables.row_count())  # Returns list[int]

# Filtering lists
large_tables = tables.greater_than("row_count", 100)
currency_cells = cells.by_format(CellFormat.CURRENCY)

Reading Table Data

# Read entire table as 2D array
table = sheet.tables()[0]
data = []
for row in table.rows():
    row_data = [cell.value for cell in row.cells()]
    data.append(row_data)

# Read specific column values
col_values = [cell.value for cell in table.columns()[0].cells()]

# Read specific row values
row_values = [cell.value for cell in table.rows()[0].cells()]

Writing Table Data

# Write to specific cell
table.cells().by_name("A1").value = "Header"

# Write row of data
row = table.rows()[0]
values = ["Name", "Age", "City"]
for i, cell in enumerate(row.cells()):
    if i < len(values):
        cell.value = values[i]

# Write 2D data array
data = [
    ["Name", "Score"],
    ["Alice", 95],
    ["Bob", 87]
]
for i, row_data in enumerate(data):
    row = table.rows()[i]
    for j, value in enumerate(row_data):
        row.cells()[j].value = value

---

See Also

• PyXA Numbers Documentation - Official PyXA documentation
• PyXA iWork Base Documentation - Source for table/cell classes
• numbers-basics.md - JXA fundamentals
• numbers-recipes.md - Common automation patterns
• numbers-advanced.md - Advanced techniques

Numbers JXA recipes

Read table values (batch)

const values = table.rows.value();

Set a single cell

table.rows[1].cells[1].value = "OK";

Basic formatting

const cell = table.rows[1].cells[1];
cell.backgroundColor = [65535, 0, 0];
cell.textColor = [0, 0, 0];

Numbers sorting patterns

Recommended approach

• Read table data in one batch.
• Sort using JS.
• Write back via clipboard shim.

const data = table.rows.value();
const header = data[0];
const body = data.slice(1);
body.sort((a, b) => (a[1] || 0) - (b[1] || 0));
const sorted = [header].concat(body);
// Use clipboard shim to paste sorted data

Numbers UI scripting patterns

When to use

• Only when dictionary access is missing or broken.

Basic pattern

const se = Application("System Events");
const n = se.processes.byName("Numbers");
Application("Numbers").activate();
delay(0.2);
// Example: open Format sidebar (path varies by version)
// n.windows[0].toolbars[0].buttons.byName("Format").click();

Notes

• Use Accessibility Inspector to find stable element paths.
• Prefer named UI elements; avoid index paths.
• Add wait loops before clicking.