omero::api::IScript

Overview

[ "ami", "amd" ] interface IScript extends ServiceInterface

Utility service for managing and launching scripts for execution by the Processor API. Typical usage might include (PYTHON):


sf = client.createSession()
svc = sf.getScriptService()
scripts = svc.getScripts()

if len(scripts) >= 1:
script_id = svc.keys()[-1]
else:
script_id = svc.uploadScript('/test/my_script.py', SCRIPT_TEXT)

params = svc.getParams(script_id)

# You will need to parse the params to create the proper input
inputs = {}

# The last parameter is how long to wait as an RInt
proc = svc.runScript(script_id, inputs, None)
try:
cb = omero.scripts.ProcessCallbackI(client, proc)
while not cb.block(1000): # ms.
pass
cb.close()
rv = proc.getResults(0)
finally:
proc.close(False)

See OMERO.scripts for more information.

Operation Index

getScripts: This method returns official server scripts as a list of model::OriginalFile objects.
getScriptsByMimetype: This method returns official server scripts identified with the specified extension as a list of model::OriginalFile objects.
getUserScripts: Returns non-official scripts which have been uploaded by individual users.
getScriptID: Get the id of an official script by the script path.
getScriptText: Get the text from the server for the script with given id.
uploadScript: Upload a user script to the server and return the id.
uploadOfficialScript: Like uploadScript but is only callable by administrators.
editScript: Modify the text for the given script object.
getScriptWithDetails: Get the script from the server with details from OriginalFile @param scriptID see above @return see above @throws ApiUsageException
getParams: Get the parameters that the script takes and returns, along with other metadata available from the script.
deleteScript: Delete the script on the server with id.
runScript: If ResourceError is thrown, then no Processor is available.
canRunScript: Returns true if there is a processor which will run the given script.
validateScript: Used internally by processor.py to check if the script attached to the model::Job has a valid script attached, based on the acceptsList and the current security context.

Operations

OriginalFileList getScripts() throws ServerError

This method returns official server scripts as a list of model::OriginalFile objects. These scripts will be executed by the server if submitted via runScript. The input parameters necessary for proper functioning can be retrieved via getParams. The model::OriginalFile::path value can be used in other official scripts via the language specific import command, since the script directory will be placed on the appropriate environment path variable.

scripts = scriptService.getScripts()
for script in scripts:
text = scriptService.getScriptText(script.id.val)
# First character is a "/" symbol
path = script.path.val[1:\]
path = path.replace("/",".")
print "Possible import: %s" % path

Return Value

see above.

Exceptions

OriginalFileList getScriptsByMimetype(string mimetype) throws ServerError

This method returns official server scripts identified with the specified extension as a list of model::OriginalFile objects. These scripts will be executed by the server if submitted via runScript. The input parameters necessary for proper functioning can be retrieved via getParams. The model::OriginalFile::path value can be used in other official scripts via the language specific import command, since the script directory will be placed on the appropriate environment path variable.

scripts = scriptService.getScripts("py")
for script in scripts:
text = scriptService.getScriptText(script.id.val)
path = script.path.val[1:\] # First symbol is a "/"
path = path.replace("/",".")
print "Possible import: %s" % path

Parameters

mimetype: the mimetype identifying the scripts.

Return Value

see above.

Exceptions

OriginalFileList getUserScripts(IObjectList acceptsList) throws ServerError

Returns non-official scripts which have been uploaded by individual users. These scripts will not be run by the server, though a user can start a personal usermode processor which will allow the scripts to be executed. This is particularly useful for testing new scripts.

long getScriptID(string path) throws ServerError

Get the id of an official script by the script path. The script service ensures that all script paths are unique. Note: there is no similar method for user scripts (e.g. getUserScriptID) since the path is not guaranteed to be unique.

Parameters

scriptName

The name of the script.

Return Value

see above.

Exceptions

string getScriptText(long scriptID) throws ServerError

Get the text from the server for the script with given id.

Parameters

scriptID

see above.

Return Value

see above.

Exceptions

long uploadScript(string path, string scriptText) throws ServerError

Upload a user script to the server and return the id. This method checks that a script with that names does not exist and that the script has parameters if possible, i.e. a usermode processor is running which for the current user.

Parameters

script

see above.

Return Value

The new id of the script.

Exceptions

long uploadOfficialScript(string path, string scriptText) throws ServerError

Like uploadScript but is only callable by administrators. The parameters for the script are also checked.

void editScript(model::OriginalFile fileObject, string scriptText) throws ServerError

Modify the text for the given script object.

Parameters

script

see above.

Exceptions

RTypeDict getScriptWithDetails(long scriptID) throws ServerError

Get the script from the server with details from OriginalFile

Parameters

scriptID

see above

Return Value

see above

Exceptions

grid::JobParams getParams(long scriptID) throws ServerError

Get the parameters that the script takes and returns, along with other metadata available from the script.

Parameters

scriptID

see above.

Return Value

see above.

Exceptions

void deleteScript(long scriptID) throws ServerError

Delete the script on the server with id. The file will also be removed from disk.

Parameters

scriptID

Id of the script to delete.

Exceptions

grid::ScriptProcess* runScript(long scriptID, RTypeDict inputs, RInt waitSecs) throws ServerError

If ResourceError is thrown, then no Processor is available. Use scheduleJob to create a model::ScriptJob in the Waiting state. A Processor may become available.
try: proc = scriptService.runScript(1, {}, None) except ResourceError: job = scriptService.scheduleScript(1, {}, None)
The ScriptProcess proxy MUST be closed before exiting. If you would like the script execution to continue in the background, pass True as the argument.
try: proc.poll() # See if process is finished finally: proc.close(True) # Detach and execution can continue # proc.close(False) # OR script is immediately stopped.

bool canRunScript(long scriptID) throws ServerError

Returns true if there is a processor which will run the given script.
Either the script is an official script and this method will return true (though an individual invocation may fail with an ResourceError for some reason) or this is a user script, and a usermode processor must be active which takes the scripts user or group.

model::OriginalFile validateScript(model::Job j, IObjectList acceptsList) throws ServerError

Used internally by processor.py to check if the script attached to the model::Job has a valid script attached, based on the acceptsList and the current security context. An example of an acceptsList might be
Experimenter(myUserId, False)
, meaning that only scripts belonging to me should be trusted. An empty list implies that the server should return what it would by default trust. A valid script will be returned if it exists; otherwise null.

Home Previous Up Next Index