us.temerity.pipeline.plugin
Class PythonActionUtils

java.lang.Object
  us.temerity.pipeline.Named
      us.temerity.pipeline.PluginID
          us.temerity.pipeline.BasePlugin
              us.temerity.pipeline.BaseAction
                  us.temerity.pipeline.plugin.CommonActionUtils
                      us.temerity.pipeline.plugin.PythonActionUtils

All Implemented Interfaces:

Serializable, Cloneable, Comparable<PluginID>, Glueable

Direct Known Subclasses:

CatFilesAction, CatFilesAction, DebugTextureAction, DjvQtAction, DLCatRIBAction, DLShadowAction, DLTextureAction, DsmToTifAction, HdrToTifAction, HfsIConvertAction, MaxActionUtils, MayaActionUtils, MayaImgCvtAction, MayaResolutionAction, MayaResolutionAction, MRayActionUtils, MRayInstGroupAction, MRayInstGroupAction, MRayShaderAction, MRayShaderIncludeAction, MRayTextureAction, MRayTextureUnpackAction, NukeReformatAction, NukeReformatAction, PythonAction, ShakeQtAction

public class PythonActionUtils
extends CommonActionUtils

Superclass of node Action plugins which use Python.

This class provides convenience methods which make it easier to write Action plugins which create and execute dynamic Python scripts.

See Also:

Serialized Form

Field Summary

Fields inherited from class us.temerity.pipeline.plugin.CommonActionUtils

aExtraOptions

Fields inherited from class us.temerity.pipeline.BasePlugin

pDescription

Fields inherited from class us.temerity.pipeline.PluginID

pVendor, pVersionID

Fields inherited from class us.temerity.pipeline.Named

pName

Constructor Summary

protected

PythonActionUtils(String name, VersionID vid, String vendor, String desc) Construct with the given name, version, vendor and description.

Method Summary

SubProcessHeavy	createPythonSubProcess(ActionAgenda agenda, File script, ArrayList<String> args, Map<String,String> env, File outFile, File errFile) A convienence method for creating the SubProcessHeavy instance to be returned by the prep method which executes a temporary Python script.
SubProcessHeavy	createPythonSubProcess(ActionAgenda agenda, File script, File outFile, File errFile) A convienence method for creating the SubProcessHeavy instance to be returned by the prep method which executes a temporary Python script.
SubProcessHeavy	createPythonSubProcess(ActionAgenda agenda, String program, ArrayList<String> args, Path sourcePath, FileSeq sourceSeq, FileSeq targetSeq, Map<String,String> env, File outFile, File errFile) A convienence method for creating the SubProcessHeavy instance to be returned by the prep method which uses Python to execute a series of related subprocesses.
static String	getPythonFileVerify(ArrayList<Path> paths, String title) Verify the existence of each of the given files.
static String	getPythonFileVerify(ArrayList<Path> paths, String title, boolean nonEmpty, int indent) Verify the existence of each of the given files.
static String	getPythonFileVerify(FileSeq fseq, String title) Verify the existence of each of the files in the given file sequence.
static String	getPythonFileVerify(FileSeq fseq, String title, boolean nonEmpty, int indent) Verify the existence of each of the files in the given file sequence.
static String	getPythonFileVerify(Path path, String title) Verify the existence of each of the given files.
static String	getPythonFileVerify(Path path, String title, boolean nonEmpty, int indent) Verify the existence of each of the given files.
static String	getPythonIndent(int level) Generate a string containing spaces for the given Python indentation level.
static String	getPythonLaunchHeader() Generate a "launch" Python function declaration.
static String	getPythonLaunchPipeHeader() Generate a "lauchPipe" Python function declaration.
static String	getPythonProgram(ActionAgenda agenda) Generate the name of the Python interpreter to use based on the Toolset environment and current operating system type.
static String	getPythonProgram(Map<String,String> env) Generate the name of the Python interpreter to use based on the Toolset environment and current operating system type.

Methods inherited from class us.temerity.pipeline.plugin.CommonActionUtils

