comet.CDocument¶

class comet.CDocument¶

This section describes all functions for the CDocument class.

CDocument represents an opened document in the current host software.

It is used to access and manipulate (e.g. saving and setting attributes) of a document.

Methods¶

CDocument.save()¶

Save this document

Returns:: None
Raises:: CometError – On internal error
Available:: InDesign® comet_pdf® Illustrator®
CScript:: document::save

CDocument.saveAs(path, options=None)¶

Save this document to a path.

The target folder is automatically created if it does not yet exist.

Existing files are overwritten.

Parameters:

path (str) – The path on disk to save the document to
options (None | dict[str, int | bool]) –
Additional options for saving the document.

InDesign® comet_pdf® Ignored.

Keys must be str. Value types depend on the provided keys.

The following options are available:
General
’compressed’
- Value type: bool
- Default: True
If True, the saved file is compressed.
’embedICCProfile’
- Value type: bool
- Default: True
If True, the document’s ICC profile is embedded in the saved file
’embedLinkedFiles’
- Value type: bool
- Default: False
If True, the linked image files is embedded in the saved file.
’pdfCompatible’
- Value type: bool
- Default: True
If True, the file is saved as a PDF compatible file.
’fontSubsetThreshold’
- Value type: int
- Default: 100
Include a subset of fonts when less than this percentage of characters is used in the document. Range: 0 to 100
’compatibility’
- Value type: int
- Default: Current Illustrator version
Specifies the version of Illustrator file format to create.
Possible values:
3 (Japanese Version 3)

8 (Illustrator 8)

9 (Illustrator 9)

10 (Illustrator 10)

11 (Illustrator 11)

12 (Illustrator 12)

13 (Illustrator 13)

14 (Illustrator 14)

15 (Illustrator 15)

16 (Illustrator 16)

17 (Illustrator 17)

19 (Illustrator 19)

20 (Illustrator 20)

Returns:

None

Raises:

TypeError – When parameter types are invalid
ValueError – When parameter path is empty
CometError – On internal error

Available:

InDesign® comet_pdf® Illustrator®

CScript:

document::saveas

CDocument.saveAsCopy(path, options=None)¶

Save this document as a copy to a path.

The target folder is automatically created if it does not yet exist.

Existing files are overwritten.

Parameters:

path (str) – The path on disk to save the document to
options (None | dict[str, int | bool]) – Export options. The same as the options parameter from saveAs()

Return type:

None

Raises:

TypeError – When parameter types are invalid
ValueError – When parameter path is empty
CometError – On internal error

Available:

InDesign® Illustrator®

CScript:

document::duplicate

CDocument.close(save=False, mode=0)¶

Close this document. All subsequent operations to this document will fail.

InDesign® Closing documents can force a lot of actions on the document.

InDesign® therefore schedules document closing to the next idle time.

The parameter mode controls how the document close is performed.

With constants.kDocCloseProcess you can force direct closing, but this may cause serious problems!

Parameters:

save (bool) – Whether to save the document before closing
mode (int) –
- constants.kDocCloseSchedule: Close normally on next idle time
- constants.kDocCloseProcess: Close right now. This may cause serious problems even on changed files!
- constants.kDocCloseImmediate: Close immediately. This is an attempt to circumvent the InDesign® problems with constants.kDocCloseProcess. Unfortunately, we cannot promise that this will work in every case - but it is worth a try.
Illustrator® Ignored

Returns:

None

Raises:

TypeError – When parameter types are invalid
ValueError – When parameter mode has invalid value
CometError – On internal error

Available:

InDesign® Illustrator®

CScript:

document::close

CDocument.getName()¶

Gets the filename of a document

Returns:: The file name of the document
Return type:: str
Available:: InDesign® comet_pdf® Illustrator®
CScript:: document::name

CDocument.getDisplayName()¶

Title of the document in the document window. In the standard case, the file name (or Unnamed-N for new documents) is used as window title. If the window title was changed by setDisplayName(), the function returns the changed window title.

Returns:: Window title of the document
Return type:: str
Raises:: CometError – On internal error
Available:: InDesign®
CScript:: document::get_display_name

CDocument.setDisplayName(name)¶

Set the display name of the document. Set the displayed name of a document. This name is used as the window title and as a suggestion for the filename when using File -> Save As.

The displayed name is not the filename.

Parameters:

name (str) – New display name of the document. Must not be empty.

Returns:

None

Raises:

TypeError – When parameter name has wrong type
ValueError – When parameter name is empty
CometError – On internal error

Available:

InDesign®

CScript:

document::set_display_name

CDocument.getPath()¶

Gets the filepath of a document

Returns:: The full file path of the document
Return type:: str
Available:: InDesign® comet_pdf® Illustrator®
CScript:: document::path

CDocument.setFront()¶

Set this document as the current front document. Functions operating on the current front document will now work on this one.

InDesign® Also valid for InDesign® Server.

Returns:: None
Raises:: CometError – On internal error
Available:: InDesign® Illustrator®
CScript:: document::select

CDocument.getID()¶

Get the Comet ID of this document.

Returns:: The comet ID.
Return type:: CIDType
Raises:: CometError – On internal error
Available:: InDesign® comet_pdf® Illustrator®
CScript:: document::getid

