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.

See also

Module document

General document related functions

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()

Returns:

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

Returns:

None

Raises:

• TypeError – When parameter types are invalid

• ValueError – When parameter key is empty

• 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

Warning

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:

• color::count_swatches

• color::get_nth_swatch

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

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

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

Available:

InDesign® comet_pdf®

See also:

CBookmark.createBookmark()

CScript:

• bookmark::create

• bookmark::create2

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:

• document::metadata::get_title

• document::metadata::get_author

• document::metadata::get_author_title

• document::metadata::get_author_descr

• document::metadata::get_descr

• document::metadata::get_keys

• document::metadata::get_copyright

• document::metadata::get_copyright_url

• document::metadata::get_copyright_state

• document::metadata::get_rating

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:

• document::metadata::set_title

• document::metadata::set_author

• document::metadata::set_author_title

• document::metadata::set_author_descr

• document::metadata::set_descr

• document::metadata::set_keys

• document::metadata::set_copyright

• document::metadata::set_copyright_url

• document::metadata::set_copyright_state

• document::metadata::set_rating

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