addExtraOptionsParam, addExtraOptionsParamToLayout, createScriptSubProcess, createSubProcess, createSubProcess, createSubProcess, createSubProcess, createTempCopySubProcess, createTempScript, escPath, escPath, getExtraOptionsArgs, getPrimarySourcePath, getPrimarySourcePath, getPrimarySourcePath, getPrimarySourcePaths, getPrimarySourcePaths, getPrimarySourcePaths, getPrimaryTargetPath, getPrimaryTargetPath, getPrimaryTargetPath, getPrimaryTargetPaths, getPrimaryTargetPaths, getPrimaryTargetPaths, getSecondarySourceBooleanParamValue, getSecondarySourceDoubleParamValue, getSecondarySourceDoubleParamValue, getSecondarySourceEnumParamIndex, getSecondarySourceIntegerParamValue, getSecondarySourceIntegerParamValue, getSecondarySourceLongParamValue, getSecondarySourceLongParamValue, getSecondarySourceOptionalBooleanParamValue, getSecondarySourceStringParamValue, getSecondarySourceStringParamValue, getSingleBooleanParamValue, getSingleDoubleParamValue, getSingleDoubleParamValue, getSingleEnumParamIndex, getSingleIntegerParamValue, getSingleIntegerParamValue, getSingleLongParamValue, getSingleLongParamValue, getSingleOptionalBooleanParamValue, getSingleStringParamValue, getSingleStringParamValue, getSingleTuple2dParamValue, getSingleTuple2dParamValue, getSingleTuple2dParamValue, getSingleTuple2iParamValue, getSingleTuple2iParamValue, getSingleTuple2iParamValue, getSingleTuple3dParamValue, getSingleTuple3dParamValue, getSingleTuple3dParamValue, getSingleTuple3iParamValue, getSingleTuple3iParamValue, getSingleTuple3iParamValue, getSingleTuple4dParamValue, getSingleTuple4dParamValue, getSingleTuple4dParamValue, getSourceBooleanParamValue, getSourceDoubleParamValue, getSourceDoubleParamValue, getSourceEnumParamIndex, getSourceIntegerParamValue, getSourceIntegerParamValue, getSourceLongParamValue, getSourceLongParamValue, getSourceOptionalBooleanParamValue, getSourceStringParamValue, getSourceStringParamValue, getWorkingNodeFilePath, getWorkingNodeFilePath, getWorkingNodeFilePath, getWorkingNodeFilePath, getWorkingNodeFilePaths

Methods inherited from class us.temerity.pipeline.BaseAction

addPreset, addPresetValues, addSingleParam, chmod, cleanupLater, clearAllLinkParams, clearLinkParams, clone, createTemp, createTemp, equals, equalSingleParams, equalSourceParams, fromGlue, getInitialSourceParams, getPluginType, getPresetChoices, getPresetValues, getSecondarySequences, getSecondarySourceNames, getSecondarySourceParam, getSecondarySourceParams, getSecondarySourceParamValue, getSingleLayout, getSingleParam, getSingleParams, getSingleParamValue, getSourceLayout, getSourceNames, getSourceParam, getSourceParams, getSourceParamValue, getTempDir, getTempPath, hasSecondarySourceParams, hasSingleParams, hasSourceParams, initSecondarySourceParams, initSourceParams, prep, removeAllSourceParams, removeSecondarySourceParams, removeSecondarySourceParams, removeSourceParams, setSecondarySourceParamValue, setSingleLayout, setSingleParamValue, setSingleParamValues, setSourceLayout, setSourceParamValue, setSourceParamValues, supportsSourceParams, toGlue

Methods inherited from class us.temerity.pipeline.BasePlugin

addSupport, compareTo, getDescription, getFullMessage, getPluginID, getResource, getResources, getResourceSize, getSupports, isUnderDevelopment, removeSupport, setSupports, supports, toString, underDevelopment

Methods inherited from class us.temerity.pipeline.PluginID

getVendor, getVersionID

Methods inherited from class us.temerity.pipeline.Named

getName

Methods inherited from class java.lang.Object

finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

PythonActionUtils

protected PythonActionUtils(String name,
                            VersionID vid,
                            String vendor,
                            String desc)

Construct with the given name, version, vendor and description.

Parameters:

name - The short name of the action.