CDocument.setID(ID)¶

Set the Comet ID of this document.

Parameters:

ID (tuple[int, int, int, str] | CIDType) –

The new Comet ID of this document.

ID1 must not be <0!

Return type:

None

Raises:

CometError – On internal error

Available:

InDesign® comet_pdf® Illustrator®

CScript:

document::setid

CDocument.getAttributes()¶

Fetch all key-values of a document

InDesign® comet_pdf® get attributes from the root node of the document structure.

Illustrator® Get a key/value pairs inspectable using the Document attributes panel

Returns:: All key/value pairs of the document
Return type:: dict[str, str]
Raises:: CometError – On internal error
Available:: InDesign® comet_pdf® Illustrator®

CDocument.getAttribute(key)¶

Fetch a single key-value of a document

InDesign® comet_pdf® get an attribute from the root node of the document structure.

Illustrator® Get a key/value pair inspectable using the Document attributes panel

Parameters:

key (str) – The key to be fetched

Returns:

The value which belongs to the key

Return type:

str

Raises:

TypeError – When parameter key has wrong type
ValueError – When parameter key is empty
CometError – When attribute is not found or other error occured

Available:

InDesign® comet_pdf® Illustrator®

CDocument.setAttribute(key, value)¶

Set a single key-value attribute of the document.

InDesign® comet_pdf® Sets an attribute to the root node of the document structure.

Illustrator® Sets a key/value pair inspectable using the Document attributes panel

Parameters:

key (str) – The key to set
value (str) – The value to set

Return type:

None

Raises:

TypeError – When parameter types are invalid
ValueError – When parameter key is empty
CometError – On internal error

Available:

InDesign® comet_pdf® Illustrator®

CDocument.removeAttributes(keys)¶

Remove key-value attributes from the document.

InDesign® comet_pdf® Removes attributes from the root node of the document structure.

Illustrator® Removes key/value pairs inspectable using the Document attributes panel

Parameters:

keys (list[str]) –

The keys for the entries to remove.

Keys which are not found are ignored.

Return type:

None

Raises:

TypeError – When parameter types are invalid
CometError – On internal error

Available:

InDesign® comet_pdf® Illustrator®

CDocument.getBleed(pageIndex=-2)¶

Get the current document bleed.

Parameters:

pageIndex (int) –

0-based page index.

The page index is important to determine via the page type which is the outer and which is the inner edge of the page.

-2 : Get values without paying attention to the page
-1 : Current page

InDesign® comet_pdf® Under InDesign® Server and comet_pdf the current page is not defined.

Illustrator® Ignored

Returns:

Bleed values in pt and whether they are uniform as a tuple.

InDesign® comet_pdf® Values are (inner, top, outer, bottom, isUniform)

Illustrator® Values are (left, top, right, bottom, isUniform)

Return type:

tuple[float, float, float, float, bool]

Raises:

CometError – On internal error

Available:

InDesign® comet_pdf® Illustrator®

CScript:

document::get_bleed

CDocument.setBleed(inner, top=-1.0, outer=-1.0, bottom=-1.0)¶

Set the document bleed. All values are in pt.

InDesign® Values are (inner, top, outer, bottom)

Illustrator® Values are (left, top, right, bottom)

Parameters:

inner (float) – The inner bleed
top (float) – The top bleed. When negative or omitted, use value of inner parameter
outer (float) – The outer bleed. When negative or omitted, use value of inner parameter
bottom (float) – The bottom bleed. When negative or omitted, use value of inner parameter

Returns:

None

Raises:

TypeError – When parameter types are invalid
ValueError – When bleeds are < 0.0
CometError – On internal error

Available:

InDesign® comet_pdf® Illustrator®

CScript:

document::set_bleed

CDocument.getRasterEffectResolution()¶

Get the document raster effect resolution.

Returns:: The resolution in dpi
Return type:: int
Raises:: CometError – On internal error
Available:: Illustrator®

CDocument.getColorModel()¶

Get the document color model

Returns:: The color model. One of One of Color models.
Return type:: int
Raises:: CometError – On internal error
Available:: Illustrator®

CDocument.getColorProfile(type)¶

Get the applied document color profile name.

This only returns a valid value when the document has an explicit color profile set, else an empty str is returned.

Parameters:

type (int) –

The profile type to query.

One of Color models.

Returns:

The overridden document color profile name

Return type:

str

Raises:

TypeError – When parameter types are invalid
ValueError – When parameter type has invalid value
CometError – On internal error

Available:

Illustrator®

CDocument.setColorProfile(type, name)¶

Set the applied document color profile override.

Parameters:

type (int) –
The profile type to set.

One of Color models.
name (str) –
The full color profile name.
- Empty str: Remove the color profile override.

Returns:

None

Raises:

TypeError – When parameter types are invalid
ValueError – When parameter type has invalid value
CometError – On internal error

Available:

Illustrator®

CDocument.getSwatch(name)¶

Find a swatch by name.

Parameters:

name (str) – The name of the swatch to find (non-translated)

Returns:

The found swatch

Return type:

CSwatch

Raises:

TypeError – When parameter types are invalid
ValueError – When parameter name is empty
KeyError – When no swatch with the provided name is found
CometError – On internal error

Available:

InDesign® comet_pdf® Illustrator®

CDocument.getSwatches()¶

Get all swatches of the document.

Returns:

The document swatches

Return type:

list[CSwatch]

Raises:

CometError – On internal error

Available:

InDesign® comet_pdf® Illustrator®

CScript:

Examples:

Fetch information about all swatches in a document and output them to the logfile.

#!py
#pragma plain

import comet

def main():
    #Retrieve all swatches from the current document
    swatches = comet.gDocument.getSwatches()

    #Loop through each swatch and extract its properties
    for swatch in swatches:
        name = swatch.getName()  #Swatch name
        space = swatch.getSpace()  #Color space (e.g., RGB, CMYK)
        type = swatch.getType()  #Swatch type (e.g., process, spot)
        tint = swatch.getTint()  #Tint percentage (if applicable)
        isSpot = swatch.isSpot()  #Indicates if the swatch is a spot color
        isReserved = swatch.isReserved()  #Indicates if the swatch is system-reserved
        isLocked = swatch.isLocked()  #Indicates if the swatch is locked
        colors = swatch.getColors()  #Color values in the defined color space

        #Log the swatch details to the console
        comet.wlog(f"""Swatch:
            Name: {name}
            Type: {type}
            Space: {space}
            Colors: {colors}
            IsSpot: {isSpot}
            IsReserved: {isReserved}
            IsLocked: {isLocked}
            Tint: {tint}"""
        )

    return 0

CDocument.createSwatchRGB(name, R, G, B, type=1)¶

Define a new swatch in RGB space.

If there is already an entry with this name in the document, the call has no effect - the pre-existing color will not be changed.

Parameters:

name (str) – The name for the new swatch.
R (int) – The red part of the color (0 - 255)
G (int) – The green part of the color (0 - 255)
B (int) – The blue part of the color (0 - 255)
type (int) –
The color type
- 0: Spot
- 1: Process

Returns:

The newly created swatch - if any - else None

Return type:

CSwatch | None

Raises:

TypeError – When parameter types are invalid
ValueError –
- When parameter document is None and there is no script document
- When parameter name is empty
- When parameters r, g, or b are out of range
- When parameter type has invalid value
CometError – On internal error

Available:

InDesign® comet_pdf® Illustrator®

CScript:

color::define_rgb

CDocument.createSwatchCMYK(name, C, M, Y, K, type=1)¶

Define a new swatch in CMYK space.

If there is already an entry with this name in the document, the call has no effect - the pre-existing color will not be changed.

Parameters:

name (str) – The name for the new swatch.
C (float) – The cyan part of the color (0.0 - 1.0)
M (float) – The magenta part of the color (0.0 - 1.0)
Y (float) – The yellow part of the color (0.0 - 1.0)
K (float) – The black part of the color (0.0 - 1.0)
type (int) –
The color type
- 0: Spot
- 1: Process

Returns:

The newly created swatch - if any - else None

Return type:

CSwatch | None

Raises:

TypeError – When parameter types are invalid
ValueError –
- When parameter document is None and there is no script document
- When parameter name is empty
- When parameters C, M, Y or K are out of range
- When parameter type has invalid value
CometError – On internal error

Available:

InDesign® comet_pdf® Illustrator®

CScript:

color::define_cmyk

CDocument.createSwatchLAB(name, l, a, b, type=1)¶

Define a new swatch in LAB space.

If there is already an entry with this name in the document, the call has no effect - the pre-existing color will not be changed.

Parameters:

name (str) – The name for the new swatch.
L (float) – The L part of the color (0.0 - 100.0)
A (int) – The A part of the color (-127 - 128)
B (int) – The B part of the color (-127 - 128)
type (int) –
The color type
- 0: Spot
- 1: Process

Returns:

The newly created swatch - if any - else None

Return type:

CSwatch | None

Raises:

TypeError – When parameter types are invalid
ValueError –
- When parameter document is None and there is no script document
- When parameter name is empty
- When parameters L, A, or B are out of range
- When parameter type has invalid value
CometError – On internal error

Available:

InDesign® comet_pdf®

CScript:

color::define_lab

CDocument.exportPDF(path='', profile='', scope=2, indices=[])¶

Export this document as a PDF.

Parameters:

path (str) –
The full file path on disk to save the document to.
- Empty str: Use path and name (with extension .pdf) of the document (does not work on unsaved documents).
profile (str | dict) –
The PDF profile to use.

The parameter type can be:
str

PDF (print) profile.
- Empty str:
  PDF (Print) with the current PDF export options for PDF (Print).
- Else:
  PDF Profile name.
  
  Illustrator® Due to limitations in the Illustrator SDK, for default profiles this has to be the PDF profile name in the current locale of Illustrator surrounded by square brackets, e.g. [High Quality Print]
dict

Illustrator® Ignored, the function falls back to the default PDF (print) options when a dict is provided.

Interactive PDF with the current settings of the PDF export for interactive PDFs.

The settings in the dict override the active settings.

Keys must be str. Value types depend on the provided keys.

