comet.table

This module provides factory functions for accessing and creating tables in a document.

See also

Class comet.CTable

Accessor for tables in a document

Methods

comet.table.create(frame: CFrame, columnCount: int, rowCount: int, insertPoint: int = 0, deleteRange: int = 0, cellHeight: float = 20.0, cellWidth: float = 30.0, headerRowCount: int = 0, footerRowCount: int = 0, tableStyle: str = '') → CTable

Create a new table

Illustrator® Since tables are not inside text frames, the table is placed at the top left corner of the current artboard.

Parameters:

  • frame (CFrame) –

    The frame to create the table inside

    Illustrator® Ignored - pass None

  • columnCount (int) – Number of table columns (at least 1)

  • rowCount (int) – Number of table rows (at least 1)

  • insertPoint (int) –

    The text index where to insert the table

    Illustrator® Ignored - pass 0

  • deleteRange (int) –

    The number of characters to delete.

    Default is constants.kEnd == until the text end

    Illustrator® Ignored - pass 0

  • cellHeight (float) – Height of the cells. Must be >= 4.0

  • cellWidth (float) – Width of the cells. Must be >= 4.0

  • headerRowCount (int) – Number of header rows. Must be >= 0

  • footerRowCount (int) – Number of footer rows. Must be >= 0

  • tableStyle (str) –

    The name of the table style to apply.

    • Empty str: Use default style.

Returns:

The new table on success

Return type:

CTable

Raises:

  • TypeError – When parameter types are invalid

  • ValueError – When parameter rows, columns or insertPoint is invalid

  • CometError – When table could not be created

Available:

InDesign® comet_pdf® Illustrator®

CScript:

table::create

comet.table.find(document: CDocument = None, pages: list[int] = [], frames: list[CFrame] = []) → list[CTable]

Find tables in the document

Parameters:

  • document (CDocument) –

    The document to search in.

    • None: Script document

  • pages (list[int]) –

    Restrict search to these pages (0 based)

    • Empty list: Impose no restriction

  • frames (list[CFrame]) –

    Restrict search to these frames

    • Empty list: Impose no restriction

Returns:

The found tables

Return type:

list[CTable]

Raises:

  • TypeError – When parameter types are invalid

  • ValueError – When parameter frames or pages contain invalid types

  • CometError – On internal error

Available:

InDesign® comet_pdf® Illustrator®

Examples:

Get the first table of the script frame and write it into the logfile.

#!py
import comet

def main() -> int:
    #Get the first table of the script frame
    tables: list[comet.CTable] = comet.table.find(frames = [comet.gFrame])

    if not tables:
        #No tables found
        return 0

    table: comet.CTable = tables[0]

    comet.wlog(str(table))

    return 0
comet.table.importCSV(source: tuple[str, bool], target: CPage | tuple[CPage, float, float], delimiters: list[str] = [','], mergeDelimiters: bool = False, textDelimiter: str = '"', columnWidths: float = 40.0, rowHeights: float = 40.0, tableStyle: str = '', headerRowCount: int = 1) → CTable

Create a table from data imported from a CSV file.

Parameters:

  • source (str) –

    The source for the CSV data.

    Entries in the tuple are:

    • str: Filepath to source or source data itself

    • bool: Whether the first provided value is a filepath (True) or CSV data itself (False)

  • target (CPage | tuple[CPage, float, float]) –

    Where to place the resulting table.

    The parameter type can be:

    • CPage: Place at the top left corner of this page.

    • tuple [CPage, float, float]: Place at the provided coordinates (X/Y) on this page.

  • delimiters (list[str]) –

    Separators used to distinguish between individual cell data records. Although CSV stands for comma-separated values, other separators such as semicolons are also frequently used. These characters can be selected and combined here so that multiple characters are interpreted as separators.

    Characters other than comma, semicolon, space and tab are ignored.

  • textDelimiter (str) – To enable separators in cell content, they must be enclosed in quotation marks. Here you can set which type of quotation marks should be used.

  • mergeDelimiters (bool) – If this option is enabled, multiple consecutive separators are interpreted as one. Otherwise, they are interpreted as empty cell contents.

  • columnWidths (float) – Uniform column widths in pt.

  • rowHeights (float) – Uniform row heigths in pt.

  • tableStyle (str) –

    Which table style to apply.

    • Empty str: Use default.

  • headerRowCount (int) – How many rows of the resulting table should be defined as header rows?

Returns:

The newly created table

Return type:

CTable

Raises:

  • TypeError – When parameter types are invalid

  • ValueError –

    • When parameter source is empty

    • When parameter delimiters is empty

    • When parameter headerRowCount is < 0

  • CometError – On internal error

Available:

Illustrator®

comet.table.importExcel(source: str | CExcelBook, target: CPage | tuple[CPage, float, float], sheet: str = '', cellRange: str = '', format: None | str = None) → CTable

Create a table from data imported from an Excel file.

Parameters:

  • source (str | CExcelBook) –

    The Excel file to import.

    The parameter type can be:

    • str Path the the Excel file.

    • CExcelBook The Excel book to import.

  • target (CPage | tuple[CPage, float, float]) –

    Where to place the resulting table.

    The parameter type can be:

    • CPage: Place at the top left corner of this page.

    • tuple [CPage, float, float]: Place at the provided coordinates on this page.

  • sheet (str) –

    Which sheet from the file to import.

    • Empty str: Use the first sheet.

  • cellRange (str) –

    The cell range to import from the Excel sheet.

    The format string format is: [First column letter][First row number]:[Last column letter][Last row number], e.g.

    ’A1:C2’

    • Empty str: Automatically determine the entire cell area to import.

  • formatTable (None | str) –

    Whether to try to import the table styling from Excel itself, or apply a table style from the document.

    The parameter type can be:

    • None: Try to import table styling from Excel.

    • str : The table style to apply. Provide an empty str to apply the default style.

Returns:

The newly created table

Return type:

CTable

Raises:

  • TypeError – When parameter types are invalid

  • ValueError – When parameter format contains negative dimensions

  • CometError – On internal error

Available:

Illustrator®