vid - The action plugin revision number.

vendor - The name of the plugin vendor.

desc - A short description of the action.

Method Detail

getPythonProgram

public static final String getPythonProgram(ActionAgenda agenda)
                                     throws PipelineException

Generate the name of the Python interpreter to use based on the Toolset environment and current operating system type.

If the environmental variable PYTHON_BINARY is defined, its value will be used as the name of the python executable instead of the "python". On Windows, this program name should include the ".exe" extension.

Parameters:

agenda - The agenda to be accomplished by the Action.

Throws:

PipelineException

getPythonProgram

public static final String getPythonProgram(Map<String,String> env)
                                     throws PipelineException

Generate the name of the Python interpreter to use based on the Toolset environment and current operating system type.

If the environmental variable PYTHON_BINARY is defined, its value will be used as the name of the python executable instead of the "python". On Windows, this program name should include the ".exe" extension.

Parameters:

env - The environment used to lookup PYTHON_BINARY.

Throws:

PipelineException

getPythonIndent

public static final String getPythonIndent(int level)

Generate a string containing spaces for the given Python indentation level.

getPythonLaunchHeader

public static final String getPythonLaunchHeader()

Generate a "launch" Python function declaration.

This launch function uses Python's subprocess.call() function to start an OS subprocess and wait for it complete. If the subprocess returns an non-zero exit code, the launch function calls sys.exit with an appropriate error message.

This method is provided as a convienence for writing dynamically generated Python scripts in a subclasses prep method which run multiple subprocesses. By using "launch", you get standardized progress messages and error handling for free.

The usage is:

launch(program, args)

Where program is the executable name and args is the list of command line arguments. The program will be found using PATH from the Toolset environment used to launch the Python interpretor.

getPythonLaunchPipeHeader

public static final String getPythonLaunchPipeHeader()

Generate a "lauchPipe" Python function declaration.

This launchPipe function uses Python's suprocess.Popen function to start an OS subprocess feeding it input from STDIN and then wait for it complete. If the subprocess returns an non-zero exit code, the launch function calls sys.exit with an appropriate error message.

This method is provided as a convienence for writing dynamically generated Python scripts in a subclasses prep method which run multiple subprocesses or require piping from STDIN. By using "launchPipe", you get standardized progress messages and error handling for free.

The usage is:

launchPipe(infile, program, args)

Where infile is the name of the file that sould be fed to the STDIN of the program launched, program is the executable name and args is the list of command line arguments. The program will be found using PATH from the Toolset environment used to launch the Python interpretor.

getPythonFileVerify

public static final String getPythonFileVerify(Path path,
                                               String title)

Verify the existence of each of the given files.

The generated code requires the "os" package to have been imported previously.

Parameters:

path - The abstract file system path to the file to check.

title - What to call the file being validated in progress and error messages.

getPythonFileVerify

public static final String getPythonFileVerify(Path path,
                                               String title,
                                               boolean nonEmpty,
                                               int indent)

Verify the existence of each of the given files.

The generated code requires the "os" package to have been imported previously.

Parameters:

path - The abstract file system path to the file to check.

title - What to call the file being validated in progress and error messages.

nonEmpty - Whether to verify that the file is not zero-length as well.

indent - The base indentation level of the generated Python code.

getPythonFileVerify

public static final String getPythonFileVerify(FileSeq fseq,
                                               String title)

Verify the existence of each of the files in the given file sequence.

The generated code requires the "os" package to have been imported previously.

Parameters:

fseq - The sequence of files to check.

title - What to call the files being validated in progress and error messages.

getPythonFileVerify

public static final String getPythonFileVerify(FileSeq fseq,
                                               String title,
                                               boolean nonEmpty,
                                               int indent)

Verify the existence of each of the files in the given file sequence.

The generated code requires the "os" package to have been imported previously.

Parameters:

fseq - The sequence of files to check.

title - What to call the files being validated in progress and error messages.

nonEmpty - Whether to verify that the files are not zero-length as well.

indent - The base indentation level of the generated Python code.

getPythonFileVerify

public static final String getPythonFileVerify(ArrayList<Path> paths,
                                               String title)

Verify the existence of each of the given files.