The following options are available:
General

’singlePages’

Value type: bool

Default: False

Create separate PDFs per page?

’singlePagesSuffix’

Value type: str

Default: ‘’

Suffix when creating separate PDFs per page.

Only used when ‘singlePages’ == True

’magnification’

Value type: str

Default: ‘actual’

Viewing : View.

Allowed values:

’actual’

’fitPage’

’fitWidth’

’fitHeight’

’fitVisible’

’25’

’50’

’75’

’100’

’pageLayout’

Value type: str

Default: ‘single’

Viewing : Layout.

Allowed values:

’single’

’singleContinue’

’twoUp’

’twoUpContinue’

’twoUpCover’

’twoUpCoverContinue’

’fullScreen’

Value type: bool

Default: False

Viewing : Open in Full Screen Mode.

’flipPages’

Value type: bool

Default: False

Viewing : Flip Pages.

Only used when ‘fullScreen’ == True

’flipSpeed’

Value type: int

Default: 5

Viewing : Flip Pages Every … seconds.

Only used when ‘fullScreen’ == True

’transition’

Value type: str

Default: ‘nothing’

Viewing : Page Transition

Allowed values:

’nothing’

’blend’

’combine’

’box’

’cover’

’push’

’uncover’

’wipe’

’zoomIn’

’zoomOut’

’disolve’

’fade’

’turn’

’split’

Only used when ‘fullScreen’ == True

’autoShow’

Value type: bool

Default: False

Viewing : View After Exporting.

’showInteractives’

Value type: bool

Default: True

Options : Forms and Media.

’thumbnails’

Value type: bool

Default: False

Options : Embed Page Thumbnails.

’layers’

Value type: bool

Default: False

Options : Create Acrobat Layers.

’tags’

Value type: bool

Default: False

Options : Create Tagged PDF.

’tabs’

Value type: str

Default: ‘definition’

Options : Use Structure for Tag Order.

Allowed values:

’definition’

’structure’

Only used when ‘tags’ == True

Compression

’compression’

Value type: str

Default: ‘auto’

Compression.

Allowed values:

’auto’

’jpeg’

’lossless’

’quality’

Value type: str

Default: ‘high’

JPEG Quality.

Allowed values:

’min’

’low’

’medium’

’high’

’max’

’resolution’

Value type: int

Default: 72

Minimum: 10

Resolution (ppi).

Accessibility

’title’

Value type: str

Default: ‘file’

Accessibility Options : Display Title.

Allowed values:

’document’

’file’

’language’

Value type: str

Default: ‘’

Accessibility Options : Language

For the available languages and their spelling, please refer to the popup menu Accessibility Options : Language.

Security
The security settings depend very much on the used PDF viewer. Viewers like Acrobat or Acrobat Pro may not be able to display all the security settings you have made. If the settings are missing, please check first whether you can create settings manually!

’password’

Value type: str

Default: ‘’

Document Open Password.

’authorization’

Value type: str

Default: ‘’

Permissions : Permissions Password.

’allowPrint’

Value type: str

Default: ‘yes’

Permissions : Print Allowed.

Allowed values:

’no’

’yes’

’low’

Only used when ‘authorization’ is set.

’allowAssembly’

Value type: bool

Default: True

Changes Allowed -> Inserting, deleting and rotating pages.

Only used when ‘authorization’ is set.

’allowFormfill’

Value type: bool

Default: True

Changes Allowed -> Fill in form fields and signing.

Only used when ‘authorization’ is set.

’allowNotes’

Value type: bool

Default: True

Changes Allowed -> Commenting.

Only used when ‘authorization’ is set.

’allowExtraction’

Value type: bool

Default: True

Changes Allowed -> Any except extracting pages.

Only used when ‘authorization’ is set.

’allowCopy’

Value type: bool

Default: True

Enable copying of text, images and other content.

Only used when ‘authorization’ is set.

’allowChange’

Value type: bool

Default: True

Enable text access of screen reader devices.

Only used when ‘authorization’ is set.

’plainTextForMeta’

Value type: bool

Default: True

Enable plaintext metadata.

Only used when ‘authorization’ is set.
scope (int) –
Export pages or spreads?
- 1 : Spreads
- 2 : Pages
Export of comet notes:
- +4 : Export all visible comet notes
- +8 : Export all comet notes
comet_pdf® All notes are always exported

Illustrator® Ignored

PDFs containing comet notes should never be used for printing.

If the document does not contain any Comet Notes which need to be exported, the PDF will remain unchanged - i.e. it will not be reassembled using PDFlib.
indices (list[int]) –
List of 0-based page or spread indices to export.
- Empty list: Export everything
When exporting Comet notes to PDF, the export must start at page 0 and contain all subsequent pages in their correct order. Otherwise, errors will occur when assigning pages to notes. Pages at the end of the document can be omitted in the export.

Return type:

None

Raises:

TypeError – When parameter types are invalid
ValueError – When parameter path is empty
CometError – On internal error

Available:

InDesign® comet_pdf® Illustrator®

CScript:

document::pdf_export

CDocument.getPageItems()¶

Get all pageitems of this document.

Parameters:

recursive (bool) –

