comet

The comet module is the primary service provider for comet related functionality

Methods

comet.getContext()

Fetches the script context in which this script is called. Depending on the type of action, scripts can be reused for multiple situations (e.g. different placeholder calls can use the same action like placeholder load and placeholder sync).

Returns:

Context this script is called in. See Contexts

Return type:

int

Available:

InDesign® comet_pdf® Illustrator®

comet.getVersion()

Determine the current comet version as a str, e.g. ‘4.3’.

Returns:

The comet version as a str

Return type:

str

Available:

InDesign® comet_pdf® Illustrator®

comet.getVersionMajor()

Determine the major comet version. e.g. 4 for comet 4.3

Returns:

The major comet version

Return type:

int

Available:

InDesign® comet_pdf® Illustrator®

comet.getVersionMinor()

Determine the minor comet version. e.g. 3 for comet 4.3

Returns:

The minor comet version

Return type:

int

Available:

InDesign® comet_pdf® Illustrator®

comet.getRevision()

Determine the current comet revision.

Returns:

The comet revision

Return type:

str

Available:

InDesign® comet_pdf® Illustrator®

comet.setOutput(identifier, value)

Set an output variable depending on the active context. This function is used to provide comet with necessary information in callback contexts. e.g. when dynamically defining function variables it is necessary to fill the variable ‘gFuncVars’ with a predefined data structure to provide comet with the necessary information to properly establish the function variables.

The type of the output variable value is dynamic and depends on the context and variable. For a table of output variables and their types by context, see Output variables

Parameters:

  • identifier (str) – The variable identifier. Must match a variable available in the context.

  • value – The new variable value. Must match the variable type required in this context.

Returns:

None

Raises:

  • TypeError –

    • When parameter types are invalid

    • When parameter type of value does not match the required type

  • CometError – On internal error

Available:

InDesign® comet_pdf® Illustrator®

comet.getKeyValue(key, frame=None, index=0, length=-1)

Query the value of a keyword.

In placeholder scripts with direct statements and in panel statements a number of <tags> are defined which are replaced with their current values before the statement is executed.

A complete list of these tags can be found here.

In scripts, you can ask for these values directly in a number of ways. To simplify matters, this function can be used to obtain the values in a uniform manner.

Parameters:

  • key (str) – The key to query, without pointed brackets

  • frame (CFrame) –

    Associated frame. For frame-independent keys like ‘now’ or ‘user’ the parameter is is not needed.

    • None: Use gFrame when available

  • index (int) –

    Character index in the text to query the value.

    The parameter is only needed for text-related keys like ‘text’.

  • length (int) –

    Character length in the text to query the value.

    The parameter is only needed for text-related keys like ‘text’.

Returns:

The resolved value

Return type:

str

Raises:
Available:

InDesign® comet_pdf® Illustrator®

CScript:

system::key_value

comet.wlog(message, targetFile='', addNewLine=True)

Write a message to the logfile

Parameters:

  • message (str) – The message to write

  • targetFile (str) – Path of the log file. If the path is empty, the standard log file is used when it is enabled.

  • addNewLine (bool) – Automatically add a line break at the end of the message?

Returns:

None

Raises:

TypeError – When parameter types are invalid

Available:

InDesign® comet_pdf® Illustrator®

CScript:

wlog

comet.wtlog(message, targetFile='', addNewLine=True)

Write a message to the logfile with the current time as prefix in the format dd.mm.yyyy hh:mm:ss, e.g.

30.06.2021 14:13:47

Parameters:

  • message (str) – The message to write

  • targetFile (str) – Path of the log file. If the path is empty, the standard log file is used when it is enabled.

  • addNewLine (bool) – Automatically add a line break at the end of the message?

Returns:

None

Raises:

TypeError – When parameter types are invalid

Available:

InDesign® comet_pdf® Illustrator®

CScript:

wtlog

comet.showMessage(message)

Display a message dialog. The message automatically is translated according to translation tables.

comet_pdf® Outputs a message to the console instead of showing a dialog

Parameters:

message (str) – The message to show

Returns:

None

Raises:

TypeError – When parameter types are invalid

Available:

InDesign® comet_pdf® Illustrator®

comet.showError(message)

Display an error dialog. The message automatically is translated according to translation tables.

comet_pdf® Outputs a message to the console instead of showing a dialog

Parameters:

message (str) – The message to show

Returns:

None

Raises:

TypeError – When parameter types are invalid

Available:

InDesign® comet_pdf® Illustrator®

comet.uncurtain(input)

Uncurtain all available $-keys in the given string. $-keys are not only the standards $HOME, $DESKTOP, $DOCUMENTS, $PREFS, $PLUGINS, $COMET, $CACHE and $COMETDATA, but also all activated aliases defined in the Settings panel.

Parameters:

input (str) – The input string to uncurtain

Returns:

The input string with all possible aliases resolved

Return type:

str

Raises:

TypeError – When parameter types are invalid

Available:

InDesign® comet_pdf® Illustrator®

comet.pyImport(path)

Try to import a module from a comet datapool where the path may contain special import tokens which are dynamically resolved to the current data connection.

See Import directives for details

Parameters:

path (str) – The path in comet import directive syntax

Returns:

The imported module

Return type:

Module

Raises:
Available:

InDesign® comet_pdf® Illustrator®

comet.mm2pt(value)

Converts a value from milimeters to pt.

Parameters:

value (float) – The value to convert

Returns:

The converted value

Return type:

float

Raises:

TypeError – When parameter types are invalid

Available:

InDesign® comet_pdf® Illustrator®

CScript:

mm2pt

comet.pt2mm(value)

Converts a value from pt to milimeters.

Parameters:

value (float) – The value to convert

Returns:

The converted value

Return type:

float

Raises:

TypeError – When parameter types are invalid

Available:

InDesign® comet_pdf® Illustrator®

CScript:

pt2mm

comet.inch2pt(value)

Converts a value from inch to pt.

Parameters:

value (float) – The value to convert

Returns:

The converted value

Return type:

float

Raises:

TypeError – When parameter types are invalid

Available:

InDesign® comet_pdf® Illustrator®

CScript:

inch2pt

comet.pt2inch(value)

Converts a value pt to inch.

Parameters:

value (float) – The value to convert

Returns:

The converted value

Return type:

float

Raises:

TypeError – When parameter types are invalid

Available:

InDesign® comet_pdf® Illustrator®

CScript:

pt2inch

comet.translate(value, findKey=False)

Try to translate the input value by looking up the internal translation tables. When findKey is True, the value is considered already translated and the search tries to find the translation key. Current locale of the host software applies.

Parameters:

  • value (str) – Either the value to translate (findKey = False) or the translated value to find the key for (findKey = True)

  • findKey (bool) – Whether to search for a translation (False) or a key for a translation (True)

Returns:

The translated value. Returns the same as value when value was not found in translation tables

Return type:

str

Raises:
Available:

InDesign® comet_pdf® Illustrator®

comet.beep()

Outputs a beep sound.

Returns:

None

Available:

InDesign® comet_pdf® Illustrator®

CScript:

beep

comet.isShiftKeyPressed()

Is the shift pressed?

Returns:

Whether the alt key is pressed

Return type:

bool

Available:

InDesign® comet_pdf® Illustrator®

CScript:

shiftkey

comet.isAltKeyPressed()

Is the alt key pressed?

Returns:

Whether the alt key is pressed

Return type:

bool

Available:

InDesign® comet_pdf® Illustrator®

CScript:

altkey

comet.isCtrlKeyPressed()

Is the control key pressed?

Returns:

Whether the alt key is pressed

Return type:

bool

Available:

InDesign® comet_pdf® Illustrator®

CScript:

controlkey

comet.runJavaScript(input, isPath=False, showErrors=False, flags=0, items=[])

Run a JavaScript (Extendscript).

For additional information see Calling other scripts

Parameters:

  • input (str) –

    Either the complete script text as a string, or a full path to a file containing the script.

    When the parameter is a path, set isPath to True.

    If the parameter is a path, the file is expected to be UTF-8 encoded!

  • isPath (bool) –

    • True: input is the path to a script file

    • False: input is a script itself

  • showErrors (bool) –

    Show error dialogs on script errors?

  • flags (int) –

    The undo behavior of the script:

    • 0: Each script statement gets a separate undo step.

    • 2: Push the entire script as a single regular undo step.

      If an error occurs, roll back to the beginning of the script request that generated the error.

    • 4: Similar to 2, however faster because we don’t snapshot each script request.

      If an error occurs, we roll back to the beginning of the entire script.

    • 6: Push the entire script as a single auto-undoable step.

  • items (list) –

    Objects which are converted to global variables in your JavaScript, see Calling other scripts.

    This parameter creates JavaScript variables named gItemRef1, gItemRef2, etc..

    When these objects are inside a document or are documents themselves, they also create the according document variables gDocRef1, gDocRef2, etc..

    Furthermore, two global arrays names gItemRefs and gDocRefs are created containing all objects. The ItemRefs are being converted to their appropriate JavaScript objects.

    The following table shows all supported object types:

    Object

    ClassID

    JavaScript Type

    CDocument

    0xe01

    Document

    CFrame

    0x6201

    PageItem

    CTable

    0xb608

    Table