The generated code requires the "os" package to have been imported previously.

Parameters:

paths - The abstract file system paths to the file to check.

title - What to call the files being validated in progress and error messages.

getPythonFileVerify

public static final String getPythonFileVerify(ArrayList<Path> paths,
                                               String title,
                                               boolean nonEmpty,
                                               int indent)

Verify the existence of each of the given files.

The generated code requires the "os" package to have been imported previously.

Parameters:

paths - The abstract file system paths to the file to check.

title - What to call the files being validated in progress and error messages.

nonEmpty - Whether to verify that the files are not zero-length as well.

indent - The base indentation level of the generated Python code.

createPythonSubProcess

public final SubProcessHeavy createPythonSubProcess(ActionAgenda agenda,
                                                    File script,
                                                    File outFile,
                                                    File errFile)
                                             throws PipelineException

A convienence method for creating the SubProcessHeavy instance to be returned by the prep method which executes a temporary Python script. This method will handle specifying the Python binary in an Toolset controlled and OS specific manner (see getPythonProgram). This method also properly specifies the process owner, title, environment and working directory for the Python process.

Parameters:

agenda - The agenda to be accomplished by the Action.

script - The temporary Python script file to execute.

outFile - The file to which all STDOUT output is redirected.

errFile - The file to which all STDERR output is redirected.

Throws:

PipelineException

createPythonSubProcess

public final SubProcessHeavy createPythonSubProcess(ActionAgenda agenda,
                                                    File script,
                                                    ArrayList<String> args,
                                                    Map<String,String> env,
                                                    File outFile,
                                                    File errFile)
                                             throws PipelineException

A convienence method for creating the SubProcessHeavy instance to be returned by the prep method which executes a temporary Python script. This method will handle specifying the Python binary in an Toolset controlled and OS specific manner (see getPythonProgram). This method also properly specifies the process owner, title, environment and working directory for the Python process. Additional command-line arguments for Python can be specified using a non-null args parameter. The default Toolset generated environment can be overridden if specified using a non-null env parameter.

Parameters:

agenda - The agenda to be accomplished by the Action.

script - The temporary Python script file to execute.

args - Additional Python command line arguments to specify before the script or null for no additional arguments.

env - The environment under which the OS level process is run or null to use the environment defined by the ActionAgenda.

outFile - The file to which all STDOUT output is redirected.

errFile - The file to which all STDERR output is redirected.

Throws:

PipelineException

createPythonSubProcess

public final SubProcessHeavy createPythonSubProcess(ActionAgenda agenda,
                                                    String program,
                                                    ArrayList<String> args,
                                                    Path sourcePath,
                                                    FileSeq sourceSeq,
                                                    FileSeq targetSeq,
                                                    Map<String,String> env,
                                                    File outFile,
                                                    File errFile)
                                             throws PipelineException

A convienence method for creating the SubProcessHeavy instance to be returned by the prep method which uses Python to execute a series of related subprocesses.

This method is useful when the Action will be running subprocesses of the form:

program [args] source-file1 target-file1 program [args] source-file2 target-file2 ... program [args] source-fileN target-fileN

Where the program and optional arguments are identical and the source and target file sequences have a one-to-one relationship. If only one source/target file exists in the agenda for the job, the program will be run directly. Otherwise, a temporary Python script will be created which runs the program for each source/target file pair with the supplied arguments.

The caller is reponsible for handling any differences in program name between operating systems, but this method will handle specifying the process owner, title, environment. The default Toolset generated environment can be overridden if specified using a non-null env parameter. This method will also handle specifying the Python binary in an Toolset controlled and OS specific manner (see getPythonProgram).

Parameters:

agenda - The agenda to be accomplished by the Action.

program - The name of program to execute for each source/target file pair.

args - The common command line arguments used by each invocation of the given program.

sourcePath - The abstract filesystem path to the directory containing the source file sequence.

sourceSeq - The source file sequence.

targetSeq - The target file sequence.

env - The environment under which the OS level process is run or null to use the environment defined by the ActionAgenda.

outFile - The file to which all STDOUT output is redirected.

errFile - The file to which all STDERR output is redirected.

Throws:

PipelineException