Whether to resolve hierarchies completely.

False Only return root pageitems.
True Flatten hierarchies, omitting groups from the result.

Returns:

The pageitems of the document.

Return type:

list[CPageItem]

Raises:

TypeError – When parameter types are invalid.
CometError – On internal error

Available:

InDesign® comet_pdf® Illustrator®

CScript:

itemlist::allframes_of_doc

CDocument.getMasterPageItems(master, linkedOnly=False, placeHolderID=0, ID=None, info1='', info2='')¶

Create a list of page items on a master page.

Parameters:

master (tuple[str, int] | int | CPage) –
The master page.

The parameter type can be:
- tuple [str, int]
  Master spread name, index in master spread.
- int
  Index of a page in this document whose master page should be used.
  
  In this case the page’s master page is automatically determined.
- CPage
  A page in this document whose master page should be used.
  
  In this case the page’s master page is automatically determined.
linkedOnly (bool) – Whether to only get page items which have placeholders applied to them.
placeHolderID (int) –
When parameter linkedOnly is True, only collect placeholders with this ID.
- 0: Ignore the parameter.
ID (None | CIDType | tuple[int, int, int, str]) –
The page item must be linked to this item.

The parameter type can be:
- None
  Ignore the parameter.
- CIDType
  The ID of the object.
- tuple [int, int, int, str]
  The ID of the object as ID1, ID2, ID3, StringID
info1 (str) – When this parameter is not empty, info1 of the frame placeholder must match this value to be included in the result.
info2 (str) – When this parameter is not empty, info2 of the frame placeholder must match this value to be included in the result.

Returns:

List of all pageitems of the master page.

Return type:

list[CPageItem]

Raises:

TypeError – When parameter types are invalid.
CometError – On internal error.

Available:

InDesign® comet_pdf®

CScript:

itemlist::masteritems

CDocument.getFrame(UID)¶

Get an existing frame by its UID.

Parameters:

UID (int) – The frame UID

Returns:

The found frame

Return type:

CFrame

Raises:

TypeError – When parameter types are invalid
ValueError – When parameter UID is < 0
KeyError – When the frame does not exist
CometError – On internal error

Available:

InDesign® comet_pdf®

CScript:

item::define

CDocument.getFrames(addSubFrames=False, placeHolders=[], layers=[], cometGroups=[], includePasteboard=False)¶

Get all frames of a document

Parameters:

addSubFrames (bool) – Add subframes aswell?
placeHolders (list[int]) –
Restrict to frames which have frame placeholders applied with these IDs.
- Empty list : Impose no restrictions
- [-1] : Restrict to all frames with placeholders
layers (list[str] | list[CLayer]) –
Restrict the result to frames on the provided layers.

The parameter type can be:
- list [str]
  Layer names
- list [CLayer]
  Layers
- Empty list : Do not impose restrictions
When the parameter is list [CLayer], all layers must belong to this document.
cometGroups (list[int]) –
Restrict to comet groups with these IDs.
- Empty list: Impose no restrictions
InDesign® comet_pdf® Not supported
includePasteboard (bool) –
Also include frames on the paste board in the result list?

Illustrator® Not supported

Returns:

A list of all frames in the document with filtering applied.

Return type:

list[CFrame]

Raises:

TypeError – When parameter types are invalid.
CometError – On internal error

Available:

InDesign® comet_pdf® Illustrator®

CScript:

itemlist::allframes_of_doc

CDocument.getGroups(recursive=False)¶

Get all groups of this document.

Parameters:

recursive (bool) –

Find groups recursively?

False: Find only root groups.
True: Find nested groups aswell.

Returns:

The found groups.

Return type:

list[CGroup]

Raises:

TypeError – When parameter types are invalid
CometError – On internal error

Available:

InDesign® comet_pdf® Illustrator®

CDocument.getSpreads()¶

Returns a list of all spreads in the document.

Returns:: The document spreads.
Return type:: list[CSpread]
Available:: InDesign® comet_pdf®

CDocument.getPage(data)¶

Get a specific document page by index or name.

Parameters:

data (int | str) –

The page to get.

The parameter type can be:

int
The page index
str
The page name

InDesign® comet_pdf® The name must exactly match the full page name

Illustrator® When multiple artboards have the same name, the first one is returned

Returns:

The found page

Return type:

CPage

Raises:

TypeError – When parameter types are invalid
IndexError – When parameter data is int and is out of bounds
ValueError – When parameter data is str and is empty
CometError –
- When the page was not found
- On internal error

Available:

InDesign® comet_pdf® Illustrator®

CDocument.getPages()¶

Returns a list of all pages in the document.

Returns:: The document pages
Return type:: list[CPage]
Available:: InDesign® comet_pdf® Illustrator®
CScript:: document::pages

CDocument.createPages(count=1, index=-1, width=0.0, height=0.0, masterPage='', localize=False)¶

Create new document pages.

InDesign® comet_pdf®

New pages can be created at an arbitrary index inside the existing pages and can be based on masterpages. When the masterpages contain frames with placeholders, they can automatically be localized (when parameter localize is True)

Illustrator® There are several limitations in the Illustrator SDK:

New artboards can only be created as the last in the list
Artboards cannot be rearranged

Due to these limitations the index parameter cannot be evaluated.

Newly created artboards are placed to the right of the rightmost artboard in the document.

Parameters:

count (int) – The number of pages to create
index (int) –
The page index to place the new pages at.
- -1: Place at end
Illustrator® Ignored
width (float) –
The new page width.

InDesign® comet_pdf® <= 0.0: Use default width of the document

Illustrator® <= 0.0: Use the width of the rightmost artboard in the document
height (float) –
The new page height.

InDesign® comet_pdf® <= 0.0: Use default height of the document

Illustrator® <= 0.0: Use the height of the rightmost artboard in the document
masterPage (str) –
The masterpage to apply to the new pages.

The name must be provided with a prefix, e.g. ‘A-Masterpage’
- Empty str: Use the default.
Illustrator® Ignored
localize (bool) –
Should masterpage frames with placeholders be localized?

Illustrator® Ignored

Returns:

The newly created pages

Return type:

list[CPage]

Raises:

TypeError – When parameter types are invalid
ValueError – When parameter count is <= 0
CometError – On internal error

Available:

InDesign® comet_pdf® Illustrator®

CScript:

page::create

CDocument.getCurrentPage()¶

Returns the current page of the document.

InDesign® Using InDesign® Server the current page is not defined. This function returns None in this case.

Returns:: The current page
Return type:: CPage
Raises:: CometError – On internal error
Available:: InDesign® Illustrator®
CScript:: document::page

CDocument.setStartPage(pageNumber, style=0)¶

Set the start page of a document. Additionally, the numbering format can also be specified.

Parameters:

pageNumber (int) – Start page number (not index)
style (int) –
Numbering format
- 0 : 1, 2, 3, 4, …
- 1 : I, II, III, IV, …
- 2 : i, ii, iii, iv, …
- 3 : A, B, C, D, …
- 4 : a, b, c, d, …

Return type:

None

Raises:

TypeError – When parameter types are invalid
ValueError – When parameter style has invalid value
CometError – On internal error

Available:

InDesign® comet_pdf®

CScript:

document::set_startpage

CDocument.getMasterPageInfo(unusedOnly=False, sortByBasedOn=True)¶

Get information the about master spreads of this document.

Parameters:

unusedOnly (bool) – Get only the unused master pages of the document?
sortByBasedOn (bool) –
Sort order in result list:
- True: The result list is sorted such that masters with other masters applied to them are later in the list than the masters they derive from.
- False: Same sequence order like in Pages panel.

Returns:

List with information as tuples: (Name, UID, Number of pages, UID of ancestor)

Return type:

list[tuple[str, int, int, int]]

Raises:

TypeError – When parameter types are invalid
CometError – On internal error

Available:

InDesign® comet_pdf®

CScript:

document::get_masterpages

CDocument.getLayer(data)¶

Get a layer by providing the layer name or path.

Illustrator® This function can be used to find nested layers by providing a layer ‘path’, which is the hierarchy above the target layer denoted by the layer names.

Parameters:

path (str | list[str] | int) –

The layer to search for.

The parameter type can be:

str
Name of a top level layer.

list [str]
Nested layer path.

int
Top level layer index counting from the bottom.

Returns:

The found layer

Return type:

CLayer

Raises:

TypeError – When parameter types are invalid
ValueError –
- When parameter data is str and empty
- When parameter data is list [str] and empty
- When parameter data is int and negative
KeyError – When the layer was not found
CometError – On internal error

CDocument.getLayers()¶

Return a list of all layers of the document.

Illustrator® Only contains top-level layers

Returns:: List of layers.
Return type:: list[CLayer]
Available:: InDesign® comet_pdf® Illustrator®
CScript:: layer::count

CDocument.createLayer(name='', before=0)¶

Create a new layer with the specified name at the specified position.

If a layer with the specified name already exists, no additional layer is added and the layer position remains unchanged.

If before is not found, the new layer will be added as the bottom-most layer.

If no name is specified, a new default name will be ascertained.

Parameters:

name (str) – The layer name. Can be empty string to use a default name.
before (str | int | CLayer) –
Where to put the new layer (before)?

The parameter type can be:
- str to incidate a layer name
- int to indicate a layer index
- CLayer to indicate a layer object

Returns:

The new layer

Return type:

CLayer

Raises:

TypeError – When parameter types are invalid
ValueError – When parameter name is empty
CometError – On internal error

Available:

InDesign® comet_pdf® Illustrator®

CScript:

layer::add

CDocument.getActiveLayer()¶

Get the active document layer.

InDesign® In InDesign® Server, the current front document is the last document opened and the active layer is the layer that was last defined in this document with CLayer.setActive(). The call of CLayer.setActive() may have been in a previous (also InDesign® Desktop) session. If CLayer.setActive() has never been executed in this current front document, the empty string is returned.

Returns:: The active layer
Return type:: CLayer
Raises:: CometError – On internal error
Available:: InDesign® comet_pdf®
CScript:: layer::front_name

CDocument.setActiveLayer(layer)¶

Set the active document layer.

