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
- 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
’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.’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
- CScript
- 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
- Returns
None
- Raises
TypeError – When parameter types are invalid
ValueError – When parameter path is empty
CometError – On internal error
- Available
- CScript
- 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
save (bool) – Whether to save the document before closing
mode (int) –
comet.kDocCloseSchedule
: Close normally on next idle timecomet.kDocCloseProcess
: Close right now. This may cause serious problems even on changed files!comet.kDocCloseImmediate
: Close immediately. This is an attempt to circumvent the InDesign® problems withcomet.kDocCloseProcess
. Unfortunately, we cannot promise that this will work in every case - but it is worth a try.
Ignored
- Returns
None
- Raises
TypeError – When parameter types are invalid
ValueError – When parameter mode has invalid value
CometError – On internal error
- Available
- CScript
- CDocument.getName()¶
Gets the filename of a document
- Returns
The file name of the document
- Return type
- Available
- CScript
- 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
- Raises
CometError – On internal error
- Available
- CScript
- 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
- CScript
- CDocument.getPath()¶
Gets the filepath of a document
- Returns
The full file path of the document
- Return type
- Available
- CScript
- 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
- 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
- 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
- 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
- Returns
None
- Raises
TypeError – When parameter types are invalid
ValueError – When parameter key is empty
CometError – On internal error
- 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 whether they are uniform as a tuple.
Values are (inner, top, outer, bottom, isUniform)
Values are (left, top, right, bottom, isUniform)
- Return type
- Raises
CometError – On internal error
- Available
- CScript
- 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
- Returns
None
- Raises
TypeError – When parameter types are invalid
ValueError – When bleeds are < 0.0
CometError – On internal error
- Available
- CScript
- CDocument.getRasterEffectResolution()¶
Get the document raster effect resolution.
- Returns
The resolution in dpi
- Return type
- 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
- 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
- Raises
TypeError – When parameter types are invalid
ValueError – When parameter type has invalid value
CometError – On internal error
- 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
TypeError – When parameter types are invalid
ValueError – When parameter type has invalid value
CometError – On internal error
- 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
- 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
- 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
- Returns
The newly created swatch - if any - else
None
- Return type
- Raises
TypeError – When parameter types are invalid
When parameter document is
None
and there is no script documentWhen 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
- 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
- Returns
The newly created swatch - if any - else
None
- Return type
- Raises
TypeError – When parameter types are invalid
When parameter document is
None
and there is no script documentWhen 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
- 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
- Returns
The newly created swatch - if any - else
None
- Return type
- Raises
TypeError – When parameter types are invalid
When parameter document is
None
and there is no script documentWhen 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
- 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).
The PDF profile to use.
The parameter type can be:
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]
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
’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’
’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
’tabs’
Value type:
str
Default: ‘definition’
Options : Use Structure for Tag Order.
Allowed values:
’definition’
’structure’
Only used when ‘tags’ ==
True
Compression
’quality’
Value type:
str
Default: ‘high’
JPEG Quality.
Allowed values:
’min’
’low’
’medium’
’high’
’max’
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!
’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.
scope (int) –
Export pages or spreads?
1 : Spreads
2 : Pages
+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.
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
- Raises
TypeError – When parameter types are invalid
ValueError – When parameter path is empty
CometError – On internal error
- Available
- CScript
- CDocument.getPageItems()¶
Get all pageitems of this document.
- Parameters
recursive (bool) –
Whether to resolve hierarchies completely.
- Returns
The pageitems of the document.
- Return type
- Raises
TypeError – When parameter types are invalid.
CometError – On internal error
- Available
- CScript
- CDocument.getFrame(UID)¶
Get an existing frame by its UID.
- Parameters
UID (int) – The frame UID
- Returns
The found frame
- Return type
- 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
- CScript
- CDocument.getFrames(addSubFrames=False, placeHolders=[], layers=[], cometGroups=[])¶
Get all frames of a document
- Parameters
addSubFrames (bool) – Add subframes aswell?
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.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
- Raises
TypeError – When parameter types are invalid.
CometError – On internal error
- Available
- CScript
- CDocument.getGroups(recursive=False)¶
Get all groups of this document.
- CDocument.getPage(data)¶
Get a specific document page by index or name.
- Parameters
The page to get.
The parameter type can be:
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
- Raises
TypeError – When parameter types are invalid
IndexError – When parameter data is
int
and is out of boundsValueError – When parameter data is
str
and is emptyWhen 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
- Available
- CScript
- 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
- Raises
TypeError – When parameter types are invalid
ValueError – When parameter count is <= 0
CometError – On internal error
- Available
- CScript
- 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
- Raises
CometError – On internal error
- Available
- CScript
- CDocument.setStartPage(pageNumber, style=0)¶
Set the start page of a document. Additionally, the numbering format can also be specified.
- Parameters
- Return type
- Raises
TypeError – When parameter types are invalid
ValueError – When parameter style has invalid value
CometError – On internal error
- Available
- CScript
- CDocument.getMasterPageInfo(unusedOnly=False, sortByBasedOn=True)¶
Get information the about master spreads of this document.
- Parameters
- Returns
List with information as tuples: (Name, UID, Number of pages, UID of ancestor)
- Return type
- Raises
TypeError – When parameter types are invalid
CometError – On internal error
- Available
- CScript
- 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.
- CDocument.getLayers()¶
Return a list of all layers of the document.
Only contains top-level layers
- Returns
List of layers.
- Return type
- Available
- CScript
- 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
- Returns
The new layer
- Return type
- Raises
TypeError – When parameter types are invalid
ValueError – When parameter name is empty
CometError – On internal error
- Available
- CScript
- 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
- Raises
TypeError – When parameter types are invalid
CometError – On internal error
- Available
- CScript
- 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
- Raises
TypeError – When parameter types are invalid
ValueError – When parameter styleType has invalid value
CometError – On internal error
- Available
- CScript
- 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
- Raises
TypeError – When parameter types are invalid
ValueError – When parameter ID is <= 0
CometError – On internal error
- Available
- CScript
- 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
- Raises
CometError – On internal error
- Available
- CScript
- CDocument.getBookmarks(recursive=False, name='')¶
Get all bookmarks of this document.
- Parameters
- Returns
All bookmarks of this document.
- Return type
- Raises
TypeError – When parameter types are invalid
CometError – On internal error
- Available
- CScript
- CDocument.createBookmark(pageDestination, name, index=- 1)¶
Create a new bookmark in this document.
- Parameters
- Returns
The newly created bookmark
- Return type
- Raises
TypeError – When parameter types are invalid
ValueError – When parameter name is empty
- Available
- See also
- CScript
- CDocument.getMetaData(key)¶
Get (XMP) Metadata from the Document.
The Metadata is found under File->File information.
- Parameters
key (str) –
The key which indicates which data to fetch.
The following keys are available:
- Returns
The data for the queried key.
The return type depends on parameter key.
- Return type
- Raises
TypeError – When parameter types are invalid.
ValueError – When parameter key has invalid value.
CometError – On internal error.
- Available
- CScript
- CDocument.setMetaData(key, value)¶
Set (XMP) Metadata into the Document.
The Metadata is found under File->File information.
- Parameters
- Return type
- Raises
TypeError – When parameter types are invalid.
ValueError – When parameter key has invalid value.
CometError – On internal error.
- Available
- CScript