Returns:

The value returned by the script itself.

The value is always is converted to str - if you need another return type you will have to convert it yourself.

Return type:

str

Raises:

  • TypeError – When parameter types are invalid

  • ValueError – When parameter input is empty

  • FileNotFoundError – When parameter isPath is True and input does not point to an existing file

  • CometError –

    • On internal error

    • When the script fails

Available:

InDesign®

CScript:

run_javascript

comet.runCScript(input, isPath=False, showErrors=False, items=[], logExecution=False)

Run a CScript.

For additional information see Calling other scripts

Parameters:

  • input (str) –

    Either the complete script text as a string, or a full path to a file containing the script.

    When the parameter is a path, set isPath to True.

    If the parameter is a path, the file is expected to be UTF-8 encoded!

  • isPath (bool) –

    • True: input is the path to a script file

    • False: input is a script itself

  • showErrors (bool) –

    Show error dialogs on script errors?

  • items (list) –

    Objects which are converted to global variables in your CScript, see Calling other scripts.

    For each entry in this list, a global variable in the executed CScript is created. These variables are accessible in your CScript like intrinsic global variables (gFrame etc…).

    Entries can be:

    • tuple [type, str]

      Variable type, variable name.

      The name must be a non-empty unique valid CScript variable name.

      It is therefore a good idea to use a unique prefix for your variables, e.g. with ‘py’ which is not used as an intrinsic prefix in comet.

    • type

      Variable type.

      In this case an automatic name is generated starting with gItemRef1 and counting upwards: gItemRef2, … gItemRefN.

    For a complete list of all supported variable types, see Calling other scripts.

    The variable values do not change, even if they are changed in CScript.

    e.g. an input variable of type list [str] which is converted to a StringList in CScript and manipulated there, remains unchanged in Python.

    The variables must not be released in your CScript!

  • logExecution (bool) – Write to log that a script is being executed, including script name, ID, execution time etc…

Returns:

The return value of the main function of the script

Return type:

int

Raises:

  • TypeError – When parameter types are invalid

  • ValueError –

    • When parameter input is empty

    • When parameter items contains a tuple with an empty name

  • FileNotFoundError – When parameter isPath is True and input does not point to an existing file.

  • CometError –

    • On internal error

    • When the script fails

Available:

InDesign® comet_pdf® Illustrator®

comet.getScriptClipboard(key)

Get a value from the script clipboard.

A copy of the value is returned, not the value itself.

For more information about supported data types, the script stack, the script clipboard and the stored values see here .

Parameters:

key (str) – The key to fetch the value for.

Returns:

The found value

Raises:

  • TypeError – When parameter types are invalid.

  • ValueError – When parameter key is empty.

  • KeyError – When the clipboard does not contain an entry for key.

Available:

InDesign® comet_pdf® Illustrator®

CScript:

get_script_clipboard

comet.setScriptClipboard(key, value, autoDelete=True)

Set a value in the script clipboard.

When the key already exists it is overwritten.

A copy of the value is stored, not the value itself.

For more information about supported data types, the script stack, the script clipboard and the stored values see here .

Parameters:

  • key (str) – The key to set the value for.

  • value – The value to set.

  • autoDelete (bool) – Whether to delete the value after the last script on the stack has finished executing.

Return type:

None

Raises:
Available:

InDesign® comet_pdf® Illustrator®

CScript:

set_script_clipboard

comet.clearScriptClipboard()

Clear the memory of the script clipboard, deleting all stored values.

For more information about supported data types, the script stack, the script clipboard and the stored values see here .

Return type:

None

Available:

InDesign® comet_pdf® Illustrator®

CScript:

clear_script_clipboard