InDesign® In InDesign® Server, the current front document is the last document opened and the active layer is the layer that was last defined in this document with CLayer.setActive(). The call of CLayer.setActive() may have been in a previous (also InDesign® Desktop) session. If CLayer.setActive() has never been executed in this current front document, the empty string is returned.

Parameters:

layer (str | CLayer) –

The new layer to set.

The parameter type can be:

str
The new active layer name.
CLayer
The new active layer.

Return type:

None

Raises:

TypeError – When parameter types are invalid
CometError – On internal error

Available:

InDesign® comet_pdf® Illustrator®

CScript:

layer::select

CDocument.getDefaultLayerName(prefix='')¶

Ascertain the next valid default name which can be used for a new layer.

If the prefix is empty, the new name is automatically determined.

If a prefix is specified, a number is attached to the prefix.

If the document already has 999 layers, the method will fail.

Parameters:

prefix (str) –

Prefix for determining the layer name.

This is prepended before the first available number.

Returns:

The next free layer name

Return type:

str

Raises:

TypeError – When parameter types are invalid
CometError – On internal error

Available:

InDesign® comet_pdf®

CScript:

layer::default_name

CDocument.getStyleNames(styleType)¶

Get all available style names for the designated style type.

Parameters:

styleType (int) –

The style type to get the names for.

One of Style types

Illustrator® constants.kStyleTypeObject not available

Returns:

List of style names

Return type:

list[str]

Raises:

TypeError – When parameter types are invalid
ValueError – When parameter styleType has invalid value
CometError – On internal error

Available:

InDesign® comet_pdf® Illustrator®

CScript:

document::get_styles

Examples:

Get all style names from every style type from the current document and show them as a message.

#!py
#pragma plain

import comet

def main():
    #Initialize message with a header
    message = 'All document styles:'

    #Iterate through all style types
    for styleType, styleTypeName in comet.constants.kStyleTypes.items():
        message += f'\n{styleTypeName}:'

        #Get all styles for the current style type
        styles = comet.gDocument.getStyleNames(styleType)

        #Append each style to the message
        for style in styles:
            message += f'\n\t{style}'

    #Display the compiled message
    comet.showMessage(message)

    return 0

CDocument.getCometGroup(ID)¶

Get a single comet group by ID from this document.

Returns None when no group with this ID exists.

Parameters:

ID (int) – The comet group ID to search for

Returns:

The found group, or None

Return type:

CCometGroup | None

Raises:

TypeError – When parameter types are invalid
ValueError – When parameter ID is <= 0
CometError – On internal error

Available:

InDesign® comet_pdf® Illustrator®

CScript:

itemlist::get_cometgroup_members

CDocument.getCometGroups()¶

Get all comet groups from this document.

Returns:: All comet groups of this document.
Return type:: list[CCometGroup]
Raises:: CometError – On internal error
Available:: InDesign® comet_pdf® Illustrator®

CDocument.placeTemplate(templateID, ID, position, page=None, layer=None, autoLoad=False, addToCometGroup=True)¶

Parameters:

templateID (int) – ID of the template to insert.
ID (tuple[int, int, int, str] | CIDType) –
The record ID to link the placeholders to.

Parameter type options:
- tuple [int, int, int, str]
  ID1, ID2, ID3, StringID
- CIDType
  A record ID.
position (tuple[float, float]) – X/Y page relative position in pt.
page (int | CPage) –
Page to place the template on.

Parameter type options:
- None:
  Use the current page.
  
  InDesign® comet_pdf® Under InDesign® Server and comet_pdf the current page is not defined.
- int:
  Page index.
- CPage:
  A page of this document.
layer (int | str | CLayer) –
The layer to place the template on.

Parameter type options:
- None:
  Use the background layer.
- int:
  Layer index.
- str:
  Layer name.
- CLayer
  A layer of this document.
autoLoad (bool) – Should the placeholders of the template be loaded?
addToCometGroup (bool) –
The frames of the template are automatically combined into a Comet group.

Should this group become a subgroup of the current script frame?
- True:
  Yes.
  
  The main frame must be on the same spread as the script frame.
- False:
  No.
  
  If you select this setting, the frames of the template form their own independent comet group.
  
  In this case, the product structure can no longer recognize that the frames actually still belong to the product.

Return type:

list[CPageItem]

Raises:

TypeError – When parameter types are invalid
CometError – On internal error

Available:

InDesign® comet_pdf®

CScript:

document::place_items

CDocument.getDocLinks()¶

Get all document links of this document.

Returns:: A list of all document links.
Return type:: list[CDocLink]
Raises:: CometError – On internal error
Available:: InDesign® comet_pdf®
CScript:: document::get_links

CDocument.getBook()¶

Get the book of this document.

The book must must be opened to be found.

Returns:

The book this document belongs to if any, else None

Return type:

CBook | None

Raises:

CometError – On internal error

Available:

InDesign®

CScript:

document::get_book

Example:

Get the path of all sibling documents in the same book and output them to the logfile.

#!py

import comet

def main():
    book = comet.gDocument.getBook()

    if book:
        gDocumentPath = comet.gDocument.getPath()
        documents = book.getDocuments()

        for docPath in documents:
            if docPath == gDocumentPath:
                continue
            comet.wlog(docPath)
    else:
        comet.wlog('No book found')

    return 0

