Muster Console Python API
The Muster Console Python API is available under the MConsoleAPI module. It can be imported into Python by simply typing:
import MConsoleAPI
Be aware that , even you can import the MConsoleAPI module inside any Python script, it will work only inside the Muster builtin Python interpreter and just on the scripts of template functions that are directly invoked by the Console. You can still import it widely inside any template, but an attempt to call a function of the Console from a wrong context, will return an error
A selective way to import modules only when launched from the correct context requires using the builtin muster.runningContext() function call like in the following example:
if (muster.runningContext() == "console"): import MConsoleAPI elif (muster.runningContext() == "dispatcher"): import MDispatcherAPI elif (muster.runningContext() == "renderclient"): import MInstanceAPI elif (muster.runningContext() == "notificator"): import MNotificatorAPI
Return types
Any function exported by the MConsoleAPI Python module returns always a MUSTERERR object as first. Each time you invoke a function, you must always check against the MUSTERERR object to check if the function has been invoked successfully.
In addition, the function may return a tuple instead of a single object with additional objects. Refer to each function specific documentation for a list of the returned objects:
import MConsoleAPI err = MConsoleAPI.nodeKillProcess(1) # This returns just the error object if (err.getErrorCode() != 0): sys.exit(err.getDescription()) err, node = MConsoleAPI.nodeGet(1) # This returns a tuple, error object and the node object if (err.getErrorCode() != 0): print("Instance ID 1 does not exist or something really wrong is going on !")
Handling GUI scripting
Muster comes with a builtin installation of PySide inside its own Python interpreter. At the time of this writing, PySide is compiled against QT 4.8.6. Due to licensing limitation, we are not allowed to distribute PyQT too as an additional GUI scripting library, but nothing prevent you from compiling or obtaining PyQT for QT 4.8.6 on your own and install it into the Muster python library folder. Installing or using PyQT as well as PySide is out of the scope of this document. We suggest you to check the PySide and PyQT sites for further information on the capabilities of the libraries.
import shiboken from PySide import QtGui, QtCore import MConsoleAPI import time winPointer = int(MConsoleAPI.getMainWindow()) if winPointer != 0: mainWindow = shiboken.wrapInstance(winPointer,QtGui.QMainWindow) #The following scripts creates a QT Dialog using Pyside and scans for jobs #Pay attention to the QtGui.qApp.processEvents() call, it allows you to process GUI events and then update the interface while doing busy operations in Python # Make the script available only if the running context is "console" if (muster.runningContext() == "console"): from PySide import QtCore, QtGui import MConsoleAPI class JobScannerDialog(QtGui.QDialog): def __init__(self,parent): super(JobScannerDialog,self).__init__(parent) self.initUI() def initUI(self): self.layout = QtGui.QVBoxLayout() self.setWindowTitle("Job scanner") self.label = QtGui.QLabel("Job progress:") self.progress = QtGui.QProgressBar() self.progress.setProperty("textVisible",0) self.scanButton = QtGui.QPushButton("Scan") self.layout.addWidget(self.label) self.layout.addWidget(self.progress) self.layout.addStretch() self.layout.addWidget(self.scanButton) self.setLayout(self.layout) self.scanButton.clicked.connect(self.onScan) def onScan(self): err, jobs = MConsoleAPI.jobGetList() if (err.getErrorCode() != 0): sys.exit("Error getting the jobs list") self.progress.setProperty("minimum",1) self.progress.setProperty("maximum",len(jobs)) for i in range(0, len(jobs)): self.progress.setValue(i) # Do something with jobs[i] MJob object time.sleep(0.1) # Give you some time to watch the progress bar moving if your queue is small :D QtGui.qApp.processEvents() # On busy blocking events, be sure to call the processEvents() function to let QT process GUI events and keep the interface interactive dlg = JobScannerDialog(mainWindow) result = dlg.show()
Execution contexts
The family of the MConsoleAPI functions can be invoked from within the following contexts:
- A Console script that targets a Console execution context
- A Console script that targets a context menu inside one of the Console builtin views (jobs, nodes, logs and chunks)
- onFieldChanged()
- onValidateJobSubmission()
Be sure to call MConsoleAPI functions only from the correct context. To avoid execution errors on templates functions that may be called from multiple contexts (like onValidateJobSubmission()) , you can execute the code selectively:
def onValidateJobSubmission(self,job): if (muster.runningContext() == "console"): # Prompt a dialog
Install your scripts programmatically
Muster Console supports a script editor window that let you create scripts on the fly and register them. The changes are saved into a scripts.xml file located in your Muster user preferences.
Alternatively, you may want to install the script from your Python code , and maybe, globally in your studio.
Console supports sourcing a console.py inside the Console root path. If the file is present, you can install your scripts in the following way:
# Content of console.py # Location context may be one of the following: # kLocationContextJobViewContextMenu # kLocationContextHostViewContextMenu # kLocationContextLogViewContextMenu # kLocationContextChunkViewContextMenu # kLocationContextMenuBar # Launching context may be one of the following: # kLaunchContextDispatcher, # kLaunchContextConsole, # kLaunchContextOnlineInstances, # kLaunchContextInstance, # kLaunchContextInstancesPool import MConsoleAPI MConsoleAPI.registerScript("Mycommand","Tools",MConsoleAPI.kLocationContextMenuBar,"print('hello!')",MConsoleAPI.kLaunchContextConsole,"")
Console APIs
Function name | Expected parameters | Additional returned objects | Meaning |
---|---|---|---|
registerScript() | actionName,groupName,locationContext, scriptContent,launchingContext,launchingContextFilter | None | Register a new custom script into Console |
example | |||
getMainWindow() | None | Pointer to QT main window | Returns a string containing a memory pointer to the QT QMainWindow object that may be used to parent your Pyside widgets |
getMenuBar() | None | Pointer to QT main menu bar | Returns a string containing a memory pointer to the QT QMenuBar object that may be used to parent your Pyside widgets |
example | |||
getJobsModel() | None | Pointer to QT QAbstractItemModel | Returns a string containing a memory pointer to the QT QAbstractItemModel associated to the jobs |
getLogsModel() | None | Pointer to QT QAbstractItemModel | Returns a string containing a memory pointer to the QT QAbstractItemModel associated to the logs |
getNodesModel() | None | Pointer to QT QAbstractItemModel | Returns a string containing a memory pointer to the QT QAbstractItemModel associated to the nodes |
example | |||
getJobViewSelection() | None | List of selection IDs | Returns the IDs of the selected jobs into the current job view, valid only if called from a context menu |
example | |||
getInstancesViewSelection() | None | List of selection IDs | Returns the IDs of the selected instance into the current instances/nodes view, valid only if called from a context menu |
example | |||
getLogsViewSelection() | None | List of selection IDs | Returns the IDs of the selected logs into the current logs view, valid only if called from a context menu |
example | |||
getChunksViewSelection() | None | Chunk view Job ID,List of selection IDs, List of history chunks selection IDs | Returns the IDs of the selected chunks(and history) into the current chunks view, valid only if called from a context menu |
example |
Nodes APIs
nodeKillProcess(id) | Node ID | None | Kills the current process of the supplied instance ID |
nodeKillProcessAndPause(id) | Node ID | None | Kills the current process and pause the supplied instance ID |
nodeKillProcessAndRestart(id) | Node ID | None | Kills the current process and restarts it on the supplied instance ID |
example | |||
nodeKillAndPauseNodesWorkingOnJob(jobID) | Node ID | None | Kills the current instances processing the supplied job ID |
nodeKillAndRedoNodesWorkingOnJob(jobID) | Node ID | None | Kills the current instances processing the supplied job ID and restarts the job |
nodeKillAndGoOnNodesWorkingOnJob(jobID) | Node ID | None | Kill the current instances processing the supplied job ID |
example | |||
nodePause(id) | Node ID | None | Pauses the supplied instance ID |
example | |||
nodeResume(id) | Node ID | None | Resumes the supplied instance ID |
example | |||
nodeSetProcessPriority(id,priority) | Node ID | New process priority | Changes the process priority level of the supplied instance ID |
example | |||
nodeSoftRestart(id) | Node ID | None | Soft restarts the supplied instance ID |
example | |||
nodePurgeTemplatesExclusion(id,templateId) | Node ID, Template ID | None | Removes the supplied template ID from the exclusion list of the supplied node ID |
example | |||
nodePurgeJobsExclusions(id,jobId) | Node ID, Job ID | None | Removes the supplied job ID from the exclusion list of the supplied node ID |
example | |||
nodeSetRealtimeLog(bool) | Node ID, Real time log status | None | Changes the real time log status of the supplied instance ID |
example | |||
nodeSendSystemEvent(id,event) | Node ID, Real time log status | None | Sends the specified system event on the supplied instance ID |
example | |||
nodeRunPythonCode(id,code) | Node ID, Real time log status | None | Runs the supplied python code on the supplied instance ID |
example | |||
nodeSetNotes(id,notes) | Node ID, Real time log status | None | Changes the notes of the supplied instance ID |
example | |||
nodeRemoveRegistration(id) | Node ID, Real time log status | None | Removes the registration of the specified offline instance ID |
example | |||
nodeGetList() | None | None | Gets the list of the registered nodes as MNode objects |
example | |||
nodeGet(id) | Node ID | MNode object | Gets the specified instance ID as an MNode object |
example | |||
nodeGetByName(name) | None name | MNode object | Gets the specified instance as an MNode object |
example |
Chunks APIs
chunkEnsureAvailability(jobId) | Job ID | None | Downloads, if missing, the chunks of the specified job ID and opens the chunks view |
example | |||
chunkGetList(jobId) | Job ID | List of MChunk objects | Gets the list of the chunks of the specified job ID |
example | |||
chunkGet(jobId,chunkId) | Job ID, Chunk ID | MChunk object | Gets the specified chunk as an MChunk object |
example | |||
chunkSetStatus(jobId,chunkId,status) | Job ID, Chunk ID, Status | None | Changes the status of the specified chunk |
example |
Jobs APIs
jobGetList() | None | list of MJob objects | Gets the job queue as a list of MJob objects |
example | |||
jobGet(id) | Job ID | MJob object | Gets the job from its job ID as an MJob object |
example | |||
jobReparent(id, parentId) | Job ID, parent Job ID | None | Changes the parent folder of the specified job ID |
example | |||
jobSubmit(job) | MJob object | None | Submit a new job into the queue |
example | |||
jobEdit(job) | MJob object | None | Edits the job into the queue |
example | |||
jobChangeAttrib(id,name,value) | job ID, name of attribute, value of attribute | None | Changes a single attribute of a job on the Dispatcher server and updates the job back on Consoles |
example | |||
jobRemoveAttrib(id,name) | job ID, name of attribute | None | Removes an attribute from a job on the Dispatcher server and updates the job back on Consoles |
example | |||
jobAddFolder(parent,priority,name) | parent job ID, folder priority, folder name | None | Submits a new folder into the queue |
example | |||
jobReinit(id) | Job ID | None | Reinit the supplied job ID |
example | |||
jobDelete(id) | Job ID | None | Removes the specified job ID from the queue |
example |