Debugging¶

Actions written in Python which are executed in priint:comet can be debugged using an external debugger. This enables running actions line by line and analyzing behavior, finding errors and observing variable values in an intuitive way.

Debugging priint:comet Python action requires setting up options in your host software aswell as possibly installing additional Python modules, depending on your operating system.

Once your environment is set up, it is possible to break script execution in priint:comet and attaching an external debugger while priint:comet is halted and waits for attachment.

Prerequisites¶

Server¶

priint:comet uses debugpy as the internal debugger server. debugpy is an adapter which provides a debugger server which external clients can connect to.

For the debugger server to work, Python inside priint:comet needs to be able to access debugpy.

Windows¶

debugpy is included with the plugin distribution and does not need to be manually installed.

Linux / Mac OS¶

You need to install debugpy manually from the commandline for your compatible Python installation:

pip install debugpy

Trying to enable the priint:comet debug functionality without debugpy will result in errors.

Client¶

We recommend Visual Studio Code together with Microsoft’s Python extension which is currently the only supported client.

Starting the server¶

The priint:comet debugger server can be started using the comet.debug.breakpoint() function, which by default starts the debugger server on the configured port.

Please note that calling this function with default parameters halts all script execution until a debugger client is attached.

The logfile shows which port the debugger server was launched on and if the execution waits for a client to attach:

Logfile example when launching server¶

# Python debugging started on port 5678.
# Waiting for debugger client connection on port 5678...

Breakpoints¶

Debugging a script requires setting a breakpoint to halt script execution at a certain point.

Usually you would open the script file in your editor which attaches the debugger client and set a breakpoint there.

However, priint:comet loads Python scripts into memory ahead of execution and executes them directly from memory. Reasons for this behavior are:

Scripts originate from project source ssuch das the priint:suite, an ODBC connection, etc.. and only exists in memory at runtime.
Even when the script exists on disk it may be encrypted (e.g. in an XML Offline project).

priint:comet provides a single debugging entry point to set a breakpoint from within the script itself before it is executed:

comet.debug.breakpoint()

This function can be used to start a debugger server, wait for the client to attach and trigger a breakpoint all at once.

When the debugger server is running, all Python scripts executed by priint:comet are written into the XCache so the debugger client has a file to work with. These script files get unique names and identifiers and changing their content has no effect on script execution.

Exceptions to this are locally stored files executed by the ‘Front Row’ panel.

The temporary files are deleted immediately after script execution.

Tutorial¶

Here is a simple step-by-step guide on debugging your first comet Python script.

Download and install Visual Studio Code
Start Visual Studio Code
Go to ‘Extensions’, search for ‘Python’ and install Microsoft’s Python extension

Create a launch configuration to attach the Python debugger client to port 5678 (this can be changed in the host software)

Here is an example configuration:

launch.json example configuration¶

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Remote debugging",
            "type": "python",
            "request": "attach",
            "connect": {
                "host": "localhost",
                "port": 5678
            },
            "justMyCode": false,
            "logToFile": false
        }
    ]
}

Create a Python script file named on your desktop in a folder called ‘cscripts’. Make sure it has the extension ‘.py’.

Insert the following code into the file:

Simple script for debugging¶

#!py
#pragma plain

import comet

def myFunction():
    comet.wlog('myFunction has been called')

def main():
    comet.debug.breakpoint(True)    #This starts the debugger server and waits for a client to connect

    #Some code below so we have something to debug
    comet.wlog('This is line A')
    myInt:      int = 5
    comet.wlog(f'myInt is {myInt}')
    myFunction()
    comet.wlog('This is line B')
    myInt = 10
    comet.wlog(f'myInt is now {myInt}')
    comet.wlog('This is line C')

    return 0

Enable logfile writing in your host software
Depending on your host software, start the script the following way:
- InDesign® Illustrator® Open the ‘Front Row’ panel where your script should appear as a button with the filename as the caption. Press the button to execute the script.
- comet_pdf® Run comet_pdf with the -e argument pointing to the script file you created.

In your logfile, you should find the following lines:

# Python debugging started on port 5678.
# Waiting for debugger client connection on port 5678...

Go to Visual Studio Code and run your debugger launch configuration
Once the debugger client has attached you are able to debug your script line by line, inspect variables etc…

Object information¶

Each priint:comet Python class supports basic, human readable, information to the debugger. This information is displayed next to variables or in variable tooltips in the debug window of Visual Studio Code.

The native Python function repr() can be used to obtain the same information in your code.

The documentation on which information is provided is found in each class documentation.