comet.jobs ******************************************************************************* .. py:module:: comet.jobs Creation and execution of a **queue of jobs**. Documentation =============================================================================== Creation and execution of a **queue of jobs**. If you want to process many documents in one action, you will be familiar with the problem: InDesign® only closes documents at the very end of the entire action at the so-called :priint-important:`idle time`. Until then, the documents remain in memory and you only need to have opened enough documents or large enough documents to cause InDesign® to crash due to memory overflow. The queue solves this problem by only starting the individual jobs of the overall action at idle time. Once the individual job is finished, the queue waits until InDesign® has also closed the document for the job in the background. Only then will the next job be processed, again at idle time. All you have to do is inform the queue of the document being processed (so that the queue knows whether it has to wait at all and for what). To do this, enter the following instruction in the job script after opening the document: .. code-block:: python comet.jobs.registerDocument(comet.document.getFront()) The following table describes the behavior of the queue in the different situations: .. table:: Queue behavior :class: comet alternating-rows :width: 100% :widths: auto +------------------------+------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------+ | Document | With registration | Without registration | +========================+====================================================================================================================================+==============================================================================================+ | Open and close | :priint-keyword:`Processing waits until the document is also closed in the background.` Only then is the next job processed. | The next job is started immediately after the end of the current job and the | | | | :priint-important:`document remains open in the background until the next idle time.` | | | | In short, you might as well not use the job queue at all. | +------------------------+------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------+ | Open only | :priint-keyword:`Processing only continues once the document has been closed.` | :priint-keyword:`The next job is started immediately after the end of the current job.` | | | | Preferably use this option to open a list of documents or to checkout and open them. | | | This option is particularly useful for **manual editing of publication documents:** The queue loads and opens the next document. | | | | The document can then be edited manually. | | | | | | | | On saving and checking in the document the next document to be processed is loaded and opened immediately. | | +------------------------+------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------+ | No document opened | It is of course possible that a job does not open a specific document at all, but processes the current document (or none at all). In this case, the job IDs could contain 'any' information, e.g. the URL of a file to download. | | | | | | :priint-keyword:`In this case, the next job is started immediately after the end of the current job.` | +------------------------+------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------+ .. container:: priint-block-important **Once all jobs have been processed, processing of the queue is automatically deactivated** and must be reactivated with :py:func:`start` to process further jobs. Queue script ------------------------------------------------------------------------------- Jobs are added to the queue using the :py:func:`add` function. The call defines the script (the action) that is to be executed for the job. For this script to 'know' what it should do, the call also defines a so-called job ID, which can be evaluated by the script as a global variable. As a rule, the job ID contains either the (complete) path of an InDesign® document or the document ID of a publication document. However, you can also enter any other description here - the only decisive factor is how the executing script evaluates this description. .. container:: priint-block The job ID does **not** have to be unique in the queue. The job ID is provided to the executing script as the global variable gJobsQueueID. The following table describes some typical job IDs: .. table:: Job IDs :class: comet alternating-rows :width: 100% :widths: auto +------------------------+------------------------------------------------------------------------------------------------------------------------------------+ | Job ID | Example | +========================+====================================================================================================================================+ | Document path | .. code-block:: python | | | :caption: Open, edit and save the document $DESKTOP/aaa.indd in a job queue: | | | | | | doc = comet.document.open(comet.gJobsQueueID) #gJobsQueueID contains the path | | | comet.jobs.registerDocument() #Our document is the front document here | | | ... | | | if doc.canSave(): | | | doc.save() | | | doc.close() | | | | +------------------------+------------------------------------------------------------------------------------------------------------------------------------+ | Document ID | .. code-block:: python | | | :caption: Open, edit and save the document with the ID 268516810 in a job queue: | | | | | | comet.publication.checkoutByID(comet.gJobsQueueID) #gJobsQueueID contains the publication ID | | | comet.jobs.registerDocument() #Our document is the front document here | | | ... | | | comet.publication.checkinByID(comet.gJobsQueueID) | | | | +------------------------+------------------------------------------------------------------------------------------------------------------------------------+ | URL | .. code-block:: python | | | :caption: Download the file of the URL http://www.hi13.de/aaa.png to my desktop: | | | | | | comet.file.download(comet.gJobsQueueID, '$DESKTOP/abc.png') #gJobsQueueID contains the URL | | | | +------------------------+------------------------------------------------------------------------------------------------------------------------------------+ | Any | .. code-block:: python | | | :caption: Split a string delimited by '+++' and log the values | | | | | | values = comet.gJobsQueueID.split('+++') #gJobsQueueID contains a '+++'-delimited string | | | comet.wlog(values) | +------------------------+------------------------------------------------------------------------------------------------------------------------------------+ Methods =============================================================================== .. autofunction:: comet.jobs.add .. autofunction:: comet.jobs.start .. autofunction:: comet.jobs.isActive .. autofunction:: comet.jobs.stop .. autofunction:: comet.jobs.clear .. autofunction:: comet.jobs.getQueue .. autofunction:: comet.jobs.registerDocument