CDocument.getBookmarks(recursive=False, name='')¶

Get all bookmarks of this document.

Parameters:

recursive (bool) –
Whether to return top level bookmarks or all bookmarks
- True Return all bookmarks and children in depth-first order
- False : Return top level bookmarks only
name (str) –
Only return bookmarks matching this name
- Empty str: Impose no name restriction

Returns:

All bookmarks of this document.

Return type:

CBook | None

Raises:

TypeError – When parameter types are invalid
CometError – On internal error

Available:

InDesign®

CScript:

bookmark::find

CDocument.createBookmark(pageDestination, name, index=-1)¶

Create a new bookmark in this document.

Parameters:

pageDestination –
The destination the bookmark points to.

The parameter type can be:
- int
  A page index.
- CPage
  A page. Must be in the same document.
name (str) – The name of the bookmark.
index (int) –
The index among the root bookmarks.

The value is clamped to valid values:
- < 0 or > max index: Last

Returns:

The newly created bookmark

Return type:

CBookmark

Raises:

TypeError – When parameter types are invalid
ValueError – When parameter name is empty
CometError – On internal error

Available:

InDesign® comet_pdf®

See also:

CBookmark.createBookmark()

CScript:

CDocument.getArticles()¶

Get a list of all articles in this document.

Returns:

The document’s articles.

Return type:

list[CArticle]

Raises:

CometError – On internal error

Available:

InDesign® comet_pdf®

CScript:

CDocument.createArticle(name='', index=-1, useForExport=True)¶

Create a new, empty article in this document.

Parameters:

name (str) –
The new article name.
- Empty str : Use default name.
index (str) –
The index of the new article.
- < 0 or > count: Append at end.
useForExport (bool) – Whether the article should be exported.

Returns:

The newly created article.

Return type:

CArticle

Raises:

TypeError – When parameter types are invalid
CometError – On internal error

Available:

InDesign® comet_pdf®

CScript:

document::article::create

CDocument.getMetaData(key)¶

Get (XMP) Metadata from the Document.

InDesign® The Metadata is found under File->File information.

Parameters:

key (str) –

The key which indicates which data to fetch.

The following keys are available:

Keys

’kTitle’

The document title.

Return value type: str

’kAuthor’

The document author.

Return value type: str

’kAuthorTitle’

The document author’s title.

Return value type: str

’kAuthorDescription’

The document author’s description.

Return value type: str

’kDescription’

The document’s description.

Return value type: str

’kKeys’

The document’s keywords.

Return value type: list [str]

’kCopyRight’

The document’s copyright notice.

Return value type: str

’kCopyRightURL’

The document’s copyright notice URL.

Return value type: str

’kCopyRightState’

The document’s copyright state.

Possible return values:

1: Protected by copyright.
2: Public domain.
else: Unknown.

Return value type: int

’kRating’

The document’s star rating (0-5 stars).

Possible return values:

1-5: Number of stars.
else: Not rated.

Return value type: int

Returns:

The data for the queried key.

The return type depends on parameter key.

Return type:

int | str | list[str]

Raises:

TypeError – When parameter types are invalid.
ValueError – When parameter key has invalid value.
CometError – On internal error.

Available:

InDesign® comet_pdf®

CScript:

CDocument.setMetaData(key, value)¶

Set (XMP) Metadata into the Document.

InDesign® The Metadata is found under File->File information.

Parameters:

key (str) –
The key which indicates which data to fetch.

The following keys are available:
Keys

’kTitle’

The document title.

Value type: str

’kAuthor’

The document author.

Value type: str

’kAuthorTitle’

The document author’s title.

Value type: str

’kAuthorDescription’

The document author’s description.

Value type: str

’kDescription’

The document’s description.

Value type: str

’kKeys’

The document’s keywords.

Value type: list [str]

’kCopyRight’

The document’s copyright notice.

Value type: str

’kCopyRightURL’

The document’s copyright notice URL.

Value type: str
’kCopyRightState’

The document’s copyright state.

Possible values:
- 1: Protected by copyright.
- 2: Public domain.
- else: Unknown.
Value type: int
’kRating’

The document’s star rating (0-5 stars).

Possible values:
- 1-5: Number of stars.
- else: Not rated.
Value type: int
value (int | str | list[str]) – The value to set. The value type depends on the parameter key.

Return type:

None

Raises:

TypeError – When parameter types are invalid.
ValueError – When parameter key has invalid value.
CometError – On internal error.

Available:

InDesign® comet_pdf®

CScript:

CDocument.redraw()¶

Force redrawing of the document window.

Return type:: None
Raises:: CometError – On internal error.
Available:: InDesign® Illustrator®
CScript:: document::force_redraw

Special methods¶

CDocument.__repr__()¶

String representation.

Returns:

<CDocument> Name: Name | Path: Path

Example¶

<CDocument> Name: DebugInfo.indd | Path: C:\Users\Leo\Desktop\DebugInfo\DebugInfo.indd

Return type:

str

comet.CDocument¶

Methods¶

Special methods¶

Table of Contents

Previous topic

Next topic

This Page