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

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.

    Ignored.

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

    The following options are available:

    General

    ’compressed’

    If True, the saved file is compressed.

    ’embedICCProfile’

    If True, the document’s ICC profile is embedded in the saved file

    ’embedLinkedFiles’

    If True, the linked image files is embedded in the saved file.

    ’pdfCompatible’

    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
Available

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
Available

CScript

document::duplicate

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

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

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 comet.kDocCloseProcess you can force direct closing, but this may cause serious problems!

Parameters
Returns

None

Raises
Available

CScript

document::close

CDocument.getName()

Gets the filename of a document

Returns

The file name of the document

Return type

str

Available

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

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
Available

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

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.

Also valid for InDesign® Server.

Returns

None

Raises

CometError – On internal error

Available

CScript

document::select

CDocument.getAttributes()

Fetch all key-values of a document

get attributes from the root node of the document structure.

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

CDocument.getAttribute(key)

Fetch a single key-value of a document

get an attribute from the root node of the document structure.

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

CDocument.setAttribute(key, value)

Set a single key-value attribute of the document.

Sets an attribute to the root node of the document structure.

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
Available

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

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

Ignored

Returns

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

Values are (inner, top, outer, bottom, isUniform)

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

Return type

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

Raises

CometError – On internal error

Available

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.

Values are (inner, top, outer, bottom)

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
Available

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

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

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
Available

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
Available

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

CDocument.getSwatches()

Get all swatches of the document.

Returns

The document swatches

Return type

list[CSwatch]

Raises

CometError – On internal error

Available

CScript
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

CScript

color::define_rgb

CDocument.createSwatchCMYK(name, C, M, Y, K, 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.

  • 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

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

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.

      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

    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’

    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’

    Viewing : Open in Full Screen Mode.

    ’flipPages’

    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’

    Viewing : View After Exporting.

    ’showInteractives’

    Options : Forms and Media.

    ’thumbnails’

    Options : Embed Page Thumbnails.

    ’layers’

    Options : Create Acrobat Layers.

    ’tags’

    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’

    Changes Allowed -> Inserting, deleting and rotating pages.

    Only used when ‘authorization’ is set.

    ’allowFormfill’

    Changes Allowed -> Fill in form fields and signing.

    Only used when ‘authorization’ is set.

    ’allowNotes’

    Changes Allowed -> Commenting.

    Only used when ‘authorization’ is set.

    ’allowExtraction’

    Changes Allowed -> Any except extracting pages.

    Only used when ‘authorization’ is set.

    ’allowCopy’

    Enable copying of text, images and other content.

    Only used when ‘authorization’ is set.

    ’allowChange’

    Enable text access of screen reader devices.

    Only used when ‘authorization’ is set.

    ’plainTextForMeta’

    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

    All notes are always exported

    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
Available

CScript

document::pdf_export

CDocument.getPageItems()

Get all pageitems of this document.

Parameters

recursive (bool) –

Wether 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
Available

CScript

itemlist::allframes_of_doc

CDocument.getFrame(UID)

Get an existing frame by its UID.

Parameters

UID (int) – The frame UID

Returns

The found frame

Return type

CFrame

Raises
Available

CScript

item::define

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

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:

    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

    Not implemented

Returns

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

Return type

list[CFrame]

Raises
Available

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
Available

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

The name must exactly match the full page name

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

CDocument.getPages()

Returns a list of all pages in the document.

Returns

The document pages

Return type

list[CPage]

Available

CScript

document::pages

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

Create new document pages.

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)

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

    Ignored

  • width (float) –

    The new page width.

    <= 0.0: Use default width of the document

    <= 0.0: Use the width of the rightmost artboard in the document

  • height (float) –

    The new page height.

    <= 0.0: Use default height of the document

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

    Ignored

  • localize (bool) –

    Should masterpage frames with placeholders be localized?

    Ignored

Returns

The newly created pages

Return type

list[CPage]

Raises
Available

CScript

page::create

CDocument.getCurrentPage()

Returns the current page of the document.

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

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
Available

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
Available

CScript

document::get_masterpages

CDocument.getLayer(data)

Get a layer by providing the layer name or path.

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.

Only contains top-level layers

Returns

List of layers.

Return type

list[CLayer]

Available

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
Available

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
Available

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

comet.kStyleTypeObject not available

Returns

List of style names

Return type

list[str]

Raises
Available

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
Available

CScript

itemlist::get_cometgroup_members

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

CScript

document::get_book

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

Get all bookmarks of this document.

Parameters

  • recursive (bool) –

    Wether 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
Available

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
Available

See also

CBookmark.createBookmark()

CScript